Configuration

Layered model

graph LR
    Helm[Helm values<br/>install/kubernetes/cilium/values.yaml]
    CM[ConfigMap<br/>cilium-config]
    Flags[CLI flags]
    Cell[Cell config structs]

    Helm -->|render| CM
    CM -->|--config-dir| Flags
    Flags --> Cell

1. Helm values are the user-facing API. Defaults live in install/kubernetes/cilium/values.yaml.
2. The chart renders them into the cilium-config ConfigMap (and a small cilium-envoy-config for the Envoy side).
3. The agent reads the ConfigMap as CLI flags via --config-dir=/tmp/cilium/config-map.
4. Each flag binds to either the legacy global option.DaemonConfig or to a per-cell typed struct registered through cell.Config.

The same chain applies to the operator (cilium-config is shared) and to other binaries (each may read cilium-config plus its own ConfigMap).

Where each layer is defined

Layer	File / package
Helm values	install/kubernetes/cilium/values.yaml
Helm templates	install/kubernetes/cilium/templates/
Generated docs	Documentation/helm-values.rst
Daemon flags	daemon/cmd/daemon_main.go, plus per-cell Flags methods
Global config	pkg/option/config.go
Per-cell config	pkg/<feature>/config.go (look for cell.Config(...))
Operator flags	operator/cmd/, operator/option/

Categories of options

Category	Examples
Networking / routing	routingMode, tunnelProtocol, ipv4.enabled, ipv6.enabled, ipam.mode
Datapath	bpf.masquerade, bpf.preallocateMaps, bpf.policyMapMax, kubeProxyReplacement
Encryption	encryption.enabled, encryption.type (wireguard / ipsec), nodeEncryption
Policy	policyEnforcementMode, policyAuditMode, enableHostFirewall
Identity	identityAllocationMode (crd / kvstore), identityChangeGracePeriod
Hubble	hubble.enabled, hubble.relay.enabled, hubble.metrics.enabled
Cluster Mesh	clustermesh.useAPIServer, clustermesh.config.*
Cloud IPAM	aws.*, azure.*, alibabacloud.*
Operator	operator.replicas, operator.rollOutPods
Envoy / mesh	envoy.enabled, envoy.image, gatewayAPI.enabled, ingressController.enabled
BGP	bgpControlPlane.enabled, bgpControlPlane.bgpv2.enabled
LB-IPAM	lbIPAM.enabled
Auth	authentication.mode, authentication.mutual.spire.*
Debug	debug.enabled, debug.verbose, pprof.enabled

For the canonical option list, see Documentation/helm-values.rst (auto-generated, ~213 KB).

Runtime config (no restart)

Some agent options are reloadable without restart through pkg/dynamicconfig/ and the REST API:

kubectl -n kube-system exec ds/cilium -- cilium config <option>=<value>

Not every option is hot-reloadable; consult pkg/dynamicconfig/ for the supported list.

Conventions for new options

• Add a Helm value with a sensible default and a comment explaining the semantics.
• Render it into the ConfigMap from install/kubernetes/cilium/templates/.
• Add a flag in the relevant cell's Flags method (or in daemon/cmd/daemon_main.go for cross-cutting options).
• Update Documentation/helm-values.rst (re-generated by make -C Documentation update-cmdref).
• Add a unit test that confirms the new option's effect when toggled.
• For "expert mode" options, use a bpf- or enable- prefix consistent with similar options.

Validation

Documentation/check-helmvalues.sh and Documentation/check-cmdref.sh are run in CI to ensure that:

• Every flag has a Helm value.
• Every Helm value documented in helm-values.rst matches the chart.
• The cmdref documentation reflects the actual cobra commands.

If any of these checks fail, the corresponding make -C Documentation update-*.sh script regenerates the docs.

Key source files

File	Purpose
install/kubernetes/cilium/values.yaml	Helm values.
pkg/option/config.go	Global DaemonConfig.
daemon/cmd/daemon_main.go	Flag definitions.
pkg/dynamicconfig/	Reloadable options.
Documentation/helm-values.rst	Generated reference.