Kubernetes CNI Plugin Behavior

Kubernetes CNI Plugin Behavior refers to the concrete sequence of operations a CNI plugin executes when invoked by the kubelet's container runtime shim, and the contractual guarantees it must uphold under the Container Network Interface specification. It describes how a plugin responds to ADD, DEL, and CHECK operations, how it communicates results back to the caller, and how it interacts with the pod's network namespace at each stage of the pod lifecycle.

The CNI Operation Contract

ADD Operation

When a pod sandbox is created, the container runtime invokes the configured CNI plugin with the ADD command, passing the pod's network namespace path, a container ID, and the plugin's JSON configuration through environment variables and standard input. The plugin is expected to create or attach a network interface inside that namespace, assign it an IP address, configure routes, and return a structured JSON result describing the interfaces, IP configuration, and DNS settings it applied.

DEL Operation

When a pod is torn down, the runtime invokes the plugin with the DEL command using the same container ID and namespace reference used during ADD. The plugin must release any IP address it allocated back to its IPAM pool and remove the interfaces and routes it created. CNI plugin behavior specifies that DEL must be idempotent and must not fail simply because some or all of the resources it is asked to clean up are already absent, since retries can occur under partial-failure conditions.

CHECK Operation

The CHECK command allows the runtime to verify that a previously configured network attachment is still in the expected state, without modifying it. Not all plugins implement CHECK, and its absence is treated as an accepted no-op rather than a failure by CNI-compliant runtimes.

Plugin Invocation Data Flow

Configuration Passing

The plugin receives its configuration as JSON on standard input, while operation-specific parameters, such as the container ID, network namespace path, and interface name, are passed as environment variables (CNI_COMMAND, CNI_CONTAINERID, CNI_NETNS, CNI_IFNAME). This strict separation between static configuration and per-invocation parameters is what allows the same configuration file to be reused across every pod placement on a node.

Result Reporting

A successful ADD invocation must produce a CNI result object on standard output describing the interface name, its assigned IP addresses and routes, and optionally DNS configuration. The kubelet's runtime layer stores this result and surfaces the pod's IP address through the Kubernetes API so that it becomes visible in the pod's status.

Chained Plugin Behavior

Sequential Execution

When multiple plugins are chained in a single configuration list, each plugin is invoked in order for ADD, receiving the previous plugin's result as part of its input alongside its own configuration snippet. This allows a later plugin in the chain to modify, augment, or apply policy on top of an interface a prior plugin already created, rather than creating its own interface from scratch.

Reverse-Order Teardown

For DEL, plugins in a chain are generally expected to be invoked in reverse order relative to ADD, ensuring that the last modification applied is the first one undone, mirroring standard stack-based cleanup semantics.

Error Handling Behavior

Non-Zero Exit and Structured Errors

A CNI plugin communicates failure by exiting with a non-zero status code and writing a structured JSON error object to standard output containing an error code and message. The invoking runtime is expected to treat this as a hard failure of the corresponding pod sandbox operation, typically causing the kubelet to retry pod creation from the beginning rather than attempting to resume a partially configured network state.

Partial Failure and Retry Semantics

Because ADD operations can fail partway through, after some but not all resources have been created, a well-behaved plugin's DEL implementation must be resilient enough to clean up whatever partial state may exist, which is why idempotency in DEL is treated as a strict requirement of correct plugin behavior rather than a best practice.

Version Negotiation

CNI Specification Versioning

Plugins declare which versions of the CNI specification they support, and the invoking runtime selects a mutually supported version to use for a given call. Mismatched version expectations between the runtime and a plugin, or between chained plugins, produce a negotiation failure surfaced as a pod sandbox creation error, which is one of the most common root causes investigated when diagnosing CNI-related pod failures.