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

• Status Codes

  • 200 OK – Success

  Request Headers

  • client-id – Client UUID should be used when the client wants to request a diff of nodes added and / or removed since the last time that client has made a request.

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.

• Status Codes

  • 200 OK – Success

  Request Headers

  • brief – Brief will return a brief representation of the Cilium status.

  Response JSON Object

  • bandwidth-manager.congestionControl (string) –

  • bandwidth-manager.devices[] (string) –

  • bandwidth-manager.enabled (boolean) – Is bandwidth manager enabled

  • bpf-maps.dynamic-size-ratio (number) – Ratio of total system memory to use for dynamic sizing of BPF maps

  • bpf-maps.maps[].name (string) – Name of the BPF map

  • bpf-maps.maps[].size (integer) – Size of the BPF map

  • cilium.msg (string) – Human readable status/error/warning message

  • cilium.state (string) – State the component is in

  • client-id (integer) – When supported by the API, this client ID should be used by the client when making another request to the server. See for example “/cluster/nodes”.

  • clock-source.hertz (integer) – Kernel Hz

  • clock-source.mode (string) – Datapath clock source

  • cluster (any) – Status of cluster +k8s:deepcopy-gen=true

  • cluster-mesh (any) – Status of ClusterMesh +k8s:deepcopy-gen=true

  • cni-chaining (any) – Status of CNI chaining +k8s:deepcopy-gen=true

  • container-runtime.msg (string) – Human readable status/error/warning message

  • container-runtime.state (string) – State the component is in

  • controllers[].configuration.error-retry (boolean) – Retry on error

  • controllers[].configuration.error-retry-base (string) – Base error retry back-off time

  • controllers[].configuration.interval (string) – Regular synchronization interval

  • controllers[].name (string) – Name of controller

  • controllers[].status.consecutive-failure-count (integer) – Number of consecutive errors since last success

  • controllers[].status.failure-count (integer) – Total number of failed runs

  • controllers[].status.last-failure-msg (string) – Error message of last failed run

  • controllers[].status.last-failure-timestamp (string) – Timestamp of last error

  • controllers[].status.last-success-timestamp (string) – Timestamp of last success

  • controllers[].status.success-count (integer) – Total number of successful runs

  • controllers[].uuid (string) – UUID of controller

  • encryption (any) – Status of transparent encryption +k8s:deepcopy-gen=true

  • host-firewall.devices[] (string) –

  • host-firewall.mode (string) –

  • host-routing.mode (string) – Datapath routing mode

  • hubble.metrics.state (string) – State of the Hubble metrics

  • hubble.msg (string) – Human readable status/error/warning message

  • hubble.observer.current-flows (integer) – Current number of flows this Hubble observer stores

  • hubble.observer.max-flows (integer) – Maximum number of flows this Hubble observer is able to store

  • hubble.observer.seen-flows (integer) – Total number of flows this Hubble observer has seen

  • hubble.observer.uptime (string) – Uptime of this Hubble observer instance

  • hubble.state (string) – State the component is in

  • identity-range (any) – Status of identity range of the cluster +k8s:deepcopy-gen=true

  • ipam (any) – Status of IP address management +k8s:deepcopy-gen=true

  • kube-proxy-replacement.deviceList[].ip[] (string) –

  • kube-proxy-replacement.deviceList[].name (string) –

  • kube-proxy-replacement.devices[] (string) –

  • kube-proxy-replacement.directRoutingDevice (string) –

  • kube-proxy-replacement.features.externalIPs.enabled (boolean) –

  • kube-proxy-replacement.features.gracefulTermination.enabled (boolean) –

  • kube-proxy-replacement.features.hostPort.enabled (boolean) –

  • kube-proxy-replacement.features.hostReachableServices.enabled (boolean) –

  • kube-proxy-replacement.features.hostReachableServices.protocols[] (string) –

  • kube-proxy-replacement.features.nat46X64.enabled (boolean) –

  • kube-proxy-replacement.features.nodePort.acceleration (string) –

  • kube-proxy-replacement.features.nodePort.algorithm (string) –

  • kube-proxy-replacement.features.nodePort.enabled (boolean) –

  • kube-proxy-replacement.features.nodePort.lutSize (integer) –

  • kube-proxy-replacement.features.nodePort.mode (string) –

  • kube-proxy-replacement.features.nodePort.portMax (integer) –

  • kube-proxy-replacement.features.nodePort.portMin (integer) –

  • kube-proxy-replacement.features.sessionAffinity.enabled (boolean) –

  • kube-proxy-replacement.features.socketLB.enabled (boolean) –

  • kube-proxy-replacement.mode (string) –

  • kubernetes.k8s-api-versions[] (string) –

  • kubernetes.msg (string) – Human readable status/error/warning message

  • kubernetes.state (string) – State the component is in

  • kvstore.msg (string) – Human readable status/error/warning message

  • kvstore.state (string) – State the component is in

  • masquerading.enabled (boolean) –

  • masquerading.enabledProtocols.ipv4 (boolean) – Is masquerading enabled for IPv4 traffic

  • masquerading.enabledProtocols.ipv6 (boolean) – Is masquerading enabled for IPv6 traffic

  • masquerading.ip-masq-agent (boolean) – Is BPF ip-masq-agent enabled

  • masquerading.mode (string) –

  • masquerading.snat-exclusion-cidr (string) – This field is obsolete, please use snat-exclusion-cidr-v4 or snat-exclusion-cidr-v6.

  • masquerading.snat-exclusion-cidr-v4 (string) – SnatExclusionCIDRv4 exempts SNAT from being performed on any packet sent to an IPv4 address that belongs to this CIDR.

  • masquerading.snat-exclusion-cidr-v6 (string) – SnatExclusionCIDRv6 exempts SNAT from being performed on any packet sent to an IPv6 address that belongs to this CIDR. For IPv6 we only do masquerading in iptables mode.

  • nodeMonitor (any) – Status of the node monitor

  • proxy.ip (string) – IP address that the proxy listens on

  • proxy.port-range (string) – Port range used for proxying

  • proxy.redirects[].name (string) – Name of the proxy redirect

  • proxy.redirects[].proxy (string) – Name of the proxy this redirect points to

  • proxy.redirects[].proxy-port (integer) – Host port that this redirect points to

  • proxy.total-ports (integer) – Total number of listening proxy ports

  • proxy.total-redirects (integer) – Total number of ports configured to redirect to proxies

  • stale (object) – List of stale information in the status

