Skip to content

Fine‑tuning of NGINX-based Wallarm Ingress Controller

Learn fine-tuning options available for the Wallarm Ingress controller to get the most out of the Wallarm solution.

Official documentation for NGINX Ingress Controller

The fine‑tuning of Wallarm Ingress Controller is quite similar to that of NGINX Ingress Controller described in the official documentation. When working with Wallarm, all options for setting up the original NGINX Ingress Controller are available.

Additional Settings for Helm Chart

The settings are performed via the values.yaml file. By default, the file looks as follows:

controller:
  wallarm:
    enabled: false
    apiHost: api.wallarm.com
    apiPort: 444
    apiSSL: true
    token: ""
    tarantool:
      kind: Deployment
      service:
        annotations: {}
      replicaCount: 1
      arena: "0.2"
      livenessProbe:
        failureThreshold: 3
        initialDelaySeconds: 10
        periodSeconds: 10
        successThreshold: 1
        timeoutSeconds: 1
      resources: {}
    metrics:
      enabled: false

      service:
        annotations:
          prometheus.io/scrape: "true"
          prometheus.io/path: /wallarm-metrics
          prometheus.io/port: "18080"

        ## List of IP addresses at which the stats-exporter service is available
        ## Ref: https://kubernetes.io/docs/user-guide/services/#external-ips
        ##
        externalIPs: []

        loadBalancerIP: ""
        loadBalancerSourceRanges: []
        servicePort: 9913
        type: ClusterIP
    synccloud:
      resources: {}
    collectd:
      resources: {}
    acl:
      enabled: false
      resources: {}

A description of the main parameters you can set up is provided below. Other parameters come with default value and rarely need to be changed; their descriptions are provided at this link.

wallarm.enabled

Allows you to enable or disable Wallarm functions.

Default value: false

wallarm.apiHost

Wallarm API endpoint. Can be:

Default value: api.wallarm.com

wallarm.token

The Wallarm Node token is created on the Wallarm portal in the EU or US cloud. It is required to access to Wallarm API.

Default value: not specified

wallarm.tarantool.replicaCount

The number of running pods for postanalytics. Postanalytics is used for the behavior‑based attack detection.

Default value: 1

wallarm.tarantool.arena

Specifies the amount of memory allocated for postanalytics service. It is recommended to set up a value sufficient to store requests data for the last 5-15 minutes.

Default value: 0.2

wallarm.metrics.enabled

This switch toggles information and metrics collection. If Prometheus is installed in the Kubernetes cluster, no additional configuration is required.

Default value: false

Global Controller Settings

Implemented via ConfigMap.

Besides the standard ones, the following additional parameters are supported:

Ingress Annotations

These annotations are used for setting up parameters for processing individual instances of Ingress.

Besides the standard ones, the following additional annotations are supported:

Applying annotation to the Ingress resource

To apply the settings to your Ingress, please use the following command:

kubectl annotate --overwrite ingress YOUR_INGRESS_NAME ANNOTATION_NAME=VALUE

  • YOUR_INGRESS_NAME is the name of your Ingress,

  • ANNOTATION_NAME is the name of the annotation from the list above,

  • VALUE is the value of the annotation from the list above.

Annotation examples

Enabling IP blocking

To enable IP blocking, create the addresses list in your Wallarm account and execute the following command:

kubectl annotate --overwrite ingress YOUR_INGRESS_NAME nginx.ingress.kubernetes.io/wallarm-acl=on

Configuring the blocking page and error code

Annotations used for the blocking page and error code configuration depend on the reason and method of blocking the requests:

  • nginx.ingress.kubernetes.io/wallarm-block-page is used if the request is blocked by the filtering node due to detected attack signs

  • nginx.ingress.kubernetes.io/wallarm-acl-block-page is used if the request is originated from a blocked IP address

For example, to return the default Wallarm blocking page and the error code 445 in the response to the blocked request:

kubectl annotate ingress <YOUR_INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='&/usr/share/nginx/html/wallarm_blocked.html response_code=445'

kubectl annotate ingress <YOUR_INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-acl-block-page='&/usr/share/nginx/html/wallarm_blocked.html response_code=445'

More details on the blocking page and error code configuration methods →

Separating the blocking page path and error code with a comma

To separate the blocking page path and error code in the Ingress annotation value, you can use a comma instead of space. For example:

kubectl annotate ingress <YOUR_INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='&/usr/share/nginx/html/wallarm_blocked.html,response_code=445'

kubectl annotate ingress <YOUR_INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-acl-block-page='&/usr/share/nginx/html/wallarm_blocked.html,response_code=445'

Enabling attack analysis with libdetection

The libdetection library additionally validates attacks detected by the library libproton. Using libdetection ensures the double‑detection of attacks and reduces the number of false positives.

To allow libdetection to parse and check the request body, buffering of a client request body must be enabled (proxy_request_buffering on).

There are two options to enable attack analysis with libdetection:

  • Applying the following nginx.ingress.kubernetes.io/server-snippet annotation to the Ingress resource:

    kubectl annotate --overwrite ingress <YOUR_INGRESS_NAME> nginx.ingress.kubernetes.io/server-snippet="wallarm_enable_libdetection on; proxy_request_buffering on;"

  • Adding the following snippet to the config object in values.yaml of the cloned Wallarm Helm chart repository:

    config: {
    server-snippet: 'wallarm_enable_libdetection on; proxy_request_buffering on;'
}