Skip to content

Running Docker Envoy‑based Image

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 the embedded Wallarm module

  • Tarantool modules for postanalytics

  • Other services and scripts

The Wallarm 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. Consequently, rate limiting and credential stuffing detection is not available in this deployment method.

See the list of parameters available for the Envoy‑based filtering node configuration →

Use cases

Among all supported Wallarm deployment options, Envoy-based Docker image is recommended for Wallarm deployment in these use cases:

  • If your organization utilizes Docker-based infrastructure, Wallarm Docker image is the ideal choice. It integrates effortlessly into your existing setup, whether you are employing a microservice architecture running on AWS ECS, Alibaba ECS, or other similar services. This solution also applies to those using virtual machines seeking a more streamlined management through Docker containers.

  • If you require fine-grained control over each container, the Docker image excels. It affords a greater level of resource isolation than typically possible with traditional VM-based deployments.

Requirements

  • Docker installed on your host system

  • Access to https://hub.docker.com/r/wallarm/envoy to download the Docker image. Please ensure the access is not blocked by a firewall

  • Access to the account with the Administrator role in Wallarm Console in the US Cloud or EU Cloud

  • Access to https://us1.api.wallarm.com if working with US Wallarm Cloud or to https://api.wallarm.com if working with EU Wallarm Cloud. Please ensure the access is not blocked by a firewall

  • Access to the IP addresses below for downloading updates to attack detection rules, as well as retrieving precise IPs for your allowlisted, denylisted, or graylisted countries, regions, or data centers

    34.96.64.17
34.110.183.149
35.235.66.155
34.102.90.100
34.94.156.115
35.235.115.105

    34.160.38.183
34.144.227.90
34.90.110.226

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

To run the container:

  1. Get Wallarm token of the appropriate type:

    1. Open Wallarm Console → Settings → API tokens in the US Cloud or EU Cloud.
    2. Find or create API token with the Deploy source role.
    3. Copy this token.
    1. Open Wallarm Console → Nodes in the US Cloud or EU Cloud.
    2. Do one of the following:
      • Create the node of the Wallarm node type and copy the generated token.
      • Use existing node group - copy token using node's menu → Copy token.

  2. Run the container with the node:

    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e ENVOY_BACKEND='example.com' -e WALLARM_API_HOST='us1.api.wallarm.com' -p 80:80 wallarm/envoy:4.8.0-1

    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e ENVOY_BACKEND='example.com' -p 80:80 wallarm/envoy:4.8.0-1

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

Environment variable Description Required
WALLARM_API_TOKEN Wallarm node or API token. Yes
ENVOY_BACKEND Domain or IP address of the resource to protect with the Wallarm solution. Yes
WALLARM_API_HOST Wallarm API server:
  • us1.api.wallarm.com for the US Cloud
  • api.wallarm.com for the EU 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 graylisted 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
WALLARM_LABELS

Available starting from node 4.6. Works only if WALLARM_API_TOKEN is set to API token with the Deploy role. Sets the group label for node instance grouping, for example:

WALLARM_LABELS="group=<GROUP>"

...will place node instance into the <GROUP> instance group (existing, or, if does not exist, it will be created).

 Yes (for API tokens)
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

The command does the following:

  • 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
    • private.key with Wallarm private 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:

To run the container:

  1. Get Wallarm token of the appropriate type:

    1. Open Wallarm Console → Settings → API tokens in the US Cloud or EU Cloud.
    2. Find or create API token with the Deploy source role.
    3. Copy this token.
    1. Open Wallarm Console → Nodes in the US Cloud or EU Cloud.
    2. Do one of the following:
      • Create the node of the Wallarm node type and copy the generated token.
      • Use existing node group - copy token using node's menu → Copy token.

  2. Run the container with the node:

    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e WALLARM_API_HOST='us1.api.wallarm.com' -v /configs/envoy.yaml:/etc/envoy/envoy.yaml -p 80:80 wallarm/envoy:4.8.0-1

    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -v /configs/envoy.yaml:/etc/envoy/envoy.yaml -p 80:80 wallarm/envoy:4.8.0-1
    • The -e option passes the following required environment variables to the container:
    Environment variable Description Required
    WALLARM_API_TOKEN Wallarm node token.

    Using one token for several installations

    You can use one token in several installations regardless of the selected platform. It allows logical grouping of node instances in the Wallarm Console UI. Example: you deploy several Wallarm nodes to a development environment, each node is on its own machine owned by a certain developer.

    		 Yes
    WALLARM_API_HOST Wallarm API server:
    • us1.api.wallarm.com for the US Cloud
    • api.wallarm.com for the EU Cloud
    By default: api.wallarm.com.    		 No
    • The -v option mounts the directory with the configuration file envoy.yaml to the /etc/envoy container directory.

The command does the following:

  • 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
    • private.key with Wallarm private key

  • Protects the resource specified in the mounted configuration file.

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

  1. Send the request with test Path Traversal attack to a protected resource address:

    curl http://localhost/etc/passwd

    If traffic is configured to be proxied to example.com, include the -H "Host: example.com" header in the request.

  2. Open Wallarm Console → Attacks section in the US Cloud or EU Cloud and make sure the attack is displayed in the list.
    Attacks in the interface