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 HTTP API is listening on port 5681. The endpoints available are:

  • /config
  • /meshes
  • /dataplanes
  • /dataplanes+insights
  • /health-checks
  • /proxytemplates
  • /traffic-logs
  • /traffic-permissions
  • /traffic-routes
  • /fault-injections
  • /meshes/{name}
  • /meshes/{name}/dataplanes
  • /meshes/{name}/dataplanes/{name}
  • /meshes/{name}/dataplanes+insights
  • /meshes/{name}/dataplanes+insights/{name}
  • /meshes/{name}/health-checks
  • /meshes/{name}/health-checks/{name}
  • /meshes/{name}/proxytemplates
  • /meshes/{name}/proxytemplates/{name}
  • /meshes/{name}/traffic-logs
  • /meshes/{name}/traffic-logs/{name}
  • /meshes/{name}/traffic-permissions
  • /meshes/{name}/traffic-permissions/{name}
  • /meshes/{name}/traffic-routes
  • /meshes/{name}/traffic-routes/{name}
  • /meshes/{name}/fault-injections
  • /meshes/{name}/fault-injections/{name}
  • /status/clusters

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 a string, 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:

  1. {
  2.   "items": [...],
  3.   "next": "http://localhost:5681/meshes/default/dataplanes?offset=10"
  4. }

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:

  1. curl http://localhost:5681/config
  1. {
  2.   "adminServer": {
  3.     "apis": {
  4.       "dataplaneToken": {
  5.         "enabled": true
  6.       }
  7.     },
  8.     "local": {
  9.       "port": 5679
  10.     },
  11.     "public": {
  12.       "clientCertsDir": "/etc/kuma.io/kuma-cp/admin-api/tls/allowed-client-certs.d",
  13.       "enabled": true,
  14.       "interface": "0.0.0.0",
  15.       "port": 5684,
  16.       "tlsCertFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.cert",
  17.       "tlsKeyFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.key"
  18.     }
  19.   },
  20.   "apiServer": {
  21.     "corsAllowedDomains": [
  22.       ".*"
  23.     ],
  24.     "port": 5681,
  25.     "readOnly": false
  26.   },
  27.   "bootstrapServer": {
  28.     "params": {
  29.       "adminAccessLogPath": "/dev/null",
  30.       "adminAddress": "127.0.0.1",
  31.       "adminPort": 0,
  32.       "xdsConnectTimeout": "1s",
  33.       "xdsHost": "kuma-control-plane.internal",
  34.       "xdsPort": 5678
  35.     },
  36.     "port": 5682
  37.   },
  38.   "dataplaneTokenServer": {
  39.     "enabled": true,
  40.     "local": {
  41.       "port": 5679
  42.     },
  43.     "public": {
  44.       "clientCertsDir": "/etc/kuma.io/kuma-cp/admin-api/tls/allowed-client-certs.d",
  45.       "enabled": true,
  46.       "interface": "0.0.0.0",
  47.       "port": 5684,
  48.       "tlsCertFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.cert",
  49.       "tlsKeyFile": "/etc/kuma.io/kuma-cp/admin-api/tls/server.key"
  50.     }
  51.   },
  52.   "defaults": {
  53.     "mesh": "type: Mesh\nname: default"
  54.   },
  55.   "discovery": {
  56.     "universal": {
  57.       "pollingInterval": "1s"
  58.     }
  59.   },
  60.   "environment": "universal",
  61.   "general": {
  62.     "advertisedHostname": "kuma-control-plane.internal"
  63.   },
  64.   "guiServer": {
  65.     "port": 5683
  66.   },
  67.   "monitoringAssignmentServer": {
  68.     "assignmentRefreshInterval": "1s",
  69.     "grpcPort": 5676
  70.   },
  71.   "reports": {
  72.     "enabled": true
  73.   },
  74.   "runtime": {
  75.     "kubernetes": {
  76.       "admissionServer": {
  77.         "address": "",
  78.         "certDir": "",
  79.         "port": 5443
  80.       }
  81.     }
  82.   },
  83.   "sdsServer": {
  84.     "grpcPort": 5677,
  85.     "tlsCertFile": "/tmp/117637813.crt",
  86.     "tlsKeyFile": "/tmp/240596112.key"
  87.   },
  88.   "store": {
  89.     "kubernetes": {
  90.       "systemNamespace": "kuma-system"
  91.     },
  92.     "postgres": {
  93.       "connectionTimeout": 5,
  94.       "dbName": "kuma",
  95.       "host": "127.0.0.1",
  96.       "password": "*****",
  97.       "port": 15432,
  98.       "user": "kuma"
  99.     },
  100.     "type": "memory"
  101.   },
  102.   "xdsServer": {
  103.     "dataplaneConfigurationRefreshInterval": "1s",
  104.     "dataplaneStatusFlushInterval": "1s",
  105.     "diagnosticsPort": 5680,
  106.     "grpcPort": 5678
  107.   }
  108. }

