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:

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 /cluster/nodes

Get nodes information stored in the cilium-agent

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 and Hubble.

GET /config

Get configuration of Cilium daemon

Returns the configuration of the Cilium daemon.

PATCH /config

Modify daemon configuration

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

GET /endpoint/{id}

Get endpoint by endpoint ID

Returns endpoint information

PUT /endpoint/{id}

Create endpoint

Creates a new endpoint

PATCH /endpoint/{id}

Modify existing endpoint

Applies the endpoint change request to an existing endpoint

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.

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.

GET /endpoint/{id}/config

Retrieve endpoint configuration

Retrieves the configuration of the specified endpoint.

PATCH /endpoint/{id}/config

Modify mutable endpoint configuration

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

GET /endpoint/{id}/labels

Retrieves the list of labels associated with an endpoint.

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.

GET /endpoint/{id}/log

Retrieves the status logs associated with this endpoint.

GET /endpoint/{id}/healthz

Retrieves the status logs associated with this endpoint.

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.

GET /identity/{id}

Retrieve identity

GET /identity/endpoints

Retrieve identities which are being used by local endpoints

POST /ipam

Allocate an IP address

POST /ipam/{ip}

Allocate an IP address

DELETE /ipam/{ip}

Release an allocated IP address

GET /policy

Retrieve entire policy tree

Returns the entire policy tree with all children.

PUT /policy

Create or update a policy (sub)tree

DELETE /policy

Delete a policy (sub)tree

GET /policy/resolve

Resolve policy for an identity context

GET /policy/selectors

See what selectors match which identities

GET /lrp

Retrieve list of all local redirect policies

GET /service

Retrieve list of all services

GET /service/{id}

Retrieve configuration of a service

PUT /service/{id}

Create or update service

DELETE /service/{id}

Delete a service

GET /recorder

Retrieve list of all recorders

GET /recorder/masks

Retrieve list of all recorder masks

GET /recorder/{id}

Retrieve configuration of a recorder

PUT /recorder/{id}

Create or update recorder

DELETE /recorder/{id}

Delete a recorder

GET /prefilter

Retrieve list of CIDRs

PATCH /prefilter

Update list of CIDRs

DELETE /prefilter

Delete list of CIDRs

GET /debuginfo

Retrieve information about the agent and evironment for debugging

GET /map

List all open maps

GET /map/{name}

Retrieve contents of BPF map

GET /metrics/

Retrieve cilium metrics

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.

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.

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.

GET /fqdn/names

List internal DNS selector representations

Retrieves the list of DNS-related fields (names to poll, selectors and their corresponding regexes).

GET /ip

Lists information about known IP addresses

Retrieves a list of IPs with known associated information such as their identities, host addresses, Kubernetes pod names, etc. The list can optionally filtered by a CIDR IP range.