The Meshes API from Kuma — 9 operation(s) for meshes.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/kuma-meshes-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Kuma Dataplane Meshes API
description: Kuma API
version: v1alpha1
x-ref-schema-name: DataplaneOverview
servers:
- url: https://localhost:5681
description: Base URL declared by the provider in apis.yml (roadmap#122).
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:
schemas:
DataplaneOverviewWithMeta:
allOf:
- $ref: '#/components/schemas/Meta'
- $ref: '#/components/schemas/DataplaneOverview'
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.
'
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 or ZoneEgress for outbound external traffic.'
oneOf:
- type: string
- type: integer
type: object
type: array
outbound:
description: 'Outbound describes a list of services consumed by the data plane proxy.
For every defined Outbound, there is a corresponding Envoy Listener.'
items:
description: Outbound describes a service consumed by the data plane proxy.
properties:
address:
description: 'IP on which the consumed service will be available to this data plane
proxy. On Kubernetes, it''s usually ClusterIP of a Service or PodIP of a
Headless Service. Defaults to 127.0.0.1'
type: string
backendRef:
description: 'BackendRef is a way to target MeshService.
Experimental. Do not use on production yet.'
properties:
kind:
description: 'Kind is a type of the object to target. Allowed: MeshService'
type: string
labels:
additionalProperties:
type: string
description: 'Labels to select a single object.
If no object is selected then outbound is not created.
If multiple objects are selected then the oldest one is used.'
type: object
name:
description: Name of the targeted object
type: string
port:
description: Port of the targeted object. Required when kind is MeshService.
type: integer
type: object
port:
description: 'Port on which the consumed service will be available to this data plane
proxy. When transparent proxying is not used, Envoy will bind to this
port.'
type: integer
tags:
additionalProperties:
type: string
description: 'Tags of consumed data plane proxies.
`kuma.io/service` tag is required.
These tags can then be referenced in `destinations` section of policies
like TrafficRoute or in `to` section in policies like MeshAccessLog. It
is recommended to only use `kuma.io/service`. If you need to consume
specific data plane proxy of a service (for example: `version=v2`) the
better practice is to use TrafficRoute.'
type: object
type: object
type: array
transparentProxying:
description: 'TransparentProxying describes the configuration for transparent proxying.
It is used by default on Kubernetes.'
properties:
directAccessServices:
description: 'List of services that will be accessed directly via IP:PORT
Use `*` to indicate direct access to every service in the Mesh.
Using `*` to directly access every service is a resource-intensive
operation, use it only if needed.'
items:
type: string
type: array
ipFamilyMode:
description: The IP family mode to enable for. Can be "IPv4" or "DualStack".
oneOf:
- type: string
- type: integer
reachableBackends:
description: 'Reachable backend via transparent proxy when running with
MeshExternalService, MeshService and MeshMultiZoneService. Setting an
explicit list of refs can dramatically improve the performance of the
mesh. If not specified, all services in the mesh are reachable.'
properties:
refs:
items:
properties:
kind:
description: "Type of the backend: MeshService or MeshExternalService\n\n\t+required"
type: string
labels:
additionalProperties:
type: string
description: "Labels used to select backends\n\n\t+optional"
type: object
name:
description: "Name of the backend.\n\n\t+optional"
type: string
namespace:
description: "Namespace of the backend. Might be empty\n\n\t+optional"
type: string
port:
description: "Port of the backend.\n\n\t+optional"
format: uint32
type: integer
type: object
type: array
type: object
reachableServices:
description: 'List of reachable services (represented by the value of
`kuma.io/service`) via transparent proxying. Setting an explicit list
can dramatically improve the performance of the mesh. If not specified,
all services in the mesh are reachable.'
items:
type: string
type: array
redirectPortInbound:
description: Port on which all inbound traffic is being transparently redirected.
type: integer
redirectPortOutbound:
description: Port on which all outbound traffic is being transparently redirected.
type: integer
type: object
type: object
probes:
description: 'Probes describe a list of endpoints that will be exposed without mTLS.
This is useful to expose the health endpoints of the application so the
orchestration system (e.g. Kubernetes) can still health check the
application.
See
https://kuma.io/docs/latest/policies/service-health-probes/#virtual-probes
for more information.
Deprecated: this feature will be removed for Universal; on Kubernetes, it''s
not needed anymore.'
properties:
endpoints:
description: List of endpoints to expose without mTLS.
items:
properties:
inboundPath:
description: 'Inbound path is a path of the application from which we expose the
endpoint. It is recommended to be as specific as possible.'
type: string
inboundPort:
description: 'Inbound port is a port of the application from which we expose the
endpoint.'
type: integer
path:
description: Path is a path on which we expose inbound path on the probes port.
type: string
type: object
type: array
port:
description: 'Port on which the probe endpoints will be exposed. This cannot overlap
with any other ports.'
type: integer
type: object
type: object
dataplaneInsight:
properties:
mTLS:
description: Insights about mTLS for Dataplane.
properties:
certificateExpirationTime:
description: 'Expiration time of the last certificate that was generated for a
Dataplane.'
properties:
nanos:
type: integer
seconds:
type: integer
type: object
certificateRegenerations:
description: Number of certificate regenerations for a Dataplane.
type: integer
issuedBackend:
description: Backend that was used to generate current certificate
type: string
lastCertificateRegeneration:
description: Time on which the last certificate was generated.
properties:
nanos:
type: integer
seconds:
type: integer
type: object
supportedBackends:
description: Supported backends (CA).
items:
# --- 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