Wallarm Ingress Controller Annotations and Policies¶

This page describes the Wallarm-specific Ingress annotations and the Wallarm Policy custom resource supported by the Wallarm Ingress Controller based on F5 NGINX Ingress Controller.

For the Helm chart values, see Configuration options.

Supported Wallarm Ingress annotations¶

In this section, you can see the Wallarm-specific Ingress annotations supported by the Wallarm Ingress Controller based on the F5 NGINX Ingress Controller.

Besides the Wallarm-specific annotations described below, standard NGINX Ingress Controller annotations are also supported.

Applying annotation to the Ingress resource¶

These annotations are applied to Kubernetes Ingress resources processed by the controller.

To set or update an annotation, use:

kubectl annotate --overwrite ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> <ANNOTATION_NAME>=<VALUE>

• <YOUR_INGRESS_NAME> is the name of your Ingress

• <YOUR_INGRESS_NAMESPACE> is the namespace 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.org/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:

• Request contains malicious payloads of the following types: input validation attacks, vpatch attacks, or attacks detected based on regular expressions.

• Request containing malicious payloads from the list above originates from a graylisted IP address and the node filters requests in the safe blocking mode.

• Request originates from the denylisted IP address.

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> -n <YOUR_INGRESS_NAMESPACE> nginx.org/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 →

Managing libdetection mode¶

You can control the libdetection mode by passing the wallarm_enable_libdetection directive into the generated NGINX configuration:

• (Per‑Ingress annotation) Requires controller.enableSnippets: true:

kubectl annotate --overwrite ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> \
  nginx.org/server-snippets="wallarm_enable_libdetection off;"

• (Cluster‑wide) Uses the controller ConfigMap (via controller.config.entries) to apply the setting globally to the Ingress Controller:

helm upgrade --reuse-values <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE> \
  --set-string controller.config.entries.server-snippets="wallarm_enable_libdetection off;"

Wallarm policy custom resource definition (CRD)¶

The F5-based controller supports Custom Resource Definitions as an alternative to standard Ingress resources for advanced routing (canary deployments, traffic splitting, header-based routing). All standard F5 NGINX Ingress Controller CRDs are available.

When using CRDs, Wallarm settings are configured via the Policy resource instead of annotations. Wallarm patches the upstream Policy CRD to add an optional spec.wallarm block — an alternative to Wallarm annotations that provides the same set of settings through a dedicated resource. The Policy is then referenced from VirtualServer or VirtualServerRoute routes.

Policy fields:

Example — two policies with different modes referenced by routes:

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: wallarm-block
spec:
  wallarm:
    mode: block
    application: 42
    fallback: "on"
---
apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: wallarm-monitoring
spec:
  wallarm:
    mode: monitoring
---
apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: my-app
spec:
  host: my-app.example.com
  upstreams:
    - name: backend
      service: backend-svc
      port: 80
  routes:
    - path: /api
      policies:
        - name: wallarm-block
      action:
        pass: backend
    - path: /internal
      policies:
        - name: wallarm-monitoring
      action:
        pass: backend

Was this page helpful?

How can we improve this article? (Optional)

Information is unclear or confusing

Insufficient information

Outdated or incorrect information

0/240

Send