Reference on Coraza Kubernetes Operator

API Reference

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

Packages

waf.k8s.coraza.io/v1alpha1

waf.k8s.coraza.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the waf v1alpha1 API group.

Resource Types

DataReference

DataReference is a reference to a RuleData object in the same namespace as the RuleSet.

Appears in:

RuleSetSpec

Field	Description	Default	Validation
`name` string	name is the name of the RuleData in the same namespace as the RuleSet.		MaxLength: 253 MinLength: 1 Required: {}

DriverConfig

DriverConfig configures how the WAF filter is deployed into the target. When omitted from the Engine spec, the operator uses a default driver (currently wasm for Istio).

Helm Chart Values

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

The Coraza Kubernetes Operator Helm chart is located at charts/coraza-kubernetes-operator/.

Values Reference

Key	Type	Default	Description
`replicas`	int	`1`	Number of operator replicas. A PodDisruptionBudget with `minAvailable: 1` is created automatically when greater than 1.
`image.repository`	string	`ghcr.io/networking-incubator/coraza-kubernetes-operator`	Container image repository.
`image.tag`	string	`latest`	Container image tag.
`image.pullPolicy`	string	`IfNotPresent`	Image pull policy.
`imagePullSecrets`	list	`[]`	Image pull secrets for private registries.
`resources.requests.cpu`	string	`10m`	CPU request.
`resources.requests.memory`	string	`128Mi`	Memory request.
`resources.limits.cpu`	string	`500m`	CPU limit.
`resources.limits.memory`	string	`256Mi`	Memory limit.
`metrics.enabled`	bool	`true`	Enable the controller-runtime metrics endpoint (HTTPS on port 8443).
`metrics.certSecret`	string	`""`	Name of a Secret with TLS cert/key for metrics. When empty, a self-signed certificate is generated.
`metrics.certName`	string	`tls.crt`	Key name of the certificate file inside `certSecret`.
`metrics.keyName`	string	`tls.key`	Key name of the private key file inside `certSecret`.
`metrics.caName`	string	`""`	Key name of a CA certificate inside `certSecret` for ServiceMonitor TLS verification.
`metrics.serviceMonitor.enabled`	bool	`false`	Create a Prometheus ServiceMonitor resource.
`logging.development`	bool	`false`	Use console encoder with debug level (development mode). When false, the production settings below apply.
`logging.encoder`	string	`json`	Log encoding format (`json` or `console`). Only used when `development` is false.
`logging.level`	string	`info`	Minimum log level (`debug`, `info`, `error`). Only used when `development` is false.
`logging.stacktraceLevel`	string	`error`	Minimum level for stack traces (`info`, `error`, `panic`). Only used when `development` is false.
`logging.timeEncoding`	string	`rfc3339nano`	Timestamp format (`epoch`, `millis`, `nano`, `iso8601`, `rfc3339`, `rfc3339nano`). Only used when `development` is false.
`istio.revision`	string	`""`	Istio control plane revision label. When empty, no revision label is set on managed resources.
`defaultWasmImage`	string	`""`	Default WASM plugin OCI URL when an Engine omits `spec.driver.wasm.image`. When empty, uses the operator’s built-in default.
`createNamespace`	bool	`true`	Manage the release namespace with Pod Security Standard labels. Requires `--create-namespace` on first install.
`openshift.enabled`	bool	`false`	Omit `runAsUser`, `fsGroup`, and `fsGroupChangePolicy` from the pod security context for OpenShift SCC compatibility.
`podSecurityStandard.version`	string	`latest`	Kubernetes version for Pod Security Standard labels (`latest` or `vX.YZ`).
`nodeSelector`	object	`{}`	Node selector constraints.
`tolerations`	list	`[]`	Tolerations.
`affinity`	object	`{}`	Affinity rules.
`topologySpreadConstraints`	list	`[]`	Topology spread constraints for pod scheduling.

Platform Requirements

