Agent REST API

Active contributors: aanm, christarazi, joestringer

Definition

The agent's REST API is defined in OpenAPI 2.0 at api/v1/openapi.yaml. It is served on the Unix socket /var/run/cilium/cilium.sock inside each agent pod. There is no remote network listener; clients run in the same pod (cilium-dbg, cilium-cli when port-forwarded, bugtool).

The cilium status and cilium endpoint list style commands in cilium-dbg are thin wrappers around this API.

Endpoint groups

Tag	Path prefix	Notes
daemon	/healthz, /config, /debuginfo	Self-health and runtime config.
endpoint	/endpoint, /endpoint/{id}/...	Endpoint listing, regenerate, log, healthz.
identity	/identity	Identity catalog.
policy	/policy, /policy/selectors	Compiled policy view.
service	/service, /lrp	Load balancer services and local redirect policies.
cluster	/cluster/nodes	Cluster Mesh node view.
prefilter	/prefilter	XDP prefilter rules.
recorder	/recorder	Hubble recorder controls.
bgp	/bgp/peers, /bgp/routes, /bgp/route-policies	BGP debug.
fqdn	/fqdn/cache, /fqdn/names	DNS proxy state.
metrics	/metrics	Server-side metrics queries.
ipam	/ipam	IP allocation queries.
statedb	/statedb/dump, /statedb/query	StateDB introspection.
map	/map, /map/{name}	Generic BPF map dumps.

Generation

Editing the OpenAPI spec → regenerated server / client / models:

make generate-api

This runs go-swagger (vendored) and produces:

• api/v1/server/... — Go HTTP server scaffolding consumed by daemon/restapi/.
• api/v1/client/... — typed Go client used by cilium-dbg, cilium-cli, etc.
• api/v1/models/... — request / response Go types.

Handlers live in daemon/restapi/ and are wired through Hive cells.

Versioning

The API surface follows the Cilium versioning policy:

• Within a minor version, no incompatible changes.
• Across minor versions, backward-compatible additions are normal; field removals require a major bump.
• Clients should treat the API as eventually consistent — it serves the agent's local view, which may briefly lag the K8s API server.

Adding an endpoint

1. Edit api/v1/openapi.yaml. Add the path, parameters, response model, and a unique operationId.
2. Run make generate-api.
3. Implement the handler in daemon/restapi/<group>.go. Register it via the corresponding cell.
4. Add a CLI command in cilium-dbg/cmd/ (and optionally cilium-cli/).
5. Add docs to Documentation/api.rst.

Key source files

File	Purpose
api/v1/openapi.yaml	The spec.
api/v1/server/	Generated server.
api/v1/client/	Generated client.
daemon/restapi/	Handler wiring.
Documentation/api.rst	User docs.