Deployment of the Wallarm Docker Image to AWS¶

This quick guide provides the steps to deploy the Docker image of the NGINX-based Wallarm node to the Amazon cloud platform using the Amazon Elastic Container Service (Amazon ECS).

The instructions limitations

These instructions do not cover the configuration of load balancing and node autoscaling. If setting up these components yourself, we recommend that you review an appropriate part of the AWS instructions.

Use cases¶

Among all supported Wallarm deployment options, Wallarm deployment on AWS ECS using the Docker image is recommended in these use cases:

If your applications leverage a microservices architecture, and are already containerized and operational on AWS ECS.
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¶

AWS account and user with the admin permissions
AWS CLI 1 or AWS CLI 2 properly installed and configured
Access to the account with the Administrator role and two‑factor authentication disabled in Wallarm Console for the US Cloud or EU Cloud

Options for the Wallarm node Docker container configuration¶

The filtering node configuration parameters should be passed to the deployed Docker container in one of the following ways:

In the environment variables. This option allows for the configuration of only basic filtering node parameters. Most directives cannot be configured through environment variables.
In the mounted configuration file. This option allows full filtering node configuration via any directives. With this configuration method, environment variables with the filtering node and Wallarm Cloud connection settings are also passed to the container.

Deploying the Wallarm node Docker container configured through environment variables¶

To deploy the containerized Wallarm filtering node configured only through environment variables, the AWS Management Console and AWS CLI are used.

Get Wallarm token of the appropriate type:
API tokenNode token
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.
Sign in to the AWS Management Console → the Services list → Elastic Container Service.
Proceed to cluster creation by the button Create Cluster:
1. Select the template EC2 Linux + Networking.
2. Specify the cluster name, for example: wallarm-cluster.
3. If required, set other settings following the AWS instructions.
4. Save the cluster.
Encrypt the sensitive data required to connect to the Wallarm Cloud (node token) by using the AWS Secrets Manager or AWS Systems Manager → Parameter Store.

In these instructions, sensitive data is stored in the AWS Secrets Manager.
Access to the sensitive data storage

To allow the Docker container to read the encrypted sensitive data, please ensure the AWS settings meet the following requirements:
- Sensitive data is stored in the region used to run the Docker container.
- The IAM policy SecretsManagerReadWrite is attached to the user specified in the executionRoleArn parameter of the task definition. More details on the IAM policies setup →

Create the following local JSON file with the task definition (task definition sets the Docker container operating scenario):

If you use the Wallarm US CloudIf you use the Wallarm EU Cloud

{
    "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
    "containerDefinitions": [
        {
            "memory": 128,
            "portMappings": [
           {
               "hostPort": 80,
               "containerPort": 80,
               "protocol": "tcp"
           }
       ],
       "essential": true,
       "environment": [
           {
               "name": "WALLARM_API_HOST",
               "value": "us1.api.wallarm.com"
           },
           {
               "name": "NGINX_BACKEND",
               "value": "<HOST_TO_PROTECT_WITH_WALLARM>"
           },
           {
               "name": "WALLARM_LABELS",
               "value": "group=<GROUP>"
           }
       ],
       "secrets": [
           {
               "name": "WALLARM_API_TOKEN",
               "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<WALLARM_API_TOKEN_PARAMETER_NAME>::"
           }
       ],
       "name": "wallarm-container",
       "image": "registry-1.docker.io/wallarm/node:4.10.4-1"
       }
   ],
   "family": "wallarm-api-security-node"
   }

{
    "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
    "containerDefinitions": [
        {
            "memory": 128,
            "portMappings": [
           {
               "hostPort": 80,
               "containerPort": 80,
               "protocol": "tcp"
           }
       ],
       "essential": true,
       "environment": [
           {
               "name": "NGINX_BACKEND",
               "value": "<HOST_TO_PROTECT_WITH_WALLARM>"
           },
           {
               "name": "WALLARM_LABELS",
               "value": "group=<GROUP>"
           }
       ],
       "secrets": [
           {
               "name": "WALLARM_API_TOKEN",
               "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<WALLARM_API_TOKEN_PARAMETER_NAME>::"
           }
       ],
       "name": "wallarm-container",
       "image": "registry-1.docker.io/wallarm/node:4.10.4-1"
       }
   ],
   "family": "wallarm-api-security-node"
   }