Platform	Minimum Version
Kubernetes	v1.32+
OpenShift Container Platform	v4.20+

OpenShift Values Example

For OpenShift installations, use the following values overlay:

kubectl-coraza CLI

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

kubectl-coraza is a kubectl plugin for generating Kubernetes manifests (RuleSource, RuleData, RuleSet) from OWASP CoreRuleSet files.

The operator validates and compiles rules after you apply manifests; this tool does not compile Coraza rules.

Installation

Build from source:

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

Copy bin/kubectl-coraza to a directory on your PATH:

cp bin/kubectl-coraza /usr/local/bin/

Once installed, the plugin is available as kubectl coraza.

Commands

`kubectl coraza generate coreruleset`

Generate RuleSource resources (one per *.conf file), an optional RuleData resource for *.data files, and a RuleSet that references them.

Operator CLI Flags

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

The operator manager binary accepts the following command-line flags. When deployed via Helm, these are configured through the chart values and passed as container arguments.

Flags

Core

Flag	Default	Description
`--metrics-bind-address`	`0`	Address for the metrics endpoint. Use `:8443` for HTTPS or `0` to disable.
`--health-probe-bind-address`	`:8081`	Address for the health and readiness probe endpoint.
`--leader-elect`	`false`	Enable leader election for controller manager. Required for running multiple replicas.
`--operator-name`	(none)	Helm release name. When set, the operator creates Istio ServiceEntry and DestinationRule prerequisites at startup.

TLS Certificates

Flag	Default	Description
`--metrics-cert-path`	(none)	Directory containing the metrics server TLS certificate.
`--metrics-cert-name`	`tls.crt`	Filename of the metrics certificate.
`--metrics-cert-key`	`tls.key`	Filename of the metrics private key.

RuleSet Cache

Flag	Default	Description
`--cache-gc-interval`	`5m`	How often to check for and remove stale cache entries.
`--cache-max-age`	`24h`	Maximum age before a cache entry is considered stale.
`--cache-max-size`	`104857600` (100 MB)	Maximum total size of all cached rules in bytes.
`--cache-server-port`	`18080`	Port for the RuleSet cache HTTP server.
`--envoy-cluster-name`	(required)	Envoy cluster name pointing to the cache server.

Istio Integration

Flag	Default	Description
`--istio-revision`	(none)	Istio revision label value for managed Istio resources.
`--default-wasm-image`	Built-in default	OCI reference for the Coraza WASM plugin used when an Engine omits the `image` field. Can also be set via the `CORAZA_DEFAULT_WASM_IMAGE` environment variable.

Environment Variables

Variable	Required	Description
`POD_NAMESPACE`	Yes	The namespace in which the operator is running. Typically set via the Kubernetes downward API.
`CORAZA_DEFAULT_WASM_IMAGE`	No	Override the default WASM plugin OCI image. Equivalent to `--default-wasm-image`.

Logging

The operator uses Zap via controller-runtime. Logging behavior is controlled through Helm values rather than direct CLI flags:

Status Conditions and Troubleshooting

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

Both Engine and RuleSet resources report their state through standard Kubernetes conditions. This page describes each condition type and provides troubleshooting guidance.

Condition Types

Type	Meaning
`Ready`	The resource has been successfully processed and is operational.
`Progressing`	The resource is being created or updated.
`Degraded`	The resource failed to reach or maintain its desired state.

Each condition includes:

status: True, False, or Unknown
reason: A programmatic identifier (CamelCase) explaining the condition.
message: A human-readable description.
lastTransitionTime: When the condition last changed.
observedGeneration: The resource generation that was observed.

Engine Conditions

Accepted

The Engine’s target Gateway has been validated. Only one Engine may target a given Gateway at a time. When multiple Engines reference the same Gateway, the oldest one (by creation timestamp) wins; if timestamps are equal, the lexicographically first name wins. The losing Engines receive Accepted=False.