pkg/identity

Active contributors: aanm, christarazi, gandro, joestringer

Purpose

pkg/identity/ defines the Identity and NumericIdentity types and the per-agent identity cache. It is one of the most central packages — every endpoint, every flow, every policy decision in Cilium is keyed by an identity from here.

For the architectural narrative see systems/identity-allocation.md. This page documents the package itself.

Layout

pkg/identity/
├── identity.go             # Identity struct
├── numericidentity.go      # NumericIdentity type + reserved IDs
├── reserved.go             # well-known identities
├── cache/                  # local cache + allocator integration
├── identitymanager/        # tracks identities used by local endpoints
├── basicallocator/         # CRD-only allocator (preferred)
├── api/                    # REST handlers for `cilium identity`
├── key/                    # encoding key for kvstore allocator
├── model/                  # api/v1 models bridge
├── cell/                   # Hive cell wiring
└── doc.go

Key abstractions

Type	File	Role
NumericIdentity	pkg/identity/numericidentity.go	A 24-bit unsigned integer; the BPF map key.
Identity	pkg/identity/identity.go	Numeric ID + canonical label set.
IdentityCache	pkg/identity/cache/cache.go	The agent's view of all known identities (local + remote).
LocalCache	pkg/identity/cache/local_cache.go	The portion the agent allocates locally for endpoints on this node.
IdentityAllocator	pkg/identity/cache/allocator.go	Allocator interface; backed by CRD by default.
IdentityManager	pkg/identity/identitymanager/	Reference-counts identities used by local endpoints; emits Prometheus metrics.

Allocation modes

Cilium supports two allocator backends, selected by the identityAllocationMode Helm value:

• crd (default) — the agent allocates by creating CiliumIdentity CRD objects. Names of identities are deterministic hashes; collisions are detected and resolved.
• kvstore (legacy) — uses pkg/kvstore/allocator/ against an etcd. This is still required for some Cluster Mesh edge cases.

Both produce the same Identity view from a consumer's perspective.

Cluster Mesh interaction

Cluster Mesh injects identities from peer clusters into each agent's cache via pkg/clustermesh/. The local cache merges them so policy resolution and ipcache lookups treat them identically to local identities.

Notifications

Consumers (pkg/policy/selectorcache.go, pkg/ipcache/) register for "identity added/removed" notifications. The cache batches and dedups updates so that policy compilation is not triggered on every individual identity churn.

Integration points

• Endpoints: every endpoint allocates one identity.
• Policy: selector cache subscribes to identity events.
• IP cache: pkg/ipcache/ writes one entry per (ip, identity) pair.
• Hubble: every flow event carries the source/destination identity labels.

Entry points for modification

• Reserved identities: pkg/identity/reserved.go plus the BPF macros in bpf/include/bpf/.
• New identity attributes: extend Identity and propagate through the cache and CRD type.
• New allocator backend: implement the IdentityAllocator interface.

Key source files

File	Purpose
pkg/identity/identity.go	Identity struct.
pkg/identity/numericidentity.go	NumericIdentity.
pkg/identity/reserved.go	Reserved IDs.
pkg/identity/cache/cache.go	Identity cache.
pkg/identity/cache/local_cache.go	Local allocation.
pkg/identity/identitymanager/manager.go	Identity manager.
pkg/k8s/apis/cilium.io/v2/types_identity.go	CRD type.
operator/identitygc/	Cluster-wide GC.