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¶
CLI Client¶
The easiest way to access the API is via the cilium
CLI client. cilium
will automatically locate the API of the agent running on the same node and
access it. However, using the -H
or --host
flag, the cilium
client
can be pointed to an arbitrary API address.
Example¶
$ cilium -H unix:///var/run/cilium/cilium.sock
[...]
Golang Package¶
The following Go packages can be used to access the API:
Package | Description |
pkg/client | Main client API abstraction |
api/v1/models | API resource data type models |
Example¶
The full example can be found in the cilium/client-example repository.
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 ofcilium-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
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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 ofcilium-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.
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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 ofcilium-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
- id (string) –
-
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
/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/{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 ofcilium-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
- id (string) –