Meshes

Get Mesh

Request: GET /meshes/{name}

Response: 200 OK with Mesh entity

Example:

  1. curl http://localhost:5681/meshes/mesh-1
  1. {
  2.   "name": "mesh-1",
  3.   "type": "Mesh",
  4.   "creationTime": "2020-05-12T12:31:45.606217+02:00",
  5.   "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  6.   "mtls": {
  7.     "backends": [
  8.       {
  9.         "name": "ca-1",
  10.         "type": "builtin"
  11.       },
  12.       {
  13.         "name": "ca-2",
  14.         "type": "provided",
  15.         "conf": {
  16.           "cert": {
  17.             "secret": "provided-cert"
  18.           },
  19.           "key": {
  20.             "secret": "provided-cert"
  21.           }
  22.         }
  23.       }
  24.     ],
  25.     "enabledBackend": "ca-1"
  26.   },
  27.   "tracing": {
  28.     "defaultBackend": "zipkin-1",
  29.     "backends": [
  30.       {
  31.         "name": "zipkin-1",
  32.         "type": "zipkin",
  33.         "conf": {
  34.           "url": "http://zipkin.local:9411/api/v2/spans"
  35.         }
  36.       }
  37.     ]
  38.   },
  39.   "logging": {
  40.     "backends": [
  41.       {
  42.         "name": "file-tmp",
  43.         "format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
  44.         "type": "file",
  45.         "conf": {
  46.           "path": "/tmp/access.log"
  47.         }
  48.       },
  49.       {
  50.         "name": "logstash",
  51.         "type": "tcp",
  52.         "conf": {
  53.           "address": "logstash.internal:9000"
  54.         }
  55.       }
  56.     ]
  57.   },
  58.   "metrics": {
  59.     "enabledBackend": "prometheus-1",
  60.     "backends": [
  61.       {
  62.         "name": "prometheus-1",
  63.         "type": "prometheus",
  64.         "conf": {
  65.           "port": 1234,
  66.           "path": "/metrics"
  67.         }
  68.       } 
  69.     ]
  70.   }
  71. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1 --data @mesh.json -H'content-type: application/json'
  1. {
  2.   "name": "mesh-1",
  3.   "type": "Mesh",
  4.   "mtls": {
  5.     "backends": [
  6.       {
  7.         "name": "ca-1",
  8.         "type": "builtin"
  9.       },
  10.       {
  11.         "name": "ca-2",
  12.         "type": "provided",
  13.         "conf": {
  14.           "cert": {
  15.             "secret": "provided-cert"
  16.           },
  17.           "key": {
  18.             "secret": "provided-cert"
  19.           }
  20.         }
  21.       }
  22.     ],
  23.     "enabledBackend": "ca-1"
  24.   },
  25.   "tracing": {
  26.     "defaultBackend": "zipkin-1",
  27.     "backends": [
  28.       {
  29.         "name": "zipkin-1",
  30.         "type": "zipkin",
  31.         "conf": {
  32.           "url": "http://zipkin.local:9411/api/v2/spans"
  33.         }
  34.       }
  35.     ]
  36.   },
  37.   "logging": {
  38.     "backends": [
  39.       {
  40.         "name": "file-tmp",
  41.         "format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
  42.         "type": "file",
  43.         "conf": {
  44.           "path": "/tmp/access.log"
  45.         }
  46.       },
  47.       {
  48.         "name": "logstash",
  49.         "type": "tcp",
  50.         "conf": {
  51.           "address": "logstash.internal:9000"
  52.         }
  53.       }
  54.     ]
  55.   },
  56.   "metrics": {
  57.     "enabledBackend": "prometheus-1",
  58.     "backends": [
  59.       {
  60.         "name": "prometheus-1",
  61.         "type": "prometheus",
  62.         "conf": {
  64.           "port": 1234,
  65.           "path": "/metrics"
  66.         }
  67.       } 
  68.     ]
  69.   }
  70. }

List Meshes

Request: GET /meshes

Response: 200 OK with body of Mesh entities

Example:

  1. curl http://localhost:5681/meshes
  1. {
  2.   "items": [
  3.     {
  4.       "name": "mesh-1",
  5.       "type": "Mesh",
  6.       "creationTime": "2020-05-12T12:31:45.606217+02:00",
  7.       "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  8.       "mtls": {
  9.         "backends": [
  10.           {
  11.             "name": "ca-1",
  12.             "type": "builtin"
  13.           },
  14.           {
  15.             "name": "ca-2",
  16.             "type": "provided",
  17.             "conf": {
  18.               "cert": {
  19.                 "secret": "provided-cert"
  20.               },
  21.               "key": {
  22.                 "secret": "provided-cert"
  23.               }
  24.             }
  25.           }
  26.         ],
  27.         "enabledBackend": "ca-1"
  28.       },
  29.       "tracing": {
  30.         "defaultBackend": "zipkin-1",
  31.         "backends": [
  32.           {
  33.             "name": "zipkin-1",
  34.             "type": "zipkin",
  35.             "conf": {
  36.               "url": "http://zipkin.local:9411/api/v2/spans"
  37.             }
  38.           }
  39.         ]
  40.       },
  41.       "logging": {
  42.         "backends": [
  43.           {
  44.             "name": "file-tmp",
  45.             "format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
  46.             "type": "file",
  47.             "conf": {
  48.               "path": "/tmp/access.log"
  49.             }
  50.           },
  51.           {
  52.             "name": "logstash",
  53.             "type": "tcp",
  54.             "conf": {
  55.               "address": "logstash.internal:9000"
  56.             }
  57.           }
  58.         ]
  59.       },
  60.       "metrics": {
  61.         "enabledBackend": "prometheus-1",
  62.         "backends": [
  63.           {
  64.             "name": "prometheus-1",
  65.             "type": "prometheus",
  66.             "conf": {
  67.               "port": 1234,
  68.               "path": "/metrics"
  69.             }
  70.           } 
  71.         ]
  72.       }
  73.     }
  74.   ],
  75.   "next": "http://localhost:5681/meshes?offset=1"
  76. }

Delete Mesh

Request: DELETE /meshes/{name}

Response: 200 OK

Example:

  1. curl -XDELETE http://localhost:5681/meshes/mesh-1

Dataplanes

Get Dataplane

Request: GET /meshes/{mesh}/dataplanes/{name}

Response: 200 OK with Mesh entity

