openapi: 3.1.0
info:
  title: Cilium BGP Daemon API
  description: The Cilium REST API provides access to the Cilium daemon and agent endpoints for managing Kubernetes network policy, security, and connectivity. The API is served by the cilium-agent process over a local Unix domain socket and HTTP interface. It covers endpoint management, identity management, policy configuration, IP address management, service configuration, BGP operations, and daemon health status.
  version: v1beta1
  contact:
    name: Cilium Community
    url: https://cilium.io/get-help/
  termsOfService: https://cilium.io/privacy/
servers:
- url: http://localhost/v1
  description: Local Cilium Agent (Unix socket or HTTP)
tags:
- name: Daemon
  description: Cilium daemon configuration, health, and cluster management
paths:
  /healthz:
    get:
      operationId: getDaemonHealth
      summary: Cilium Get daemon health status
      description: Returns the overall health status of the Cilium daemon including connectivity to the kvstore, container runtime, Kubernetes API server, and the status of each configured subsystem.
      tags:
      - Daemon
      parameters:
      - $ref: '#/components/parameters/BriefParam'
      responses:
        '200':
          description: Daemon health status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /config:
    get:
      operationId: getDaemonConfig
      summary: Cilium Get daemon configuration
      description: Returns the current runtime configuration of the Cilium daemon, including mutable and immutable settings such as policy enforcement mode, enabled features, and address pool information.
      tags:
      - Daemon
      responses:
        '200':
          description: Daemon configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DaemonConfiguration'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchDaemonConfig
      summary: Cilium Modify daemon configuration
      description: Modifies the mutable runtime configuration of the Cilium daemon. Supports updating policy enforcement mode and feature toggles without restarting the agent.
      tags:
      - Daemon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DaemonConfigurationSpec'
      responses:
        '200':
          description: Configuration updated successfully
        '400':
          description: Invalid configuration parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cluster/nodes:
    get:
      operationId: getClusterNodes
      summary: Cilium List cluster nodes
      description: Returns information about all nodes in the Cilium cluster, including their addresses, health status, and connectivity information.
      tags:
      - Daemon
      parameters:
      - $ref: '#/components/parameters/ClientIDParam'
      responses:
        '200':
          description: Cluster node list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterNodeStatus'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /debuginfo:
    get:
      operationId: getDebugInfo
      summary: Cilium Get debugging information
      description: Returns comprehensive debugging information about the Cilium daemon, including BPF map state, policy state, endpoint information, and environment details useful for troubleshooting.
      tags:
      - Daemon
      responses:
        '200':
          description: Debug information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebugInfo'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /map:
    get:
      operationId: getBPFMaps
      summary: Cilium List BPF maps
      description: Returns a list of all open BPF maps used by the Cilium datapath, including their names, types, key/value sizes, and current entry counts.
      tags:
      - Daemon
      responses:
        '200':
          description: BPF map list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BPFMap'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /node/ids:
    get:
      operationId: getNodeIDs
      summary: Cilium Get node IDs
      description: Returns the mapping of node names to their allocated numeric node IDs used in the BPF datapath for traffic identification and policy enforcement.
      tags:
      - Daemon
      responses:
        '200':
          description: Node ID mappings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NodeID'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DaemonConfigurationStatus:
      type: object
      description: Current effective configuration of the Cilium daemon.
      properties:
        immutable:
          type: object
          description: Immutable configuration options.
          additionalProperties:
            type: string
        realized:
          $ref: '#/components/schemas/DaemonConfigurationSpec'
    StatusResponse:
      type: object
      description: Overall health and status of the Cilium daemon, including connectivity to external dependencies and subsystem health.
      properties:
        cilium:
          $ref: '#/components/schemas/Status'
        cluster:
          $ref: '#/components/schemas/ClusterStatus'
        container-runtime:
          $ref: '#/components/schemas/Status'
        controllers:
          $ref: '#/components/schemas/ControllerStatuses'
        ipam:
          $ref: '#/components/schemas/IPAMStatus'
        kube-proxy-replacement:
          $ref: '#/components/schemas/KubeProxyReplacementStatus'
        kubernetes:
          $ref: '#/components/schemas/K8sStatus'
        kvstore:
          $ref: '#/components/schemas/Status'
        nodeMonitor:
          $ref: '#/components/schemas/MonitorStatus'
    BPFMapEntry:
      type: object
      description: A single key-value entry in a BPF map.
      properties:
        key:
          type: string
          description: BPF map entry key.
        value:
          type: string
          description: BPF map entry value.
        desiredAction:
          type: string
          description: Desired reconciliation action for this entry.
    BPFMap:
      type: object
      description: Information about a BPF map used by the Cilium datapath.
      properties:
        path:
          type: string
          description: File system path to the pinned BPF map.
        cache:
          type: array
          items:
            $ref: '#/components/schemas/BPFMapEntry'
          description: Current entries in the BPF map.
    ClusterNodeStatus:
      type: object
      description: Cluster-wide node status and membership information.
      properties:
        self:
          type: string
          description: Name of this node.
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/NodeElement'
          description: All nodes in the cluster.
    DaemonConfigurationSpec:
      type: object
      description: Mutable configuration options for the Cilium daemon.
      properties:
        options:
          type: object
          description: Map of configuration option names to their values.
          additionalProperties:
            type: string
        policyEnforcement:
          type: string
          description: Policy enforcement mode.
          enum:
          - default
          - always
          - never
    NodeElement:
      type: object
      description: Information about a single cluster node.
      properties:
        name:
          type: string
          description: Node hostname.
        primaryAddress:
          $ref: '#/components/schemas/NodeAddress'
        health-endpoint-address:
          $ref: '#/components/schemas/NodeAddress'
        encryption:
          type: object
          description: Node encryption configuration.
    AddressPair:
      type: object
      description: IPv4 and IPv6 address pair for an endpoint.
      properties:
        ipv4:
          type: string
          description: IPv4 address.
        ipv6:
          type: string
          description: IPv6 address.
    ControllerStatus:
      type: object
      description: Status of a single Cilium background controller.
      properties:
        name:
          type: string
          description: Controller name.
        status:
          type: object
          description: Controller run status details.
          properties:
            consecutiveFailureCount:
              type: integer
              description: Number of consecutive failures.
            failureCount:
              type: integer
              description: Total failure count.
            lastFailureTimestamp:
              type: string
              format: date-time
              description: Time of last failure.
            lastSuccessTimestamp:
              type: string
              format: date-time
              description: Time of last success.
            successCount:
              type: integer
              description: Total success count.
    Identity:
      type: object
      description: A Cilium security identity, derived from the set of labels associated with a workload and used for policy enforcement decisions.
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identity ID.
        labels:
          type: array
          items:
            type: string
          description: Labels that define this identity.
        labelsSHA256:
          type: string
          description: SHA256 hash of the label set for change detection.
    NodeID:
      type: object
      description: Mapping of a node name to its numeric datapath ID.
      properties:
        id:
          type: integer
          description: Numeric node ID used in the BPF datapath.
        labels:
          type: array
          items:
            type: string
          description: Labels associated with this node.
        cidr:
          type: string
          description: CIDR block allocated to this node.
    Error:
      type: string
      description: Human-readable error message.
    KubeProxyReplacementStatus:
      type: object
      description: Status of the kube-proxy replacement functionality.
      properties:
        mode:
          type: string
          description: kube-proxy replacement mode (disabled, partial, strict).
    MonitorStatus:
      type: object
      description: Status of the Cilium node monitor.
      properties:
        cpus:
          type: integer
          description: Number of CPUs the monitor is running on.
        lost:
          type: integer
          format: int64
          description: Number of monitor events lost due to buffer overflow.
        unknown:
          type: integer
          format: int64
          description: Number of unknown monitor events received.
    K8sStatus:
      type: object
      description: Status of Kubernetes API server connectivity and version.
      properties:
        state:
          type: string
          description: Connection state to the Kubernetes API server.
        msg:
          type: string
          description: Additional Kubernetes connectivity information.
        k8s-api-versions:
          type: array
          items:
            type: string
          description: List of supported Kubernetes API versions.
    DebugInfo:
      type: object
      description: Comprehensive debugging information about the Cilium daemon.
      properties:
        cilium-version:
          type: string
          description: Cilium version string.
        kernel-version:
          type: string
          description: Linux kernel version.
        policy-information:
          type: object
          description: Current policy state.
        endpoint-list:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
          description: All managed endpoints.
    EndpointPolicyStatus:
      type: object
      description: Policy enforcement status for an endpoint.
      properties:
        allowed:
          type: object
          description: Map of allowed traffic flows.
        denied:
          type: object
          description: Map of denied traffic flows.
        realized:
          $ref: '#/components/schemas/EndpointPolicy'
        spec:
          $ref: '#/components/schemas/EndpointPolicy'
    DaemonConfiguration:
      type: object
      description: Current runtime configuration of the Cilium daemon.
      properties:
        spec:
          $ref: '#/components/schemas/DaemonConfigurationSpec'
        status:
          $ref: '#/components/schemas/DaemonConfigurationStatus'
    EndpointPolicy:
      type: object
      description: Desired or realized policy for an endpoint.
      properties:
        allowed-egress-identities:
          type: array
          items:
            type: integer
          description: Identity IDs that egress traffic is allowed to reach.
        allowed-ingress-identities:
          type: array
          items:
            type: integer
          description: Identity IDs allowed to send ingress traffic.
        cidr-policy:
          type: object
          description: CIDR-based policy configuration.
        id:
          type: integer
          description: Policy revision number.
    EndpointStatus:
      type: object
      description: Current status of an endpoint.
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        networking:
          $ref: '#/components/schemas/EndpointNetworking'
        policy:
          $ref: '#/components/schemas/EndpointPolicyStatus'
        state:
          type: string
          description: Current lifecycle state of the endpoint.
          enum:
          - waiting-for-identity
          - not-ready
          - waiting-to-regenerate
          - regenerating
          - restoring
          - ready
          - disconnecting
          - disconnected
          - invalid
        health:
          $ref: '#/components/schemas/EndpointHealth'
    ClusterStatus:
      type: object
      description: Status of the Cilium cluster mesh connectivity.
      properties:
        self:
          type: string
          description: Name of this cluster.
        nodes:
          type: object
          description: Map of node names to their connectivity status.
          additionalProperties:
            $ref: '#/components/schemas/NodeStatus'
    NodeAddress:
      type: object
      description: Network address information for a cluster node.
      properties:
        ip:
          type: string
          description: IP address of the node.
        allocationCIDR:
          type: string
          description: CIDR block allocated to this node for pod IPs.
    NodeStatus:
      type: object
      description: Connectivity and health status of a single cluster node.
      properties:
        name:
          type: string
          description: Node name.
        primaryAddress:
          $ref: '#/components/schemas/NodeAddress'
        healthEndpointAddress:
          $ref: '#/components/schemas/NodeAddress'
    EndpointSpec:
      type: object
      description: Desired configuration for an endpoint.
      properties:
        addressing:
          $ref: '#/components/schemas/AddressPair'
        containerID:
          type: string
          description: Container runtime ID for this endpoint.
        containerName:
          type: string
          description: Container name.
        k8sNamespace:
          type: string
          description: Kubernetes namespace.
        k8sPodName:
          type: string
          description: Kubernetes pod name.
        labels:
          type: array
          items:
            type: string
          description: Security labels associated with this endpoint.
    IPAMStatus:
      type: object
      description: Current IPAM pool usage and allocation statistics.
      properties:
        ipv4:
          type: array
          items:
            type: string
          description: List of allocated IPv4 addresses.
        ipv6:
          type: array
          items:
            type: string
          description: List of allocated IPv6 addresses.
    ControllerStatuses:
      type: object
      description: Map of controller names to their current status.
      additionalProperties:
        $ref: '#/components/schemas/ControllerStatus'
    Endpoint:
      type: object
      description: A Cilium-managed network endpoint, typically corresponding to a Kubernetes pod or container with associated identity and policy state.
      properties:
        id:
          type: integer
          format: int64
          description: Numeric endpoint ID assigned by Cilium.
        status:
          $ref: '#/components/schemas/EndpointStatus'
        spec:
          $ref: '#/components/schemas/EndpointSpec'
    Status:
      type: object
      description: Health status of a single Cilium subsystem or dependency.
      properties:
        state:
          type: string
          description: State of the subsystem. One of Ok, Warning, Failure, or Disabled.
          enum:
          - Ok
          - Warning
          - Failure
          - Disabled
        msg:
          type: string
          description: Additional message describing the current state.
    EndpointHealth:
      type: object
      description: Health status of an endpoint's BPF programs and policy.
      properties:
        bpf:
          type: string
          description: Health status of the BPF program for this endpoint.
        connected:
          type: boolean
          description: Whether the endpoint is connected to the network.
        overallHealth:
          type: string
          description: Overall health status of the endpoint.
        policy:
          type: string
          description: Health status of policy enforcement for this endpoint.
    EndpointNetworking:
      type: object
      description: Network addressing information for an endpoint.
      properties:
        addressing:
          type: array
          items:
            $ref: '#/components/schemas/AddressPair'
          description: IP addresses assigned to this endpoint.
        node:
          type: string
          description: IP address of the node hosting this endpoint.
  parameters:
    BriefParam:
      name: brief
      in: query
      required: false
      description: Return brief response with reduced detail.
      schema:
        type: boolean
    ClientIDParam:
      name: client-id
      in: query
      required: false
      description: Unique client ID for long-polling. Returns only changes since the last response to this client.
      schema:
        type: integer
        format: int64
externalDocs:
  description: Cilium API Documentation
  url: https://docs.cilium.io/en/stable/api/