Envoy Proxy Cluster Discovery API

openapi: 3.1.0
info:
  title: Envoy Proxy Admin Certificates Cluster Discovery API
  description: The Envoy Proxy Administration Interface provides a local HTTP-based management API for querying and modifying various aspects of the Envoy server at runtime. It serves as a critical operational tool for monitoring, debugging, and managing Envoy proxy instances. The admin interface typically runs on port 9901 by default. All mutation operations must be sent as HTTP POST requests; GET requests will not perform changes. Note that this endpoint is not authenticated, so access should be restricted in production environments.
  version: 1.38.0
  contact:
    name: Envoy Proxy
    url: https://www.envoyproxy.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:9901
  description: Default Envoy Admin Interface
tags:
- name: Cluster Discovery
  description: Cluster Discovery Service (CDS) endpoints for dynamically discovering upstream clusters.
paths:
  /v3/discovery:clusters:
    post:
      operationId: discoverClusters
      summary: Envoy Proxy Cluster Discovery Service (CDS)
      description: Fetches cluster configuration from the management server. The Cluster Discovery Service (CDS) returns a set of dynamically discovered upstream clusters that Envoy should route traffic to. Each cluster defines how Envoy connects to a group of upstream hosts including load balancing policy, connection limits, circuit breaking thresholds, and health checking configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoveryRequest'
      responses:
        '200':
          description: Successful cluster discovery response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryResponse'
      tags:
      - Cluster Discovery
components:
  schemas:
    Node:
      type: object
      description: Identifies the Envoy instance making a discovery request. Contains metadata about the proxy node including its identity, cluster membership, locality, and build version.
      properties:
        id:
          type: string
          description: An opaque node identifier for the Envoy instance. This must be set when using any of the xDS APIs.
        cluster:
          type: string
          description: The cluster that the Envoy instance belongs to. Defines the redundancy domain for the proxy.
        metadata:
          type: object
          additionalProperties: true
          description: Opaque metadata extending the node identifier. Used by the management server for filtering and configuration targeting.
        locality:
          type: object
          description: The locality the Envoy instance is running in.
          properties:
            region:
              type: string
              description: Region this proxy belongs to.
            zone:
              type: string
              description: Zone within the region.
            sub_zone:
              type: string
              description: Sub-zone within the zone.
        user_agent_name:
          type: string
          description: Free-form string that identifies the entity requesting config, e.g. envoy or grpc.
        user_agent_version:
          type: string
          description: Free-form string that identifies the version of the requesting entity.
    DiscoveryResponse:
      type: object
      description: A response from the management server containing xDS resources. The resources are encoded as protobuf Any messages and identified by their type URL.
      properties:
        version_info:
          type: string
          description: The version of the response data, used for ACK/NACK and request-response pairing.
        resources:
          type: array
          items:
            type: object
            properties:
              '@type':
                type: string
                description: The type URL identifying the resource type.
            additionalProperties: true
          description: The xDS resources being returned.
        type_url:
          type: string
          description: The type URL of the resources in this response.
        nonce:
          type: string
          description: A nonce that must be provided in the next DiscoveryRequest to ACK or NACK this response.
        control_plane:
          type: object
          description: The control plane instance that sent the response.
          properties:
            identifier:
              type: string
              description: An opaque identifier for the control plane.
    DiscoveryRequest:
      type: object
      description: A request from an Envoy instance to the management server for xDS resources. Contains the node identity, requested resource names, the type URL of the resource being requested, and version information for ACK/NACK semantics.
      properties:
        version_info:
          type: string
          description: The version of the resources being requested. On the first request this is empty. On subsequent requests it is the version received in the last DiscoveryResponse.
        node:
          $ref: '#/components/schemas/Node'
        resource_names:
          type: array
          items:
            type: string
          description: List of resource names to subscribe to. For LDS and CDS, this is typically empty to receive all resources. For RDS and EDS, this contains the specific route configuration or cluster names.
        type_url:
          type: string
          description: The type URL of the resource being requested, such as type.googleapis.com/envoy.config.cluster.v3.Cluster.
        response_nonce:
          type: string
          description: The nonce from the most recent successfully processed DiscoveryResponse. Used to pair requests with responses.
        error_detail:
          type: object
          description: Error details when the previous DiscoveryResponse could not be applied. Populated when NACKing a configuration update.
          properties:
            code:
              type: integer
              description: gRPC status code.
            message:
              type: string
              description: Error message describing the rejection reason.