config

Documentation

Overview

Package config provides CNI plugin configuration parsing and data structures.

The CNI plugin configuration is provided as JSON via stdin during plugin invocation. It includes the standard CNI PluginConf fields plus Aether-specific fields for agent communication and container runtime integration.

Index

• type AetherConf
  • func NewConf(stdinData []byte) (AetherConf, error)
  • func (c AetherConf) NetnsPinPath(containerID string) string
  • func (c AetherConf) NetnsUnpinDelay() time.Duration
• type K8sArgs
• type RuntimeConfig

Types

type AetherConf

type AetherConf struct {
	types.PluginConf
	// AgentCNIPath is the path to the Aether agent's CNI gRPC socket
	AgentCNIPath string `json:"agent_cni_path"`
	// CRISocket is the path to the container runtime interface socket
	CRISocket string `json:"cri_socket"`

	// NetnsPinDisabled turns off netns pinning (on by default): Envoy dials
	// local pods inside their netns by filepath, and a dial racing the
	// runtime's netns removal segfaults Envoy (upstream bug; e2e findings
	// 2026-06-10). CNI ADD bind-mounts the netns to an aether-owned path that
	// stays valid until the agent has confirmed the pod's xDS resources are
	// gone, so late dials fail gracefully instead of crashing the proxy.
	NetnsPinDisabled bool `json:"netns_pin_disabled"`
	// NetnsPinDir is where CNI ADD bind-mounts each pod's netns. Must be a
	// host path visible to the aether-proxy container (which mounts /run/aether
	// with HostToContainer propagation). Empty = /run/aether/netns.
	NetnsPinDir string `json:"netns_pin_dir"`
	// NetnsUnpinDelaySeconds is how long CNI DEL waits after the agent has
	// deregistered the pod (and Envoy acked the listener removal) before
	// unpinning the netns, covering Envoy's deferred cluster destruction and
	// connection-pool drains that can still dial for a few seconds.
	// 0 = 10s default; negative = no delay.
	NetnsUnpinDelaySeconds int `json:"netns_unpin_delay_seconds"`

	// ReadinessProbeDisabled turns off the in-netns data-plane readiness probe
	// (on by default): after the agent confirms a pod's xDS config, CNI ADD
	// probes the pod's outbound capture listener from inside its netns until
	// the proxy's health_check filter answers 200, proving the data plane is
	// actually serving (socket bound in the netns, workers accepting) before
	// pod start completes. CNI DEL probes until the listener socket is gone.
	// Best-effort: a probe timeout is logged, never fails the CNI operation.
	ReadinessProbeDisabled bool `json:"readiness_probe_disabled"`

	// CaptureRedirectAllDefault makes redirect-all the DEFAULT for managed pods
	// (proposal 022, M2-default Step 4 — the "flip"). When true, every non-ignored
	// pod on the node gets the broad redirect-all capture (ALL outbound non-local
	// TCP into the capture listener :18001; Envoy's ORIGINAL_DST recovers the real
	// destination and non-mesh egress passes through in plain TCP) UNLESS it
	// carries the capture.aether.io/redirect-all="false" opt-out annotation. This
	// is the Istio-style "capture what the app sends" posture, with zero per-pod
	// config. When false, redirect-all is per-pod opt-in via the same annotation.
	//
	// The scoped mesh-ClusterIP:18081 capture redirect (proposal 018, Phase 3a)
	// is UNCONDITIONAL (proposal 031) — the Envoy side always carries the capture
	// listener and the passthrough fallback chain, so this is the single
	// remaining node-wide capture knob.
	//
	// Redirect-all exclusions installed to prevent loops and proxy self-traffic:
	//   - loopback (127.0.0.0/8) skipped — the :18081 fast-lane is untouched
	//   - the capture port itself (:18001 TCP) skipped — prevents re-entry
	//   - established/related connections skipped via conntrack (RELATED,ESTABLISHED)
	//   - DNS (:53 UDP+TCP) NOT excluded — passes through Envoy if MeshDNSEnabled=false,
	//     or remains DNAT'd to the mesh-DNS resolver if MeshDNSEnabled=true
	CaptureRedirectAllDefault bool `json:"capture_redirect_all_default"`

	// MeshDNSEnabled installs, inside each pod's netns, an nft DNAT of outbound DNS
	// (UDP+TCP :53, non-loopback) -> the node agent's resolver at HostIP:18054
	// (proposal 018, mesh-global FQDN). Off by default; pairs with the agent's
	// --mesh-dns.
	MeshDNSEnabled bool `json:"mesh_dns_enabled"`
	// HostIP is the node IP the mesh-DNS DNAT targets (the agent's host-local
	// resolver). Written by cni-install from the downward-API HOST_IP.
	HostIP string `json:"host_ip,omitempty"`

	// OTLPEndpoint enables OTel telemetry (traces + metrics) pushed to the
	// given OTLP gRPC collector (host:port, insecure). The plugin binary is
	// exec'd by the container runtime, so its environment is the runtime's,
	// not a pod's — the endpoint travels in the netconf (written by
	// cni-install) instead. Empty = the standard OTEL_EXPORTER_OTLP_* env
	// vars, if the runtime happens to set them; otherwise telemetry is off.
	OTLPEndpoint string `json:"otlp_endpoint,omitempty"`

	// RuntimeConfig holds runtime-provided configuration like pod annotations
	RuntimeConfig *RuntimeConfig `json:"runtimeConfig,omitempty"`
}

