Careful!
You are browsing documentation for a version of Kuma that is not the latest release.
HTTP API
Kuma ships with a RESTful HTTP interface that you can use to retrieve the state of your configuration and policies on every environment, and when running on Universal mode it will also allow to make changes to the state. On Kubernetes, you will use native CRDs to change the state in order to be consistent with Kubernetes best practices.
CI/CD: The HTTP API can be used for infrastructure automation to either retrieve data, or to make changes when running in Universal mode. The kumactl CLI is built on top of the HTTP API, which you can also access with any other HTTP client like curl.
By default the API Server is listening on port 5681 (HTTP) and on 5682 (HTTPS). The endpoints available are:
/config/versions/meshes/mesh-insights/mesh-insights/{name}/dataplanes/dataplanes+insights/health-checks/proxytemplates/traffic-logs/traffic-permissions/traffic-routes/fault-injections/service-insights/retries/secrets/global-secrets/global-secrets/{name}/meshes/{name}/meshes/{mesh}/dataplanes/meshes/{mesh}/dataplanes/{name}/meshes/{mesh}/dataplanes+insights/meshes/{mesh}/dataplanes+insights/{name}/meshes/{mesh}/health-checks/meshes/{mesh}/health-checks/{name}/meshes/{mesh}/proxytemplates/meshes/{mesh}/proxytemplates/{name}/meshes/{mesh}/traffic-logs/meshes/{mesh}/traffic-logs/{name}/meshes/{mesh}/traffic-permissions/meshes/{mesh}/traffic-permissions/{name}/meshes/{mesh}/traffic-routes/meshes/{mesh}/traffic-routes/{name}/meshes/{mesh}/fault-injections/meshes/{mesh}/fault-injections/{name}/meshes/{mesh}/external-services/meshes/{mesh}/external-services/{name}/meshes/{mesh}/service-insights/meshes/{mesh}/service-insights/{name}/meshes/{mesh}/retries/meshes/{mesh}/retries/{name}/meshes/{mesh}/secrets/meshes/{mesh}/secrets/{name}/status/zones/tokens/zones/zones/{name}/zones+insights/zones+insights/{name}/global-insights
You can use GET requests to retrieve the state of Kuma on both Universal and Kubernetes, and PUT and DELETE requests on Universal to change the state.
Pagination
Every resource list in Kuma is paginated. To use pagination, you can use following query parameters:
size- size of the page (default - 1000, maximum value - 10000).offset- offset from which the page will be listed. The offset is astring, it does not have to be a number (it depends on the environment).
A response with a pagination contains next field with URL to fetch the next page. Example:
{
"items": [...],
"next": "http://localhost:5681/meshes/default/dataplanes?offset=10"
}
If next field is null there is no more pages to fetch.
Control Plane configuration
Get effective configuration of the Control Plane
Request: GET /config
Response: 200 OK with the effective configuration of the Control Plane (notice that secrets, such as database passwords, will never appear in the response)
Example:
curl http://localhost:5681/config
{
"adminServer": {
"apis": {
"dataplaneToken": {
"enabled": true
}
},
"local": {
"port": 5679
},
"public": {
"clientCertsDir": "/etc/kuma.io/kuma-cp/admin-api/tls/allowed-client-certs.d",
"enabled": true,
"interface": "0.0.0.0",
"port": 5684,
"tlsCertFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.cert",
"tlsKeyFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.key"
}
},
"apiServer": {
"corsAllowedDomains": [
".*"
],
"port": 5681,
"readOnly": false
},
"bootstrapServer": {
"params": {
"adminAccessLogPath": "/dev/null",
"adminAddress": "127.0.0.1",
"adminPort": 0,
"xdsConnectTimeout": "1s",
"xdsHost": "kuma-control-plane.internal",
"xdsPort": 5678
},
"port": 5682
},
"dataplaneTokenServer": {
"enabled": true,
"local": {
"port": 5679
},
"public": {
"clientCertsDir": "/etc/kuma.io/kuma-cp/admin-api/tls/allowed-client-certs.d",
"enabled": true,
"interface": "0.0.0.0",
"port": 5684,
"tlsCertFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.cert",
"tlsKeyFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.key"
}
},
"defaults": {
"mesh": "type: Mesh\nname: default"
},
"discovery": {
"universal": {
"pollingInterval": "1s"
}
},
"environment": "universal",
"general": {
"advertisedHostname": "kuma-control-plane.internal"
},
"guiServer": {
},
"monitoringAssignmentServer": {
"assignmentRefreshInterval": "1s",
"grpcPort": 5676
},
"reports": {
"enabled": true
},
"runtime": {
"kubernetes": {
"admissionServer": {
"address": "",
"certDir": "",
"port": 5443
}
}
},
"sdsServer": {
"grpcPort": 5677,
"tlsCertFile": "/tmp/117637813.crt",
"tlsKeyFile": "/tmp/240596112.key"
},
"store": {
"kubernetes": {
"systemNamespace": "kuma-system"
},
"postgres": {
"connectionTimeout": 5,
"dbName": "kuma",
"host": "127.0.0.1",
"password": "*****",
"port": 15432,
"user": "kuma"
},
"type": "memory"
},
"xdsServer": {
"dataplaneConfigurationRefreshInterval": "1s",
"dataplaneStatusFlushInterval": "1s",
"diagnosticsPort": 5680,
"grpcPort": 5678
}
}
Supported Envoy versions
List supported Envoy versions
Request: GET /versions
Response: 200 OK with versions of Envoy supported by Kuma DPs
Example:
curl http://localhost:5681/versions
{
"kumaDp": {
"1.0.0": {
"envoy": "1.16.0"
},
"1.0.1": {
"envoy": "1.16.0"
},
"1.0.2": {
"envoy": "1.16.1"
},
"1.0.3": {
"envoy": "1.16.1"
},
"1.0.4": {
"envoy": "1.16.1"
},
"1.0.5": {
"envoy": "1.16.2"
},
"1.0.6": {
"envoy": "1.16.2"
},
"1.0.7": {
"envoy": "1.16.2"
},
"1.0.8": {
"envoy": "1.16.2"
}
}
}
Meshes
Get Mesh
Request: GET /meshes/{name}
Response: 200 OK with Mesh entity
Example:
curl http://localhost:5681/meshes/mesh-1
{
"name": "mesh-1",
"type": "Mesh",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"mtls": {
"backends": [
{
"name": "ca-1",
"type": "builtin"
},
{
"name": "ca-2",
"type": "provided",
"conf": {
"cert": {
"secret": "provided-cert"
},
"key": {
"secret": "provided-cert"
}
}
}
],
"enabledBackend": "ca-1"
},
"tracing": {
"defaultBackend": "zipkin-1",
"backends": [
{
"name": "zipkin-1",
"type": "zipkin",
"conf": {
"url": "http://zipkin.local:9411/api/v2/spans"
}
}
]
},
"logging": {
"backends": [
{
"name": "file-tmp",
"format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
"type": "file",
"conf": {
"path": "/tmp/access.log"
}
},
{
"name": "logstash",
"type": "tcp",
"conf": {
"address": "logstash.internal:9000"
}
}
]
},
"metrics": {
"enabledBackend": "prometheus-1",
"backends": [
{
"name": "prometheus-1",
"type": "prometheus",
"conf": {
"port": 1234,
"path": "/metrics"
}
}
]
}
}
Create/Update Mesh
Request: PUT /meshes/{name} with Mesh entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1 --data @mesh.json -H'content-type: application/json'
{
"name": "mesh-1",
"type": "Mesh",
"mtls": {
"backends": [
{
"name": "ca-1",
"type": "builtin"
},
{
"name": "ca-2",
"type": "provided",
"conf": {
"cert": {
"secret": "provided-cert"
},
"key": {
"secret": "provided-cert"
}
}
}
],
"enabledBackend": "ca-1"
},
"tracing": {
"defaultBackend": "zipkin-1",
"backends": [
{
"name": "zipkin-1",
"type": "zipkin",
"conf": {
"url": "http://zipkin.local:9411/api/v2/spans"
}
}
]
},
"logging": {
"backends": [
{
"name": "file-tmp",
"format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
"type": "file",
"conf": {
"path": "/tmp/access.log"
}
},
{
"name": "logstash",
"type": "tcp",
"conf": {
"address": "logstash.internal:9000"
}
}
]
},
"metrics": {
"enabledBackend": "prometheus-1",
"backends": [
{
"name": "prometheus-1",
"type": "prometheus",
"conf": {
"port": 1234,
"path": "/metrics"
}
}
]
}
}
List Meshes
Request: GET /meshes
Response: 200 OK with body of Mesh entities
Example:
curl http://localhost:5681/meshes
{
"items": [
{
"name": "mesh-1",
"type": "Mesh",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"mtls": {
"backends": [
{
"name": "ca-1",
"type": "builtin"
},
{
"name": "ca-2",
"type": "provided",
"conf": {
"cert": {
"secret": "provided-cert"
},
"key": {
"secret": "provided-cert"
}
}
}
],
"enabledBackend": "ca-1"
},
"tracing": {
"defaultBackend": "zipkin-1",
"backends": [
{
"name": "zipkin-1",
"type": "zipkin",
"conf": {
"url": "http://zipkin.local:9411/api/v2/spans"
}
}
]
},
"logging": {
"backends": [
{
"name": "file-tmp",
"format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
"type": "file",
"conf": {
"path": "/tmp/access.log"
}
},
{
"name": "logstash",
"type": "tcp",
"conf": {
"address": "logstash.internal:9000"
}
}
]
},
"metrics": {
"enabledBackend": "prometheus-1",
"backends": [
{
"name": "prometheus-1",
"type": "prometheus",
"conf": {
"port": 1234,
"path": "/metrics"
}
}
]
}
}
],
"next": "http://localhost:5681/meshes?offset=1"
}
Delete Mesh
Request: DELETE /meshes/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1
Mesh Insights
Get Mesh Insights
Request: GET /mesh-insights/{name}
Response: 200 OK with MeshInsight entity
Example:
curl http://localhost:5681/mesh-insights/default
{
"type": "MeshInsight",
"name": "default",
"creationTime": "2020-11-17T08:10:24.886346Z",
"modificationTime": "2020-11-17T19:21:39.912878Z",
"lastSync": "2020-11-17T12:21:39.912877Z",
"dataplanes": {
"total": 4,
"offline": 2,
"partiallyDegraded": 2
},
"dataplanesByType": {
"standard": {
"total": 2,
"offline": 1,
"partiallyDegraded": 1
},
"gateway": {
"total": 2,
"offline": 1,
"partiallyDegraded": 1
}
},
"policies": {
"Secret": {
"total": 1
},
"TrafficPermission": {
"total": 1
},
"TrafficRoute": {
"total": 1
}
},
"dpVersions": {
"kumaDp": {
"1.0.0-rc2-119-g50e35395": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
},
"1.0.4": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
},
"unknown": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
},
"envoy": {
"1.15.0": {
"total": 2,
"online": 2,
"partiallyDegraded": 1
},
"unknown": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
}
},
"mTLS": {
"issuedBackends": {
"ca-1": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
},
"supportedBackends": {
"ca-1": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
}
},
"services": {
"total": 3,
"internal": 2,
"external": 1
}
}
List Mesh Insights
Request: GET /mesh-insights
Response: 200 OK with body of Mesh Insight entities
Example:
curl http://localhost:5681/mesh-insights
{
"total": 2,
"items": [
{
"type": "MeshInsight",
"name": "default",
"creationTime": "0001-01-01T00:00:00Z",
"modificationTime": "0001-01-01T00:00:00Z",
"lastSync": "2020-11-17T12:24:11.905350Z",
"dataplanes": {
"total": 4,
"offline": 2,
"partiallyDegraded": 2
},
"dataplanesByType": {
"standard": {
"total": 2,
"offline": 1,
"partiallyDegraded": 1
},
"gateway": {
"total": 2,
"offline": 1,
"partiallyDegraded": 1
}
},
"policies": {
"Secret": {
"total": 1
},
"TrafficPermission": {
"total": 1
},
"TrafficRoute": {
"total": 1
}
},
"dpVersions": {
"kumaDp": {
"1.0.0-rc2-119-g50e35395": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
},
"1.0.4": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
},
"unknown": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
},
"envoy": {
"1.15.0": {
"total": 2,
"online": 2,
"partiallyDegraded": 1
},
"unknown": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
}
},
"mTLS": {
"issuedBackends": {
"ca-1": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
},
"supportedBackends": {
"ca-1": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
}
},
"services": {
"total": 3,
"internal": 2,
"external": 1
}
},
{
"type": "MeshInsight",
"name": "mymesh1",
"creationTime": "0001-01-01T00:00:00Z",
"modificationTime": "0001-01-01T00:00:00Z",
"lastSync": "2020-11-17T12:24:11.941534Z",
"dataplanes": {
"total": 4,
"offline": 2,
"partiallyDegraded": 2
},
"dataplanesByType": {
"standard": {
"total": 2,
"offline": 1,
"partiallyDegraded": 1
},
"gateway": {
"total": 2,
"offline": 1,
"partiallyDegraded": 1
}
},
"policies": {
"Secret": {
"total": 1
},
"TrafficPermission": {
"total": 1
},
"TrafficRoute": {
"total": 1
}
},
"dpVersions": {
"kumaDp": {
"1.0.0-rc2-119-g50e35395": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
},
"1.0.4": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
},
"unknown": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
},
"envoy": {
"1.15.0": {
"total": 2,
"online": 2,
"partiallyDegraded": 1
},
"unknown": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
}
},
"mTLS": {
"issuedBackends": {
"ca-1": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
},
"supportedBackends": {
"ca-1": {
"total": 1,
"online": 1,
"partiallyDegraded": 1
}
}
},
"services": {
"total": 3,
"internal": 2,
"external": 1
}
}
],
"next": null
}
Dataplanes
Get Dataplane
Request: GET /meshes/{mesh}/dataplanes/{name}
Response: 200 OK with Mesh entity
Example:
curl http://localhost:5681/meshes/mesh-1/dataplanes/backend-1
{
"type": "Dataplane",
"name": "backend-1",
"mesh": "mesh-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"networking": {
"address": "127.0.0.1",
"inbound": [
{
"port": 11011,
"servicePort": 11012,
"tags": {
"service": "backend",
"version": "2.0",
"env": "production"
}
}
],
"outbound": [
{
"port": 33033,
"service": "database"
},
{
"port": 44044,
"service": "user"
}
]
}
}
Create/Update Dataplane
Request: PUT /meshes/{mesh}/dataplanes/{name} with Dataplane entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1/dataplanes/backend-1 --data @dataplane.json -H'content-type: application/json'
{
"type": "Dataplane",
"name": "backend-1",
"mesh": "mesh-1",
"networking": {
"address": "127.0.0.1",
"inbound": [
{
"port": 11011,
"servicePort": 11012,
"tags": {
"service": "backend",
"version": "2.0",
"env": "production"
}
}
],
"outbound": [
{
"port": 33033,
"service": "database"
},
{
"port": 44044,
"service": "user"
}
]
}
}
List Dataplanes
Request: GET /meshes/{mesh}/dataplanes
Response: 200 OK with body of Dataplane entities
Example:
curl http://localhost:5681/meshes/mesh-1/dataplanes
{
"items": [
{
"type": "Dataplane",
"name": "backend-1",
"mesh": "mesh-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"networking": {
"address": "127.0.0.1",
"inbound": [
{
"port": 11011,
"servicePort": 11012,
"tags": {
"service": "backend",
"version": "2.0",
"env": "production"
}
}
],
"outbound": [
{
"port": 33033,
"service": "database"
},
{
"port": 44044,
"service": "user"
}
]
}
}
],
"next": "http://localhost:5681/meshes/mesh-1/dataplanes?offset=1"
}
Delete Dataplane
Request: DELETE /meshes/{mesh}/dataplanes/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1/dataplanes/backend-1
Dataplane Overviews
Get Dataplane Overview
Request: GET /meshes/{mesh}/dataplane+insights/{name}
Response: 200 OK with Dataplane entity including insight
Example:
curl http://localhost:5681/meshes/default/dataplanes+insights/example
{
"type": "DataplaneOverview",
"mesh": "default",
"name": "example",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"dataplane": {
"networking": {
"address": "127.0.0.1",
"inbound": [
{
"port": 11011,
"servicePort": 11012,
"tags": {
"env": "production",
"service": "backend",
"version": "2.0"
}
}
],
"outbound": [
{
"port": 33033,
"service": "database"
}
]
}
},
"dataplaneInsight": {
"mTLS": {
"certificateExpirationTime": "2019-10-24T14:04:57.832482Z",
"lastCertificateRegeneration": "2019-10-24T12:04:57.832482Z",
"certificateRegenerations": 3,
"issuedBackend": "ca-1",
"supportedBackends": ["ca-1"]
},
"subscriptions": [
{
"id": "426fe0d8-f667-11e9-b081-acde48001122",
"controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
"connectTime": "2019-10-24T14:04:56.820350Z",
"status": {
"lastUpdateTime": "2019-10-24T14:04:57.832482Z",
"total": {
"responsesSent": "3",
"responsesAcknowledged": "3"
},
"cds": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"eds": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"lds": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"rds": {}
}
}
]
}
}
List Dataplane Overviews
Request: GET /meshes/{mesh}/dataplane+insights/
Response: 200 OK with Dataplane entities including insight
Example:
curl http://localhost:5681/meshes/default/dataplanes+insights
{
"items": [
{
"type": "DataplaneOverview",
"mesh": "default",
"name": "example",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"dataplane": {
"networking": {
"address": "127.0.0.1",
"inbound": [
{
"port": 11011,
"servicePort": 11012,
"tags": {
"env": "production",
"service": "backend",
"version": "2.0"
}
}
],
"outbound": [
{
"port": 33033,
"service": "database"
}
]
}
},
"dataplaneInsight": {
"mTLS": {
"certificateExpirationTime": "2019-10-24T14:04:57.832482Z",
"lastCertificateRegeneration": "2019-10-24T12:04:57.832482Z",
"certificateRegenerations": 3,
"issuedBackend": "ca-1",
"supportedBackends": ["ca-1"]
},
"subscriptions": [
{
"id": "426fe0d8-f667-11e9-b081-acde48001122",
"controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
"connectTime": "2019-10-24T14:04:56.820350Z",
"status": {
"lastUpdateTime": "2019-10-24T14:04:57.832482Z",
"total": {
"responsesSent": "3",
"responsesAcknowledged": "3"
},
"cds": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"eds": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"lds": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"rds": {}
}
}
]
}
}
],
"total": 2,
"next": "http://localhost:5681/meshes/default/dataplanes+insights?offset=1"
}
Health Check
Get Health Check
Request: GET /meshes/{mesh}/health-checks/{name}
Response: 200 OK with Health Check entity
Example:
curl http://localhost:5681/meshes/mesh-1/health-checks/web-to-backend
{
"type": "HealthCheck",
"mesh": "mesh-1",
"name": "web-to-backend",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"service": "web"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"interval": "10s",
"timeout": "2s",
"unhealthyThreshold": 3,
"healthyThreshold": 1,
"reuseConnection": false,
"tcp": {
"send": "Zm9v",
"receive": [
"YmFy",
"YmF6"
]
},
"http": {
"path": "/health",
"requestHeadersToAdd": [
{
"append": false,
"header": {
"key": "Content-Type",
"value": "application/json"
}
},
{
"header": {
"key": "Accept",
"value": "application/json"
}
}
],
"expectedStatuses": [
200,
201
],
"useHttp1": true
}
}
}
Create/Update Health Check
Request: PUT /meshes/{mesh}/health-checks/{name} with Health Check entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1/health-checks/web-to-backend --data @healthcheck.json -H'content-type: application/json'
{
"type": "HealthCheck",
"mesh": "mesh-1",
"name": "web-to-backend",
"sources": [
{
"match": {
"service": "web"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"interval": "10s",
"timeout": "2s",
"unhealthyThreshold": 3,
"healthyThreshold": 1,
"reuseConnection": false,
"tcp": {
"send": "Zm9v",
"receive": [
"YmFy",
"YmF6"
]
},
"http": {
"path": "/health",
"requestHeadersToAdd": [
{
"append": false,
"header": {
"key": "Content-Type",
"value": "application/json"
}
},
{
"header": {
"key": "Accept",
"value": "application/json"
}
}
],
"expectedStatuses": [
200,
201
],
"useHttp1": true
}
}
}
List Health Checks
Request: GET /meshes/{mesh}/health-checks
Response: 200 OK with body of Health Check entities
Example:
curl http://localhost:5681/meshes/mesh-1/health-checks
{
"items": [
{
"type": "HealthCheck",
"mesh": "mesh-1",
"name": "web-to-backend",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"service": "web"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"interval": "10s",
"timeout": "2s",
"unhealthyThreshold": 3,
"healthyThreshold": 1,
"reuseConnection": false,
"tcp": {
"send": "Zm9v",
"receive": [
"YmFy",
"YmF6"
]
},
"http": {
"path": "/health",
"requestHeadersToAdd": [
{
"append": false,
"header": {
"key": "Content-Type",
"value": "application/json"
}
},
{
"header": {
"key": "Accept",
"value": "application/json"
}
}
],
"expectedStatuses": [
200,
201
],
"useHttp1": true
}
}
}
],
"next": "http://localhost:5681/meshes/mesh-1/health-checks?offset=1"
}
Delete Health Check
Request: DELETE /meshes/{mesh}/health-checks/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1/health-checks/web-to-backend
Proxy Template
Get Proxy Template
Request: GET /meshes/{mesh}/proxytemplates/{name}
Response: 200 OK with Proxy Template entity
Example:
curl http://localhost:5681/meshes/mesh-1/proxytemplates/pt-1
{
"type": "ProxyTemplate",
"mesh": "mesh-1",
"name": "pt-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"selectors": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"imports": [
"default-proxy"
],
"resources": [
{
"name": "raw-name",
"version": "raw-version",
"resource": "'@type': type.googleapis.com/envoy.api.v2.Cluster\nconnectTimeout: 5s\nloadAssignment:\n clusterName: localhost:8443\n endpoints:\n - lbEndpoints:\n - endpoint:\n address:\n socketAddress:\n address: 127.0.0.1\n portValue: 8443\nname: localhost:8443\ntype: STATIC\n"
}
]
}
}
Create/Update Proxy Template
Request: PUT /meshes/{mesh}/proxytemplates/{name} with Proxy Template entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1/proxytemplates/pt-1 --data @proxytemplate.json -H'content-type: application/json'
{
"type": "ProxyTemplate",
"name": "pt-1",
"mesh": "mesh-1",
"selectors": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"imports": [
"default-proxy"
],
"resources": [
{
"name": "raw-name",
"version": "raw-version",
"resource": "'@type': type.googleapis.com/envoy.api.v2.Cluster\nconnectTimeout: 5s\nloadAssignment:\n clusterName: localhost:8443\n endpoints:\n - lbEndpoints:\n - endpoint:\n address:\n socketAddress:\n address: 127.0.0.1\n portValue: 8443\nname: localhost:8443\ntype: STATIC\n"
}
]
}
}
List Proxy Templates
Request: GET /meshes/{mesh}/proxytemplates
Response: 200 OK with body of Proxy Template entities
Example:
curl http://localhost:5681/meshes/mesh-1/proxytemplates
{
"items": [
{
"type": "ProxyTemplate",
"mesh": "mesh-1",
"name": "pt-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"selectors": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"imports": [
"default-proxy"
],
"resources": [
{
"name": "raw-name",
"version": "raw-version",
"resource": "'@type': type.googleapis.com/envoy.api.v2.Cluster\nconnectTimeout: 5s\nloadAssignment:\n clusterName: localhost:8443\n endpoints:\n - lbEndpoints:\n - endpoint:\n address:\n socketAddress:\n address: 127.0.0.1\n portValue: 8443\nname: localhost:8443\ntype: STATIC\n"
}
]
}
}
],
"next": "http://localhost:5681/meshes/mesh-1/proxytemplates?offset=1"
}
Delete Proxy Template
Request: DELETE /meshes/{mesh}/proxytemplates/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1/proxytemplates/pt-1
Traffic Permission
Get Traffic Permission
Request: GET /meshes/{mesh}/traffic-permissions/{name}
Response: 200 OK with Traffic Permission entity
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-permissions/tp-1
{
"type": "TrafficPermission",
"mesh": "mesh-1",
"name": "tp-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"service": "backend"
}
}
],
"destinations": [
{
"match": {
"service": "redis"
}
}
]
}
Create/Update Traffic Permission
Request: PUT /meshes/{mesh}/trafficpermissions/{name} with Traffic Permission entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-permissions/tp-1 --data @trafficpermission.json -H'content-type: application/json'
{
"type": "TrafficPermission",
"name": "tp-1",
"mesh": "mesh-1",
"sources": [
{
"match": {
"service": "backend"
}
}
],
"destinations": [
{
"match": {
"service": "redis"
}
}
]
}
List Traffic Permissions
Request: GET /meshes/{mesh}/traffic-permissions
Response: 200 OK with body of Traffic Permission entities
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-permissions
{
"items": [
{
"type": "TrafficPermission",
"mesh": "mesh-1",
"name": "tp-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"service": "backend"
}
}
],
"destinations": [
{
"match": {
"service": "redis"
}
}
]
}
],
"next": "http://localhost:5681/meshes/mesh-1/traffic-permissions?offset=1"
}
Delete Traffic Permission
Request: DELETE /meshes/{mesh}/traffic-permissions/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1/traffic-permissions/pt-1
Traffic Log
Get Traffic Log
Request: GET /meshes/{mesh}/traffic-logs/{name}
Response: 200 OK with Traffic Log entity
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-logs/tl-1
{
"type": "TrafficLog",
"mesh": "mesh-1",
"name": "tl-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"service": "web",
"version": "1.0"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"backend": "file"
}
}
Create/Update Traffic Log
Request: PUT /meshes/{mesh}/traffic-logs/{name} with Traffic Log entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-logs/tl-1 --data @trafficlog.json -H'content-type: application/json'
{
"type": "TrafficLog",
"mesh": "mesh-1",
"name": "tl-1",
"sources": [
{
"match": {
"service": "web",
"version": "1.0"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"backend": "file"
}
}
List Traffic Logs
Request: GET /meshes/{mesh}/traffic-logs
Response: 200 OK with body of Traffic Log entities
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-logs
{
"items": [
{
"type": "TrafficLog",
"mesh": "mesh-1",
"name": "tl-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"service": "web",
"version": "1.0"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"backend": "file"
}
}
],
"next": "http://localhost:5681/meshes/mesh-1/traffic-logs?offset=1"
}
Delete Traffic Log
Request: DELETE /meshes/{mesh}/traffic-logs/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1/traffic-logs/tl-1
Traffic Route
Get Traffic Route
Request: GET /meshes/{mesh}/traffic-routes/{name}
Response: 200 OK with Traffic Route entity
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-routes/web-to-backend
{
"type": "TrafficRoute",
"mesh": "mesh-1",
"name": "web-to-backend",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"region": "us-east-1",
"service": "web",
"version": "v10"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"split": [
{
"weight": 90,
"destination": {
"region": "us-east-1",
"service": "backend",
"version": "v2"
}
},
{
"weight": 10,
"destination": {
"service": "backend",
"version": "v3"
}
}
]
}
}
Create/Update Traffic Route
Request: PUT /meshes/{mesh}/traffic-routes/{name} with Traffic Route entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-routes/web-to-backend --data @trafficroute.json -H'content-type: application/json'
{
"type": "TrafficRoute",
"name": "web-to-backend",
"mesh": "mesh-1",
"sources": [
{
"match": {
"region": "us-east-1",
"service": "web",
"version": "v10"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"split": [
{
"weight": 90,
"destination": {
"region": "us-east-1",
"service": "backend",
"version": "v2"
}
},
{
"weight": 10,
"destination": {
"service": "backend",
"version": "v3"
}
}
]
}
}
List Traffic Routes
Request: GET /meshes/{mesh}/traffic-routes
Response: 200 OK with body of Traffic Route entities
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-routes
{
"items": [
{
"type": "TrafficRoute",
"mesh": "mesh-1",
"name": "web-to-backend",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"region": "us-east-1",
"service": "web",
"version": "v10"
}
}
],
"destinations": [
{
"match": {
"service": "backend"
}
}
],
"conf": {
"split": [
{
"weight": 90,
"destination": {
"region": "us-east-1",
"service": "backend",
"version": "v2"
}
},
{
"weight": 10,
"destination": {
"service": "backend",
"version": "v3"
}
}
]
}
}
],
"next": "http://localhost:5681/meshes/mesh-1/traffic-routes?offset=1"
}
Delete Traffic Route
Request: DELETE /meshes/{mesh}/traffic-routes/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1/traffic-routes/web-to-backend
Traffic Trace
Get Traffic Trace
Request: GET /meshes/{mesh}/traffic-traces/{name}
Response: 200 OK with Traffic Trace entity
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-traces/tt-1
{
"type": "TrafficTrace",
"mesh": "mesh-1",
"name": "tt-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"conf": {
"backend": "my-zipkin"
},
"selectors": [
{
"match": {
"service": "*"
}
}
]
}
Create/Update Traffic Trace
Request: PUT /meshes/{mesh}/traffic-traces/{name} with Traffic Trace entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-traces/tt-1 --data @traffictrace.json -H'content-type: application/json'
{
"type": "TrafficTrace",
"mesh": "mesh-1",
"name": "tt-1",
"conf": {
"backend": "my-zipkin"
},
"selectors": [
{
"match": {
"service": "*"
}
}
]
}
List Traffic Traces
Request: GET /meshes/{mesh}/traffic-traces
Response: 200 OK with body of Traffic Trace entities
Example:
curl http://localhost:5681/meshes/mesh-1/traffic-traces
{
"items": [
{
"type": "TrafficTrace",
"mesh": "mesh-1",
"name": "tt-1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"selectors": [
{
"match": {
"service": "*"
}
}
],
"conf": {
"backend": "my-zipkin"
}
}
],
"next": "http://localhost:5681/meshes/mesh-1/traffic-traces?offset=1"
}
Delete Traffic Trace
Request: DELETE /meshes/{mesh}/traffic-traces/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/mesh-1/traffic-traces/tt-1
Fault Injection
Get Fault Injection
Request: GET /meshes/{mesh}/fault-injections/{name}
Response: 200 OK with Fault Injection entity
Example:
curl http://localhost:5681/meshes/default/fault-injections/fi1
{
"type": "FaultInjection",
"mesh": "default",
"name": "fi1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"protocol": "http",
"service": "frontend",
"version": "0.1"
}
}
],
"destinations": [
{
"match": {
"protocol": "http",
"service": "backend"
}
}
],
"conf": {
"delay": {
"percentage": 50.5,
"value": "5s"
},
"abort": {
"percentage": 50,
"httpStatus": 500
},
"responseBandwidth": {
"percentage": 50,
"limit": "50 mbps"
}
}
}
Create/Update Fault Injection
Request: PUT /meshes/{mesh}/fault-injections/{name} with Fault Injection entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/default/fault-injections/fi1 --data @faultinjection.json -H'content-type: application/json'
{
"type": "FaultInjection",
"mesh": "default",
"name": "fi1",
"sources": [
{
"match": {
"service": "frontend",
"version": "0.1",
"protocol": "http"
}
}
],
"destinations": [
{
"match": {
"service": "backend",
"protocol": "http"
}
}
],
"conf": {
"delay": {
"percentage": 50.5,
"value": "5s"
},
"abort": {
"httpStatus": 500,
"percentage": 50
},
"responseBandwidth": {
"limit": "50 mbps",
"percentage": 50
}
}
}
List Fault Injections
Request: GET /meshes/{mesh}/fault-injections
Response: 200 OK with body of Fault Injection entities
Example:
curl http://localhost:5681/meshes/default/fault-injections
{
"items": [
{
"type": "FaultInjection",
"mesh": "default",
"name": "fi1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"protocol": "http",
"service": "frontend",
"version": "0.1"
}
}
],
"destinations": [
{
"match": {
"protocol": "http",
"service": "backend"
}
}
],
"conf": {
"delay": {
"percentage": 50.5,
"value": "5s"
},
"abort": {
"percentage": 50,
"httpStatus": 500
},
"responseBandwidth": {
"percentage": 50,
"limit": "50 mbps"
}
}
}
],
"next": "http://localhost:5681/meshes/default/fault-injections?offset=1"
}
Delete Fault Injection
Request: DELETE /meshes/{mesh}/fault-injections/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/default/fault-injections/fi1
The kumactl CLI under the hood makes HTTP requests to this API.
Retry
Get Retry
Request: GET /meshes/{mesh}/retries/{name}
Response: 200 OK with Retry entity
Example:
curl http://localhost:5681/meshes/default/retries/r1
{
"type": "Retry",
"mesh": "default",
"name": "r1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"protocol": "http",
"service": "frontend",
"version": "0.1"
}
}
],
"destinations": [
{
"match": {
"protocol": "http",
"service": "backend"
}
}
],
"conf": {
"http": {
"numRetries": 5,
"perTryTimeout": "0.2s",
"backOff": {
"baseInterval": "0.02s",
"maxInterval": "1s"
},
"retriableStatusCodes": [500, 504]
},
"grpc": {
"numRetries": 5,
"perTryTimeout": "0.3s",
"backOff": {
"baseInterval": "0.03s",
"maxInterval": "1.2s"
},
"retryOn": [
"cancelled",
"deadline_exceeded",
"internal",
"resource_exhausted",
"unavailable"
]
},
"tcp": {
"maxConnectAttempts": 4
}
}
}
Create/Update Retry
Request: PUT /meshes/{mesh}/retries/{name} with Retry entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/default/retries/fi1 --data @retry.json -H'content-type: application/json'
{
"type": "Retry",
"mesh": "default",
"name": "r1",
"sources": [
{
"match": {
"service": "frontend",
"version": "0.1",
"protocol": "http"
}
}
],
"destinations": [
{
"match": {
"service": "backend",
"protocol": "http"
}
}
],
"conf": {
"http": {
"numRetries": 5,
"perTryTimeout": "0.2s",
"backOff": {
"baseInterval": "0.02s",
"maxInterval": "1s"
},
"retriableStatusCodes": [500, 504]
},
"grpc": {
"numRetries": 5,
"perTryTimeout": "0.3s",
"backOff": {
"baseInterval": "0.03s",
"maxInterval": "1.2s"
},
"retryOn": [
"cancelled",
"deadline_exceeded",
"internal",
"resource_exhausted",
"unavailable"
]
},
"tcp": {
"maxConnectAttempts": 4
}
}
}
List Retries
Request: GET /meshes/{mesh}/retries
Response: 200 OK with body of Retry entities
Example:
curl http://localhost:5681/meshes/default/retries
{
"items": [
{
"type": "Retry",
"mesh": "default",
"name": "r1",
"creationTime": "2020-05-12T12:31:45.606217+02:00",
"modificationTime": "2020-05-12T12:31:45.606217+02:00",
"sources": [
{
"match": {
"protocol": "http",
"service": "frontend",
"version": "0.1"
}
}
],
"destinations": [
{
"match": {
"protocol": "http",
"service": "backend"
}
}
],
"conf": {
"http": {
"numRetries": 5,
"perTryTimeout": "0.2s",
"backOff": {
"baseInterval": "0.02s",
"maxInterval": "1s"
},
"retriableStatusCodes": [500, 504]
},
"grpc": {
"numRetries": 5,
"perTryTimeout": "0.3s",
"backOff": {
"baseInterval": "0.03s",
"maxInterval": "1.2s"
},
"retryOn": [
"cancelled",
"deadline_exceeded",
"internal",
"resource_exhausted",
"unavailable"
]
},
"tcp": {
"maxConnectAttempts": 4
}
}
}
],
"next": "http://localhost:5681/meshes/default/retries?offset=1"
}
Delete Retry
Request: DELETE /meshes/{mesh}/retries/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/default/retries/r1
The kumactl CLI under the hood makes HTTP requests to this API.
Timeout
Get Timeout
Request: GET /meshes/{mesh}/timeouts/{name}
Response: 200 OK with Timeout entity
Example:
curl http://localhost:5681/meshes/default/timeouts/default-timeouts-web
{
"type": "Timeout",
"mesh": "default",
"name": "default-timeouts-web",
"creationTime": "2021-02-16T18:41:26.016089+07:00",
"modificationTime": "2021-02-16T18:41:26.016089+07:00",
"sources": [
{
"match": {
"kuma.io/service": "*"
}
}
],
"destinations": [
{
"match": {
"kuma.io/service": "web"
}
}
],
"conf": {
"connectTimeout": "10s",
"grpc": {
"streamIdleTimeout": "4s",
"maxStreamDuration": "15s"
}
}
}
Create/Update Timeout
Request: PUT /meshes/{mesh}/timeouts/{name} with Timeout entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/default/timeouts/fi1 --data @timeout.json -H'content-type: application/json'
{
"type": "Timeout",
"mesh": "default",
"name": "default-timeouts-web",
"sources": [
{
"match": {
"kuma.io/service": "*"
}
}
],
"destinations": [
{
"match": {
"kuma.io/service": "web"
}
}
],
"conf": {
"connectTimeout": "10s",
"grpc": {
"streamIdleTimeout": "4s",
"maxStreamDuration": "15s"
}
}
}
List Timeouts
Request: GET /meshes/{mesh}/retries
Response: 200 OK with body of Timeout entities
Example:
curl http://localhost:5681/meshes/default/timeouts
{
"total": 2,
"items": [
{
"type": "Timeout",
"mesh": "default",
"name": "default-timeouts-web",
"creationTime": "2021-02-16T18:41:26.016089+07:00",
"modificationTime": "2021-02-16T18:41:26.016089+07:00",
"sources": [
{
"match": {
"kuma.io/service": "*"
}
}
],
"destinations": [
{
"match": {
"kuma.io/service": "web"
}
}
],
"conf": {
"connectTimeout": "10s",
"grpc": {
"streamIdleTimeout": "4s",
"maxStreamDuration": "15s"
}
}
},
{
"type": "Timeout",
"mesh": "default",
"name": "timeout-all-default",
"creationTime": "2021-02-16T14:01:53.532599+07:00",
"modificationTime": "2021-02-16T14:01:53.532599+07:00",
"sources": [
{
"match": {
"kuma.io/service": "*"
}
}
],
"destinations": [
{
"match": {
"kuma.io/service": "*"
}
}
],
"conf": {
"connectTimeout": "5s",
"tcp": {
"idleTimeout": "3600s"
},
"http": {
"requestTimeout": "15s",
"idleTimeout": "3600s"
},
"grpc": {
"streamIdleTimeout": "300s"
}
}
}
],
"next": null
}
Delete Timeout
Request: DELETE /meshes/{mesh}/timeouts/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/default/timeouts/t1
The kumactl CLI under the hood makes HTTP requests to this API.
Zones
Get Zone
Request: GET /zones/{name}
Response: 200 OK with Zone entity
Example:
curl http://localhost:5681/zones/cluster-1
{
"type": "Zone",
"name": "cluster-1",
"creationTime": "2020-07-28T13:14:48Z",
"modificationTime": "2020-07-28T13:14:48Z",
"enabled": true
}
Create/Update Zone
Request: PUT /zones/{name} with Zone entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/zones/cluster-1 --data @zone.json -H'content-type: application/json'
{
"type": "Zone",
"name": "cluster-1",
"enabled": true
}
List Zones
Request: GET /zones
Response: 200 OK with body of Zone entities
Example:
curl http://localhost:5681/zones
{
"total": 2,
"items": [
{
"type": "Zone",
"name": "cluster-1",
"creationTime": "2020-07-28T13:14:48Z",
"modificationTime": "2020-07-28T13:14:48Z",
"enabled": true
},
{
"type": "Zone",
"name": "cluster-2",
"creationTime": "2020-07-28T13:14:50Z",
"modificationTime": "2020-07-28T13:14:50Z",
"enabled": false
}
],
"next": null
}
Delete Zone
Request: DELETE /zones/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/zones/cluster-1
Zone Overview
Get Zone Overview
Request: GET /zones+insights/{name}
Response: 200 OK with Zone entity including insight
Example:
curl http://localhost:5681/zones+insights/cluster-1
{
"type": "ZoneOverview",
"mesh": "default",
"name": "cluster-1",
"creationTime": "2020-07-28T23:08:22.317322+07:00",
"modificationTime": "2020-07-28T23:08:22.317322+07:00",
"zone": {
"enabled": true
},
"zoneInsight": {
"subscriptions": [
{
"config": "\"whole /config from zone\"",
"id": "466aa63b-70e8-4435-8bee-a7146e2cdf11",
"globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
"connectTime": "2020-07-28T16:08:09.743141Z",
"disconnectTime": "2020-07-28T16:08:09.743194Z",
"status": {
"total": {}
},
"version": {
"kumaCp": {
"version": "1.2.0-rc2-211-g823fe8ce",
"gitTag": "1.0.0-rc2-211-g823fe8ce",
"gitCommit": "823fe8cef6430a8f75e72a7224eb5a8ab571ec42",
"buildDate": "2021-02-18T13:22:30Z"
}
}
},
{
"config": "\"whole /config from zone\"",
"id": "f586f89c-2c4e-4f93-9a56-f0ea2ff010b7",
"globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
"connectTime": "2020-07-28T16:08:24.760801Z",
"status": {
"lastUpdateTime": "2020-07-28T16:08:25.770774Z",
"total": {
"responsesSent": "11",
"responsesAcknowledged": "11"
},
"stat": {
"CircuitBreaker": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"Dataplane": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"FaultInjection": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"HealthCheck": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"Mesh": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"ProxyTemplate": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"Secret": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficLog": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficPermission": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficRoute": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficTrace": {
"responsesSent": "1",
"responsesAcknowledged": "1"
}
}
}
}
]
}
}
List Zone Overview
Request: GET /zones+insights
Response: 200 OK with Zone entities including insight
Example:
curl http://localhost:5681/zones+insights
{
"total": 1,
"items": [
{
"type": "ZoneOverview",
"mesh": "default",
"name": "cluster-1",
"creationTime": "2020-07-28T23:08:22.317322+07:00",
"modificationTime": "2020-07-28T23:08:22.317322+07:00",
"zone": {
"enabled": true
},
"zoneInsight": {
"subscriptions": [
{
"config": "\"whole /config from zone\"",
"id": "466aa63b-70e8-4435-8bee-a7146e2cdf11",
"globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
"connectTime": "2020-07-28T16:08:09.743141Z",
"disconnectTime": "2020-07-28T16:08:09.743194Z",
"status": {
"total": {}
},
"version": {
"kumaCp": {
"version": "1.2.0-rc2-211-g823fe8ce",
"gitTag": "1.0.0-rc2-211-g823fe8ce",
"gitCommit": "823fe8cef6430a8f75e72a7224eb5a8ab571ec42",
"buildDate": "2021-02-18T13:22:30Z"
}
}
},
{
"config": "\"whole /config from zone\"",
"id": "f586f89c-2c4e-4f93-9a56-f0ea2ff010b7",
"globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
"connectTime": "2020-07-28T16:08:24.760801Z",
"status": {
"lastUpdateTime": "2020-07-28T16:08:25.770774Z",
"total": {
"responsesSent": "11",
"responsesAcknowledged": "11"
},
"stat": {
"CircuitBreaker": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"Dataplane": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"FaultInjection": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"HealthCheck": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"Mesh": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"ProxyTemplate": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"Secret": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficLog": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficPermission": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficRoute": {
"responsesSent": "1",
"responsesAcknowledged": "1"
},
"TrafficTrace": {
"responsesSent": "1",
"responsesAcknowledged": "1"
}
}
},
"version": {
"kumaCp": {
"version": "1.2.0-rc2-211-g823fe8ce",
"gitTag": "1.0.0-rc2-211-g823fe8ce",
"gitCommit": "823fe8cef6430a8f75e72a7224eb5a8ab571ec42",
"buildDate": "2021-02-18T13:22:30Z"
}
}
}
]
}
}
],
"next": null
}
External Services
Get External Service
Request: GET /meshes/{mesh}/external-services/{name}
Response: 200 OK with External Service entity
Example:
curl localhost:5681/meshes/default/external-services/httpbin
{
"type": "ExternalService",
"mesh": "default",
"name": "httpbin",
"creationTime": "2020-10-12T09:40:27.224648+03:00",
"modificationTime": "2020-10-12T09:40:27.224648+03:00",
"networking": {
"address": "httpbin.org:80",
"tls": {}
},
"tags": {
"kuma.io/protocol": "http",
"kuma.io/service": "httpbin"
}
}
Create/Update External Service
Request: PUT /meshes/{mesh}/external-services/{name} with External Service entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/default/external-services/es --data @es.json -H'content-type: application/json'
{
"type": "ExternalService",
"mesh": "default",
"name": "es",
"networking": {
"address": "httpbin.org:80",
"tls": {}
},
"tags": {
"kuma.io/protocol": "http",
"kuma.io/service": "es"
}
}
List External Services
Request: GET /external-services
Response: 200 OK with body of Zone entities
Example:
curl http://localhost:5681/external-services
{
"total": 2,
"items": [
{
"type": "ExternalService",
"mesh": "default",
"name": "httpbin",
"creationTime": "2020-10-12T09:40:27.224648+03:00",
"modificationTime": "2020-10-12T09:40:27.224648+03:00",
"networking": {
"address": "httpbin.org:80",
"tls": {}
},
"tags": {
"kuma.io/protocol": "http",
"kuma.io/service": "httpbin"
}
},
{
"type": "ExternalService",
"mesh": "default",
"name": "httpsbin",
"creationTime": "2020-10-12T09:41:07.275867+03:00",
"modificationTime": "2020-10-12T09:41:07.275867+03:00",
"networking": {
"address": "httpbin.org:443",
"tls": {
"enabled": true,
"caCert": {
"inline": "LS0tLS1=="
}
}
},
"tags": {
"kuma.io/protocol": "http",
"kuma.io/service": "httpsbin"
}
}
],
"next": null
}
Delete External Services
Request: DELETE /meshes/{mesh}/external-services/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/default/external-services/es
Service Insights
Get Service Insight
Request: GET /meshes/{mesh}/service-insights/{name}
Response: 200 OK with Service Insight entity
Example:
curl localhost:5681/meshes/default/service-insights/backend
{
"type": "ServiceInsight",
"mesh": "default",
"name": "backend",
"creationTime": "2020-10-12T09:40:27.224648+03:00",
"modificationTime": "2020-10-12T09:40:27.224648+03:00",
"status": "partially_degraded",
"dataplanes": {
"online": 1,
"offline": 1,
"total": 2
}
}
List Service Insights
Request: GET /service-insights
Response: 200 OK with body of Service Insights entities
Example:
curl http://localhost:5681/service-insights
{
"total": 2,
"items": [
{
"type": "ServiceInsight",
"mesh": "default",
"name": "backend",
"creationTime": "2020-10-12T09:40:27.224648+03:00",
"modificationTime": "2020-10-12T09:40:27.224648+03:00",
"status": "partially_degraded",
"dataplanes": {
"online": 1,
"offline": 1,
"total": 2
}
},
{
"type": "ServiceInsight",
"mesh": "default",
"name": "backend-api",
"creationTime": "2020-10-12T09:40:27.224648+03:00",
"modificationTime": "2020-10-12T09:40:27.224648+03:00",
"status": "partially_degraded",
"dataplanes": {
"online": 1,
"offline": 1,
"total": 2
}
}
],
"next": null
}
Secrets
Get Secret
Request: GET /meshes/{mesh}/secrets/{name}
Response: 200 OK with Secret entity
Example:
curl localhost:5681/meshes/default/secrets/sample-secret
{
"type": "Secret",
"mesh": "default",
"name": "sample-secret",
"creationTime": "2021-02-18T18:46:42.195647+01:00",
"modificationTime": "2021-02-18T18:46:42.195647+01:00",
"data": "dGVzdAo="
}
Create/Update Secret
Request: PUT /meshes/{mesh}/secrets/{name} with Secret entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/meshes/default/secrets/sample-secret --data @secret.json -H'content-type: application/json'
{
"type": "Secret",
"mesh": "default",
"name": "sample-secret",
"data": "dGVzdAo="
}
List Secrets
Request: GET /meshes/{mesh}/secrets
Response: 200 OK with body of Secret entities
Example:
curl http://localhost:5681/meshes/default/secrets
{
"total": 1,
"items": [
{
"type": "Secret",
"name": "sample-secret",
"mesh": "default",
"creationTime": "2021-02-18T18:46:42.195647+01:00",
"modificationTime": "2021-02-18T18:46:42.195647+01:00",
"data": "dGVzdAo="
}
],
"next": null
}
Delete Secret
Request: DELETE /meshes/{mesh}/secrets/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/meshes/default/secrets/sample-secret
Global Secrets
Get Global Secret
Request: GET /global-secrets/{name}
Response: 200 OK with Global Secret entity
Example:
curl localhost:5681/sample-global-secret
{
"type": "Secret",
"name": "sample-global-secret",
"creationTime": "2021-02-18T18:46:42.195647+01:00",
"modificationTime": "2021-02-18T18:46:42.195647+01:00",
"data": "dGVzdAo="
}
Create/Update Global Secret
Request: PUT /global-secrets/{name} with Global Secret entity in body
Response: 201 Created when the resource is created and 200 OK when it is updated
Example:
curl -XPUT http://localhost:5681/global-secrets/sample-global-secret --data @secret.json -H'content-type: application/json'
{
"type": "Secret",
"name": "sample-global-secret",
"data": "dGVzdAo="
}
List Global Secrets
Request: GET /global-secrets
Response: 200 OK with body of Global Secret entities
Example:
curl http://localhost:5681/global-secrets
{
"total": 1,
"items": [
{
"type": "Secret",
"name": "sample-global-secret",
"creationTime": "2021-02-18T18:46:42.195647+01:00",
"modificationTime": "2021-02-18T18:46:42.195647+01:00",
"data": "dGVzdAo="
}
],
"next": null
}
Delete Global Secret
Request: DELETE /global-secrets/{name}
Response: 200 OK
Example:
curl -XDELETE http://localhost:5681/global-secrets/sample-global-secret
Multi-zone
These APIs are available on the Global control plane, when running in a distributed multi-zone mode.
Zones status
Request: GET /status/zones
Response: 200 OK
Example:
curl -XGET http://localhost:5681/status/zones
[
{
"name": "zone-1",
"url": "grpcs://1.1.1.1:5685",
"active": true
},
{
"name": "zone-2",
"url": "grpcs://2.2.2.2:5685",
"active": false
}
]
Dataplane Proxy Tokens
Generate the data plane proxy tokens required for data plane proxy authentication.
For details, see data plane proxy authentication.
Generate dataplane proxy token
Request: PUT /tokens with the following body:
{
"name": "dp-echo-1",
"mesh": "default",
"tags": {
"kuma.io/service": ["backend", "backend-admin"]
}
}
Response: 200 OK
Example:
curl -XPOST \
-H "Content-Type: application/json" \
--data '{"name": "dp-echo-1", "mesh": "default", "tags": {"kuma.io/service": ["backend", "backend-admin"]}}' \
http://localhost:5681/tokens
Global Insights
Get Global Insights
Request: GET /global-insights
Response: 200 OK with Global Insights entity
Example:
curl localhost:5681/global-insights
{
"type": "GlobalInsights",
"creationTime": "2021-11-05T08:11:37.880477+01:00",
"resources": {
"GlobalSecret": {
"total": 3
},
"Mesh": {
"total": 1
},
"Zone": {
"total": 0
},
"ZoneIngress": {
"total": 0
}
}
}