Kuma Meshes API

openapi: 3.1.0
info:
  title: Kuma Dataplane Meshes API
  description: Kuma API
  version: v1alpha1
  x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: Meshes
paths:
  /meshes/{mesh}/dataplanes/{name}/_config:
    get:
      operationId: get-dataplanes-xds-config
      summary: Get a proxy XDS config on a CP, this endpoint is only available on zone CPs.
      description: Returns the [xds](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol) configuration of the proxy.
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the diff for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the diff for.
        schema:
          type: string
      - in: query
        name: shadow
        description: 'When computing XDS config the CP take into account policies with ''kuma.io/effect: shadow'' label

          '
        schema:
          type: boolean
          default: false
      - in: query
        name: include
        description: 'An array of extra fields to include in the response. When `include=diff` the server computes a diff in JSONPatch format

          between the current proxy XDS config and the config returned in the ''xds'' field.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - diff
      responses:
        '200':
          $ref: '#/components/responses/GetDataplaneXDSConfigResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/{name}/_layout:
    get:
      operationId: get-dataplanes-layout
      summary: Get networking layout for this dataplane
      description: Returns detailed dataplane networking layout with most important information on dataplane and list of its inbounds and outbounds
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the layout for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the layout for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/DataplaneNetworkingLayoutResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/{name}/_policies:
    get:
      operationId: get-proxy-policy-conf
      summary: Get proxy policies for this dataplane
      description: Returns proxy level policy configuration derived from combining all proxy policies selecting this dataplane
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the diff for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the diff for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/ProxyPolicyConfResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/{name}/_inbounds/{inbound-kri}/_policies:
    get:
      operationId: get-inbound-policy-conf
      summary: Get policies for this inbound
      description: Returns inbound policy configuration derived from combining all policies selecting this dataplane
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the policies for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the policies for.
        schema:
          type: string
      - in: path
        name: inbound-kri
        required: true
        description: The name of the Inbound from DPP to get the policies for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/InboundPolicyConfResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/{name}/_outbounds/{kri}/_policies:
    get:
      operationId: get-outbound-policy-conf
      summary: Get policies for this outbound
      description: Returns outbound policy configuration derived from combining all policies selecting this dataplane
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the policies for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the policies for.
        schema:
          type: string
      - in: path
        name: kri
        required: true
        description: The KRI of the Outbound to get the policies for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/OutboundPolicyConfResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/{name}/_outbounds/{kri}/_routes:
    get:
      operationId: get-outbound-routes
      summary: Get routes configuration for this outbound
      description: Returns routes configuration derived from combining all routes on this outbound
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the policies for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the policies for.
        schema:
          type: string
      - in: path
        name: kri
        required: true
        description: The KRI of the Outbound to get the routes for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/RoutesListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/{name}/_outbounds/{outbound-kri}/_routes/{route-kri}/_policies:
    get:
      operationId: get-route-policy-conf
      summary: Get policies for this route
      description: Returns route policy configuration derived from combining all policies selecting this dataplane
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the policies for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the policies for.
        schema:
          type: string
      - in: path
        name: outbound-kri
        required: true
        description: The KRI of the Outbound to get the routes for.
        schema:
          type: string
      - in: path
        name: route-kri
        required: true
        description: The KRI of the Route to get the configuration for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/RoutePolicyConfResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/{name}/_overview:
    get:
      operationId: getDataplaneOverview
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the diff for.
        schema:
          type: string
      - in: path
        name: name
        required: true
        description: The name of the DPP within the mesh to get the diff for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GetDataplaneOverviewResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
  /meshes/{mesh}/dataplanes/_overview:
    get:
      operationId: getDataplaneOverviewList
      parameters:
      - in: path
        name: mesh
        required: true
        description: The mesh of the DPP to get the diff for.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/GetDataplaneOverviewListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
      tags:
      - Meshes
