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

Install from the Helm Repository

Add the Helm repository hosted on GitHub Pages and install:

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

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

Pin a Specific Version

helm upgrade --install coraza-kubernetes-operator \
 coraza-kubernetes-operator/coraza-kubernetes-operator \
 --namespace coraza-system \
 --create-namespace \
 --version <chart-version>

Replace <chart-version> with the desired version (e.g. 0.1.0). Available versions are listed on the releases page.

Install on OpenShift

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

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

Prerequisites

OpenShift Container Platform v4.20 or later
Cluster administrator privileges
Gateway API enabled on your cluster (see Enable Gateway API below)
OpenShift Service Mesh or Istio installed with Gateway API support

Enable Gateway API

On OpenShift 4.20 and later, the Gateway API CRDs are included by default. You must create the openshift-default GatewayClass, which is the officially supported GatewayClass provided by the OpenShift Ingress Operator:

Creating Firewall Rules

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

Firewall rules in the Coraza Kubernetes Operator are written using ModSecurity SecLang syntax. Rule text is stored in RuleSource resources; a RuleSet lists RuleSource (and optional RuleData) names in order and drives compilation and caching.

Writing rules in RuleSources

Each RuleSource has spec.rules: a string containing SecLang directives (use a | block scalar in YAML for multiline text).

A basic RuleSource with Coraza engine configuration:

apiVersion: waf.k8s.coraza.io/v1alpha1
kind: RuleSource
metadata:
 name: base-rules
spec:
 rules: |
 SecRuleEngine On
 SecRequestBodyAccess On
 SecResponseBodyAccess Off
 SecAuditLog /dev/stdout
 SecAuditLogFormat JSON
 SecAuditEngine RelevantOnly

A RuleSource 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 a Gateway via an Istio WasmPlugin.

Creating an Engine

The minimum Engine configuration requires a RuleSet reference and a target that identifies your Gateway:

apiVersion: waf.k8s.coraza.io/v1alpha1
kind: Engine
metadata:
 name: my-engine
spec:
 ruleSet:
 name: my-ruleset
 target:
 type: Gateway
 name: my-gateway
 provider: Istio

Selecting a Gateway

The target.name identifies the Gateway resource in the same namespace. The operator derives the workload label selector using the GEP-1762 convention (gateway.networking.k8s.io/gateway-name label).

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 RuleSource, RuleData, and RuleSet manifests 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 provides these files from RuleData resources, referenced by the RuleSet spec.data list.

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. Store that file in a RuleData spec.files map (filename → content).

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
 target:
 type: Gateway
 name: my-gateway
 provider: Istio

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

Install from the Helm Repository

Pin a Specific Version

Install on OpenShift

Prerequisites

Enable Gateway API

Creating Firewall Rules

Writing rules in RuleSources

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: