Cilium CRDs

Active contributors: aanm, christarazi, sayboras, mhofstetter, gandro

CRD groups

Cilium owns the cilium.io API group. CRD types live under pkg/k8s/apis/cilium.io/:

• v2/ — GA CRDs.
• v2alpha1/ — alpha CRDs that may evolve.

A live catalog lives in Documentation/crdlist.rst. The rendered YAML manifests (used by Helm) sit under pkg/k8s/apis/cilium.io/client/crds/.

GA (v2) resource catalogue

Kind	Purpose	Source file
CiliumNetworkPolicy (CNP)	Namespaced policy.	pkg/k8s/apis/cilium.io/v2/cnp_types.go
CiliumClusterwideNetworkPolicy (CCNP)	Cluster-scoped policy.	pkg/k8s/apis/cilium.io/v2/ccnp_types.go
CiliumIdentity	Identity allocation record.	pkg/k8s/apis/cilium.io/v2/types_identity.go
CiliumEndpoint (CEP)	Per-pod endpoint state (informational).	pkg/k8s/apis/cilium.io/v2/types_endpoint.go
CiliumNode	Per-node IPAM and config.	pkg/k8s/apis/cilium.io/v2/types_node.go
CiliumExternalWorkload	External (non-K8s) workload.	pkg/k8s/apis/cilium.io/v2/types_external_workload.go
CiliumLocalRedirectPolicy	Local redirect (LRP).	pkg/k8s/apis/cilium.io/v2/types_lrp.go
CiliumEnvoyConfig (CEC)	Per-namespace Envoy config.	pkg/k8s/apis/cilium.io/v2/types_envoy_config.go
CiliumClusterwideEnvoyConfig (CCEC)	Cluster-wide Envoy config.	pkg/k8s/apis/cilium.io/v2/types_clusterwide_envoy_config.go
CiliumCIDRGroup	Reusable CIDR sets.	pkg/k8s/apis/cilium.io/v2/types_cidr_group.go
CiliumLoadBalancerIPPool	LB-IPAM allocation pool.	pkg/k8s/apis/cilium.io/v2/types_lb_ip_pool.go
CiliumBGPClusterConfig	BGP cluster-wide config.	pkg/k8s/apis/cilium.io/v2/types_bgp_cluster.go
CiliumBGPPeerConfig	BGP peer reusable config.	pkg/k8s/apis/cilium.io/v2/types_bgp_peer.go
CiliumBGPNodeConfig	Per-node BGP config (operator-derived).	pkg/k8s/apis/cilium.io/v2/types_bgp_node.go
CiliumBGPAdvertisement	What to advertise.	pkg/k8s/apis/cilium.io/v2/types_bgp_advertisement.go
CiliumGatewayClassConfig	Gateway API class config.	pkg/k8s/apis/cilium.io/v2/types_gatewayclass_config.go

(Names track the Go file naming; the actual list evolves and Documentation/crdlist.rst is authoritative.)

Alpha (v2alpha1)

Alpha CRDs that evolved (or are evolving) before promotion to v2 include:

• CiliumEndpointSlice (CES)
• CiliumPodIPPool
• CiliumL2AnnouncementPolicy
• CiliumBGPNodeConfigOverride
• CiliumBGPPeeringPolicy (legacy single-CRD BGP API)
• CiliumLoadBalancerIPPool (was alpha, now v2)
• ...

Generation

make generate-k8s-api

Driven by controller-gen, this regenerates:

• DeepCopy methods (zz_generated_deepcopy.go).
• Typed clientsets, listers, informers under pkg/k8s/apis/cilium.io/client/.
• CRD YAML manifests under pkg/k8s/apis/cilium.io/client/crds/.
• The docs table in Documentation/crdlist.rst.

A CI check (Documentation/check-crd-compat-table.sh) ensures CRD diff stays compatible.

Owners and consumers

• Operator owns the lifecycle of CiliumIdentity, CiliumEndpoint, CiliumEndpointSlice, CiliumNode. It garbage-collects them.
• Agent consumes everything — policy, envoy config, BGP, FQDN cache via CRDs.
• CLI (cilium-cli) renders some CRDs into Helm values for installation defaults.
• Cluster Mesh exports identities, services, and node info via the kvstore — CRDs remain local but their effect propagates.

Conversion and storage

CRDs use Kubernetes' built-in storage. Cilium does not run a conversion webhook today; alpha → GA promotions duplicate types under v2/ with backward-compatible field renames.

Schema evolution rules

• New optional fields are always allowed.
• New required fields must be added in a new alpha CRD or in a new minor of an alpha CRD with a default migration.
• Field removals require a major version of the API group, which has not happened — cilium.io/v1 does not exist for production CRDs.
• Validation is enforced via +kubebuilder:validation: annotations and admission webhooks where needed.

Key source files

File	Purpose
pkg/k8s/apis/cilium.io/v2/types_*.go	CRD definitions.
pkg/k8s/apis/cilium.io/client/crds/	Rendered YAML.
Documentation/crdlist.rst	User-facing catalog.
Documentation/check-crd-compat-table.sh	Compat enforcement.
make generate-k8s-api	Regenerator.