components:
  responses:
    Internal:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    GetDataplaneOverviewResponse:
      description: A response containing the overview of a dataplane.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataplaneOverviewWithMeta'
    GetDataplaneXDSConfigResponse:
      description: Successfully retrieved proxy XDS config.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataplaneXDSConfig'
    InboundPolicyConfResponse:
      description: A response containing policies configuration for selected inbound
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InboundPoliciesList'
    DataplaneNetworkingLayoutResponse:
      description: A response containing dataplane networking layout.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataplaneNetworkingLayout'
    GetDataplaneOverviewListResponse:
      description: A response containing the overview of a dataplane.
      content:
        application/json:
          schema:
            type: object
            properties:
              total:
                type: integer
                example: 200
              next:
                type: string
              items:
                type: array
                items:
                  $ref: '#/components/schemas/DataplaneOverviewWithMeta'
    RoutePolicyConfResponse:
      description: A response containing policies configuration for selected route
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoliciesList'
    RoutesListResponse:
      description: A response containing routes configuration for selected outbound
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RoutesList'
    ProxyPolicyConfResponse:
      description: A response containing policies configuration for selected dataplane
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoliciesList'
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    OutboundPolicyConfResponse:
      description: A response containing policies configuration for selected outbound
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PoliciesList'
  schemas:
    Meta:
      type: object
      required:
      - type
      - mesh
      - name
      - labels
      properties:
        type:
          type: string
          example: Dataplane
          description: the type of this resource
        mesh:
          type: string
          example: default
          description: the mesh this resource is part of
        name:
          type: string
          example: my-resource
          description: the name of the resource
        kri:
          type: string
          readOnly: true
          x-go-name: KRI
          example: kri_mtp_default_zone-east_kuma-demo_mypolicy1_
          description: Kuma Resource Identifier (KRI) of the given resource
        labels:
          type: object
          additionalProperties:
            type: string
          example:
            k8s.kuma.io/namespace: kuma-system
            kuma.io/display-name: mtp
            kuma.io/mesh: default
            kuma.io/origin: zone
          description: 'Labels of the resource. Note: certain system labels are immutable after creation:

            - `kuma.io/origin`: Resource origin (zone/global). Immutable.

            - `kuma.io/zone`: Zone where resource originated. Immutable.

            - `kuma.io/display-name`: Display name for the resource. Immutable.

            '
    DataplaneInbound:
      type: object
      required:
      - kri
      - port
      - protocol
      - proxyResourceName
      properties:
        kri:
          type: string
        port:
          type: integer
          x-go-type: int32
        protocol:
          type: string
        proxyResourceName:
          type: string
    JsonPatchItem:
      type: object
      required:
      - op
      - path
      - value
      properties:
        op:
          type: string
          description: Operation to be performed.
          enum:
          - add
          - remove
          - test
        path:
          type: string
          description: A JSON Pointer path indicating the part of the document to operate on.
        value:
          description: The value to be used within the operations.
    RouteRules:
      type: object
      required:
      - kri
      - conf
      - matches
      properties:
        kri:
          type: string
        matches:
          type: array
          description: List of matches for which this rule will apply
          items:
            type: object
            additionalProperties: true
            x-go-type: interface{}
        conf:
          description: The final computed configuration for the data plane proxy, derived by merging all policies whose 'targetRef' field matches the proxy. The merging process follows [RFC 7396 (JSON Merge Patch)](https://datatracker.ietf.org/doc/html/rfc7396), with the order of merging influenced by factors such as where the policy was applied (e.g., custom namespace, system, or global control plane), policy role, and targetRef specificity.
          type: object
          additionalProperties: true
          x-go-type: interface{}
    RoutesList:
      type: object
      required:
      - routes
      properties:
        routes:
          type: array
          description: Computed list of routes
          items:
            $ref: '#/components/schemas/RouteConf'
    DataplaneOverviewWithMeta:
      allOf:
      - $ref: '#/components/schemas/Meta'
      - $ref: '#/components/schemas/DataplaneOverview'
    InboundPoliciesList:
      type: object
      required:
      - policies
      properties:
        policies:
          type: array
          description: The final computed configuration, derived by merging all policies whose 'targetRef' field matches the proxy. The merging process follows [RFC 7396 (JSON Merge Patch)](https://datatracker.ietf.org/doc/html/rfc7396), with the order of merging influenced by factors such as where the policy was applied (e.g., custom namespace, system, or global control plane), policy role, and targetRef specificity.
          items:
            $ref: '#/components/schemas/InboundPolicyConf'
    RouteConf:
      type: object
      required:
      - kind
      - rules
      - origins
      properties:
        kind:
          type: string
        rules:
          type: array
          description: Computed list of routing rules
          items:
            $ref: '#/components/schemas/RouteRules'
        origins:
          type: array
          description: The list of policies KRI that contributed to the 'conf'. The order is important as it reflects in what order confs were merged to get the resulting 'conf'.
          items:
            $ref: '#/components/schemas/PolicyOrigin'
    PoliciesList:
      type: object
      required:
      - policies
      properties:
        policies:
          type: array
          description: The final computed configuration, derived by merging all policies whose 'targetRef' field matches the proxy. The merging process follows [RFC 7396 (JSON Merge Patch)](https://datatracker.ietf.org/doc/html/rfc7396), with the order of merging influenced by factors such as where the policy was applied (e.g., custom namespace, system, or global control plane), policy role, and targetRef specificity.
          items:
            $ref: '#/components/schemas/PolicyConf'
    PolicyConf:
      type: object
      required:
      - kind
      - conf
      - origins
      properties:
        kind:
          type: string
        conf:
          description: The final computed configuration for the data plane proxy, derived by merging all policies whose 'targetRef' field matches the proxy. The merging process follows [RFC 7396 (JSON Merge Patch)](https://datatracker.ietf.org/doc/html/rfc7396), with the order of merging influenced by factors such as where the policy was applied (e.g., custom namespace, system, or global control plane), policy role, and targetRef specificity.
          type: object
          additionalProperties: true
          x-go-type: interface{}
        origins:
          type: array
          description: The list of policies KRI that contributed to the 'conf'. The order is important as it reflects in what order confs were merged to get the resulting 'conf'.
          items:
            $ref: '#/components/schemas/PolicyOrigin'
    DataplaneNetworkingLayout:
      type: object
      title: DataplaneLayout
      description: Dataplane networking layout. It contains the most important information about the dataplane and lists the available inbounds, outbounds, and zone proxy listeners
      required:
      - kri
      - labels
      - inbounds
      - outbounds
      - listeners
      properties:
        kri:
          type: string
          example: kri_dp_default_default_kuma-demo_demo-app-75ff54499c-ttwd7_http-port
        labels:
          type: object
          additionalProperties:
            type: string
          example:
            k8s.kuma.io/namespace: kuma-demo
            kuma.io/display-name: demo-app
            kuma.io/mesh: default
            kuma.io/origin: zone
        inbounds:
          type: array
          items:
            $ref: '#/components/schemas/DataplaneInbound'
        outbounds:
          type: array
          items:
            $ref: '#/components/schemas/DataplaneOutbound'
        listeners:
          type: array
          items:
            $ref: '#/components/schemas/DataplaneListener'
        spiffeId:
          type: string
          description: SPIFFE ID of the dataplane's workload identity certificate
    InboundPolicyConf:
      type: object
      required:
      - kind
      - rules
      - origins
      properties:
        kind:
          type: string
        rules:
          type: array
          items:
            $ref: '#/components/schemas/PolicyRule'
        origins:
          type: array
          description: The list of policies KRI that contributed to the 'conf'. The order is important as it reflects in what order confs were merged to get the resulting 'conf'.
          items:
            $ref: '#/components/schemas/PolicyOrigin'
    PolicyRule:
      type: object
      required:
      - conf
      properties:
        conf:
          description: The final computed configuration for the data plane proxy, derived by merging all policies whose 'targetRef' field matches the proxy. The merging process follows [RFC 7396 (JSON Merge Patch)](https://datatracker.ietf.org/doc/html/rfc7396), with the order of merging influenced by factors such as where the policy was applied (e.g., custom namespace, system, or global control plane), policy role, and targetRef specificity.
          type: object
          additionalProperties: true
          x-go-type: interface{}
        kri:
          type: string
    DataplaneOverview:
      description: DataplaneOverview defines the projected state of a Dataplane.
      properties:
        dataplane:
          properties:
            metrics:
              description: 'Configuration for metrics that should be collected and exposed by the

                data plane proxy.


                Settings defined here will override their respective defaults

                defined at a Mesh level.'
              properties:
                conf:
                  oneOf:
                  - $ref: '#/components/schemas/PrometheusMetricsBackendConfig'
                  type: object
                name:
                  description: Name of the backend, can be then used in Mesh.metrics.enabledBackend
                  type: string
                type:
                  description: Type of the backend (Kuma ships with 'prometheus')
                  type: string
              type: object
            networking:
              description: 'Networking describes inbound and outbound interfaces of the data plane

                proxy.'
              properties:
                address:
                  description: 'IP on which the data plane proxy is accessible to the control plane and

                    other data plane proxies in the same network. This can also be a

                    hostname, in which case the control plane will periodically resolve it.'
                  type: string
                admin:
                  description: 'Admin describes configuration related to Envoy Admin API.

                    Due to security, all the Envoy Admin endpoints are exposed only on

                    localhost. Additionally, Envoy will expose `/ready` endpoint on

                    `networking.address` for health checking systems to be able to check the

                    state of Envoy. The rest of the endpoints exposed on `networking.address`

                    are always protected by mTLS and only meant to be consumed internally by

                    the control plane.'
                  properties:
                    port:
                      description: Port on which Envoy Admin API server will be listening
                      type: integer
                  type: object
                advertisedAddress:
                  description: 'In some situations, a data plane proxy resides in a private network (e.g.

                    Docker) and is not reachable via `address` to other data plane proxies.

                    `advertisedAddress` is configured with a routable address for such data

                    plane proxy so that other proxies in the mesh can connect to it over

                    `advertisedAddress` and not via address.


                    Envoy still binds to the `address`, not `advertisedAddress`.'
                  type: string
                gateway:
                  description: Gateway describes a configuration of the gateway of the data plane proxy.
                  properties:
                    tags:
                      additionalProperties:
                        type: string
                      description: 'Tags associated with a gateway of this data plane to, e.g.

                        `kuma.io/service=gateway`, `env=prod`. `kuma.io/service` tag is

                        mandatory.'
                      type: object
                    type:
                      description: 'Type of gateway this data plane proxy manages.

                        There are two types: `DELEGATED` and `BUILTIN`. Defaults to

                        `DELEGATED`.


                        A `DELEGATED` gateway is an independently deployed proxy (e.g., Kong,

                        Contour, etc) that receives inbound traffic that is not proxied by

                        Kuma, and it sends outbound traffic into the data plane proxy.


                        The `BUILTIN` gateway type causes the data plane proxy itself to be

                        configured as a gateway.


                        See https://kuma.io/docs/latest/explore/gateway/ for more information.'
                      oneOf:
                      - type: string
                      - type: integer
                  type: object
                inbound:
                  description: 'Inbound describes a list of inbound interfaces of the data plane proxy.


                    Inbound describes a service implemented by the data plane proxy.

                    All incoming traffic to a data plane proxy is going through inbound

                    listeners. For every defined Inbound there is a corresponding Envoy

                    Listener.'
                  items:
                    description: Inbound describes a service implemented by the data plane proxy.
                    properties:
                      address:
                        description: 'Address on which inbound listener will be exposed.

                          Defaults to `networking.address`.'
                        type: string
                      health:
                        description: 'Health describes the status of an inbound.

                          If ''health'' is nil we consider data plane proxy as healthy.

                          Unhealthy data plane proxies are excluded from Endpoints Discovery

                          Service (EDS). On Kubernetes, it is filled automatically by the control

                          plane if Pod has readiness probe configured. On Universal, it can be

                          set by the external health checking system, but the most common way is

                          to use service probes.


                          See https://kuma.io/docs/latest/documentation/health for more

                          information.'
                        properties:
                          ready:
                            description: 'Ready indicates if the data plane proxy is ready to serve the

                              traffic.'
                            type: boolean
                        type: object
                      name:
                        description: Name adds another way of referencing this port, usable with MeshService
                        type: string
                      port:
                        description: 'Port of the inbound interface that will forward requests to the

                          service.


                          When transparent proxying is used, it is a port on which the service is

                          listening to. When transparent proxying is not used, Envoy will bind to

                          this port.'
                        type: integer
                      protocol:
                        description: Protocol of the service (tcp, http, grpc, etc).
                        type: string
                      serviceAddress:
                        description: 'Address of the service that requests will be forwarded to.

                          Defaults to ''inbound.address'', since Kuma DP should be deployed next

                          to the service.'
                        type: string
                      servicePort:
                        description: 'Port of the service that requests will be forwarded to.

                          Defaults to the same value as `port`.'
                        type: integer
                      serviceProbe:
                        description: 'ServiceProbe defines parameters for probing the service next to

                          sidecar. When service probe is defined, Envoy will periodically health

                          check the application next to it and report the status to the control

                          plane. On Kubernetes, Kuma deployments rely on Kubernetes probes so

                          this is not used.


                          See https://kuma.io/docs/latest/documentation/health for more

                          information.'
                        properties:
                          healthyThreshold:
                            description: 'Number of consecutive healthy checks before considering a host

                              healthy.'
                            format: uint32
                            type: integer
                          interval:
                            description: Interval between consecutive health checks.
                            properties:
                              nanos:
                                type: integer
                              seconds:
                                type: integer
                            type: object
                          tcp:
                            description: Tcp checker tries to establish tcp connection with destination
                            properties: {}
                            type: object
                          timeout:
                            description: Maximum time to wait for a health check response.
                            properties:
                              nanos:
                                type: integer
                              seconds:
                                type: integer
                            type: object
                          unhealthyThreshold:
                            description: 'Number of consecutive unhealthy checks before considering a host

                              unhealthy.'
                            format: uint32
                            type: integer
                        type: object
                      state:
                        description: State describes the current state of the listener.
                        oneOf:
                        - type: string
                        - type: integer
                      tags:
                        additionalProperties:
                          type: string
                        description: 'Tags associated with an application this data plane proxy is deployed

                          next to, e.g. `kuma.io/service=web`, `version=1.0`. You can then

                          reference these tags in policies like MeshTrafficPermission.

                          `kuma.io/service` tag is mandatory.'
                        type: object
                    type: object
                  type: array
                listeners:
                  description: 'Listeners describes zone proxy listeners embedded in this Dataplane.

                    Listeners may coexist with inbounds and gateways.'
                  items:
                    description: Listener describes a zone proxy listener (ZoneIngress or ZoneEgress) embedded in a regular Dataplane.
                    properties:
                      address:
                        description: Address on which the listener will be exposed.
                        type: string
                      name:
                        description: 'Name uniquely identifies this listener within the Dataplane and is

                          used to reference it via sectionName in policies.

                          Optional: if unset, the port value is used as the name (as a string).'
                        type: string
                      port:
                        description: Port on which the listener will be exposed.
                        type: integer
                      state:
                        description: 'State describes the current health state of the listener.

                          The control plane sets this based on the readiness of the underlying

                          pod and sidecar container.'
                        oneOf:
                        - type: string
                        - type: integer
                      type:
                        description: 'Type determines the role of this listener: ZoneIngress for inbound

                          cross-zone traffic

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kuma/refs/heads/main/openapi/kuma-meshes-api-openapi.yml