Development version. This documentation is for unreleased features on the main branch. View the latest stable documentation.

Status Conditions and Troubleshooting

Understanding resource status conditions and common troubleshooting steps.

Engine, RuleSet, RuleSource, and RuleData 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.

Reason	Description	Resolution
`Accepted`	The target Gateway is available and not contested by another Engine.	No action needed.
`TargetNotFound`	The referenced Gateway does not exist in the Engine’s namespace.	Verify the Gateway name and namespace in the Engine spec.
`TargetConflict`	Another Engine already targets the same Gateway.	Only one Engine may target a given Gateway. Remove the conflicting Engine or change the target.

Ready

The Engine is deployed and attached to a Gateway.

kubectl get engine my-engine -n my-namespace

Progressing

The Engine is being reconciled. This is normal during creation or after updates.

Degraded

The Engine could not reach its desired state. Common reasons:

Reason	Description	Resolution
`RuleSetNotFound`	The referenced RuleSet does not exist.	Verify the RuleSet name and namespace in the Engine spec.
`RuleSetDegraded`	The referenced RuleSet is in a Degraded state.	Check the RuleSet status: `kubectl describe ruleset <name>`.
`InvalidConfiguration`	The Engine spec contains an invalid configuration.	Check the condition message for details and fix the Engine spec.
`ProvisioningFailed`	Failed to create or update the WasmPlugin resource.	Check operator logs and RBAC permissions.
`NetworkPolicyFailed`	Failed to apply the NetworkPolicy for the cache server.	Check operator logs and RBAC permissions.
`ServiceAccountFailed`	Failed to ensure the cache client ServiceAccount.	Check operator logs and RBAC permissions.
`TokenFailed`	Failed to ensure the cache client token.	Check operator logs and RBAC permissions.

RuleSource Conditions

RuleSource status is updated by the RuleSource reconciler whenever the object’s spec generation changes (or the per-source validation annotation changes). Per-source validation does not load RuleSet-scoped RuleData; aggregate validation on the RuleSet still runs with the merged virtual filesystem when a RuleSet references this source.

Ready

The operator has validated spec.rules with Coraza, or validation was skipped via annotation.

Reason	Description
`Validated`	Per-source Coraza rule validation passed (without RuleSet-scoped RuleData).
`ValidationSkipped`	Validation was skipped via the `waf.k8s.coraza.io/rule-validation: "false"` annotation.

Degraded

Per-source rule validation failed.

Reason	Description	Resolution
`InvalidRules`	The SecLang rules failed Coraza validation.	Check the condition message for the validation error and fix the rule text.

RuleData Conditions

RuleData status is updated by the RuleSet reconciler when a RuleSet references the data. If a RuleData is not referenced by any RuleSet, its status reflects the last reconciliation that touched it.

Ready

The RuleData has been loaded by a RuleSet reconciliation.

Reason	Description
`Loaded`	The data was read successfully.

Note: Coraza does not validate individual data files before aggregation, so RuleData has no Degraded condition. Data-related errors (missing files, access errors) are reported on the RuleSet status.

RuleSet Conditions

Ready

The rules have been compiled, validated, and cached. When the Ready condition is True, the reason is typically RulesCached.

Progressing

The RuleSet is being processed. This happens when the RuleSet or a referenced RuleSource or RuleData changes. While waiting for RuleSource validation status to match the current source generation, the reason may be AwaitingRuleSourceValidation (the message lists pending source names).

Degraded

The RuleSet could not be compiled or cached. Common reasons:

Reason	Description	Resolution
`UnsupportedRules`	The RuleSet contains rules not supported in the current execution environment.	Remove the unsupported rules, or add the annotation `waf.k8s.coraza.io/skip-unsupported-rules-check: "true"` to the RuleSet.
`InvalidRuleSet`	Aggregate validation failed (including `@pmFromFile` references that are not backed by a key in merged RuleData).	Add or fix `spec.data` so every `@pmFromFile` basename exists in the referenced RuleData objects; fix other SecLang issues in the message.
`ReferencedRuleSourceInvalid`	A referenced RuleSource is in `Degraded` with `InvalidRules` for its current spec generation.	Fix the RuleSource `spec.rules` (see that object’s status message).
`RuleSourceNotFound`	A RuleSource named in `spec.sources` does not exist.	Create the RuleSource or correct the name; it must be in the same namespace as the RuleSet.
`RuleSourceAccessError`	The operator could not read a referenced RuleSource.	Check RBAC and API errors in operator logs.
`RuleDataNotFound`	A RuleData named in `spec.data` does not exist.	Create the RuleData or correct the name.
`RuleDataAccessError`	The operator could not read a referenced RuleData.	Check RBAC and API errors in operator logs.
`DuplicateReference`	A RuleSource or RuleData name appears more than once in `spec.sources` or `spec.data`.	Remove the duplicate reference.

Troubleshooting

Checking Resource Status

View the summary:

kubectl get engine,ruleset -n my-namespace

View detailed conditions:

kubectl describe engine my-engine -n my-namespace
kubectl describe ruleset my-ruleset -n my-namespace

Checking Operator Logs

kubectl logs -n coraza-system deploy/coraza-kubernetes-operator

For more verbose output, set the logging level to debug in the Helm values:

logging:
  level: debug

Common Issues

RuleSet stays in Progressing state

The operator may be waiting for referenced RuleSource or RuleData objects, or for RuleSource validation to complete (AwaitingRuleSourceValidation). Verify sources and data exist in the same namespace as the RuleSet and inspect RuleSource status:

kubectl get rulesource,ruledata -n my-namespace
kubectl describe rulesource <name> -n my-namespace

Engine is Ready but traffic is not filtered

Verify the Engine’s target name matches the Gateway resource:
```
kubectl get gateways -n my-namespace
```
Check that the WasmPlugin was created:
```
kubectl get wasmplugin -n my-namespace
```

Check the Gateway proxy logs for Coraza output:

kubectl logs -n my-namespace deploy/<gateway-name>-istio

RuleSet Degraded with UnsupportedRules

Some rules are not compatible with the WASM execution environment. See Known Limitations for details. To proceed despite unsupported rules:

kubectl annotate ruleset my-ruleset -n my-namespace \
  waf.k8s.coraza.io/skip-unsupported-rules-check=true