GET /config

Get configuration of Cilium daemon

Returns the configuration of the Cilium daemon.

• Status Codes

  • 200 OK – Success

  Response JSON Object

  • spec.options (object) – Map of configuration key/value pairs.

  • spec.policy-enforcement (string) – The policy-enforcement mode

  • status.addressing.ipv4.address-type (string) – Node address type, one of HostName, ExternalIP or InternalIP

  • status.addressing.ipv4.alloc-range (string) – Address pool to be used for local endpoints

  • status.addressing.ipv4.enabled (boolean) – True if address family is enabled

  • status.addressing.ipv4.ip (string) – IP address of node

  • status.addressing.ipv6.address-type (string) – Node address type, one of HostName, ExternalIP or InternalIP

  • status.addressing.ipv6.alloc-range (string) – Address pool to be used for local endpoints

  • status.addressing.ipv6.enabled (boolean) – True if address family is enabled

  • status.addressing.ipv6.ip (string) – IP address of node

  • status.daemonConfigurationMap (any) – Config map which contains all the active daemon configurations

  • status.datapathMode (string) – Datapath mode

  • status.deviceMTU (integer) – MTU on workload facing devices

  • status.egress-multi-home-ip-rule-compat (boolean) – Configured compatibility mode for –egress-multi-home-ip-rule-compat

  • status.immutable (object) – Map of configuration key/value pairs.

  • status.ipam-mode (string) – Configured IPAM mode

  • status.ipvlanConfiguration.masterDeviceIndex (integer) – Workload facing ipvlan master device ifindex.

  • status.ipvlanConfiguration.operationMode (string) – Mode in which ipvlan setup operates.

  • status.k8s-configuration (string) –

  • status.k8s-endpoint (string) –

  • status.kvstoreConfiguration (any) – Configuration used for the kvstore

  • status.masquerade (boolean) –

  • status.masqueradeProtocols.ipv4 (boolean) – Status of masquerading for IPv4 traffic

  • status.masqueradeProtocols.ipv6 (boolean) – Status of masquerading for IPv6 traffic

  • status.nodeMonitor (any) – Status of the node monitor

  • status.realized.options (object) – Map of configuration key/value pairs.

  • status.realized.policy-enforcement (string) – The policy-enforcement mode

  • status.routeMTU (integer) – MTU for network facing routes

PATCH /config

Modify daemon configuration

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