<AWS_ACCOUNT_ID>: your AWS account ID.
The environment object sets the environment variables that should be passed to the Docker container in a text format. The set of available environment variables is described in the table below. It is recommended to pass the variable WALLARM_API_TOKEN in the secrets object.

The secret object sets the environment variables that should be passed to the Docker container as the links to the sensitive data storage. The format of values depends on the selected storage (see more details in the AWS Secrets Manager or AWS Systems Manager → Parameter Store documentation).

It is recommended to pass the variable WALLARM_API_TOKEN in the secrets object.

Environment variable	Description	Required
`WALLARM_API_TOKEN`	Wallarm node or API token.	Yes
`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)
`NGINX_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_APPLICATION`	Unique identifier of the protected application to be used in the Wallarm Cloud. The value can be a positive integer except for `0`. Default value (if the variable is not passed to the container) is `-1` which indicates the default application displayed in Wallarm Console → Settings → Application. More details on setting up applications →	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
`NGINX_PORT`	Sets a port that NGINX will use inside the Docker container. Starting from the Docker image `4.0.2-1`, the `wallarm-status` service automatically runs on the same port as NGINX. Default value (if the variable is not passed to the container) is `80`. Syntax is `NGINX_PORT='443'`.	No
`WALLARM_STATUS_ALLOW`	Custom CIDRs that are allowed to access the `/wallarm-status` endpoint from outside the Docker container. Example value: `10.0.0.0/8`. If you need to pass several values, use a comma `,` as a separator. To access the service externally, use the Docker container's IP, specifying the `/wallarm-status` endpoint path.	No
`DISABLE_IPV6`	The variable with any value except for an empty one deletes the `listen [::]:80 default_server ipv6only=on;` line from the NGINX configuration file which will stop NGINX from IPv6 connection processing. If the variable is not specified explicitly or has an empty value `""`, NGINX processes both IPv6 and IPv4 connections.	No
`WALLARM_APIFW_ENABLE`	This setting toggles API Specification Enforcement on or off, available from release 4.10 onwards. Please note that activating this feature does not substitute for the required subscription and configuration through the Wallarm Console UI. Its default value is `true`, enabling the functionality.	No

All configuration file parameters are described in the AWS documentation.

Register the task definition based on the JSON configuration file by using the aws ecs register‑task‑definition command:
```
aws ecs register-task-definition --cli-input-json file://<PATH_TO_JSON_FILE>/<JSON_FILE_NAME>
```
- <PATH_TO_JSON_FILE>: path to the JSON file with the task definition on the local machine.
- <JSON_FILE_NAME>: name and extension of the JSON file with the task definition.
Run the task in the cluster by using the aws ecs run-task command:
```
aws ecs run-task --cluster <CLUSTER_NAME> --launch-type EC2 --task-definition <FAMILY_PARAM_VALUE>
```
- <CLUSTER_NAME>: name of the cluster created in the first step. For example, wallarm-cluster.
- <FAMILY_PARAM_VALUE>: name of the created task definition. The value should correspond to the family parameter value specified in the JSON file with the task definition. For example, wallarm-api-security-node.
Open the AWS Management Console → Elastic Container Service → cluster with the running task → Tasks and ensure the task is displayed in the list.
Test the filtering node operation.

Deploying the Wallarm node Docker container configured through the mounted file¶

To deploy the containerized Wallarm filtering node configured through environment variables and mounted file, the AWS Management Console and AWS CLI are used.

In these instructions, the configuration file is mounted from the AWS EFS file system. You can review other methods for mounting the file in the AWS documentation.

To deploy the container with environment variables and configuration file mounted from AWS EFS:

Get Wallarm token of the appropriate type:
API tokenNode token
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.
Sign in to the AWS Management Console → the Services list → Elastic Container Service.
Proceed to cluster creation by the button Create Cluster:
- Template: EC2 Linux + Networking.
- Cluster name: wallarm-cluster (as an example).
- Provisioning Model: On-Demand Instance.
- EC2 instance type: t2.micro.
- Number of instances: 1.
- EC2 AMI ID: Amazon Linux 2 Amazon ECS-optimized AMI.
- Key pair: key pair for SSH connection to the instance. You will need to connect to the instance via SSH to upload the configuration file to the storage.
- Other settings can be left as default. When changing other settings, it is recommended to follow the instructions on AWS EFS setup.
Configure the AWS EFS storage following steps 2-4 of the AWS instructions.

In the 4^th step of AWS instructions, create the configuration file default and place the file in the directory that stores the files for mounting by default. The file default should cover the filtering node configuration. An example of the file with minimal settings:

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;
    #listen 443 ssl;

    server_name localhost;

    #ssl_certificate cert.pem;
    #ssl_certificate_key cert.key;

    root /usr/share/nginx/html;

    index index.html index.htm;

    wallarm_mode monitoring;
    # wallarm_application 1;

    location / {
            proxy_pass http://example.com;
            include proxy_params;
    }
}

Set of filtering node directives that can be specified in the configuration file →

Encrypt the sensitive data required to connect to the Wallarm Cloud (node token) by using the AWS Secrets Manager or AWS Systems Manager → Parameter Store.

In these instructions, sensitive data is stored in the AWS Secrets Manager.
Access to the sensitive data storage

To allow the Docker container to read the encrypted sensitive data, please ensure the AWS settings meet the following requirements:
- Sensitive data is stored in the region used to run the Docker container.
- The IAM policy SecretsManagerReadWrite is attached to the user specified in the executionRoleArn parameter of the task definition. More details on the IAM policies setup →

Create the following local JSON file with the task definition (task definition sets the Docker container operating scenario):

If you use the Wallarm US CloudIf you use the Wallarm EU Cloud

{
    "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
    "containerDefinitions": [
        {
            "memory": 128,
            "portMappings": [
           {
               "hostPort": 80,
               "containerPort": 80,
               "protocol": "tcp"
           }
       ],
       "essential": true,
       "mountPoints": [
           {
               "containerPath": "<PATH_FOR_MOUNTED_CONFIG>",
               "sourceVolume": "<NAME_FROM_VOLUMES_OBJECT>"
           }
       ],
       "environment": [
           {
               "name": "WALLARM_API_HOST",
               "value": "us1.api.wallarm.com"
           },
           {
               "name": "WALLARM_LABELS",
               "value": "group=<GROUP>"
           }
       ],
       "secrets": [
           {
               "name": "WALLARM_API_TOKEN",
               "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<WALLARM_API_TOKEN_PARAMETER_NAME>::"
           }
       ],
       "name": "wallarm-container",
       "image": "registry-1.docker.io/wallarm/node:4.10.4-1"
       }
   ],
   "volumes": [
       {
           "name": "<VOLUME_NAME>",
           "efsVolumeConfiguration": {
               "fileSystemId": "<EFS_FILE_SYSTEM_ID>",
               "transitEncryption": "ENABLED"
           }
       }
   ],
   "family": "wallarm-api-security-node"
   }

{
    "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole",
    "containerDefinitions": [
        {
            "memory": 128,
            "portMappings": [
           {
               "hostPort": 80,
               "containerPort": 80,
               "protocol": "tcp"
           }
       ],
       "essential": true,
       "mountPoints": [
           {
               "containerPath": "/etc/nginx/sites-enabled",
               "sourceVolume": "default"
           }
       ],
       "environment": [
           {
               "name": "WALLARM_LABELS",
               "value": "group=<GROUP>"
           }
       ],
       "secrets": [
           {
               "name": "WALLARM_API_TOKEN",
               "valueFrom": "arn:aws:secretsmanager:<SECRETS_MANAGER_AWS_REGION>:<AWS_ACCOUNT_ID>:secret:<SECRET_NAME>:<WALLARM_API_TOKEN_PARAMETER_NAME>::"
           }
       ],
       "name": "wallarm-container",
       "image": "registry-1.docker.io/wallarm/node:4.10.4-1"
       }
   ],
   "volumes": [
       {
           "name": "default",
           "efsVolumeConfiguration": {
               "fileSystemId": "<EFS_FILE_SYSTEM_ID>",
               "transitEncryption": "ENABLED"
           }
       }
   ],
   "family": "wallarm-api-security-node"
   }

<AWS_ACCOUNT_ID>: your AWS account ID.
<PATH_FOR_MOUNTED_CONFIG>: directory of the container to mount the configuration file to. Configuration files can be mounted to the following container directories used by NGINX:
- /etc/nginx/conf.d — common settings
- /etc/nginx/sites-enabled — virtual host settings
- /var/www/html — static files
The filtering node directives should be described in the /etc/nginx/sites-enabled/default file.
<NAME_FROM_VOLUMES_OBJECT>: name of the volumes object containing the configuration of the mounted file AWS EFS storage (the value should be the same as <VOLUME_NAME>).
<VOLUME_NAME>: name of the volumes object that contains the configuration of the mounted file AWS EFS storage.
<EFS_FILE_SYSTEM_ID>: ID of the AWS EFS file system containing the file that should be mounted to the container. ID is displayed in the AWS Management Console → Services → EFS → File systems.
The environment object sets the environment variables that should be passed to the Docker container in a text format. The set of available environment variables is described in the table below. It is recommended to pass the variable WALLARM_API_TOKEN in the secrets object.

The secret object sets the environment variables that should be passed to the Docker container as the links to the sensitive data storage. The format of values depends on the selected storage (see more details in the AWS Secrets Manager or AWS Systems Manager → Parameter Store documentation).

It is recommended to pass the variable WALLARM_API_TOKEN in the secrets object.

Environment variable Description Required

WALLARM_API_TOKEN Wallarm node or API token. 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_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)

All configuration file parameters are described in the AWS documentation.

Register the task definition based on the JSON configuration file by using the aws ecs register‑task‑definition command:
```
aws ecs register-task-definition --cli-input-json file://<PATH_TO_JSON_FILE>/<JSON_FILE_NAME>
```
- <PATH_TO_JSON_FILE>: path to the JSON file with the task definition on the local machine.
- <JSON_FILE_NAME>: name and extension of the JSON file with the task definition.
Run the task in the cluster by using the aws ecs run-task command:
```
aws ecs run-task --cluster <CLUSTER_NAME> --launch-type EC2 --task-definition <FAMILY_PARAM_VALUE>
```
- <CLUSTER_NAME>: name of the cluster created in the first step. For example, wallarm-cluster.
- <FAMILY_PARAM_VALUE>: name of the created task definition. The value should correspond to the family parameter value specified in the JSON file with the task definition. For example, wallarm-api-security-node.
Open the AWS Management Console → Elastic Container Service → cluster with the running task → Tasks and ensure the task is displayed in the list.
Test the filtering node operation.

Testing the filtering node operation¶

In the AWS Management Console, open the running task and copy the container IP address from the field External Link.

If the IP address is empty, please ensure the container is in the RUNNING status.
Send the request with the test Path Traversal attack to the copied address:
```
curl http://<COPIED_IP>/etc/passwd
```
Open Wallarm Console → Attacks in the US Cloud or EU Cloud and make sure the attack is displayed in the list.

Details on errors that occurred during the container deployment are displayed in the task details in the AWS Management Console. If the container is unavailable, please ensure required filtering node parameters with correct values are passed to the container.