AetherConf represents the CNI plugin configuration for Aether.

It extends the standard CNI PluginConf with Aether-specific fields:

• AgentCNIPath: Path to the Unix domain socket where the Aether agent listens for pod add/remove requests. If omitted, defaults to the default socket path defined in constants.
• CRISocket: Path to the container runtime interface (CRI) socket for retrieving container process information via CRI APIs when PID cannot be determined from the network namespace path.
• RuntimeConfig: Optional runtime configuration passed by the container runtime, including pod annotations.

func NewConf

func NewConf(stdinData []byte) (AetherConf, error)

NewConf parses CNI configuration from JSON-formatted stdin data. It unmarshals the data into AetherConf, sets the agent CNI path default if not provided, and parses the previous plugin result using the standard CNI version negotiation. Returns an error if the JSON is invalid or the previous result cannot be parsed.

func (AetherConf) NetnsPinPath

func (c AetherConf) NetnsPinPath(containerID string) string

NetnsPinPath returns the pin target for a container (sandbox) ID.

func (AetherConf) NetnsUnpinDelay

func (c AetherConf) NetnsUnpinDelay() time.Duration

NetnsUnpinDelay returns the effective unpin delay.

type K8sArgs

type K8sArgs struct {
	types.CommonArgs

	// K8S_POD_NAME is the pod's name in Kubernetes
	K8S_POD_NAME types.UnmarshallableString // nolint: revive, stylecheck
	// K8S_POD_NAMESPACE is the pod's namespace in Kubernetes
	K8S_POD_NAMESPACE types.UnmarshallableString // nolint: revive, stylecheck
	// K8S_POD_INFRA_CONTAINER_ID is the pod's sandbox (infrastructure) container ID
	K8S_POD_INFRA_CONTAINER_ID types.UnmarshallableString // nolint: revive, stylecheck
	// K8S_POD_UID is the pod's unique identifier in Kubernetes
	K8S_POD_UID types.UnmarshallableString // nolint: revive, stylecheck
}

K8sArgs represents Kubernetes-specific CNI arguments passed via the CNI_ARGS environment variable. The field names must exactly match the keys in containerd's args for proper unmarshalling. See https://github.com/containerd/containerd/blob/main/pkg/cri/server/sandbox_run.go

type RuntimeConfig

type RuntimeConfig struct {
	// PodAnnotations contains Kubernetes pod annotations
	PodAnnotations *map[string]string `json:"io.kubernetes.cri.pod-annotations,omitempty"`
}

RuntimeConfig holds container runtime-provided configuration passed to the CNI plugin.