API Reference¶

Introduction¶

The Cilium API is JSON based and provided by the cilium-agent. The purpose of the API is to provide visibility and control over an individual agent instance. In general, all API calls affect only the resources managed by the individual cilium-agent serving the API. A few selected API calls such as the security identity resolution provides cluster wide visibility. Such API calls are marked specifically. Unless noted otherwise, API calls will only affect local agent resources.

How to access the API¶

$ cilium -H unix:///var/run/cilium/cilium.sock
[...]

import (
        "fmt"

        "github.com/cilium/cilium/pkg/client"
)

func main() {
        c, err := client.NewDefaultClient()
        if err != nil {
                ...
        }

        endpoints, err := c.EndpointList()
        if err != nil {
                ...
        }

        for _, ep := range endpoints {
                fmt.Printf("%8d %14s %16s %32s\n", ep.ID, ep.ContainerName, ep.Addressing.IPV4, ep.Addressing.IPV6)
        }

Compatibility Guarantees¶

Cilium API is stable as of version 1.0, backward compatibility will be upheld for whole lifecycle of Cilium 1.x.

API Reference¶

GET /healthz¶

Get health of Cilium daemon

Returns health and status information of the Cilium daemon and related components such as the local container runtime, connected datastore, Kubernetes integration.

Status Codes:	200 OK – Success

GET /config¶

Get configuration of Cilium daemon

Returns the configuration of the Cilium daemon.

Status Codes:	200 OK – Success

PATCH /config¶

Modify daemon configuration

Updates the daemon configuration by applying the provided ConfigurationMap and regenerates & recompiles all required datapath components.

Status Codes:	200 OK – Success 400 Bad Request – Bad configuration parameters 500 Internal Server Error – Recompilation failed

GET /endpoint/{id}¶

Get endpoint by endpoint ID

Returns endpoint information

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 400 Bad Request – Invalid endpoint ID format for specified type 404 Not Found – Endpoint not found

PUT /endpoint/{id}¶

Create endpoint

Creates a new endpoint

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

201 Created – Created 400 Bad Request – Invalid endpoint in request 409 Conflict – Endpoint already exists 500 Internal Server Error – Endpoint creation failed

PATCH /endpoint/{id}¶

Modify existing endpoint

Applies the endpoint change request to an existing endpoint

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 400 Bad Request – Invalid modify endpoint request 404 Not Found – Endpoint does not exist 500 Internal Server Error – Endpoint update failed

DELETE /endpoint/{id}¶

Delete endpoint

Deletes the endpoint specified by the ID. Deletion is imminent and atomic, if the deletion request is valid and the endpoint exists, deletion will occur even if errors are encountered in the process. If errors have been encountered, the code 202 will be returned, otherwise 200 on success.

All resources associated with the endpoint will be freed and the workload represented by the endpoint will be disconnected.It will no longer be able to initiate or receive communications of any sort.

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 206 Partial Content – Deleted with a number of errors encountered 400 Bad Request – Invalid endpoint ID format for specified type. Details in error message 404 Not Found – Endpoint not found

GET /endpoint¶

Retrieves a list of endpoints that have metadata matching the provided parameters.

Retrieves a list of endpoints that have metadata matching the provided parameters, or all endpoints if no parameters provided.

Status Codes:	200 OK – Success 404 Not Found – Endpoints with provided parameters not found

GET /endpoint/{id}/config¶

Retrieve endpoint configuration

Retrieves the configuration of the specified endpoint.

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 404 Not Found – Endpoint not found

PATCH /endpoint/{id}/config¶

Modify mutable endpoint configuration

Update the configuration of an existing endpoint and regenerates & recompiles the corresponding programs automatically.

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 400 Bad Request – Invalid configuration request 404 Not Found – Endpoint not found 500 Internal Server Error – Update failed. Details in message.

GET /endpoint/{id}/labels¶

Retrieves the list of labels associated with an endpoint.

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 404 Not Found – Endpoint not found

PATCH /endpoint/{id}/labels¶

Set label configuration of endpoint

Sets labels associated with an endpoint. These can be user provided or derived from the orchestration system.

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 404 Not Found – Endpoint not found 500 Internal Server Error – Error while updating labels

GET /endpoint/{id}/log¶

Retrieves the status logs associated with this endpoint.

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 400 Bad Request – Invalid identity provided 404 Not Found – Endpoint not found

GET /endpoint/{id}/healthz¶

Retrieves the status logs associated with this endpoint.

Parameters:

id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444

Status Codes:

200 OK – Success 400 Bad Request – Invalid identity provided 404 Not Found – Endpoint not found

GET /identity¶

Retrieves a list of identities that have metadata matching the provided parameters.

Retrieves a list of identities that have metadata matching the provided parameters, or all identities if no parameters are provided.

Status Codes:	200 OK – Success 404 Not Found – Identities with provided parameters not found 520 – Identity storage unreachable. Likely a network problem. 521 – Invalid identity format in storage

GET /identity/{id}¶

Retrieve identity

Parameters:	id (string) – Cluster wide unique identifier of a security identity.
Status Codes:	200 OK – Success 400 Bad Request – Invalid identity provided 404 Not Found – Identity not found 520 – Identity storage unreachable. Likely a network problem. 521 – Invalid identity format in storage

POST /ipam¶

Allocate an IP address

Query Parameters:
	family (string) –
Status Codes:	201 Created – Success 502 Bad Gateway – Allocation failure

POST /ipam/{ip}¶

Allocate an IP address

Parameters:	ip (string) – IP address
Status Codes:	200 OK – Success 400 Bad Request – Invalid IP address 409 Conflict – IP already allocated 500 Internal Server Error – IP allocation failure. Details in message. 501 Not Implemented – Allocation for address family disabled

DELETE /ipam/{ip}¶

Release an allocated IP address

Parameters:	ip (string) – IP address
Status Codes:	200 OK – Success 400 Bad Request – Invalid IP address 404 Not Found – IP address not found 500 Internal Server Error – Address release failure 501 Not Implemented – Allocation for address family disabled

GET /policy¶

Retrieve entire policy tree

Returns the entire policy tree with all children.

Status Codes:	200 OK – Success 404 Not Found – No policy rules found

PUT /policy¶

Create or update a policy (sub)tree

Status Codes:	200 OK – Success 400 Bad Request – Invalid policy 460 – Invalid path 500 Internal Server Error – Policy import failed

DELETE /policy¶

Delete a policy (sub)tree

Status Codes:	200 OK – Success 400 Bad Request – Invalid request 404 Not Found – Policy not found 500 Internal Server Error – Error while deleting policy

GET /policy/resolve¶

Resolve policy for an identity context

Status Codes:	200 OK – Success

GET /service¶

Retrieve list of all services

Status Codes:	200 OK – Success

GET /service/{id}¶

Retrieve configuration of a service

Parameters:	id (integer) – ID of service
Status Codes:	200 OK – Success 404 Not Found – Service not found

PUT /service/{id}¶

Create or update service

Parameters:	id (integer) – ID of service
Status Codes:	200 OK – Updated 201 Created – Created 460 – Invalid frontend in service configuration 461 – Invalid backend in service configuration 500 Internal Server Error – Error while creating service

DELETE /service/{id}¶

Delete a service

Parameters:	id (integer) – ID of service
Status Codes:	200 OK – Success 404 Not Found – Service not found 500 Internal Server Error – Service deletion failed

GET /prefilter¶

Retrieve list of CIDRs

Status Codes:	200 OK – Success 500 Internal Server Error – Prefilter get failed

PATCH /prefilter¶

Update list of CIDRs

Status Codes:	200 OK – Updated 461 – Invalid CIDR prefix 500 Internal Server Error – Prefilter update failed

GET /debuginfo¶

Retrieve information about the agent and evironment for debugging

Status Codes:	200 OK – Success 500 Internal Server Error – DebugInfo get failed

GET /map¶

List all open maps

Status Codes:	200 OK – Success

GET /map/{name}¶

Retrieve contents of BPF map

Parameters:	name (string) – Name of map
Status Codes:	200 OK – Success 404 Not Found – Map not found

GET /metrics/¶

Retrieve cilium metrics

Status Codes:	200 OK – Success 500 Internal Server Error – Metrics cannot be retrieved

GET /fqdn/cache¶

Retrieves the list of DNS lookups intercepted from all endpoints.

Retrieves the list of DNS lookups intercepted from endpoints, optionally filtered by endpoint id, DNS name, or CIDR IP range.

Query Parameters:
	matchpattern (string) – A toFQDNs compatible matchPattern expression cidr (string) – A CIDR range of IPs
Status Codes:	200 OK – Success 400 Bad Request – Invalid request (error parsing parameters) 404 Not Found – No DNS data with provided parameters found

DELETE /fqdn/cache¶

Deletes matching DNS lookups from the policy-generation cache.

Deletes matching DNS lookups from the cache, optionally restricted by DNS name. The removed IP data will no longer be used in generated policies.

Query Parameters:
	matchpattern (string) – A toFQDNs compatible matchPattern expression
Status Codes:	200 OK – Success 400 Bad Request – Invalid request (error parsing parameters)

GET /fqdn/cache/{id}¶

Retrieves the list of DNS lookups intercepted from an endpoint.

Retrieves the list of DNS lookups intercepted from endpoints, optionally filtered by endpoint id, DNS name, or CIDR IP range.

Parameters:	id (string) – String describing an endpoint with the format [prefix:]id. If no prefix is specified, a prefix of cilium-local: is assumed. Not all endpoints will be addressable by all endpoint ID prefixes with the exception of the local Cilium UUID which is assigned to all endpoints. Supported endpoint id prefixes: cilium-local: Local Cilium endpoint UUID, e.g. cilium-local:3389595 cilium-global: Global Cilium endpoint UUID, e.g. cilium-global:cluster1:nodeX:452343 container-id: Container runtime ID, e.g. container-id:22222 container-name: Container name, e.g. container-name:foobar pod-name: pod name for this container if K8s is enabled, e.g. pod-name:default:foobar docker-endpoint: Docker libnetwork endpoint ID, e.g. docker-endpoint:4444
Query Parameters:
	matchpattern (string) – A toFQDNs compatible matchPattern expression cidr (string) – A CIDR range of IPs
Status Codes:	200 OK – Success 400 Bad Request – Invalid request (error parsing parameters) 404 Not Found – No DNS data with provided parameters found