|
This is unreleased documentation for Runtime Enforcer 0.12-dev. |
Kubewarden Runtime Enforcer Quick Start
Welcome to the Kubewarden Runtime Enforcer Quick Start!
This guide walks you through the following steps:
-
Deploying the Runtime Enforcer in a Kubernetes cluster
-
Deploying a simple workload and looking at the generated
WorkloadPolicyProposal. -
Converting the WorkloadPolicyProposal into a
WorkloadPolicyin monitor mode and observing the alert. -
Switching the WorkloadPolicy to protect mode and seeing enforcement in action.
Prerequisites
Before deployment, you need to prepare the following:
-
A Kubernetes cluster (you can simply run a kind cluster)
-
helminstalled locally -
kubectlinstalled locally -
cert-manager and
cert-manager-csi-driverinstalled in the cluster
|
Please check your environment satisfies the minimum Runtime Enforcer requirements. |
Install cert-manager and cert-manager-csi-driver
To install cert-manager, run the following commands:
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--set crds.enabled=true \
--wait
|
For more information on configuring cert-manager, please visit the cert-manager documentation. |
The cert-manager-csi-driver is used to automatically provision and mount TLS
certificates directly inside Runtime Enforcer pods (controller,
agent, and debugger). It does not create intermediate Secret
resources. To install it, run the following commands:
helm install cert-manager-csi-driver jetstack/cert-manager-csi-driver \
--namespace cert-manager \
--wait
Deploy Runtime Enforcer
Follow these simple steps from your local machine to get Runtime Enforcer up and running:
Install the Helm chart
The chart does not deploy an OpenTelemetry collector, and this guide does not need one. Runtime Enforcer records each violation in the status of the policy. To export the violation events and metrics to your own collector, see Export telemetry to an OpenTelemetry collector.
helm repo add kubewarden https://charts.kubewarden.io
helm repo update
helm install runtime-enforcer kubewarden/runtime-enforcer \
--namespace runtime-enforcer \
--create-namespace \
--wait
WorkloadPolicyProposal generation
When Runtime Enforcer starts, it observes newly started processes on the node.
For each Kubernetes workload, it generates a WorkloadPolicyProposal containing
the list of observed executables. Executables that ran before the agent started
won’t be visible in the proposal.
Deploy a simple application
Let’s create a fresh new openSUSE Deployment.
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
name: opensuse-deployment
labels:
app: opensuse-deployment
spec:
replicas: 1
selector:
matchLabels:
app: opensuse-deployment
template:
metadata:
labels:
app: opensuse-deployment
spec:
containers:
- name: opensuse
image: registry.opensuse.org/opensuse/bci/bci-ci:3
# Create a while loop to continually run sleep and ls.
# This helps detect two groups of processes in this test:
# 1. process snapshot (bash)
# 2. process events (sleep and ls).
command: ["bash", "-c", "while true; do sleep 5; ls; done"]
EOF
# wait for the pod to be ready
kubectl wait --for=condition=Ready pod -l app=opensuse-deployment --timeout=300s
Proposal generation
After a few seconds, you should see a new WorkloadPolicyProposal resource
created for the openSUSE deployment.
kubectl get workloadpolicyproposals.runtimeenforcer.kubewarden.io deploy-opensuse-deployment -o yaml
apiVersion: runtimeenforcer.kubewarden.io/v1alpha1
kind: WorkloadPolicyProposal
metadata:
name: deploy-opensuse-deployment
namespace: default
ownerReferences:
- apiVersion: apps/v1
blockOwnerDeletion: true
controller: true
kind: Deployment
name: opensuse-deployment
uid: f5e1a25e-8a80-4c2a-b21a-b70f28a0651c
uid: 6aeac998-d4b6-4e17-9ce1-4d76bc4def61
spec:
rulesByContainer:
opensuse:
executables:
allowed:
- /usr/bin/bash
- /usr/bin/ls
- /usr/bin/sleep
selector:
matchLabels:
app: opensuse
type: deployment
Notes on this proposal:
-
The proposal includes a list of observed executables for the
opensusecontainer. As expected, it captured thebash,lsandsleepcommands. -
As the name suggests, this is only a proposal and not a definitive policy yet, so nothing is enforced at this stage. To enforce it, create a
WorkloadPolicy. -
This proposal is tied to a specific workload. Its name is always in the form of
<workload-type>-<workload-name>. There is also an owner reference to the Deployment so that when the workload is deleted, the proposal can be cleaned up automatically.
WorkloadPolicy (monitor mode)
This proposal looks reasonable for the Deployment, so the next step is
converting it into a definitive policy. To do that, set the
runtimeenforcer.kubewarden.io/promote label of the WorkloadPolicyProposal to monitor.
kubectl label workloadpolicyproposals.runtimeenforcer.kubewarden.io deploy-opensuse-deployment runtimeenforcer.kubewarden.io/promote=monitor
You can also use the kubectl plugin to perform the same step:
kubectl runtime-enforcer proposal promote deploy-opensuse-deployment --mode monitor
After a few seconds, you should see a new Custom Resource called
WorkloadPolicy.
kubectl get workloadpolicy.runtimeenforcer.kubewarden.io deploy-opensuse-deployment -o yaml
apiVersion: runtimeenforcer.kubewarden.io/v1alpha1
kind: WorkloadPolicy
metadata:
labels:
runtimeenforcer.kubewarden.io/promoted-from: deploy-opensuse-deployment
name: deploy-opensuse-deployment
namespace: default
spec:
mode: monitor
rulesByContainer:
opensuse:
executables:
allowed:
- /usr/bin/bash
- /usr/bin/sleep
- /usr/bin/ls
The syntax is similar to the proposal, but there is one important
difference: the spec.mode: monitor field. monitor is a passive mode:
violations of the executable list are reported but not blocked. This means that
if a process other than bash, ls, or sleep is executed, it’s reported as
a violation, but the policy does not block it.
Here the proposal is promoted in monitor mode but you can
promote a proposal directly in protect mode. In that case the enforcement
is applied immediately, blocking any disallowed executables from running.
See the protect mode section for details.
|
Container enforcement is scoped by container name in |
Converting a proposal into a policy isn’t enough to apply it to a workload: the workload needs to be bound to the policy. This is done by adding a label to the workload pods. Since this example uses a Deployment, the correct approach is to add the label to the Deployment’s pod template.
|
You should set the |
kubectl patch deployment opensuse-deployment --type=merge -p '{"spec":{"template":{"metadata":{"labels":{"runtimeenforcer.kubewarden.io/policy":"deploy-opensuse-deployment"}}}}}'
# wait for the new pods to be ready
kubectl wait --for=condition=Ready pod -l runtimeenforcer.kubewarden.io/policy=deploy-opensuse-deployment --timeout=300s
|
This label update causes a deployment rollout. To avoid this, you should put the label on the workload at creation time. |
After the rollout, the policy will be applied. Let’s test it.
Run an allowed command:
kubectl exec -n default deployment/opensuse-deployment -- ls
The policy allows ls, so Runtime Enforcer reports nothing.
Now, run a command that is not in the allowlist:
kubectl exec -n default deployment/opensuse-deployment -- ps
The command runs, because the policy is in monitor mode. Runtime Enforcer
records a violation for it.
Violations are visible directly on the WorkloadPolicy status. The
controller updates the status at each status sync, at intervals of up to
30 seconds. Then you can see the violations with kubectl:
kubectl get workloadpolicy.runtimeenforcer.kubewarden.io deploy-opensuse-deployment -o yaml
In the output, look for the Violations section under Status:
status:
activeViolationCount: 1
violationCount: 1
violations:
- action: monitor
containerName: opensuse
executablePath: /usr/bin/ps
id: 0
nodeName: kind-control-plane
podName: opensuse-deployment-f69df6b94-7s7f4
timestamp: "2026-01-14T10:39:01Z"
workloadKind: Deployment
workloadName: opensuse-deployment
-
violationCountis the total number of violations that have occurred for this policy; it is a historical count. -
activeViolationCountis the number of currently active violations for this policy.
At this point, both are 1 because a single violation has been recorded.
|
The controller scrapes violation records from agents via gRPC during its
periodic status sync and stores the most recent 100 entries in the
WorkloadPolicy status. No external observability stack is required to view
violations. If you turn on the
telemetry export, the agent also sends a
|
Add a binary to the allowed list
Now suppose ps is an allowed binary and you want to add it to the allowed
list and clear the violation. You can use the kubectl plugin to add the binary,
and the violations should be updated automatically by Runtime Enforcer.
kubectl runtime-enforcer policy allow deploy-opensuse-deployment opensuse /usr/bin/ps
Looking at the resource again shows that the violation has been cleared:
kubectl get workloadpolicy.runtimeenforcer.kubewarden.io deploy-opensuse-deployment -o yaml
apiVersion: runtimeenforcer.kubewarden.io/v1alpha1
kind: WorkloadPolicy
metadata:
labels:
runtimeenforcer.kubewarden.io/promoted-from: deploy-opensuse-deployment
name: deploy-opensuse-deployment
namespace: default
spec:
mode: monitor
rulesByContainer:
opensuse:
executables:
allowed:
- /usr/bin/bash
- /usr/bin/sleep
- /usr/bin/ls
- /usr/bin/ps
status:
activeViolationCount: 0
violationCount: 1
-
/usr/bin/psis now part of the allowed list -
violationCountis still 1 since it is a historical count -
activeViolationCountis now 0 since the violation has been cleared.
WorkloadPolicy (protect mode)
Once confident in the policy and wanting to enforce it, change the mode to
protect. From now on, every violation of the executable list is blocked.
kubectl patch workloadpolicy deploy-opensuse-deployment -n default --type='json' -p='[{"op": "replace", "path": "/spec/mode", "value": "protect"}]'
You can also use the kubectl plugin to perform the same step:
kubectl runtime-enforcer policy protect deploy-opensuse-deployment -n default
Now run an allowed binary again; nothing should be reported.
kubectl exec -n default deployment/opensuse-deployment -- ls
This time, if you run a command that the policy does not allow, Runtime Enforcer reports the violation and also blocks the process.
kubectl exec -n default deployment/opensuse-deployment -- cat /etc/os-release
The terminal tells us the process is blocked with EPERM.
exec /usr/bin/cat: operation not permitted
command terminated with exit code 255
The status of the policy shows the new violation:
status:
activeViolationCount: 1
violationCount: 2
violations:
- action: protect
containerName: opensuse
executablePath: /usr/bin/cat
id: 1
nodeName: kind-control-plane
podName: opensuse-deployment-f69df6b94-7s7f4
timestamp: "2026-01-14T10:49:11Z"
workloadKind: Deployment
workloadName: opensuse-deployment
Acknowledge a violation
Assume the cat violation was due to a debugging session and now it needs to be marked as resolved. You can add an acknowledgment for this violation; the most
intuitive way is to use the kubectl plugin.
kubectl runtime-enforcer policy ack deploy-opensuse-deployment 1 --reason "inspect OS release during debugging"
The reason of the acknowledgment can be provided through the --reason flag.
The status should change as follows:
status:
acknowledgedViolations:
- acknowledgedAt: "2026-01-14T10:50:03Z"
reason: inspect OS release during debugging
violation:
action: protect
containerName: opensuse
executablePath: /usr/bin/cat
id: 1
nodeName: kind-control-plane
podName: opensuse-deployment-f69df6b94-7s7f4
timestamp: "2026-01-14T10:49:11Z"
workloadKind: Deployment
workloadName: opensuse-deployment
activeViolationCount: 0
violationCount: 2
The active violation is no longer listed. Instead, it appears under
acknowledgedViolations.
Advanced Configuration
Export telemetry
Runtime Enforcer can send the violation events and one metric to an
OpenTelemetry collector that you deploy. The export is off by default. To turn
it on, set the global.otel.endpoint Helm value to the address of your
collector:
helm upgrade runtime-enforcer kubewarden/runtime-enforcer \
--namespace runtime-enforcer \
--set global.otel.endpoint=https://otel-collector.otel-collector.svc.cluster.local:4317
See Export telemetry to an OpenTelemetry collector for the TLS values and for a collector configuration.