• Request JSON Object

  • options (object) – Map of configuration key/value pairs.

  • policy-enforcement (string) – The policy-enforcement mode

  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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – Invalid endpoint ID format for specified type
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
Response JSON Object
-   **id** (*integer*) – The cilium-agent-local ID of the endpoint
-   **spec.label-configuration.user\[\]** (*string*) –
-   **spec.options** (*object*) – Map of configuration key/value pairs.
-   **status.controllers\[\].configuration.error-retry** (*boolean*) – Retry on error
-   **status.controllers\[\].configuration.error-retry-base** (*string*) – Base error retry back-off time
-   **status.controllers\[\].configuration.interval** (*string*) – Regular synchronization interval
-   **status.controllers\[\].name** (*string*) – Name of controller
-   **status.controllers\[\].status.consecutive-failure-count** (*integer*) – Number of consecutive errors since last success
-   **status.controllers\[\].status.failure-count** (*integer*) – Total number of failed runs
-   **status.controllers\[\].status.last-failure-msg** (*string*) – Error message of last failed run
-   **status.controllers\[\].status.last-failure-timestamp** (*string*) – Timestamp of last error
-   **status.controllers\[\].status.last-success-timestamp** (*string*) – Timestamp of last success
-   **status.controllers\[\].status.success-count** (*integer*) – Total number of successful runs
-   **status.controllers\[\].uuid** (*string*) – UUID of controller
-   **status.external-identifiers.container-id** (*string*) – ID assigned by container runtime
-   **status.external-identifiers.container-name** (*string*) – Name assigned to container
-   **status.external-identifiers.docker-endpoint-id** (*string*) – Docker endpoint ID
-   **status.external-identifiers.docker-network-id** (*string*) – Docker network ID
-   **status.external-identifiers.k8s-namespace** (*string*) – K8s namespace for this endpoint
-   **status.external-identifiers.k8s-pod-name** (*string*) – K8s pod name for this endpoint
-   **status.external-identifiers.pod-name** (*string*) – K8s pod for this endpoint(Deprecated, use K8sPodName and K8sNamespace instead)
-   **status.health.bpf** (*string*) – A common set of statuses for endpoint health \* `OK` = All components operational \* `Bootstrap` = This component is being created \* `Pending` = A change is being processed to be applied \* `Warning` = This component is not applying up-to-date policies (but is still applying the previous version) \* `Failure` = An error has occurred and no policy is being applied \* `Disabled` = This endpoint is disabled and will not handle traffic
-   **status.health.connected** (*boolean*) – Is this endpoint reachable
-   **status.health.overallHealth** (*string*) – A common set of statuses for endpoint health \* `OK` = All components operational \* `Bootstrap` = This component is being created \* `Pending` = A change is being processed to be applied \* `Warning` = This component is not applying up-to-date policies (but is still applying the previous version) \* `Failure` = An error has occurred and no policy is being applied \* `Disabled` = This endpoint is disabled and will not handle traffic
-   **status.health.policy** (*string*) – A common set of statuses for endpoint health \* `OK` = All components operational \* `Bootstrap` = This component is being created \* `Pending` = A change is being processed to be applied \* `Warning` = This component is not applying up-to-date policies (but is still applying the previous version) \* `Failure` = An error has occurred and no policy is being applied \* `Disabled` = This endpoint is disabled and will not handle traffic
-   **status.identity.id** (*integer*) – Unique identifier
-   **status.identity.labelsSHA256** (*string*) – SHA256 of labels
-   **status.identity.labels\[\]** (*string*) –
-   **status.labels.derived\[\]** (*string*) –
-   **status.labels.disabled\[\]** (*string*) –
-   **status.labels.realized.user\[\]** (*string*) –
-   **status.labels.security-relevant\[\]** (*string*) –
-   **status.log\[\].code** (*string*) – Code indicate type of status change
-   **status.log\[\].message** (*string*) – Status message
-   **status.log\[\].state** (*string*) – State of endpoint
-   **status.log\[\].timestamp** (*string*) – Timestamp when status change occurred
-   **status.namedPorts\[\].name** (*string*) – Optional layer 4 port name
-   **status.namedPorts\[\].port** (*integer*) – Layer 4 port number
-   **status.namedPorts\[\].protocol** (*string*) – Layer 4 protocol
-   **status.networking.addressing\[\].ipv4** (*string*) – IPv4 address
-   **status.networking.addressing\[\].ipv4-expiration-uuid** (*string*) – UUID of IPv4 expiration timer
-   **status.networking.addressing\[\].ipv6** (*string*) – IPv6 address
-   **status.networking.addressing\[\].ipv6-expiration-uuid** (*string*) – UUID of IPv6 expiration timer
-   **status.networking.host-addressing.ipv4.address-type** (*string*) – Node address type, one of HostName, ExternalIP or InternalIP
-   **status.networking.host-addressing.ipv4.alloc-range** (*string*) – Address pool to be used for local endpoints
-   **status.networking.host-addressing.ipv4.enabled** (*boolean*) – True if address family is enabled
-   **status.networking.host-addressing.ipv4.ip** (*string*) – IP address of node
-   **status.networking.host-addressing.ipv6.address-type** (*string*) – Node address type, one of HostName, ExternalIP or InternalIP
-   **status.networking.host-addressing.ipv6.alloc-range** (*string*) – Address pool to be used for local endpoints
-   **status.networking.host-addressing.ipv6.enabled** (*boolean*) – True if address family is enabled
-   **status.networking.host-addressing.ipv6.ip** (*string*) – IP address of node
-   **status.networking.host-mac** (*string*) – MAC address
-   **status.networking.interface-index** (*integer*) – Index of network device
-   **status.networking.interface-name** (*string*) – Name of network device
-   **status.networking.mac** (*string*) – MAC address
-   **status.policy.proxy-policy-revision** (*integer*) – The policy revision currently enforced in the proxy for this endpoint
-   **status.policy.proxy-statistics\[\].allocated-proxy-port** (*integer*) – The port the proxy is listening on
-   **status.policy.proxy-statistics\[\].location** (*string*) – Location of where the redirect is installed
-   **status.policy.proxy-statistics\[\].port** (*integer*) – The port subject to the redirect
-   **status.policy.proxy-statistics\[\].protocol** (*string*) – Name of the L7 protocol
-   **status.policy.proxy-statistics\[\].statistics.requests.denied** (*integer*) – Number of messages denied
-   **status.policy.proxy-statistics\[\].statistics.requests.error** (*integer*) – Number of errors while parsing messages
-   **status.policy.proxy-statistics\[\].statistics.requests.forwarded** (*integer*) – Number of messages forwarded
-   **status.policy.proxy-statistics\[\].statistics.requests.received** (*integer*) – Number of messages received
-   **status.policy.proxy-statistics\[\].statistics.responses.denied** (*integer*) – Number of messages denied
-   **status.policy.proxy-statistics\[\].statistics.responses.error** (*integer*) – Number of errors while parsing messages
-   **status.policy.proxy-statistics\[\].statistics.responses.forwarded** (*integer*) – Number of messages forwarded
-   **status.policy.proxy-statistics\[\].statistics.responses.received** (*integer*) – Number of messages received
-   **status.policy.realized.allowed-egress-identities\[\]** (*integer*) –
-   **status.policy.realized.allowed-ingress-identities\[\]** (*integer*) –
-   **status.policy.realized.build** (*integer*) – Build number of calculated policy in use
-   **status.policy.realized.cidr-policy.egress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.realized.cidr-policy.ingress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.realized.denied-egress-identities\[\]** (*integer*) –
-   **status.policy.realized.denied-ingress-identities\[\]** (*integer*) –
-   **status.policy.realized.id** (*integer*) – Own identity of endpoint
-   **status.policy.realized.l4.egress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.realized.l4.ingress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.realized.policy-enabled** (*string*) – Whether policy enforcement is enabled (ingress, egress, both or none)
-   **status.policy.realized.policy-revision** (*integer*) – The agent-local policy revision
-   **status.policy.spec.allowed-egress-identities\[\]** (*integer*) –
-   **status.policy.spec.allowed-ingress-identities\[\]** (*integer*) –
-   **status.policy.spec.build** (*integer*) – Build number of calculated policy in use
-   **status.policy.spec.cidr-policy.egress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.spec.cidr-policy.ingress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.spec.denied-egress-identities\[\]** (*integer*) –
-   **status.policy.spec.denied-ingress-identities\[\]** (*integer*) –
-   **status.policy.spec.id** (*integer*) – Own identity of endpoint
-   **status.policy.spec.l4.egress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.spec.l4.ingress\[\]** (*any*) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true
-   **status.policy.spec.policy-enabled** (*string*) – Whether policy enforcement is enabled (ingress, egress, both or none)
-   **status.policy.spec.policy-revision** (*integer*) – The agent-local policy revision
-   **status.realized.label-configuration.user\[\]** (*string*) –
-   **status.realized.options** (*object*) – Map of configuration key/value pairs.
-   **status.state** (*string*) – State of endpoint (required)

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

