API Reference

Introduction

The Cilium API is JSON based and provided by the cilium-agent. The purpose of the API is to provide visbility 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 visbility. 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

The Cilium API is still marked unstable overall at this point but several core sections have already matured a lot. We will declare the overall API stable with the release of version 1.0. In the meantime, we would like maintain the flexibility to adjust to feedback. The APIs are also heavily dependant on the evolution of various orchestration systems which have not stabilized yet.

If you are planning to utilize the API and could benefit from a stable API, please approach us on Slack and we can discuss marking certain sections of the API stable and start maintaining backwards compatibility.

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:
GET /config

Get configuration of Cilium daemon

Returns the configuration of the Cilium daemon.

Status Codes:
PATCH /config

Modify daemon configuration

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

Status Codes:
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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
PUT /endpoint/{id}

Create endpoint

Updates 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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
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:
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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
PUT /endpoint/{id}/labels

Modify label configuration of endpoint

Updates the list of labels associated with an endpoint by applying a label modificator structure to the label configuration of an endpoint.

The label configuration mutation is only executed as a whole, i.e. if any of the labels to be deleted are not either on the list of orchestration system labels, custom labels, or already disabled, then the request will fail. Labels to be added which already exist on either the orchestration list or custom list will be ignored.

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-net-endpoint: Docker libnetwork endpoint ID, e.g. docker-net-endpoint:4444
Status Codes:
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:
POST /ipam/{ip}

Allocate an IP address

Parameters:
  • ip (string) – IP address
Status Codes:
DELETE /ipam/{ip}

Release an allocated IP address

Parameters:
  • ip (string) – IP address
Status Codes:
GET /policy

Retrieve entire policy tree

Returns the entire policy tree with all children.

Status Codes:
PUT /policy

Create or update a policy (sub)tree

Status Codes:
DELETE /policy

Delete a policy (sub)tree

Status Codes:
GET /policy/resolve

Resolve policy for an identity context

Status Codes:
GET /service

Retrieve list of all services

Status Codes:
GET /service/{id}

Retrieve configuration of a service

Parameters:
  • id (integer) – ID of service
Status Codes:
PUT /service/{id}

Create or update service

Parameters:
  • id (integer) – ID of service
Status Codes:
DELETE /service/{id}

Delete a service

Parameters:
  • id (integer) – ID of service
Status Codes:
GET /prefilter

Retrieve list of CIDRs

Status Codes:
PUT /prefilter

Update list of CIDRs

Status Codes:
DELETE /prefilter

Delete list of CIDRs

Status Codes: