Running Docker Envoy‑based image¶

Image overview¶

These instructions describe the steps to run the Wallarm Docker image based on Envoy 1.18.4. The image contains all systems required for correct Wallarm node operation:

Envoy proxy services with embedded Wallarm API Security module
Tarantool modules for postanalytics
Other services and scripts

Wallarm API Security module is designed as an Envoy HTTP filter for requests proxying.

Supported configuration parameters

Please note that the most directives for the NGINX‑based filtering node configuration are not supported for the Envoy‑based filtering node configuration. See the list of parameters available for the Envoy‑based filtering node configuration →

If you deploy several Wallarm nodes

All Wallarm nodes deployed to your environment must be of the same versions. The postanalytics modules installed on separated servers must be of the same versions too.

Before installation of the additional node, please ensure its version matches the version of already deployed modules. If the deployed module version is deprecated or will be deprecated soon (3.2 or lower), upgrade all modules to the latest version.

To check the installed version, run the following command in the container:

yum list wallarm-node

Requirements¶

Access to the account with the Deploy or Administrator role and two‑factor authentication disabled in Wallarm Console in the EU Cloud or US Cloud
Access to https://api.wallarm.com:444 if working with EU Wallarm Cloud or https://us1.api.wallarm.com:444 if working with US Wallarm Cloud. Please ensure the access is not blocked by a firewall

Options for running the container¶

The filtering node configuration parameters can be passed to the docker run command in the following ways:

In the environment variables. This option allows for configuration of only basic filtering node parameters, the most parameters cannot be changed through environment variables.
In the mounted configuration file. This option allows for configuration of all the filtering node parameters.

Run the container passing the environment variables¶

You can pass the following basic filtering node settings to the container via the option -e:

Environment variable	Description	Required
`DEPLOY_USER`	Email to the Deploy or Administrator user account in Wallarm Console.	Yes
`DEPLOY_PASSWORD`	Password to the Deploy or Administrator user account in Wallarm Console.	Yes
`ENVOY_BACKEND`	Domain or IP address of the resource to protect with Wallarm API Security.	Yes
`WALLARM_API_HOST`	Wallarm API server: `api.wallarm.com` for the EU Cloud `us1.api.wallarm.com` for the US Cloud By default: `api.wallarm.com`.	No
`WALLARM_MODE`	Node mode: `block` to block malicious requests `safe_blocking` to block only those malicious requests originated from greylisted IP addresses `monitoring` to analyze but not block requests `off` to disable traffic analyzing and processing By default: `monitoring`. Detailed description of filtration modes →	No
`TARANTOOL_MEMORY_GB`	Amount of memory allocated to Tarantool. The value can be an integer or a float (a dot `.` is a decimal separator). By default: 0.2 gygabytes.	No
`DEPLOY_FORCE`	Replaces an existing Wallarm node with a new one if an existing Wallarm node name matches the identifier of the container you are running. The following values can be assigned to a variable: `true` to replace the filtering node `false` to disable the replacement of the filtering node Default value (if the variable is not passed to the container) is `false`. The Wallarm node name always matches the identifier of the container you are running. Filtering node replacement is helpful if the Docker container identifiers in your environment are static and you are trying to run another Docker container with the filtering node (for example, a container with a new version of the image). If in this case the variable value is `false`, the filtering node creation process will fail.	No

To run the image, use the command:

EU CloudUS Cloud

docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -e ENVOY_BACKEND='example.com' -p 80:80 wallarm/envoy:3.6.1-1

docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -e ENVOY_BACKEND='example.com' -e WALLARM_API_HOST='us1.api.wallarm.com' -p 80:80 wallarm/envoy:3.6.1-1

The command does the following:

Automatically creates new filtering node in the Wallarm Cloud. Created filtering node will be displayed in Wallarm Console → Nodes.
Creates the file envoy.yaml with minimal Envoy configuration in the /etc/envoy container directory.
Creates files with filtering node credentials to access the Wallarm Cloud in the /etc/wallarm container directory:
- node.yaml with filtering node UUID and secret key
- license.key with Wallarm license key
Protects the resource http://ENVOY_BACKEND:80.

Run the container mounting envoy.yaml¶

You can mount the prepared file envoy.yaml to the Docker container via the -v option. The file must contain the following settings:

Filtering node settings as described in the instructions
Envoy settings as described in the Envoy instructions

To run the image:

Pass required environment variables to the container via the -e option:

Environment variable	Description	Required
`DEPLOY_USER`	Email to the Deploy or Administrator user account in Wallarm Console.	Yes
`DEPLOY_PASSWORD`	Password to the Deploy or Administrator user account in Wallarm Console.	Yes
`WALLARM_API_HOST`	Wallarm API server: `api.wallarm.com` for the EU Cloud `us1.api.wallarm.com` for the US Cloud By default: `api.wallarm.com`.	No
`DEPLOY_FORCE`	Replaces an existing Wallarm node with a new one if an existing Wallarm node name matches the identifier of the container you are running. The following values can be assigned to a variable: `true` to replace the filtering node `false` to disable the replacement of the filtering node Default value (if the variable is not passed to the container) is `false`. The Wallarm node name always matches the identifier of the container you are running. Filtering node replacement is helpful if the Docker container identifiers in your environment are static and you are trying to run another Docker container with the filtering node (for example, a container with a new version of the image). If in this case the variable value is `false`, the filtering node creation process will fail.	No

Mount the directory with the configuration file envoy.yaml to the /etc/envoy container directory via the -v option.

EU CloudUS Cloud

docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -v /configs/envoy.yaml:/etc/envoy/envoy.yaml -p 80:80 wallarm/envoy:3.6.1-1

docker run -d -e DEPLOY_USER='deploy@example.com' -e DEPLOY_PASSWORD='very_secret' -e WALLARM_API_HOST='us1.api.wallarm.com' -v /configs/envoy.yaml:/etc/envoy/envoy.yaml -p 80:80 wallarm/envoy:3.6.1-1

The command does the following:

Automatically creates new filtering node in the Wallarm Cloud. Created filtering node will be displayed in Wallarm Console → Nodes.
Mounts the file envoy.yaml into the /etc/envoy container directory.
Creates files with filtering node credentials to access the Wallarm Cloud in the /etc/wallarm container directory:
- node.yaml with filtering node UUID and secret key
- license.key with Wallarm license key
Protects the resource http://ENVOY_BACKEND:80.

Configuration of log rotation (optional)¶

The log file rotation is preconfigured and enabled by default. You can adjust the rotation settings if necessary. These settings are located in the /etc/logrotate.d directory of the container.

Testing Wallarm node operation¶

Send the request with test SQLI and XSS attacks to the protected resource address:
```
curl http://localhost/?id='or+1=1--a-<script>prompt(1)</script>'
```
Open the Wallarm Console → Events section in the EU Cloud or US Cloud and ensure attacks are displayed in the list.