How-to Guides on Coraza Kubernetes Operator

Install on Kubernetes with Helm

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers installing the Coraza Kubernetes Operator using Helm on a standard Kubernetes cluster.

Prerequisites

Kubernetes cluster running v1.32 or later
Istio installed with Gateway API CRDs
Helm 3 installed

Add the Helm Repository

helm repo add coraza-kubernetes-operator \
 https://networking-incubator.github.io/coraza-kubernetes-operator/
helm repo update

Install with Default Values

helm upgrade --install coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system \
 --create-namespace

Customize the Installation

Override default values by passing a values file or individual settings:

Install on OpenShift via OperatorHub

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers installing the Coraza Kubernetes Operator on OpenShift Container Platform using the OperatorHub.

Prerequisites

OpenShift Container Platform v4.20 or later
Cluster administrator privileges
OpenShift Service Mesh or Istio installed with Gateway API support

Install from OperatorHub (Web Console)

Log in to the OpenShift web console as a cluster administrator.
Navigate to Operators > OperatorHub.
Search for Coraza Kubernetes Operator.
Select the operator tile and click Install.
Choose the update channel, installation mode, and approval strategy.
Click Install and wait for the operator to reach the Succeeded phase.

Install from OperatorHub (CLI)

If the operator is available in your cluster’s default catalog, create a Subscription resource:

Creating Firewall Rules

Mon, 01 Jan 0001 00:00:00 +0000

Firewall rules in the Coraza Kubernetes Operator are written using ModSecurity SecLang syntax, stored in ConfigMaps, and aggregated by a RuleSet resource.

Writing Rules in ConfigMaps

Each ConfigMap must contain a key named rules with SecLang directives as its value.

A basic ConfigMap with Coraza engine configuration:

apiVersion: v1
kind: ConfigMap
metadata:
 name: base-rules
data:
 rules: |
 SecRuleEngine On
 SecRequestBodyAccess On
 SecResponseBodyAccess Off
 SecAuditLog /dev/stdout
 SecAuditLogFormat JSON
 SecAuditEngine RelevantOnly

A ConfigMap with a SQL injection detection rule:

Deploying a WAF Engine

Mon, 01 Jan 0001 00:00:00 +0000

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:

Using the OWASP CoreRuleSet

Mon, 01 Jan 0001 00:00:00 +0000

The OWASP CoreRuleSet (CRS) is a widely used set of attack detection rules for ModSecurity-compatible WAFs. The kubectl-coraza plugin can generate Kubernetes ConfigMaps and RuleSet resources from CRS rule files.

Important

This project does not provide, maintain, or support CoreRuleSet rules. Users must supply their own rules. The tools described here are provided for convenience.

Install the kubectl-coraza Plugin

Build the plugin from the operator repository:

git clone https://github.com/networking-incubator/coraza-kubernetes-operator.git
cd coraza-kubernetes-operator
make build

This produces bin/kubectl-coraza. Copy it to a directory on your PATH:

Using Data Files with Rules

Mon, 01 Jan 0001 00:00:00 +0000

Some SecLang rules use the @pmFromFile directive to match against patterns stored in external data files. The Coraza Kubernetes Operator supports this through Secrets of type coraza/data.

When to Use Data Files

Use data files when your rules reference @pmFromFile. For example:

SecRule ARGS "@pmFromFile bad-patterns.data" \
 "id:3001,phase:2,deny,status:403,msg:'Blocked pattern detected'"

This rule reads patterns from a file named bad-patterns.data. To make this file available to the operator, store it in a Secret.

Configuring Failure Policies

Mon, 01 Jan 0001 00:00:00 +0000

The Engine failurePolicy field determines how traffic is handled when the WAF is not ready or encounters an error during rule evaluation.

Available Policies

Policy	Behavior
`fail` (default)	Block all traffic when the WAF is not ready or encounters an error. This prioritizes security.
`allow`	Allow traffic through when the WAF is not ready or encounters an error. This prioritizes availability.

Setting the Failure Policy

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

When to Use Each Policy

Use `fail` when:

Security is the highest priority.
You prefer to block traffic rather than risk allowing unfiltered requests.
The application behind the Gateway can tolerate brief outages during WAF startup or rule updates.

Use `allow` when:

Availability is the highest priority.
You prefer to serve traffic unfiltered rather than block it during WAF startup.
The WAF provides defense-in-depth alongside other security controls.

Changing the Policy

You can change the failure policy on an existing Engine at any time:

Monitoring with Prometheus

Mon, 01 Jan 0001 00:00:00 +0000

The Coraza Kubernetes Operator exposes Prometheus metrics over HTTPS for monitoring the RuleSet cache server.

Enabling the Metrics Endpoint

Metrics are enabled by default. The endpoint is served over HTTPS on port 8443 with TLS 1.3 and requires authentication via a Kubernetes ServiceAccount token.

To disable metrics:

# values.yaml
metrics:
 enabled: false

Enabling the ServiceMonitor

If you use the Prometheus Operator, enable the ServiceMonitor to automatically discover the metrics endpoint:

Upgrading the Operator

Mon, 01 Jan 0001 00:00:00 +0000

Upgrading with Helm

To upgrade to the latest version:

helm repo update
helm upgrade coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system

To upgrade to a specific version:

helm upgrade coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system \
 --version 0.3.0

Helm automatically applies any CRD changes included in the new chart version.

Upgrading on OpenShift (OLM)

If you installed the operator through OperatorHub with automatic approval, OLM handles upgrades automatically when new versions are published to the catalog.

How-to Guides on Coraza Kubernetes Operator

Install on Kubernetes with Helm

Prerequisites

Add the Helm Repository

Install with Default Values

Customize the Installation

Install on OpenShift via OperatorHub

Prerequisites

Install from OperatorHub (Web Console)

Install from OperatorHub (CLI)

Creating Firewall Rules

Writing Rules in ConfigMaps

Deploying a WAF Engine

Creating an Engine

Selecting a Gateway

Using the OWASP CoreRuleSet

Install the kubectl-coraza Plugin

Using Data Files with Rules

When to Use Data Files

Configuring Failure Policies

Available Policies

Setting the Failure Policy

When to Use Each Policy

Use fail when:

Use allow when:

Changing the Policy

Monitoring with Prometheus

Enabling the Metrics Endpoint

Enabling the ServiceMonitor

Upgrading the Operator

Upgrading with Helm

Upgrading on OpenShift (OLM)

Use `fail` when:

Use `allow` when: