Identity allocation

Active contributors: aanm, christarazi, gandro, joestringer

Purpose

Cilium does not enforce policy on IPs — it enforces it on security identities. Every workload (a pod, a node, a remote node, a reserved entity like world or host) is mapped to a 24-bit numeric identity derived from its label set. The dataplane uses these identities to look up policy maps and ipcache entries on every packet.

Identities must be:

• Stable — the same label set always yields the same identity.
• Cluster-wide unique — every node sees the same identity for the same labels, so policy decisions are consistent.
• Compact — stored efficiently in BPF maps that are read on every packet.

Directory layout

pkg/identity/
├── identity.go             # the Identity type
├── numericidentity.go      # the 24-bit ID type and reserved values
├── reserved.go             # well-known identities (world, host, init, ...)
├── cache/                  # local caches + remote lookups
├── identitymanager/        # tracks identities currently used by local endpoints
├── basicallocator/         # CRD-only allocator (default in modern installs)
├── api/                    # REST handlers
├── key/                    # key encoding for kvstore allocator
├── model/                  # api/v1 models bridge
└── doc.go

pkg/allocator/              # generic allocator interface (CRD or kvstore-backed)
pkg/k8s/apis/cilium.io/v2/  # CiliumIdentity CRD
operator/identitygc/        # identity garbage collection cell

Key abstractions

Type	File	Role
NumericIdentity	pkg/identity/numericidentity.go	A 24-bit unsigned integer used everywhere as the identity key.
Identity	pkg/identity/identity.go	Numeric identity plus the labels that produced it.
IdentityCache	pkg/identity/cache/	The agent's local cache of all known identities; receives notifications when identities are added/removed.
IdentityManager	pkg/identity/identitymanager/	Tracks which identities are referenced by local endpoints; used by metrics and policy invalidation.
Allocator	pkg/allocator/	Generic interface — implemented by the CRD allocator and (legacy) kvstore allocator.
CRD allocator	pkg/identity/cache/local_cache.go (and helpers)	Allocates identities by creating CiliumIdentity CRDs with deterministic label hashes.

Reserved identities

A small set of identities are well-known and never allocated dynamically. Defined in pkg/identity/reserved.go:

Name	ID	Meaning
host	1	Local host (the node).
world	2	Anything outside the cluster.
unmanaged	3	Pod not yet managed by Cilium.
health	4	Cilium health endpoint.
init	5	Init phase of pod creation.
remote-node	6	A remote node in the cluster.
kube-apiserver	7	The K8s API server identity.
ingress	8	Cilium ingress traffic.
world-ipv4 / world-ipv6	9, 10	Family-specific world identities.

The CIDR identity range starts at a higher offset so that label-derived identities don't clash with reserved ones.

How the CRD allocator works

sequenceDiagram
    participant Pod
    participant Agent as cilium-agent
    participant Cache as identity cache
    participant CRD as CiliumIdentity CRD
    participant API as kube-apiserver

    Pod->>Agent: pod created with labels L
    Agent->>Cache: lookup(label_hash(L))
    alt cache miss
        Agent->>API: list CiliumIdentity by label hash
        alt no existing
            Agent->>API: create CiliumIdentity with computed ID
            API-->>Agent: created
        else found
            Agent->>API: get existing
        end
    end
    Cache-->>Agent: NumericIdentity
    Agent->>Agent: program ipcache + policy maps

Each CiliumIdentity CRD has:

• A name equal to the numeric identity (e.g., 12345).
• A securityLabels map carrying the canonical label set.
• Owner references to the namespaces consuming it.

The operator (operator/identitygc/) periodically scans for identities not referenced by any live endpoint and removes them.

How identity is propagated to remote nodes

Every agent watches CiliumIdentity and CiliumEndpoint. When a new identity appears on any node, all nodes see it via the same watch and update their local ipcache (pkg/ipcache/) and policy maps. With Cluster Mesh, the same flow extends across clusters via the kvstore-backed export of identities.

Integration points

• ipcache: maps every IP in the cluster to its identity (pkg/ipcache/).
• Policy: policy verdicts are expressed identity-to-identity.
• Hubble: every flow event is annotated with source/destination identity labels.
• Cluster Mesh: identities from peer clusters are merged via pkg/clustermesh/.
• Mutual auth: pkg/auth/ derives SPIFFE IDs from identity labels.

Entry points for modification

• Adding a reserved identity: edit pkg/identity/reserved.go, plus the BPF macros in bpf/include/bpf/. Bumping reserved IDs is a sensitive cross-version change.
• Changing identity allocation strategy: extend pkg/allocator/. The legacy kvstore mode lives behind feature flags.
• Identity GC tuning: operator/identitygc/.

Key source files

File	Purpose
pkg/identity/numericidentity.go	24-bit ID type + utilities.
pkg/identity/identity.go	Identity struct.
pkg/identity/reserved.go	Reserved IDs.
pkg/identity/cache/local_cache.go	Local cache + CRD allocator glue.
pkg/allocator/	Generic allocator interface.
operator/identitygc/	GC cell.
pkg/k8s/apis/cilium.io/v2/types_identity.go	CRD type.

See features/identity-and-security.md for the user-facing model.