Deploying a WAF Engine

An Engine resource references a RuleSet and attaches the Coraza WAF to one or more Gateways via an Istio WasmPlugin.

Creating an Engine

The minimum Engine configuration requires a RuleSet reference and a workload selector that matches your Gateway:

apiVersion: waf.k8s.coraza.io/v1alpha1
kind: Engine
metadata:
  name: my-engine
spec:
  ruleSet:
    name: my-ruleset
  driver:
    istio:
      wasm:
        mode: gateway
        workloadSelector:
          matchLabels:
            gateway.networking.k8s.io/gateway-name: my-gateway
        ruleSetCacheServer:
          pollIntervalSeconds: 15

Selecting a Gateway

The workloadSelector determines which Gateway pods the WAF attaches to. Kubernetes Gateway API implementations typically label Gateway pods with gateway.networking.k8s.io/gateway-name. Use the label that matches your Gateway:

kubectl get pods -n my-namespace --show-labels

Look for labels on the Gateway pods and use them in matchLabels.

Configuring the Failure Policy

The failurePolicy field controls what happens when the WAF is not ready or encounters an error:

spec:
  failurePolicy: allow

See Configuring Failure Policies for guidance on choosing.

Configuring the Poll Interval

The pollIntervalSeconds field controls how often the WASM plugin checks the cache for updated rules. The default is 15 seconds. Valid range: 1 to 3600.

spec:
  driver:
    istio:
      wasm:
        ruleSetCacheServer:
          pollIntervalSeconds: 30

Lower values mean faster rule updates but slightly more network traffic between the WASM plugin and the cache server.

Using a Custom WASM Image

By default, the operator uses its built-in WASM plugin image. To use a custom image, specify it in the Engine:

spec:
  driver:
    istio:
      wasm:
        image: "oci://ghcr.io/my-org/coraza-proxy-wasm:v1.0.0"

The image must use the oci:// URI scheme.

If the image is in a private registry, provide an image pull secret:

spec:
  driver:
    istio:
      wasm:
        image: "oci://my-registry.example.com/coraza-proxy-wasm:v1.0.0"
        imagePullSecret: my-registry-credentials

The Secret must exist in the same namespace as the Engine.

Verifying the Engine

Check the Engine status:

kubectl get engine my-engine -n my-namespace

The output shows the referenced RuleSet, failure policy, and readiness:

NAME        RULESET      FAILURE POLICY   READY   AGE
my-engine   my-ruleset   fail             True    5m

For detailed status including matched Gateways:

kubectl describe engine my-engine -n my-namespace