Glossary

A violation that you mark as accepted, with a reason. You add the annotation runtimeenforcer.kubewarden.io/acknowledge-<id> to the WorkloadPolicy, with the reason as the value. The <id> is the id of the violation record. The controller moves the record to status.acknowledgedViolations, keeps the reason, and removes the annotation. The kubectl plugin command policy ack sets the annotation for you.

A violation record that is still in status.violations. It is not acknowledged, and its executable is not in the allow-list. The field status.activeViolationCount holds the number of active violations. This is the number that needs a decision.

The component that runs on each node, as a DaemonSet. It loads the eBPF programs, learns the executables that containers run, and enforces the WorkloadPolicy that each pod is bound to. It is also an NRI plugin, so it sees each container before the first process starts. It serves gRPC to the controller and the debugger.

The list of executables that a container can run. It is the field spec.rulesByContainer[<container>].executables.allowed of a WorkloadPolicyProposal or a WorkloadPolicy. Each entry is an absolute executable path. A process that is not in the allow-list is a violation.

The link between a pod and its WorkloadPolicy. You set the policy label on the pod, in the pod template of the workload. The label must be present when the pod is created. A Validating Admission Policy rejects changes to the label on a running pod.

BPF Type Format. Kernel type information that the eBPF programs of the agent need. The kernel must have CONFIG_DEBUG_INFO_BTF=y.

A prerequisite. Together with the cert-manager CSI driver, it issues and mounts TLS certificates. The agent, the controller, and the OpenTelemetry collector use these certificates to talk to each other.

The container runtimes that Runtime Enforcer supports. Both must have NRI enabled. The cri-dockerd runtime is not supported.

The component that owns the policy resources. It runs as a Deployment. It handles promotion. It serves the admission webhooks, one of which completes the owner reference of each new WorkloadPolicyProposal. It reads the violation records from each agent over gRPC and writes them to the WorkloadPolicy status on each status sync.

An optional Deployment. It compares the pods and containers that each agent knows about with the pods in the Kubernetes API. Use it when a WorkloadPolicy does not apply to a pod that you expect it to. It is off by default.

Extended Berkeley Packet Filter. A way to run small programs inside the Linux kernel. The agent loads an eBPF program that runs before each process starts in a container. The program checks the executable path against the allow-list. In protect mode, it refuses the start.

The absolute path of the file that a process runs, for example /usr/bin/curl. The agent records this path during learning and compares it with the allow-list during enforcement. When a container runs a script, the agent records the path of the script. It does not record the interpreter. The allow-list matches paths only. It does not match arguments, hashes, or patterns.

The behavior when a pod carries a policy label that names a WorkloadPolicy that does not exist. By default, the agent does not start the container. This is the safe default. If you set the Helm value agent.nriFailopen=true, the container starts without protection.

The protocol between the agent on each node and the controller or the debugger. The controller uses it to read the violation records that the agent holds.

The kubectl runtime-enforcer command. It sets the labels and annotations that drive promotion, mode changes, changes to the allow-list, and acknowledgement. The policy show protection subcommand lists each workload with its policy, mode, and status. You can do each task without the plugin, with kubectl label, kubectl annotate, or kubectl edit.

The first phase. The agent observes the executables that each container runs and writes them to a WorkloadPolicyProposal. Nothing is blocked. Learning starts when the agent starts. It stops for a workload when you promote its proposal. A proposal holds at most 100 executables.

The Helm value learning.namespaceSelector. It limits the learn phase to the namespaces that match a label selector. The default selects all namespaces. The value {} turns learning off.

The field spec.mode of a WorkloadPolicy. The values are monitor and protect. You change the mode with kubectl edit or with the kubectl plugin. A mode change applies to running pods without a restart.

A phase and a mode. The agent reports each executable that is not in the allow-list as a violation. It does not block the executable. A promoted proposal starts in this mode.

The code field of each entry in status.nodesWithIssues of a WorkloadPolicy. The values are Ready, Missing, Failed, and Transitioning. The map holds at most 20 nodes.

Node Resource Interface. An interface of the container runtime that lets a plugin act when a container is created or started. The agent is an NRI plugin. Through NRI, it learns the cgroup of each container and attaches the WorkloadPolicy before the first process starts. NRI must be enabled in containerd or CRI-O.

