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:
-
enable-wallarm
- enables the Wallarm module in NGINX -
enable-wallarm-acl
- enables blocking by IP addresses specified in your Wallarm account
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:
-
nginx.ingress.kubernetes.io/wallarm-mode, default: off
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;' }