The Dataplane API from Kuma — 2 operation(s) for dataplane.
openapi: 3.1.0
info:
title: Kuma Dataplane API
description: Kuma API
version: v1alpha1
x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: Dataplane
paths:
/meshes/{mesh}/dataplanes:
get:
operationId: getDataplaneList
parameters:
- description: offset in the list of entities
example: 0
in: query
name: offset
required: false
schema:
type: integer
- description: the number of items per page
in: query
name: size
required: false
schema:
default: 100
maximum: 1000
minimum: 1
type: integer
- description: filter by labels when multiple filters are present, they are ANDed
example:
label.k8s.kuma.io/namespace: my-ns
in: query
name: filter
required: false
schema:
properties:
key:
type: string
value:
type: string
type: object
- description: name of the mesh
in: path
name: mesh
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/DataplaneList'
summary: Returns a list of Dataplane in the mesh.
tags:
- Dataplane
/meshes/{mesh}/dataplanes/{name}:
delete:
operationId: deleteDataplane
parameters:
- description: name of the mesh
in: path
name: mesh
required: true
schema:
type: string
- description: name of the Dataplane
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/DataplaneDeleteSuccessResponse'
'404':
$ref: '#/components/responses/NotFound'
summary: Deletes Dataplane entity
tags:
- Dataplane
get:
operationId: getDataplane
parameters:
- description: name of the mesh
in: path
name: mesh
required: true
schema:
type: string
- description: name of the Dataplane
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/DataplaneItem'
'404':
$ref: '#/components/responses/NotFound'
summary: Returns Dataplane entity
tags:
- Dataplane
put:
operationId: putDataplane
parameters:
- description: name of the mesh
in: path
name: mesh
required: true
schema:
type: string
- description: name of the Dataplane
in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DataplaneItem'
description: Put request
required: true
responses:
'200':
$ref: '#/components/responses/DataplaneCreateOrUpdateSuccessResponse'
'201':
$ref: '#/components/responses/DataplaneCreateOrUpdateSuccessResponse'
summary: Creates or Updates Dataplane entity
tags:
- Dataplane
components:
responses:
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
DataplaneDeleteSuccessResponse:
content:
application/json:
schema:
type: object
description: Successful response
DataplaneList:
content:
application/json:
schema:
properties:
items:
items:
$ref: '#/components/schemas/DataplaneItem'
type: array
next:
description: URL to the next page
type: string
total:
description: The total number of entities
type: number
type: object
description: List
DataplaneItem:
content:
application/json:
schema:
$ref: '#/components/schemas/DataplaneItem'
description: Successful response
DataplaneCreateOrUpdateSuccessResponse:
content:
application/json:
schema:
properties:
warnings:
description: 'warnings is a list of warning messages to return to the requesting Kuma API clients.
Warning messages describe a problem the client making the API request should correct or be aware of.
'
items:
type: string
readOnly: true
type: array
type: object
description: Successful response
schemas:
PrometheusMetricsBackendConfig:
description: PrometheusMetricsBackendConfig defines configuration of Prometheus backend
properties:
aggregate:
description: 'Map with the configuration of applications which metrics are going to be
scrapped by kuma-dp.'
items:
description: PrometheusAggregateMetricsConfig defines endpoints that should be scrapped by kuma-dp for prometheus metrics.
properties:
address:
description: Address on which a service expose HTTP endpoint with Prometheus metrics.
type: string
enabled:
description: 'If false then the application won''t be scrapped. If nil, then it is treated
as true and kuma-dp scrapes metrics from the service.'
type: boolean
name:
description: Name which identify given configuration.
type: string
path:
description: Path on which a service expose HTTP endpoint with Prometheus metrics.
type: string
port:
description: Port on which a service expose HTTP endpoint with Prometheus metrics.
type: integer
type: object
type: array
envoy:
description: Configuration of Envoy's metrics.
properties:
filterRegex:
description: 'FilterRegex value that is going to be passed to Envoy for filtering
Envoy metrics.'
type: string
usedOnly:
description: 'If true then return metrics that Envoy has updated (counters incremented
at least once, gauges changed at least once, and histograms added to at
least once). If nil, then it is treated as false.'
type: boolean
type: object
path:
description: 'Path on which a dataplane should expose HTTP endpoint with Prometheus
metrics.'
type: string
port:
description: 'Port on which a dataplane should expose HTTP endpoint with Prometheus
metrics.'
type: integer
skipMTLS:
description: 'If true then endpoints for scraping metrics won''t require mTLS even if mTLS
is enabled in Mesh. If nil, then it is treated as false.'
type: boolean
tags:
additionalProperties:
type: string
description: 'Tags associated with an application this dataplane is deployed next to,
e.g. service=web, version=1.0.
`service` tag is mandatory.'
type: object
tls:
description: Configuration of TLS for prometheus listener.
properties:
mode:
description: 'mode defines how configured is the TLS for Prometheus.
Supported values, delegated, disabled, activeMTLSBackend. Default to
`activeMTLSBackend`.'
oneOf:
- type: string
- type: integer
type: object
type: object
NotFoundError:
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
status:
type: integer
enum:
- 404
example: 404
description: 'The HTTP status code for NotFoundError MUST be 404.
'
title:
type: string
example: Not Found
type:
type: string
example: https://httpstatuses.com/404
detail:
type: string
example: The requested resource was not found
InvalidParameters:
type: object
title: Invalid Parameters
required:
- field
- reason
- source
properties:
field:
type: string
description: The name of the field that caused the error.
reason:
type: string
description: 'A short, human-readable description of the problem.
_Should_ be provided as "Sentence case" for direct use in a UI.
'
rule:
type: string
description: 'May be provided as a hint to the user to help understand the type of failure.
Additional guidance may be provided in additional fields, i.e. `choices`.
'
choices:
type: array
description: 'Optional field to provide a list of valid choices for the field that caused the error.
'
items:
type: string
source:
type: string
description: 'The location of the field that caused the error.
'
enum:
- body
- query
- header
- path
DataplaneItem:
properties:
labels:
additionalProperties:
type: string
type: object
mesh:
type: string
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
name:
type: string
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:
type: string
required:
- type
- name
- mesh
type: object
Error:
type: object
title: Error
description: 'Standard error. Follows the [AIP #193 - Errors](https://kong-aip.netlify.app/aip/193/) specification.
'
x-examples:
Example 1:
status: 404
title: Not Found
type: https://kongapi.info/konnect/not-found
instance: portal:trace:2287285207635123011
detail: The requested document was not found
required:
- status
- title
- instance
- type
- detail
properties:
status:
type: integer
description: The HTTP status code.
example: 404
title:
type: string
description: 'A short, human-readable summary of the problem.
It **should not** change between occurrences of a problem, except for localization.
Should be provided as "Sentence case" for potential direct use in a UI
'
example: Not Found
type:
type: string
description: 'A unique identifier for this error. When dereferenced it must provide human-readable documentation for the problem.
'
example: Not Found
instance:
type: string
example: portal:trace:2287285207635123011
description: 'Used to return the correlation ID back to the user, in the format `<app>:trace:<correlation_id>`.
'
detail:
type: string
example: The requested team was not found
description: 'A human readable explanation specific to this occurrence of the problem.
This field may contain request/entity data to help the user understand what went wrong.
Enclose variable values in square brackets.
_Should_ be provided as "Sentence case" for direct use in a UI
'
invalid_parameters:
type: array
description: 'All 400 errors **MUST** return an `invalid_parameters` key in the response.
Used to indicate which fields have invalid values when validated.
'
items:
$ref: '#/components/schemas/InvalidParameters'
securitySchemes:
BasicAuth:
type: http
scheme: basic
BearerAuth:
type: http
scheme: bearer