Documentation
Documentation
https://kuma.io/docs/latest/reference/http-api/
GettingStarted
https://kuma.io/docs/latest/installation/
OpenAPI Specification
openapi: 3.1.0
info:
title: Kuma Dataplane Mesh API
description: Kuma API
version: v1alpha1
x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: Mesh
paths:
/meshes:
get:
operationId: getMeshList
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
responses:
'200':
$ref: '#/components/responses/MeshList'
summary: Returns a list of Mesh in the mesh.
tags:
- Mesh
/meshes/{name}:
delete:
operationId: deleteMesh
parameters:
- description: name of the Mesh
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/MeshDeleteSuccessResponse'
'404':
$ref: '#/components/responses/NotFound'
summary: Deletes Mesh entity
tags:
- Mesh
get:
operationId: getMesh
parameters:
- description: name of the Mesh
in: path
name: name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/MeshItem'
'404':
$ref: '#/components/responses/NotFound'
summary: Returns Mesh entity
tags:
- Mesh
put:
operationId: putMesh
parameters:
- description: name of the Mesh
in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MeshItem'
description: Put request
required: true
responses:
'200':
$ref: '#/components/responses/MeshCreateOrUpdateSuccessResponse'
'201':
$ref: '#/components/responses/MeshCreateOrUpdateSuccessResponse'
summary: Creates or Updates Mesh entity
tags:
- Mesh
components:
schemas:
DataSource_File:
properties:
file:
description: 'Data source is a path to a file.
Deprecated, use other sources of a data.'
type: string
type: object
BuiltinCertificateAuthorityConfig:
properties:
caCert:
properties:
expiration:
type: string
rsaBits:
format: uint32
type: integer
type: object
type: object
DataSource_InlineString:
properties:
inlineString:
description: Data source is inline string
type: string
type: object
TcpLoggingBackendConfig:
description: TcpLoggingBackendConfig defines configuration for TCP based access logs
properties:
address:
description: Address to TCP service that will receive logs
type: string
type: object
FileLoggingBackendConfig:
description: FileLoggingBackendConfig defines configuration for file based access logs
properties:
path:
description: Path to a file that logs will be written to
type: string
type: object
MeshItem:
properties:
constraints:
description: Constraints that applies to the mesh and its entities
properties:
dataplaneProxy:
description: 'DataplaneProxyMembership defines a set of requirements for data plane
proxies to be a member of the mesh.'
properties:
requirements:
description: 'Requirements defines a set of requirements that data plane proxies must
fulfill in order to join the mesh. A data plane proxy must fulfill at
least one requirement in order to join the mesh. Empty list of allowed
requirements means that any proxy that is not explicitly denied can join.'
items:
description: Rules defines a set of rules for data plane proxies to be member of the mesh.
properties:
tags:
additionalProperties:
type: string
description: 'Tags defines set of required tags. You can specify ''*'' in value to
require non empty value of tag'
type: object
type: object
type: array
restrictions:
description: 'Restrictions defines a set of restrictions that data plane proxies cannot
fulfill in order to join the mesh. A data plane proxy cannot fulfill any
requirement in order to join the mesh.
Restrictions takes precedence over requirements.'
items:
description: Rules defines a set of rules for data plane proxies to be member of the mesh.
properties:
tags:
additionalProperties:
type: string
description: 'Tags defines set of required tags. You can specify ''*'' in value to
require non empty value of tag'
type: object
type: object
type: array
type: object
type: object
labels:
additionalProperties:
type: string
type: object
logging:
description: 'Logging settings.
+optional'
properties:
backends:
description: List of available logging backends
items:
description: LoggingBackend defines logging backend available to mesh.
properties:
conf:
oneOf:
- $ref: '#/components/schemas/FileLoggingBackendConfig'
- $ref: '#/components/schemas/TcpLoggingBackendConfig'
type: object
format:
description: 'Format of access logs. Placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log'
type: string
name:
description: 'Name of the backend, can be then used in Mesh.logging.defaultBackend or in
TrafficLogging'
type: string
type:
description: Type of the backend (Kuma ships with 'tcp' and 'file')
type: string
type: object
type: array
defaultBackend:
description: Name of the default backend
type: string
type: object
meshServices:
properties:
mode:
oneOf:
- type: string
- type: integer
type: object
metrics:
description: 'Configuration for metrics collected and exposed by dataplanes.
Settings defined here become defaults for every dataplane in a given Mesh.
Additionally, it is also possible to further customize this configuration
for each dataplane individually using Dataplane resource.
+optional'
properties:
backends:
description: List of available Metrics backends
items:
description: MetricsBackend defines metric backends
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
type: array
enabledBackend:
description: Name of the enabled backend
type: string
type: object
mtls:
description: 'mTLS settings.
+optional'
properties:
backends:
description: List of available Certificate Authority backends
items:
description: CertificateAuthorityBackend defines Certificate Authority backend
properties:
conf:
oneOf:
- $ref: '#/components/schemas/ProvidedCertificateAuthorityConfig'
- $ref: '#/components/schemas/BuiltinCertificateAuthorityConfig'
type: object
dpCert:
description: Dataplane certificate settings
properties:
requestTimeout:
description: Timeout on request to CA for DP certificate generation and retrieval
properties:
nanos:
type: integer
seconds:
type: integer
type: object
rotation:
description: Rotation settings
properties:
expiration:
description: Time after which generated certificate for Dataplane will expire
type: string
type: object
type: object
mode:
description: 'Mode defines the behaviour of inbound listeners with regard to traffic
encryption'
oneOf:
- type: string
- type: integer
name:
description: Name of the backend
type: string
rootChain:
properties:
requestTimeout:
description: 'Timeout on request for to CA for root certificate chain.
If not specified, defaults to 10s.'
properties:
nanos:
type: integer
seconds:
type: integer
type: object
type: object
type:
description: 'Type of the backend. Has to be one of the loaded plugins (Kuma ships with
builtin and provided)'
type: string
type: object
type: array
enabledBackend:
description: Name of the enabled backend
type: string
skipValidation:
description: If enabled, skips CA validation.
type: boolean
type: object
name:
type: string
networking:
description: Networking settings of the mesh
properties:
outbound:
description: Outbound settings
properties:
passthrough:
description: Control the passthrough cluster
type: boolean
type: object
type: object
routing:
description: Routing settings of the mesh
properties:
defaultForbidMeshExternalServiceAccess:
description: 'If true, blocks traffic to MeshExternalServices.
Default: false'
type: boolean
localityAwareLoadBalancing:
description: Enable the Locality Aware Load Balancing
type: boolean
zoneEgress:
description: 'Enable routing traffic to services in other zone or external services
through ZoneEgress. Default: false'
type: boolean
type: object
skipCreatingInitialPolicies:
description: 'List of policies to skip creating by default when the mesh is created.
e.g. TrafficPermission, MeshRetry, etc. An ''*'' can be used to skip all
policies.'
items:
type: string
type: array
tracing:
description: 'Tracing settings.
+optional'
properties:
backends:
description: List of available tracing backends
items:
description: TracingBackend defines tracing backend available to mesh.
properties:
conf:
oneOf:
- $ref: '#/components/schemas/DatadogTracingBackendConfig'
- $ref: '#/components/schemas/ZipkinTracingBackendConfig'
type: object
name:
description: 'Name of the backend, can be then used in Mesh.tracing.defaultBackend or in
TrafficTrace'
type: string
sampling:
description: 'Percentage of traces that will be sent to the backend (range 0.0 - 100.0).
Empty value defaults to 100.0%'
type: number
type:
description: Type of the backend (Kuma ships with 'zipkin')
type: string
type: object
type: array
defaultBackend:
description: Name of the default backend
type: string
type: object
type:
type: string
required:
- type
- name
type: object
ZipkinTracingBackendConfig:
properties:
apiVersion:
description: 'Version of the API. values: httpJson, httpJsonV1, httpProto. Default:
httpJson see
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/trace.proto#envoy-v3-api-enum-config-trace-v3-zipkinconfig-collectorendpointversion'
type: string
sharedSpanContext:
description: 'Determines whether client and server spans will share the same span
context. Default: true.
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/v3/zipkin.proto#config-trace-v3-zipkinconfig'
type: boolean
traceId128bit:
description: 'Generate 128bit traces. Default: false'
type: boolean
url:
description: Address of Zipkin collector.
type: string
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
DataSource_Secret:
properties:
secret:
description: Data source is a secret with given Secret key.
type: string
type: object
DataSource_Inline:
properties:
inline:
description: Data source is inline bytes.
format: byte
type: string
type: object
DatadogTracingBackendConfig:
properties:
address:
description: Address of datadog collector.
type: string
port:
description: Port of datadog collector
type: integer
splitService:
description: 'Determines if datadog service name should be split based on traffic
direction and destination. For example, with `splitService: true` and a
`backend` service that communicates with a couple of databases, you would
get service names like `backend_INBOUND`, `backend_OUTBOUND_db1`, and
`backend_OUTBOUND_db2` in Datadog. Default: false'
type: boolean
type: object
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
ProvidedCertificateAuthorityConfig:
properties:
cert:
oneOf:
- $ref: '#/components/schemas/DataSource_File'
- $ref: '#/components/schemas/DataSource_Inline'
- $ref: '#/components/schemas/DataSource_InlineString'
- $ref: '#/components/schemas/DataSource_Secret'
key:
oneOf:
- $ref: '#/components/schemas/DataSource_File'
- $ref: '#/components/schemas/DataSource_Inline'
- $ref: '#/components/schemas/DataSource_InlineString'
- $ref: '#/components/schemas/DataSource_Secret'
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'
responses:
MeshCreateOrUpdateSuccessResponse:
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
MeshItem:
content:
application/json:
schema:
$ref: '#/components/schemas/MeshItem'
description: Successful response
MeshDeleteSuccessResponse:
content:
application/json:
schema:
type: object
description: Successful response
MeshList:
content:
application/json:
schema:
properties:
items:
items:
$ref: '#/components/schemas/MeshItem'
type: array
next:
description: URL to the next page
type: string
total:
description: The total number of entities
type: number
type: object
description: List
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
securitySchemes:
BasicAuth:
type: http
scheme: basic
BearerAuth:
type: http
scheme: bearer