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 defined in 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: {}

To change this setting, we recommend using the option --set of helm install (if installing the Ingress controller) or helm upgrade (if updating the installed Ingress controller parameters). For example:

helm install --set controller.wallarm.enabled=true <INGRESS_CONTROLLER_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

helm upgrade --reuse-values --set controller.wallarm.enabled=true <INGRESS_CONTROLLER_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

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.

controller.wallarm.enabled

Allows you to enable or disable Wallarm functions.

Default value: false

controller.wallarm.apiHost

Wallarm API endpoint. Can be:

Default value: api.wallarm.com

controller.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

controller.wallarm.tarantool.replicaCount

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

Default value: 1

controller.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

controller.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

Configuring the blocking page and error code

The annotation nginx.ingress.kubernetes.io/wallarm-block-page is used to configure the blocking page and error code returned in the response to the request blocked for the following reasons:

For example, to return the default Wallarm blocking page and the error code 445 in the response to any 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 type=attack,acl_ip,acl_source"

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

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;"

  • Pass the parameter controller.config.server-snippet to the Helm chart:

    helm install --set controller.config.server-snippet='wallarm_enable_libdetection on; proxy_request_buffering on;' <INGRESS_CONTROLLER_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

    There are also other parameters required for correct Ingress controller installation. Please pass them in the --set option too.

    helm upgrade --reuse-values --set controller.config.server-snippet='wallarm_enable_libdetection on; proxy_request_buffering on;' <INGRESS_CONTROLLER_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>