API surface

Active contributors: aanm, sayboras, mhofstetter, glibsm, rolinh

Purpose

Cilium exposes three external API surfaces. Each has its own definition format, generator, and clients.

Surface	Format	Used by
Agent REST API (/v1/...)	OpenAPI 2.0 in api/v1/openapi.yaml	cilium-cli, cilium-dbg, internal tools
Hubble gRPC API	Protobuf under api/v1/observer/, relay/, peer/, flow/	hubble CLI, Hubble UI, third-party flow consumers
Cilium CRDs	Go types under pkg/k8s/apis/cilium.io/v2/ and v2alpha1/	All Kubernetes clients (kubectl, controllers, operators)

Directory layout

api/
└── v1/
    ├── openapi.yaml            # The agent REST API definition
    ├── client/                 # Generated Go client (used by cilium-cli, cilium-dbg)
    ├── server/                 # Generated Go server (used by daemon/restapi/)
    ├── models/                 # Generated request/response models
    ├── observer/               # Hubble Observer gRPC (.proto + generated .pb.go)
    ├── relay/                  # Hubble Relay gRPC
    ├── peer/                   # Hubble Peer gRPC (peer discovery)
    ├── flow/                   # Hubble flow message
    └── ...

CRDs live elsewhere:

pkg/k8s/apis/cilium.io/
├── v2/                         # GA CRDs (CiliumNetworkPolicy, CiliumIdentity, ...)
├── v2alpha1/                   # alpha CRDs (CiliumLoadBalancerIPPool, BGP, ...)
├── client/                     # Generated typed client + listers + informers
└── client/crds/                # YAML CRD manifests rendered for Helm

Agent REST API

The agent serves a Unix-socket REST API at /var/run/cilium/cilium.sock. Every endpoint is defined in api/v1/openapi.yaml and grouped by tag:

• /cluster/* — node and Cluster Mesh state.
• /endpoint/* — endpoint listing, regenerate, log, healthz.
• /identity/* — identity catalog.
• /policy/* — compiled policy view.
• /service/* — load balancer services.
• /healthz — agent self-health.
• /config/* — runtime config.
• /debuginfo — bugtool data.
• /fqdn/* — DNS proxy state.
• /bgp/* — BGP peers and routes.
• /recorder/* — Hubble recorder.

The OpenAPI generator (go-swagger, vendored) produces both server and client code. Handlers are wired into Hive cells under daemon/restapi/.

Hubble gRPC API

The Hubble services are defined in .proto files under api/v1/:

• Observer — flow stream and queries.
• Peer — peer list for Relay.
• Relay — relay-specific service.
• Recorder — pcap recording.

The proto definitions are stable across minor versions and are also published to cilium/hubble-api.

CRDs

Cilium owns these CRD groups (all under cilium.io):

Kind	Version	Purpose
CiliumNetworkPolicy (CNP)	v2	Namespaced policy.
CiliumClusterwideNetworkPolicy (CCNP)	v2	Cluster-scoped policy.
CiliumExternalWorkload	v2	External (non-K8s) workload.
CiliumIdentity	v2	Identity allocation.
CiliumEndpoint (CEP)	v2	Per-pod state.
CiliumEndpointSlice (CES)	v2alpha1	Batched endpoint state for scale.
CiliumNode	v2	Per-node IPAM and config.
CiliumLoadBalancerIPPool	v2	LB-IPAM pool (IP ranges for LoadBalancer services).
CiliumBGPPeeringPolicy / CiliumBGPClusterConfig / CiliumBGPNodeConfig / CiliumBGPAdvertisement / CiliumBGPPeerConfig	v2alpha1/v2	BGP control plane configuration.
CiliumGatewayClass and others	varies	Gateway API integration.
CiliumPodIPPool	v2alpha1	Per-namespace pod IPAM pool.
CiliumEnvoyConfig / CiliumClusterwideEnvoyConfig	v2	Custom Envoy configuration via xDS.
CiliumL2AnnouncementPolicy	v2alpha1	L2 announcement policy.
CiliumCIDRGroup	v2	Reusable CIDR sets for policy.

The full live catalog is in Documentation/crdlist.rst and the Go types under pkg/k8s/apis/cilium.io/.

Generation pipeline

graph LR
    OAS[api/v1/openapi.yaml]
    Proto[api/v1/.../*.proto]
    GoTypes[pkg/k8s/apis/cilium.io/]

    OAS -->|swagger generate| ServerClient[api/v1/server + client]
    Proto -->|protoc-gen-go| HubblePB[api/v1/.../*.pb.go]
    GoTypes -->|controller-gen| DeepCopy[zz_generated_*.go]
    GoTypes -->|controller-gen| CRDYAML[pkg/k8s/apis/cilium.io/client/crds/]
    GoTypes -->|client-gen| TypedClient[pkg/k8s/apis/.../client/]

Top-level make targets:

• make generate-api — OpenAPI server/client.
• make -C api proto — Hubble proto.
• make generate-k8s-api — CRD deepcopy, schemas, typed client.

Versioning rules

• REST API surface: backwards compatible within a minor version. Removal happens only across major versions.
• Hubble proto: backwards compatible across all currently supported minor versions. Field numbers must not be reused.
• CRDs: alpha → beta → GA, with conversion webhooks where necessary. Once GA, fields can be added but not removed.

Key source files

File	Purpose
api/v1/openapi.yaml	Agent REST definition.
api/v1/observer/observer.proto	Hubble Observer service.
pkg/k8s/apis/cilium.io/v2/types.go	CRD Go types.
pkg/k8s/apis/cilium.io/client/crds/	Generated CRD YAML.
Documentation/api.rst	User-facing API docs.
Documentation/crdlist.rst	Live CRD catalog.

See packages/k8s.md for how CRDs are consumed.