The service that receives the violation events from the agent. The Helm chart can deploy one for you, or you can point the agent at your own. The agent emits a policy_violation event for each violation and a policy_violation_acknowledged event for each acknowledgement. The bundled collector exports a Prometheus counter of violations. The controller exports a gauge of active violations.

One of the three stages of the Runtime Enforcer workflow: learn, monitor, and protect. Monitor and protect are also the two values of the mode field. Learn has no mode. In the learn phase, the workload has a WorkloadPolicyProposal and no WorkloadPolicy. Do not confuse the phase with the status phase.

The label runtimeenforcer.kubewarden.io/policy on a pod. Its value is the name of a WorkloadPolicy in the same namespace. It creates the binding between the pod and the policy. A pod without this label is not enforced.

The label runtimeenforcer.kubewarden.io/promote on a WorkloadPolicyProposal. The value is monitor or protect. It starts the promotion. If you remove the label before the controller acts, learning continues.

The label runtimeenforcer.kubewarden.io/promoted-from on a WorkloadPolicy. Its value is the name of the WorkloadPolicyProposal that the policy came from. The controller sets it. The controller uses it to know that the workload has a policy, so that it does not create a new proposal.

The step from a WorkloadPolicyProposal to a WorkloadPolicy. You set the promote label on the proposal, or you run kubectl runtime-enforcer proposal promote. The controller creates the policy with the same allow-list, sets the promoted-from label, and deletes the proposal. The policy starts in monitor mode unless you ask for protect.

A phase and a mode. The eBPF program refuses to start each executable that is not in the allow-list. The process gets the error EPERM, "operation not permitted". The agent also records a violation.

The pod annotation required-plugins.noderesource.dev. Its value is a list of NRI plugin names, for example '["runtime-enforcer-agent"]'. The container runtime refuses to start the pod when a named plugin is not present. Use it to make sure that no pod starts without the agent. It needs containerd 2.2 or later, or CRI-O 1.34 or later.

The field status.phase of a WorkloadPolicy. It has three values. Ready means that all the targeted nodes enforce the policy. Failed means that at least one node has a problem. Transitioning means that some nodes are still changing mode. See node issue code for the detail per node. This is not the same as the workflow phase.

The period at which the controller reads the violation records from each agent and writes them to the WorkloadPolicy status. The default is 30 seconds. A violation can take up to 30 seconds to appear in kubectl. The OpenTelemetry events arrive at once.

A Kubernetes admission rule written in CEL. Runtime Enforcer installs one that makes the policy label immutable on a running pod. This needs Kubernetes 1.31 or later.

The start of a process whose executable path is not in the allow-list of its container. In monitor mode the process runs. In protect mode it does not. In both modes the agent emits an event to the OpenTelemetry collector and keeps a violation record.

One entry in status.violations or status.acknowledgedViolations of a WorkloadPolicy. It holds the id, the pod, the container, the executable path, the node, and the mode. It also holds the workload, the first and last time seen, and the number of occurrences. Each list holds the 100 most recent records. The field status.violationCount counts all the records that the policy ever had. This count includes the trimmed records.

A Deployment, StatefulSet, DaemonSet, Job, or CronJob. The learn phase creates one WorkloadPolicyProposal per workload. A standalone Pod or a ReplicaSet is not a workload for learning. You can still bind such a pod to a WorkloadPolicy that you write by hand.

The resource that holds the enforced allow-list of a workload, per container, and its mode. Namespaced. The controller creates it on promotion. You can also write one by hand. Pods bind to it with the policy label. Its status holds the status phase, the violation records, and the node issue codes. You cannot delete it while a pod refers to it. It has no cluster-specific state, so you can store it in Git and apply it to other clusters.

The resource that holds the allow-list learned for one workload, per container. Namespaced. The agent creates and updates it during the learn phase. Its name is the kind and the name of the workload, for example deploy-nginx. It is owned by the workload, so Kubernetes deletes it with the workload. Nothing is enforced while a workload has only a proposal. Promotion replaces it with a WorkloadPolicy.