Example:

  1. curl http://localhost:5681/meshes/mesh-1/dataplanes/backend-1
  1. {
  2.   "type": "Dataplane",
  3.   "name": "backend-1",
  4.   "mesh": "mesh-1",
  5.   "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.   "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.   "networking": {
  8.     "address": "127.0.0.1",
  9.     "inbound": [
  10.       {
  11.         "port": 11011,
  12.         "servicePort": 11012,
  13.         "tags": {
  14.           "service": "backend",
  15.           "version": "2.0",
  16.           "env": "production"
  17.         }
  18.       }
  19.     ],
  20.     "outbound": [
  21.       {
  22.         "port": 33033,
  23.         "service": "database"
  24.       },
  25.       {
  26.         "port": 44044,
  27.         "service": "user"
  28.       }
  29.     ]
  30.   }
  31. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1/dataplanes/backend-1 --data @dataplane.json -H'content-type: application/json'
  1. {
  2.   "type": "Dataplane",
  3.   "name": "backend-1",
  4.   "mesh": "mesh-1",
  5.   "networking": {
  6.     "address": "127.0.0.1",
  7.     "inbound": [
  8.       {
  9.         "port": 11011,
  10.         "servicePort": 11012,
  11.         "tags": {
  12.           "service": "backend",
  13.           "version": "2.0",
  14.           "env": "production"
  15.         }
  16.       }
  17.     ],
  18.     "outbound": [
  19.       {
  20.         "port": 33033,
  21.         "service": "database"
  22.       },
  23.       {
  24.         "port": 44044,
  25.         "service": "user"
  26.       }
  27.     ]
  28.   }
  29. }

List Dataplanes

Request: GET /meshes/{mesh}/dataplanes

Response: 200 OK with body of Dataplane entities

Example:

  1. curl http://localhost:5681/meshes/mesh-1/dataplanes
  1. {
  2.   "items": [
  3.     {
  4.       "type": "Dataplane",
  5.       "name": "backend-1",
  6.       "mesh": "mesh-1",
  7.       "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.       "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.       "networking": {
  10.         "address": "127.0.0.1",
  11.         "inbound": [
  12.           {
  13.             "port": 11011,
  14.             "servicePort": 11012,
  15.             "tags": {
  16.               "service": "backend",
  17.               "version": "2.0",
  18.               "env": "production"
  19.             }
  20.           }
  21.         ],
  22.         "outbound": [
  23.           {
  24.             "port": 33033,
  25.             "service": "database"
  26.           },
  27.           {
  28.             "port": 44044,
  29.             "service": "user"
  30.           }
  31.         ]
  32.       }
  33.     }
  34.   ],
  35.   "next": "http://localhost:5681/meshes/mesh-1/dataplanes?offset=1"
  36. }

Delete Dataplane

Request: DELETE /meshes/{mesh}/dataplanes/{name}

Response: 200 OK

Example:

  1. 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:

  1. curl http://localhost:5681/meshes/default/dataplanes+insights/example
  1. {
  2.  "type": "DataplaneOverview",
  3.  "mesh": "default",
  4.  "name": "example",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "dataplane": {
  8.   "networking": {
  9.    "address": "127.0.0.1",
  10.    "inbound": [
  11.     {
  12.      "port": 11011,
  13.      "servicePort": 11012,
  14.      "tags": {
  15.       "env": "production",
  16.       "service": "backend",
  17.       "version": "2.0"
  18.      }
  19.     }
  20.    ],
  21.    "outbound": [
  22.     {
  23.      "port": 33033,
  24.      "service": "database"
  25.     }
  26.    ]
  27.   }
  28.  },
  29.  "dataplaneInsight": {
  30.   "subscriptions": [
  31.    {
  32.     "id": "426fe0d8-f667-11e9-b081-acde48001122",
  33.     "controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
  34.     "connectTime": "2019-10-24T14:04:56.820350Z",
  35.     "status": {
  36.      "lastUpdateTime": "2019-10-24T14:04:57.832482Z",
  37.      "total": {
  38.       "responsesSent": "3",
  39.       "responsesAcknowledged": "3"
  40.      },
  41.      "cds": {
  42.       "responsesSent": "1",
  43.       "responsesAcknowledged": "1"
  44.      },
  45.      "eds": {
  46.       "responsesSent": "1",
  47.       "responsesAcknowledged": "1"
  48.      },
  49.      "lds": {
  50.       "responsesSent": "1",
  51.       "responsesAcknowledged": "1"
  52.      },
  53.      "rds": {}
  54.     }
  55.    }
  56.   ]
  57.  }
  58. }

List Dataplane Overviews

Request: GET /meshes/{mesh}/dataplane+insights/

Response: 200 OK with Dataplane entities including insight

Example:

  1. curl http://localhost:5681/meshes/default/dataplanes+insights
  1. {
  2.   "items": [
  3.     {
  4.      "type": "DataplaneOverview",
  5.      "mesh": "default",
  6.      "name": "example",
  7.      "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.      "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.      "dataplane": {
  10.       "networking": {
  11.        "address": "127.0.0.1",
  12.        "inbound": [
  13.         {
  14.          "port": 11011,
  15.          "servicePort": 11012,
  16.          "tags": {
  17.           "env": "production",
  18.           "service": "backend",
  19.           "version": "2.0"
  20.          }
  21.         }
  22.        ],
  23.        "outbound": [
  24.         {
  25.          "port": 33033,
  26.          "service": "database"
  27.         }
  28.        ]
  29.       }
  30.      },
  31.      "dataplaneInsight": {
  32.       "subscriptions": [
  33.        {
  34.         "id": "426fe0d8-f667-11e9-b081-acde48001122",
  35.         "controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
  36.         "connectTime": "2019-10-24T14:04:56.820350Z",
  37.         "status": {
  38.          "lastUpdateTime": "2019-10-24T14:04:57.832482Z",
  39.          "total": {
  40.           "responsesSent": "3",
  41.           "responsesAcknowledged": "3"
  42.          },
  43.          "cds": {
  44.           "responsesSent": "1",
  45.           "responsesAcknowledged": "1"
  46.          },
  47.          "eds": {
  48.           "responsesSent": "1",
  49.           "responsesAcknowledged": "1"
  50.          },
  51.          "lds": {
  52.           "responsesSent": "1",
  53.           "responsesAcknowledged": "1"
  54.          },
  55.          "rds": {}
  56.         }
  57.        }
  58.       ]
  59.      }
  60.     }
  61.   ],
  62.   "next": "http://localhost:5681/meshes/default/dataplanes+insights?offset=1"
  63. }

Health Check

Get Health Check

Request: GET /meshes/{mesh}/health-checks/{name}

Response: 200 OK with Health Check entity

Example:

  1. curl http://localhost:5681/meshes/mesh-1/health-checks/web-to-backend
  1. {
  2.  "type": "HealthCheck",
  3.  "mesh": "mesh-1",
  4.  "name": "web-to-backend",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "sources": [
  8.   {
  9.    "match": {
  10.     "service": "web"
  11.    }
  12.   }
  13.  ],
  14.  "destinations": [
  15.   {
  16.    "match": {
  17.     "service": "backend"
  18.    }
  19.   }
  20.  ],
  21.  "conf": {
  22.   "activeChecks": {
  23.    "interval": "10s",
  24.    "timeout": "2s",
  25.    "unhealthyThreshold": 3,
  26.    "healthyThreshold": 1
  27.   }
  28.  }
  29. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1/health-checks/web-to-backend --data @healthcheck.json -H'content-type: application/json'
  1. {
  2.  "type": "HealthCheck",
  3.  "mesh": "mesh-1",
  4.  "name": "web-to-backend",
  5.  "sources": [
  6.   {
  7.    "match": {
  8.     "service": "web"
  9.    }
  10.   }
  11.  ],
  12.  "destinations": [
  13.   {
  14.    "match": {
  15.     "service": "backend"
  16.    }
  17.   }
  18.  ],
  19.  "conf": {
  20.   "activeChecks": {
  21.    "interval": "10s",
  22.    "timeout": "2s",
  23.    "unhealthyThreshold": 3,
  24.    "healthyThreshold": 1
  25.   }
  26.  }
  27. }

List Health Checks

Request: GET /meshes/{mesh}/health-checks

Response: 200 OK with body of Health Check entities

Example:

  1. curl http://localhost:5681/meshes/mesh-1/health-checks
  1. {
  2.  "items": [
  3.   {
  4.    "type": "HealthCheck",
  5.    "mesh": "mesh-1",
  6.    "name": "web-to-backend",
  7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.    "sources": [
  10.     {
  11.      "match": {
  12.       "service": "web"
  13.      }
  14.     }
  15.    ],
  16.    "destinations": [
  17.     {
  18.      "match": {
  19.       "service": "backend"
  20.      }
  21.     }
  22.    ],
  23.    "conf": {
  24.     "activeChecks": {
  25.      "interval": "10s",
  26.      "timeout": "2s",
  27.      "unhealthyThreshold": 3,
  28.      "healthyThreshold": 1
  29.     }
  30.    }
  31.   }
  32.  ],
  33.  "next": "http://localhost:5681/meshes/mesh-1/health-checks?offset=1"
  34. }

Delete Health Check

Request: DELETE /meshes/{mesh}/health-checks/{name}

Response: 200 OK

Example:

  1. 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:

  1. curl http://localhost:5681/meshes/mesh-1/proxytemplates/pt-1
  1. {
  2.  "type": "ProxyTemplate",
  3.  "mesh": "mesh-1",
  4.  "name": "pt-1",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "selectors": [
  8.   {
  9.    "match": {
  10.     "service": "backend"
  11.    }
  12.   }
  13.  ],
  14.  "conf": {
  15.   "imports": [
  16.    "default-proxy"
  17.   ],
  18.   "resources": [
  19.    {
  20.     "name": "raw-name",
  21.     "version": "raw-version",
  22.     "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"
  23.    }
  24.   ]
  25.  }
  26. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1/proxytemplates/pt-1 --data @proxytemplate.json -H'content-type: application/json'
  1. {
  2.   "type": "ProxyTemplate",
  3.   "name": "pt-1",
  4.   "mesh": "mesh-1",
  5.   "selectors": [
  6.     {
  7.       "match": {
  8.           "service": "backend"
  9.       }
  10.     }
  11.   ],
  12.   "conf": {
  13.     "imports": [
  14.       "default-proxy"
  15.     ],
  16.     "resources": [
  17.       {
  18.         "name": "raw-name",
  19.         "version": "raw-version",
  20.         "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"
  21.       }
  22.     ]
  23.   }
  24. }

List Proxy Templates

Request: GET /meshes/{mesh}/proxytemplates

Response: 200 OK with body of Proxy Template entities

Example:

  1. curl http://localhost:5681/meshes/mesh-1/proxytemplates
  1. {
  2.  "items": [
  3.   {
  4.    "type": "ProxyTemplate",
  5.    "mesh": "mesh-1",
  6.    "name": "pt-1",
  7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.    "selectors": [
  10.     {
  11.      "match": {
  12.       "service": "backend"
  13.      }
  14.     }
  15.    ],
  16.    "conf": {
  17.     "imports": [
  18.      "default-proxy"
  19.     ],
  20.     "resources": [
  21.      {
  22.       "name": "raw-name",
  23.       "version": "raw-version",
  24.       "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"
  25.      }
  26.     ]
  27.    }
  28.   }
  29.  ],
  30.  "next": "http://localhost:5681/meshes/mesh-1/proxytemplates?offset=1"
  31. }

Delete Proxy Template

Request: DELETE /meshes/{mesh}/proxytemplates/{name}

Response: 200 OK

Example:

  1. 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:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-permissions/tp-1
  1. {
  2.  "type": "TrafficPermission",
  3.  "mesh": "mesh-1",
  4.  "name": "tp-1",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "sources": [
  8.   {
  9.    "match": {
  10.     "service": "backend"
  11.    }
  12.   }
  13.  ],
  14.  "destinations": [
  15.   {
  16.    "match": {
  17.     "service": "redis"
  18.    }
  19.   }
  20.  ]
  21. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-permissions/tp-1 --data @trafficpermission.json -H'content-type: application/json'
  1. {
  2.   "type": "TrafficPermission",
  3.   "name": "tp-1",
  4.   "mesh": "mesh-1",
  5.   "sources": [
  6.     {
  7.       "match": {
  8.         "service": "backend"
  9.       }
  10.     }
  11.   ],
  12.   "destinations": [
  13.     {
  14.       "match": {
  15.         "service": "redis"
  16.       }
  17.     }
  18.   ]
  19. }

List Traffic Permissions

Request: GET /meshes/{mesh}/traffic-permissions

Response: 200 OK with body of Traffic Permission entities

Example:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-permissions
  1. {
  2.  "items": [
  3.   {
  4.    "type": "TrafficPermission",
  5.    "mesh": "mesh-1",
  6.    "name": "tp-1",
  7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.    "sources": [
  10.     {
  11.      "match": {
  12.       "service": "backend"
  13.      }
  14.     }
  15.    ],
  16.    "destinations": [
  17.     {
  18.      "match": {
  19.       "service": "redis"
  20.      }
  21.     }
  22.    ]
  23.   }
  24.  ],
  25.  "next": "http://localhost:5681/meshes/mesh-1/traffic-permissions?offset=1"
  26. }

Delete Traffic Permission

Request: DELETE /meshes/{mesh}/traffic-permissions/{name}

Response: 200 OK

Example:

  1. 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:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-logs/tl-1
  1. {
  2.  "type": "TrafficLog",
  3.  "mesh": "mesh-1",
  4.  "name": "tl-1",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "sources": [
  8.   {
  9.    "match": {
  10.     "service": "web",
  11.     "version": "1.0"
  12.    }
  13.   }
  14.  ],
  15.  "destinations": [
  16.   {
  17.    "match": {
  18.     "service": "backend"
  19.    }
  20.   }
  21.  ],
  22.  "conf": {
  23.   "backend": "file"
  24.  }
  25. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-logs/tl-1 --data @trafficlog.json -H'content-type: application/json'
  1. {
  2.   "type": "TrafficLog",
  3.   "mesh": "mesh-1",
  4.   "name": "tl-1",
  5.   "sources": [
  6.     {
  7.       "match": {
  8.         "service": "web",
  9.         "version": "1.0"
  10.       }
  11.     }
  12.   ],
  13.   "destinations": [
  14.     {
  15.       "match": {
  16.         "service": "backend"
  17.       }
  18.     }
  19.   ],
  20.   "conf": {
  21.     "backend": "file"
  22.   }
  23. }

List Traffic Logs

Request: GET /meshes/{mesh}/traffic-logs

Response: 200 OK with body of Traffic Log entities

Example:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-logs
  1. {
  2.  "items": [
  3.   {
  4.    "type": "TrafficLog",
  5.    "mesh": "mesh-1",
  6.    "name": "tl-1",
  7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.    "sources": [
  10.     {
  11.      "match": {
  12.       "service": "web",
  13.       "version": "1.0"
  14.      }
  15.     }
  16.    ],
  17.    "destinations": [
  18.     {
  19.      "match": {
  20.       "service": "backend"
  21.      }
  22.     }
  23.    ],
  24.    "conf": {
  25.     "backend": "file"
  26.    }
  27.   }
  28.  ],
  29.  "next": "http://localhost:5681/meshes/mesh-1/traffic-logs?offset=1"
  30. }

Delete Traffic Log

Request: DELETE /meshes/{mesh}/traffic-logs/{name}

Response: 200 OK

Example:

  1. 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:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-routes/web-to-backend
  1. {
  2.  "type": "TrafficRoute",
  3.  "mesh": "mesh-1",
  4.  "name": "web-to-backend",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "sources": [
  8.   {
  9.    "match": {
  10.     "region": "us-east-1",
  11.     "service": "web",
  12.     "version": "v10"
  13.    }
  14.   }
  15.  ],
  16.  "destinations": [
  17.   {
  18.    "match": {
  19.     "service": "backend"
  20.    }
  21.   }
  22.  ],
  23.  "conf": [
  24.   {
  25.    "weight": 90,
  26.    "destination": {
  27.     "region": "us-east-1",
  28.     "service": "backend",
  29.     "version": "v2"
  30.    }
  31.   },
  32.   {
  33.    "weight": 10,
  34.    "destination": {
  35.     "service": "backend",
  36.     "version": "v3"
  37.    }
  38.   }
  39.  ]
  40. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-routes/web-to-backend --data @trafficroute.json -H'content-type: application/json'
  1. {
  2.  "type": "TrafficRoute",
  3.  "name": "web-to-backend",
  4.  "mesh": "mesh-1",
  5.  "sources": [
  6.   {
  7.    "match": {
  8.     "region": "us-east-1",
  9.     "service": "web",
  10.     "version": "v10"
  11.    }
  12.   }
  13.  ],
  14.  "destinations": [
  15.   {
  16.    "match": {
  17.     "service": "backend"
  18.    }
  19.   }
  20.  ],
  21.  "conf": [
  22.   {
  23.    "weight": 90,
  24.    "destination": {
  25.     "region": "us-east-1",
  26.     "service": "backend",
  27.     "version": "v2"
  28.    }
  29.   },
  30.   {
  31.    "weight": 10,
  32.    "destination": {
  33.     "service": "backend",
  34.     "version": "v3"
  35.    }
  36.   }
  37.  ]
  38. }

List Traffic Routes

Request: GET /meshes/{mesh}/traffic-routes

Response: 200 OK with body of Traffic Route entities

Example:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-routes
  1. {
  2.  "items": [
  3.   {
  4.    "type": "TrafficRoute",
  5.    "mesh": "mesh-1",
  6.    "name": "web-to-backend",
  7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.    "sources": [
  10.     {
  11.      "match": {
  12.       "region": "us-east-1",
  13.       "service": "web",
  14.       "version": "v10"
  15.      }
  16.     }
  17.    ],
  18.    "destinations": [
  19.     {
  20.      "match": {
  21.       "service": "backend"
  22.      }
  23.     }
  24.    ],
  25.    "conf": [
  26.     {
  27.      "weight": 90,
  28.      "destination": {
  29.       "region": "us-east-1",
  30.       "service": "backend",
  31.       "version": "v2"
  32.      }
  33.     },
  34.     {
  35.      "weight": 10,
  36.      "destination": {
  37.       "service": "backend",
  38.       "version": "v3"
  39.      }
  40.     }
  41.    ]
  42.   }
  43.  ],
  44.  "next": "http://localhost:5681/meshes/mesh-1/traffic-routes?offset=1"
  45. }

Delete Traffic Route

Request: DELETE /meshes/{mesh}/traffic-routes/{name}

Response: 200 OK

Example:

  1. 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:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-traces/tt-1
  1. {
  2.  "type": "TrafficTrace",
  3.  "mesh": "mesh-1",
  4.  "name": "tt-1",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "conf": {
  8.   "backend": "my-zipkin"
  9.  },
  10.  "selectors": [
  11.   {
  12.    "match": {
  13.     "service": "*"
  14.    }
  15.   }
  16.  ]
  17. }

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:

  1. curl -XPUT http://localhost:5681/meshes/mesh-1/traffic-traces/tt-1 --data @traffictrace.json -H'content-type: application/json'
  1. {
  2.  "type": "TrafficTrace",
  3.  "mesh": "mesh-1",
  4.  "name": "tt-1",
  5.  "conf": {
  6.   "backend": "my-zipkin"
  7.  },
  8.  "selectors": [
  9.   {
  10.    "match": {
  11.     "service": "*"
  12.    }
  13.   }
  14.  ]
  15. }

List Traffic Traces

Request: GET /meshes/{mesh}/traffic-traces

Response: 200 OK with body of Traffic Trace entities

Example:

  1. curl http://localhost:5681/meshes/mesh-1/traffic-traces
  1. {
  2.  "items": [
  3.   {
  4.    "type": "TrafficTrace",
  5.    "mesh": "mesh-1",
  6.    "name": "tt-1",
  7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.    "selectors": [
  10.     {
  11.      "match": {
  12.       "service": "*"
  13.      }
  14.     }
  15.    ],
  16.    "conf": {
  17.     "backend": "my-zipkin"
  18.    }
  19.   }
  20.  ],
  21.  "next": "http://localhost:5681/meshes/mesh-1/traffic-traces?offset=1"
  22. }

Delete Traffic Trace

Request: DELETE /meshes/{mesh}/traffic-traces/{name}

Response: 200 OK

Example:

  1. 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:

  1. curl http://localhost:5681/meshes/default/fault-injections/fi1
  1. {
  2.  "type": "FaultInjection",
  3.  "mesh": "default",
  4.  "name": "fi1",
  5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  7.  "sources": [
  8.   {
  9.    "match": {
  10.     "protocol": "http",
  11.     "service": "frontend",
  12.     "version": "0.1"
  13.    }
  14.   }
  15.  ],
  16.  "destinations": [
  17.   {
  18.    "match": {
  19.     "protocol": "http",
  20.     "service": "backend"
  21.    }
  22.   }
  23.  ],
  24.  "conf": {
  25.   "delay": {
  26.    "percentage": 50.5,
  27.    "value": "5s"
  28.   },
  29.   "abort": {
  30.    "percentage": 50,
  31.    "httpStatus": 500
  32.   },
  33.   "responseBandwidth": {
  34.    "percentage": 50,
  35.    "limit": "50 mbps"
  36.   }
  37.  }
  38. }

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:

  1. curl -XPUT http://localhost:5681/meshes/default/fault-injections/fi1 --data @faultinjection.json -H'content-type: application/json'
  1. {
  2.   "type": "FaultInjection",
  3.   "mesh": "default",
  4.   "name": "fi1",
  5.   "sources": [
  6.     {
  7.       "match": {
  8.         "service": "frontend",
  9.         "version": "0.1",
  10.         "protocol": "http"
  11.       }
  12.     }
  13.   ],
  14.   "destinations": [
  15.     {
  16.       "match": {
  17.         "service": "backend",
  18.         "protocol": "http"
  19.       }
  20.     }
  21.   ],
  22.   "conf": {
  23.     "delay": {
  24.       "percentage": 50.5,
  25.       "value": "5s"
  26.     },
  27.     "abort": {
  28.       "httpStatus": 500,
  29.       "percentage": 50
  30.     },
  31.     "responseBandwidth": {
  32.       "limit": "50 mbps",
  33.       "percentage": 50
  34.     }
  35.   }
  36. }

List Fault Injections

Request: GET /meshes/{mesh}/fault-injections

Response: 200 OK with body of Fault Injection entities

Example:

  1. curl http://localhost:5681/meshes/default/fault-injections
  1. {
  2.  "items": [
  3.   {
  4.    "type": "FaultInjection",
  5.    "mesh": "default",
  6.    "name": "fi1",
  7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
  8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  9.    "sources": [
  10.     {
  11.      "match": {
  12.       "protocol": "http",
  13.       "service": "frontend",
  14.       "version": "0.1"
  15.      }
  16.     }
  17.    ],
  18.    "destinations": [
  19.     {
  20.      "match": {
  21.       "protocol": "http",
  22.       "service": "backend"
  23.      }
  24.     }
  25.    ],
  26.    "conf": {
  27.     "delay": {
  28.      "percentage": 50.5,
  29.      "value": "5s"
  30.     },
  31.     "abort": {
  32.      "percentage": 50,
  33.      "httpStatus": 500
  34.     },
  35.     "responseBandwidth": {
  36.      "percentage": 50,
  37.      "limit": "50 mbps"
  38.     }
  39.    }
  40.   }
  41.  ],
  42.  "next": "http://localhost:5681/meshes/default/fault-injections?offset=1"
  43. }

Delete Fault Injection

Request: DELETE /meshes/{mesh}/fault-injections/{name}

Response: 200 OK

Example:

  1. curl -XDELETE http://localhost:5681/meshes/default/fault-injections/fi1

The kumactl CLI under the hood makes HTTP requests to this API.

Multicluster

These APIs are available on the Global control plane, when running in a distributed multicluster mode.

Zones status

Request: GET /status/config

Response: 200 OK

Example:

  1. curl -XGET http://localhost:5681/status/clusters
  1. [
  2.  {
  3.   "name": "zone-1",
  4.   "url": "grpcs://1.1.1.1:5685",
  5.   "active": true
  6.  },
  7.  {
  8.   "name": "`zone-2`",
  9.   "url": "grpcs://2.2.2.2:5685",
  10.   "active": false
  11.  }
  12. ]