Request JSON Object
-   **addressing.ipv4** (*string*) – IPv4 address
-   **addressing.ipv4-expiration-uuid** (*string*) – UUID of IPv4 expiration timer
-   **addressing.ipv6** (*string*) – IPv6 address
-   **addressing.ipv6-expiration-uuid** (*string*) – UUID of IPv6 expiration timer
-   **container-id** (*string*) – ID assigned by container runtime
-   **container-name** (*string*) – Name assigned to container
-   **datapath-configuration.disable-sip-verification** (*boolean*) – Disable source IP verification for the endpoint.
-   **datapath-configuration.external-ipam** (*boolean*) – Indicates that IPAM is done external to Cilium. This will prevent the IP from being released and re-allocation of the IP address is skipped on restore.
-   **datapath-configuration.install-endpoint-route** (*boolean*) – Installs a route in the Linux routing table pointing to the device of the endpoint’s interface.
-   **datapath-configuration.require-arp-passthrough** (*boolean*) – Enable ARP passthrough mode
-   **datapath-configuration.require-egress-prog** (*boolean*) – Endpoint requires a host-facing egress program to be attached to implement ingress policy and reverse NAT.
-   **datapath-configuration.require-routing** (*boolean*) – Endpoint requires BPF routing to be enabled, when disabled, routing is delegated to Linux routing.
-   **datapath-map-id** (*integer*) – ID of datapath tail call map
-   **docker-endpoint-id** (*string*) – Docker endpoint ID
-   **docker-network-id** (*string*) – Docker network ID
-   **host-mac** (*string*) – MAC address
-   **id** (*integer*) – Local endpoint ID
-   **interface-index** (*integer*) – Index of network device
-   **interface-name** (*string*) – Name of network device
-   **k8s-namespace** (*string*) – Kubernetes namespace name
-   **k8s-pod-name** (*string*) – Kubernetes pod name
-   **labels\[\]** (*string*) –
-   **mac** (*string*) – MAC address
-   **pid** (*integer*) – Process ID of the workload belonging to this endpoint
-   **policy-enabled** (*boolean*) – Whether policy enforcement is enabled or not
-   **state** (*string*) – State of endpoint (required)
-   **sync-build-endpoint** (*boolean*) – Whether to build an endpoint synchronously
Status Codes
-   [201 Created](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2) – Created
-   [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – Invalid endpoint in request
-   [409 Conflict](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) – Endpoint already exists
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
-   [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – 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

Request JSON Object
-   **addressing.ipv4** (*string*) – IPv4 address
-   **addressing.ipv4-expiration-uuid** (*string*) – UUID of IPv4 expiration timer
-   **addressing.ipv6** (*string*) – IPv6 address
-   **addressing.ipv6-expiration-uuid** (*string*) – UUID of IPv6 expiration timer
-   **container-id** (*string*) – ID assigned by container runtime
-   **container-name** (*string*) – Name assigned to container
-   **datapath-configuration.disable-sip-verification** (*boolean*) – Disable source IP verification for the endpoint.
-   **datapath-configuration.external-ipam** (*boolean*) – Indicates that IPAM is done external to Cilium. This will prevent the IP from being released and re-allocation of the IP address is skipped on restore.
-   **datapath-configuration.install-endpoint-route** (*boolean*) – Installs a route in the Linux routing table pointing to the device of the endpoint’s interface.
-   **datapath-configuration.require-arp-passthrough** (*boolean*) – Enable ARP passthrough mode
-   **datapath-configuration.require-egress-prog** (*boolean*) – Endpoint requires a host-facing egress program to be attached to implement ingress policy and reverse NAT.
-   **datapath-configuration.require-routing** (*boolean*) – Endpoint requires BPF routing to be enabled, when disabled, routing is delegated to Linux routing.
-   **datapath-map-id** (*integer*) – ID of datapath tail call map
-   **docker-endpoint-id** (*string*) – Docker endpoint ID
-   **docker-network-id** (*string*) – Docker network ID
-   **host-mac** (*string*) – MAC address
-   **id** (*integer*) – Local endpoint ID
-   **interface-index** (*integer*) – Index of network device
-   **interface-name** (*string*) – Name of network device
-   **k8s-namespace** (*string*) – Kubernetes namespace name
-   **k8s-pod-name** (*string*) – Kubernetes pod name
-   **labels\[\]** (*string*) –
-   **mac** (*string*) – MAC address
-   **pid** (*integer*) – Process ID of the workload belonging to this endpoint
-   **policy-enabled** (*boolean*) – Whether policy enforcement is enabled or not
-   **state** (*string*) – State of endpoint (required)
-   **sync-build-endpoint** (*boolean*) – Whether to build an endpoint synchronously
Status Codes
-   [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – Invalid modify endpoint request
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint does not exist
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
-   [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – 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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [206 Partial Content](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7) – Deleted with a number of errors encountered
-   [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – Invalid endpoint ID format for specified type. Details in error message
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame

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.

• Request JSON Object

  • [] (string) –

  Status Codes

  • 200 OK – Success

  • 404 Not Found – Endpoints with provided parameters not found

  • 429 Too Many Requests – Rate-limiting too many requests in the given time frame

  Response JSON Object

  • [].id (integer) – The cilium-agent-local ID of the endpoint

  • [].spec.label-configuration.user[] (string) –

  • [].spec.options (object) – Map of configuration key/value pairs.

  • [].status.controllers[].configuration.error-retry (boolean) – Retry on error

  • [].status.controllers[].configuration.error-retry-base (string) – Base error retry back-off time

  • [].status.controllers[].configuration.interval (string) – Regular synchronization interval

  • [].status.controllers[].name (string) – Name of controller

  • [].status.controllers[].status.consecutive-failure-count (integer) – Number of consecutive errors since last success

  • [].status.controllers[].status.failure-count (integer) – Total number of failed runs

  • [].status.controllers[].status.last-failure-msg (string) – Error message of last failed run

  • [].status.controllers[].status.last-failure-timestamp (string) – Timestamp of last error

  • [].status.controllers[].status.last-success-timestamp (string) – Timestamp of last success

  • [].status.controllers[].status.success-count (integer) – Total number of successful runs

  • [].status.controllers[].uuid (string) – UUID of controller

  • [].status.external-identifiers.container-id (string) – ID assigned by container runtime

  • [].status.external-identifiers.container-name (string) – Name assigned to container

  • [].status.external-identifiers.docker-endpoint-id (string) – Docker endpoint ID

  • [].status.external-identifiers.docker-network-id (string) – Docker network ID

  • [].status.external-identifiers.k8s-namespace (string) – K8s namespace for this endpoint

  • [].status.external-identifiers.k8s-pod-name (string) – K8s pod name for this endpoint

  • [].status.external-identifiers.pod-name (string) – K8s pod for this endpoint(Deprecated, use K8sPodName and K8sNamespace instead)

  • [].status.health.bpf (string) – A common set of statuses for endpoint health * OK = All components operational * Bootstrap = This component is being created * Pending = A change is being processed to be applied * Warning = This component is not applying up-to-date policies (but is still applying the previous version) * Failure = An error has occurred and no policy is being applied * Disabled = This endpoint is disabled and will not handle traffic

  • [].status.health.connected (boolean) – Is this endpoint reachable

  • [].status.health.overallHealth (string) – A common set of statuses for endpoint health * OK = All components operational * Bootstrap = This component is being created * Pending = A change is being processed to be applied * Warning = This component is not applying up-to-date policies (but is still applying the previous version) * Failure = An error has occurred and no policy is being applied * Disabled = This endpoint is disabled and will not handle traffic

  • [].status.health.policy (string) – A common set of statuses for endpoint health * OK = All components operational * Bootstrap = This component is being created * Pending = A change is being processed to be applied * Warning = This component is not applying up-to-date policies (but is still applying the previous version) * Failure = An error has occurred and no policy is being applied * Disabled = This endpoint is disabled and will not handle traffic

  • [].status.identity.id (integer) – Unique identifier

  • [].status.identity.labelsSHA256 (string) – SHA256 of labels

  • [].status.identity.labels[] (string) –

  • [].status.labels.derived[] (string) –

  • [].status.labels.disabled[] (string) –

  • [].status.labels.realized.user[] (string) –

  • [].status.labels.security-relevant[] (string) –

  • [].status.log[].code (string) – Code indicate type of status change

  • [].status.log[].message (string) – Status message

  • [].status.log[].state (string) – State of endpoint

  • [].status.log[].timestamp (string) – Timestamp when status change occurred

  • [].status.namedPorts[].name (string) – Optional layer 4 port name

  • [].status.namedPorts[].port (integer) – Layer 4 port number

  • [].status.namedPorts[].protocol (string) – Layer 4 protocol

  • [].status.networking.addressing[].ipv4 (string) – IPv4 address

  • [].status.networking.addressing[].ipv4-expiration-uuid (string) – UUID of IPv4 expiration timer

  • [].status.networking.addressing[].ipv6 (string) – IPv6 address

  • [].status.networking.addressing[].ipv6-expiration-uuid (string) – UUID of IPv6 expiration timer

  • [].status.networking.host-addressing.ipv4.address-type (string) – Node address type, one of HostName, ExternalIP or InternalIP

  • [].status.networking.host-addressing.ipv4.alloc-range (string) – Address pool to be used for local endpoints

  • [].status.networking.host-addressing.ipv4.enabled (boolean) – True if address family is enabled

  • [].status.networking.host-addressing.ipv4.ip (string) – IP address of node

  • [].status.networking.host-addressing.ipv6.address-type (string) – Node address type, one of HostName, ExternalIP or InternalIP

  • [].status.networking.host-addressing.ipv6.alloc-range (string) – Address pool to be used for local endpoints

  • [].status.networking.host-addressing.ipv6.enabled (boolean) – True if address family is enabled

  • [].status.networking.host-addressing.ipv6.ip (string) – IP address of node

  • [].status.networking.host-mac (string) – MAC address

  • [].status.networking.interface-index (integer) – Index of network device

  • [].status.networking.interface-name (string) – Name of network device

  • [].status.networking.mac (string) – MAC address

  • [].status.policy.proxy-policy-revision (integer) – The policy revision currently enforced in the proxy for this endpoint

  • [].status.policy.proxy-statistics[].allocated-proxy-port (integer) – The port the proxy is listening on

  • [].status.policy.proxy-statistics[].location (string) – Location of where the redirect is installed

  • [].status.policy.proxy-statistics[].port (integer) – The port subject to the redirect

  • [].status.policy.proxy-statistics[].protocol (string) – Name of the L7 protocol

  • [].status.policy.proxy-statistics[].statistics.requests.denied (integer) – Number of messages denied

  • [].status.policy.proxy-statistics[].statistics.requests.error (integer) – Number of errors while parsing messages

  • [].status.policy.proxy-statistics[].statistics.requests.forwarded (integer) – Number of messages forwarded

  • [].status.policy.proxy-statistics[].statistics.requests.received (integer) – Number of messages received

  • [].status.policy.proxy-statistics[].statistics.responses.denied (integer) – Number of messages denied

  • [].status.policy.proxy-statistics[].statistics.responses.error (integer) – Number of errors while parsing messages

  • [].status.policy.proxy-statistics[].statistics.responses.forwarded (integer) – Number of messages forwarded

  • [].status.policy.proxy-statistics[].statistics.responses.received (integer) – Number of messages received

  • [].status.policy.realized.allowed-egress-identities[] (integer) –

  • [].status.policy.realized.allowed-ingress-identities[] (integer) –

  • [].status.policy.realized.build (integer) – Build number of calculated policy in use

  • [].status.policy.realized.cidr-policy.egress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.realized.cidr-policy.ingress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.realized.denied-egress-identities[] (integer) –

  • [].status.policy.realized.denied-ingress-identities[] (integer) –

  • [].status.policy.realized.id (integer) – Own identity of endpoint

  • [].status.policy.realized.l4.egress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.realized.l4.ingress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.realized.policy-enabled (string) – Whether policy enforcement is enabled (ingress, egress, both or none)

  • [].status.policy.realized.policy-revision (integer) – The agent-local policy revision

  • [].status.policy.spec.allowed-egress-identities[] (integer) –

  • [].status.policy.spec.allowed-ingress-identities[] (integer) –

  • [].status.policy.spec.build (integer) – Build number of calculated policy in use

  • [].status.policy.spec.cidr-policy.egress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.spec.cidr-policy.ingress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.spec.denied-egress-identities[] (integer) –

  • [].status.policy.spec.denied-ingress-identities[] (integer) –

  • [].status.policy.spec.id (integer) – Own identity of endpoint

  • [].status.policy.spec.l4.egress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.spec.l4.ingress[] (any) – A policy rule including the rule labels it derives from +k8s:deepcopy-gen=true

  • [].status.policy.spec.policy-enabled (string) – Whether policy enforcement is enabled (ingress, egress, both or none)

  • [].status.policy.spec.policy-revision (integer) – The agent-local policy revision

  • [].status.realized.label-configuration.user[] (string) –

  • [].status.realized.options (object) – Map of configuration key/value pairs.

  • [].status.state (string) – State of endpoint (required)

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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
Response JSON Object
-   **error** (*string*) –
-   **immutable** (*object*) – Map of configuration key/value pairs.
-   **realized.label-configuration.user\[\]** (*string*) –
-   **realized.options** (*object*) – Map of configuration key/value pairs.

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

Request JSON Object
-   **label-configuration.user\[\]** (*string*) –
-   **options** (*object*) – Map of configuration key/value pairs.
Status Codes
-   [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – Invalid configuration request
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
-   [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – 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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
Response JSON Object
-   **spec.user\[\]** (*string*) –
-   **status.derived\[\]** (*string*) –
-   **status.disabled\[\]** (*string*) –
-   **status.realized.user\[\]** (*string*) –
-   **status.security-relevant\[\]** (*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 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

Request JSON Object
-   **user\[\]** (*string*) –
Status Codes
-   [200 OK](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
-   [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – 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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – Invalid identity provided
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
Response JSON Object
-   **\[\].code** (*string*) – Code indicate type of status change
-   **\[\].message** (*string*) – Status message
-   **\[\].state** (*string*) – State of endpoint
-   **\[\].timestamp** (*string*) – Timestamp when status change occurred

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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – Success
-   [400 Bad Request](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – Invalid identity provided
-   [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – Endpoint not found
-   [429 Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4) – Rate-limiting too many requests in the given time frame
Response JSON Object
-   **bpf** (*string*) – A common set of statuses for endpoint health \* `OK` = All components operational \* `Bootstrap` = This component is being created \* `Pending` = A change is being processed to be applied \* `Warning` = This component is not applying up-to-date policies (but is still applying the previous version) \* `Failure` = An error has occurred and no policy is being applied \* `Disabled` = This endpoint is disabled and will not handle traffic
-   **connected** (*boolean*) – Is this endpoint reachable
-   **overallHealth** (*string*) – A common set of statuses for endpoint health \* `OK` = All components operational \* `Bootstrap` = This component is being created \* `Pending` = A change is being processed to be applied \* `Warning` = This component is not applying up-to-date policies (but is still applying the previous version) \* `Failure` = An error has occurred and no policy is being applied \* `Disabled` = This endpoint is disabled and will not handle traffic
-   **policy** (*string*) – A common set of statuses for endpoint health \* `OK` = All components operational \* `Bootstrap` = This component is being created \* `Pending` = A change is being processed to be applied \* `Warning` = This component is not applying up-to-date policies (but is still applying the previous version) \* `Failure` = An error has occurred and no policy is being applied \* `Disabled` = This endpoint is disabled and will not handle traffic

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.

• Request JSON Object

  • [] (string) –

  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

  Response JSON Object

  • [].id (integer) – Unique identifier

  • [].labelsSHA256 (string) – SHA256 of labels

  • [].labels[] (string) –

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

  Response JSON Object

  • id (integer) – Unique identifier

  • labelsSHA256 (string) – SHA256 of labels

  • labels[] (string) –

GET /identity/endpoints

Retrieve identities which are being used by local endpoints

• Status Codes

  • 200 OK – Success

  • 404 Not Found – Set of identities which are being used by local endpoints could not be found.

  Response JSON Object

  • [].identity.id (integer) – Unique identifier

  • [].identity.labelsSHA256 (string) – SHA256 of labels

  • [].identity.labels[] (string) –

  • [].refCount (integer) – number of endpoints consuming this identity locally (should always be > 0)

POST /ipam

Allocate an IP address

• Query Parameters

  • family (string) –

  • owner (string) –

  Status Codes

  • 201 Created – Success

  • 502 Bad Gateway – Allocation failure

  Request Headers

  • expiration –

  Response JSON Object

  • address.ipv4 (string) – IPv4 address

  • address.ipv4-expiration-uuid (string) – UUID of IPv4 expiration timer

  • address.ipv6 (string) – IPv6 address

  • address.ipv6-expiration-uuid (string) – UUID of IPv6 expiration timer

  • host-addressing.ipv4.address-type (string) – Node address type, one of HostName, ExternalIP or InternalIP

  • host-addressing.ipv4.alloc-range (string) – Address pool to be used for local endpoints

  • host-addressing.ipv4.enabled (boolean) – True if address family is enabled

  • host-addressing.ipv4.ip (string) – IP address of node

  • host-addressing.ipv6.address-type (string) – Node address type, one of HostName, ExternalIP or InternalIP

  • host-addressing.ipv6.alloc-range (string) – Address pool to be used for local endpoints

  • host-addressing.ipv6.enabled (boolean) – True if address family is enabled

  • host-addressing.ipv6.ip (string) – IP address of node

  • ipv4.cidrs[] (string) –

  • ipv4.expiration-uuid (string) – The UUID for the expiration timer. Set when expiration has been enabled while allocating.

  • ipv4.gateway (string) – IP of gateway

  • ipv4.interface-number (string) – InterfaceNumber is a field for generically identifying an interface. This is only useful in ENI mode.

  • ipv4.ip (string) – Allocated IP for endpoint

  • ipv4.master-mac (string) – MAC of master interface if address is a slave/secondary of a master interface

  • ipv6.cidrs[] (string) –

  • ipv6.expiration-uuid (string) – The UUID for the expiration timer. Set when expiration has been enabled while allocating.

  • ipv6.gateway (string) – IP of gateway

  • ipv6.interface-number (string) – InterfaceNumber is a field for generically identifying an interface. This is only useful in ENI mode.

  • ipv6.ip (string) – Allocated IP for endpoint

  • ipv6.master-mac (string) – MAC of master interface if address is a slave/secondary of a master interface

POST /ipam/{ip}

Allocate an IP address

• Parameters

  • ip (string) – IP address

  Query Parameters

  • owner (string) –

  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 or owner name

  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.

• Request JSON Object

  • [] (string) –

  Status Codes

  • 200 OK – Success

  • 404 Not Found – No policy rules found

  Response JSON Object

  • policy (string) – Policy definition as JSON.

  • revision (integer) – Revision number of the policy. Incremented each time the policy is changed in the agent’s repository

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

  Response JSON Object

  • policy (string) – Policy definition as JSON.

  • revision (integer) – Revision number of the policy. Incremented each time the policy is changed in the agent’s repository

DELETE /policy

Delete a policy (sub)tree

• Request JSON Object

  • [] (string) –

  Status Codes

  • 200 OK – Success

  • 400 Bad Request – Invalid request

  • 404 Not Found – Policy not found

  • 500 Internal Server Error – Error while deleting policy

  Response JSON Object

  • policy (string) – Policy definition as JSON.

  • revision (integer) – Revision number of the policy. Incremented each time the policy is changed in the agent’s repository

GET /policy/resolve

Resolve policy for an identity context

• Request JSON Object

  • from.labels[] (string) –

  • to.dports[].name (string) – Optional layer 4 port name

  • to.dports[].port (integer) – Layer 4 port number

  • to.dports[].protocol (string) – Layer 4 protocol

  • to.labels[] (string) –

  • verbose (boolean) – Enable verbose tracing.

  Status Codes

  • 200 OK – Success

  Response JSON Object

  • log (string) –

  • verdict (string) –

GET /policy/selectors

See what selectors match which identities

• Status Codes

  • 200 OK – Success

  Response JSON Object

  • [].identities[] (integer) –

  • [].selector (string) – string form of selector

  • [].users (integer) – number of users of this selector in the cache

GET /lrp

Retrieve list of all local redirect policies

• Status Codes

  • 200 OK – Success

  Response JSON Object

  • [].frontend-mappings[].backends[].backend-address.ip (string) – Layer 3 address (required)

  • [].frontend-mappings[].backends[].backend-address.nodeName (string) – Optional name of the node on which this backend runs

  • [].frontend-mappings[].backends[].backend-address.port (integer) – Layer 4 port number

  • [].frontend-mappings[].backends[].backend-address.preferred (boolean) – Indicator if this backend is preferred in the context of clustermesh service affinity. The value is set based on related annotation of global service. Applicable for active state only.

  • [].frontend-mappings[].backends[].backend-address.state (string) – State of the backend for load-balancing service traffic

  • [].frontend-mappings[].backends[].pod-id (string) – Namespace and name of the backend pod

  • [].frontend-mappings[].frontend-address.ip (string) – Layer 3 address

  • [].frontend-mappings[].frontend-address.port (integer) – Layer 4 port number

  • [].frontend-mappings[].frontend-address.protocol (string) – Layer 4 protocol

  • [].frontend-mappings[].frontend-address.scope (string) – Load balancing scope for frontend address

  • [].frontend-type (string) – LRP frontend type

  • [].lrp-type (string) – LRP config type

  • [].name (string) – LRP service name

  • [].namespace (string) – LRP service namespace

  • [].service-id (string) – matching k8s service namespace and name

  • [].uid (string) – Unique identification

GET /service

Retrieve list of all services

• Status Codes

  • 200 OK – Success

  Response JSON Object

  • [].spec.backend-addresses[].ip (string) – Layer 3 address (required)

  • [].spec.backend-addresses[].nodeName (string) – Optional name of the node on which this backend runs

  • [].spec.backend-addresses[].port (integer) – Layer 4 port number

  • [].spec.backend-addresses[].preferred (boolean) – Indicator if this backend is preferred in the context of clustermesh service affinity. The value is set based on related annotation of global service. Applicable for active state only.

  • [].spec.backend-addresses[].state (string) – State of the backend for load-balancing service traffic

  • [].spec.flags.healthCheckNodePort (integer) – Service health check node port

  • [].spec.flags.name (string) – Service name (e.g. Kubernetes service name)

  • [].spec.flags.namespace (string) – Service namespace (e.g. Kubernetes namespace)

  • [].spec.flags.natPolicy (string) – Service protocol NAT policy

  • [].spec.flags.trafficPolicy (string) – Service traffic policy

  • [].spec.flags.type (string) – Service type

  • [].spec.frontend-address.ip (string) – Layer 3 address

  • [].spec.frontend-address.port (integer) – Layer 4 port number

  • [].spec.frontend-address.protocol (string) – Layer 4 protocol

  • [].spec.frontend-address.scope (string) – Load balancing scope for frontend address

  • [].spec.id (integer) – Unique identification

  • [].spec.updateServices (boolean) – Update all services selecting the backends with their given states (id and frontend are ignored)

  • [].status.realized.backend-addresses[].ip (string) – Layer 3 address (required)

  • [].status.realized.backend-addresses[].nodeName (string) – Optional name of the node on which this backend runs

  • [].status.realized.backend-addresses[].port (integer) – Layer 4 port number

  • [].status.realized.backend-addresses[].preferred (boolean) – Indicator if this backend is preferred in the context of clustermesh service affinity. The value is set based on related annotation of global service. Applicable for active state only.

  • [].status.realized.backend-addresses[].state (string) – State of the backend for load-balancing service traffic

  • [].status.realized.flags.healthCheckNodePort (integer) – Service health check node port

  • [].status.realized.flags.name (string) – Service name (e.g. Kubernetes service name)

  • [].status.realized.flags.namespace (string) – Service namespace (e.g. Kubernetes namespace)

  • [].status.realized.flags.natPolicy (string) – Service protocol NAT policy

  • [].status.realized.flags.trafficPolicy (string) – Service traffic policy

  • [].status.realized.flags.type (string) – Service type

  • [].status.realized.frontend-address.ip (string) – Layer 3 address

  • [].status.realized.frontend-address.port (integer) – Layer 4 port number

  • [].status.realized.frontend-address.protocol (string) – Layer 4 protocol

  • [].status.realized.frontend-address.scope (string) – Load balancing scope for frontend address

  • [].status.realized.id (integer) – Unique identification

  • [].status.realized.updateServices (boolean) – Update all services selecting the backends with their given states (id and frontend are ignored)

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

  Response JSON Object

  • spec.backend-addresses[].ip (string) – Layer 3 address (required)

  • spec.backend-addresses[].nodeName (string) – Optional name of the node on which this backend runs

  • spec.backend-addresses[].port (integer) – Layer 4 port number

  • spec.backend-addresses[].preferred (boolean) – Indicator if this backend is preferred in the context of clustermesh service affinity. The value is set based on related annotation of global service. Applicable for active state only.

  • spec.backend-addresses[].state (string) – State of the backend for load-balancing service traffic

  • spec.flags.healthCheckNodePort (integer) – Service health check node port

  • spec.flags.name (string) – Service name (e.g. Kubernetes service name)

  • spec.flags.namespace (string) – Service namespace (e.g. Kubernetes namespace)

  • spec.flags.natPolicy (string) – Service protocol NAT policy

  • spec.flags.trafficPolicy (string) – Service traffic policy

  • spec.flags.type (string) – Service type

  • spec.frontend-address.ip (string) – Layer 3 address

  • spec.frontend-address.port (integer) – Layer 4 port number

  • spec.frontend-address.protocol (string) – Layer 4 protocol

  • spec.frontend-address.scope (string) – Load balancing scope for frontend address

  • spec.id (integer) – Unique identification

  • spec.updateServices (boolean) – Update all services selecting the backends with their given states (id and frontend are ignored)

  • status.realized.backend-addresses[].ip (string) – Layer 3 address (required)

  • status.realized.backend-addresses[].nodeName (string) – Optional name of the node on which this backend runs

  • status.realized.backend-addresses[].port (integer) – Layer 4 port number

  • status.realized.backend-addresses[].preferred (boolean) – Indicator if this backend is preferred in the context of clustermesh service affinity. The value is set based on related annotation of global service. Applicable for active state only.

  • status.realized.backend-addresses[].state (string) – State of the backend for load-balancing service traffic

  • status.realized.flags.healthCheckNodePort (integer) – Service health check node port

  • status.realized.flags.name (string) – Service name (e.g. Kubernetes service name)

  • status.realized.flags.namespace (string) – Service namespace (e.g. Kubernetes namespace)

  • status.realized.flags.natPolicy (string) – Service protocol NAT policy

  • status.realized.flags.trafficPolicy (string) – Service traffic policy

  • status.realized.flags.type (string) – Service type

  • status.realized.frontend-address.ip (string) – Layer 3 address

  • status.realized.frontend-address.port (integer) – Layer 4 port number

  • status.realized.frontend-address.protocol (string) – Layer 4 protocol

  • status.realized.frontend-address.scope (string) – Load balancing scope for frontend address

  • status.realized.id (integer) – Unique identification

  • status.realized.updateServices (boolean) – Update all services selecting the backends with their given states (id and frontend are ignored)

PUT /service/{id}

Create or update service

• Parameters

  • id (integer) – ID of service

  Request JSON Object

  • backend-addresses[].ip (string) – Layer 3 address (required)

  • backend-addresses[].nodeName (string) – Optional name of the node on which this backend runs

  • backend-addresses[].port (integer) – Layer 4 port number

  • backend-addresses[].preferred (boolean) – Indicator if this backend is preferred in the context of clustermesh service affinity. The value is set based on related annotation of global service. Applicable for active state only.

  • backend-addresses[].state (string) – State of the backend for load-balancing service traffic

  • flags.healthCheckNodePort (integer) – Service health check node port

  • flags.name (string) – Service name (e.g. Kubernetes service name)

  • flags.namespace (string) – Service namespace (e.g. Kubernetes namespace)

  • flags.natPolicy (string) – Service protocol NAT policy

  • flags.trafficPolicy (string) – Service traffic policy

  • flags.type (string) – Service type

  • frontend-address.ip (string) – Layer 3 address

  • frontend-address.port (integer) – Layer 4 port number

  • frontend-address.protocol (string) – Layer 4 protocol

  • frontend-address.scope (string) – Load balancing scope for frontend address

  • id (integer) – Unique identification

  • updateServices (boolean) – Update all services selecting the backends with their given states (id and frontend are ignored)

  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

  • 501 Not Implemented – Error while updating backend states

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 /recorder

Retrieve list of all recorders

• Status Codes

  • 200 OK – Success

  Response JSON Object

  • [].spec.capture-length (integer) – Maximum packet length or zero for full packet length

  • [].spec.filters[].dst-port (string) – Layer 4 destination port, zero (or in future range)

  • [].spec.filters[].dst-prefix (string) – Layer 3 destination CIDR

  • [].spec.filters[].protocol (string) – Layer 4 protocol

  • [].spec.filters[].src-port (string) – Layer 4 source port, zero (or in future range)

  • [].spec.filters[].src-prefix (string) – Layer 3 source CIDR

  • [].spec.id (integer) – Unique identification (required)

  • [].status.realized.capture-length (integer) – Maximum packet length or zero for full packet length

  • [].status.realized.filters[].dst-port (string) – Layer 4 destination port, zero (or in future range)

  • [].status.realized.filters[].dst-prefix (string) – Layer 3 destination CIDR

  • [].status.realized.filters[].protocol (string) – Layer 4 protocol

  • [].status.realized.filters[].src-port (string) – Layer 4 source port, zero (or in future range)

  • [].status.realized.filters[].src-prefix (string) – Layer 3 source CIDR

  • [].status.realized.id (integer) – Unique identification (required)

GET /recorder/masks

Retrieve list of all recorder masks

• Status Codes

  • 200 OK – Success

  Response JSON Object

  • [].status.realized.dst-port-mask (string) – Layer 4 destination port mask

  • [].status.realized.dst-prefix-mask (string) – Layer 3 destination IP mask

  • [].status.realized.priority (integer) – Priority of this mask

  • [].status.realized.protocol-mask (string) – Layer 4 protocol mask

  • [].status.realized.src-port-mask (string) – Layer 4 source port mask

  • [].status.realized.src-prefix-mask (string) – Layer 3 source IP mask

  • [].status.realized.users (integer) – Number of users of this mask

GET /recorder/{id}

Retrieve configuration of a recorder

• Parameters

  • id (integer) – ID of recorder

  Status Codes

  • 200 OK – Success

  • 404 Not Found – Recorder not found

  Response JSON Object

  • spec.capture-length (integer) – Maximum packet length or zero for full packet length

  • spec.filters[].dst-port (string) – Layer 4 destination port, zero (or in future range)

  • spec.filters[].dst-prefix (string) – Layer 3 destination CIDR

  • spec.filters[].protocol (string) – Layer 4 protocol

  • spec.filters[].src-port (string) – Layer 4 source port, zero (or in future range)

  • spec.filters[].src-prefix (string) – Layer 3 source CIDR

  • spec.id (integer) – Unique identification (required)

  • status.realized.capture-length (integer) – Maximum packet length or zero for full packet length

  • status.realized.filters[].dst-port (string) – Layer 4 destination port, zero (or in future range)

  • status.realized.filters[].dst-prefix (string) – Layer 3 destination CIDR

  • status.realized.filters[].protocol (string) – Layer 4 protocol

  • status.realized.filters[].src-port (string) – Layer 4 source port, zero (or in future range)

  • status.realized.filters[].src-prefix (string) – Layer 3 source CIDR

  • status.realized.id (integer) – Unique identification (required)