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:

  • /meshes
  • /meshes/{name}
  • /meshes/{name}/dataplanes
  • /meshes/{name}/dataplanes/{name}

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.

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.   "mtls": {
  5.     "ca": {
  6.       "builtin": {}
  7.     },
  8.     "enabled": true
  9.   },
  10.   "tracing": {},
  11.   "logging": {
  12.     "backends": [
  13.       {
  14.         "name": "file-tmp",
  15.         "format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
  16.         "file": {
  17.           "path": "/tmp/access.log"
  18.         }
  19.       },
  20.       {
  21.         "name": "logstash",
  22.         "tcp": {
  23.           "address": "logstash.internal:9000"
  24.         }
  25.       }
  26.     ]
  27.   }
  28. }

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 

  1. {
  2.   "name": "mesh-1",
  3.   "type": "Mesh",
  4.   "mtls": {
  5.     "ca": {
  6.       "builtin": {}
  7.     },
  8.     "enabled": true
  9.   },
  10.   "tracing": {},
  11.   "logging": {
  12.     "backends": [
  13.       {
  14.         "name": "file-tmp",
  15.         "format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
  16.         "file": {
  17.           "path": "/tmp/access.log"
  18.         }
  19.       },
  20.       {
  21.         "name": "logstash",
  22.         "tcp": {
  23.           "address": "logstash.internal:9000"
  24.         }
  25.       }
  26.     ]
  27.   }
  28. }

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.       "type": "Mesh",
  5.       "name": "mesh-1",
  6.       "mtls": {
  7.         "ca": {
  8.           "builtin": {}
  9.         },
  10.         "enabled": true
  11.       },
  12.       "tracing": {},
  13.       "logging": {
  14.         "backends": [
  15.           {
  16.             "name": "file-tmp",
  17.             "format": "{ \"destination\": \"%KUMA_DESTINATION_SERVICE%\", \"destinationAddress\": \"%UPSTREAM_LOCAL_ADDRESS%\", \"source\": \"%KUMA_SOURCE_SERVICE%\", \"sourceAddress\": \"%KUMA_SOURCE_ADDRESS%\", \"bytesReceived\": \"%BYTES_RECEIVED%\", \"bytesSent\": \"%BYTES_SENT%\"}",
  18.             "file": {
  19.               "path": "/tmp/access.log"
  20.             }
  21.           },
  22.           {
  23.             "name": "logstash",
  24.             "tcp": {
  25.               "address": "logstash.internal:9000"
  26.             }
  27.           }
  28.         ]
  29.       }
  30.     }
  31.   ]
  32. }

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.   "networking": {
  6.     "inbound": [
  7.       {
  8.         "interface": "127.0.0.1:11011:11012",
  9.         "tags": {
  10.           "service": "backend",
  11.           "version": "2.0",
  12.           "env": "production"
  13.         }
  14.       }
  15.     ],
  16.     "outbound": [
  17.       {
  18.         "interface": ":33033",
  19.         "service": "database"
  20.       },
  21.       {
  22.         "interface": ":44044",
  23.         "service": "user"
  24.       }
  25.     ]
  26.   }
  27. }

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.     "inbound": [
  7.       {
  8.         "interface": "127.0.0.1:11011:11012",
  9.         "tags": {
  10.           "service": "backend",
  11.           "version": "2.0",
  12.           "env": "production"
  13.         }
  14.       }
  15.     ],
  16.     "outbound": [
  17.       {
  18.         "interface": ":33033",
  19.         "service": "database"
  20.       },
  21.       {
  22.         "interface": ":44044",
  23.         "service": "user"
  24.       }
  25.     ]
  26.   }
  27. }

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.       "networking": {
  8.         "inbound": [
  9.           {
  10.             "interface": "127.0.0.1:11011:11012",
  11.             "tags": {
  12.               "service": "backend",
  13.               "version": "2.0",
  14.               "env": "production"
  15.             }
  16.           }
  17.         ],
  18.         "outbound": [
  19.           {
  20.             "interface": ":33033",
  21.             "service": "database"
  22.           },
  23.           {
  24.             "interface": ":44044",
  25.             "service": "user"
  26.           }
  27.         ]
  28.       }
  29.     }
  30.   ]
  31. }

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.  "dataplane": {
  6.   "networking": {
  7.    "inbound": [
  8.     {
  9.      "interface": "127.0.0.1:11011:11012",
  10.      "tags": {
  11.       "env": "production",
  12.       "service": "backend",
  13.       "version": "2.0"
  14.      }
  15.     }
  16.    ],
  17.    "outbound": [
  18.     {
  19.      "interface": ":33033",
  20.      "service": "database"
  21.     }
  22.    ]
  23.   }
  24.  },
  25.  "dataplaneInsight": {
  26.   "subscriptions": [
  27.    {
  28.     "id": "426fe0d8-f667-11e9-b081-acde48001122",
  29.     "controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
  30.     "connectTime": "2019-10-24T14:04:56.820350Z",
  31.     "status": {
  32.      "lastUpdateTime": "2019-10-24T14:04:57.832482Z",
  33.      "total": {
  34.       "responsesSent": "3",
  35.       "responsesAcknowledged": "3"
  36.      },
  37.      "cds": {
  38.       "responsesSent": "1",
  39.       "responsesAcknowledged": "1"
  40.      },
  41.      "eds": {
  42.       "responsesSent": "1",
  43.       "responsesAcknowledged": "1"
  44.      },
  45.      "lds": {
  46.       "responsesSent": "1",
  47.       "responsesAcknowledged": "1"
  48.      },
  49.      "rds": {}
  50.     }
  51.    }
  52.   ]
  53.  }
  54. }

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.      "dataplane": {
  8.       "networking": {
  9.        "inbound": [
  10.         {
  11.          "interface": "127.0.0.1:11011:11012",
  12.          "tags": {
  13.           "env": "production",
  14.           "service": "backend",
  15.           "version": "2.0"
  16.          }
  17.         }
  18.        ],
  19.        "outbound": [
  20.         {
  21.          "interface": ":33033",
  22.          "service": "database"
  23.         }
  24.        ]
  25.       }
  26.      },
  27.      "dataplaneInsight": {
  28.       "subscriptions": [
  29.        {
  30.         "id": "426fe0d8-f667-11e9-b081-acde48001122",
  31.         "controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
  32.         "connectTime": "2019-10-24T14:04:56.820350Z",
  33.         "status": {
  34.          "lastUpdateTime": "2019-10-24T14:04:57.832482Z",
  35.          "total": {
  36.           "responsesSent": "3",
  37.           "responsesAcknowledged": "3"
  38.          },
  39.          "cds": {
  40.           "responsesSent": "1",
  41.           "responsesAcknowledged": "1"
  42.          },
  43.          "eds": {
  44.           "responsesSent": "1",
  45.           "responsesAcknowledged": "1"
  46.          },
  47.          "lds": {
  48.           "responsesSent": "1",
  49.           "responsesAcknowledged": "1"
  50.          },
  51.          "rds": {}
  52.         }
  53.        }
  54.       ]
  55.      }
  56.     }
  57.   ]
  58. }

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.   "name": "pt-1",
  4.   "mesh": "mesh-1",
  5.   "selectors": [
  6.     {
  7.       "match": {
  8.           "app": "backend"
  9.       }
  10.     }
  11.   ],
  12.   "imports": [
  13.     "default-proxy"
  14.   ],
  15.   "resources": [
  16.     {
  17.       "name": "raw-name",
  18.       "version": "raw-version",
  19.       "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"
  20.     }
  21.   ]
  22. }

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.           "app": "backend"
  9.       }
  10.     }
  11.   ],
  12.   "imports": [
  13.     "default-proxy"
  14.   ],
  15.   "resources": [
  16.     {
  17.       "name": "raw-name",
  18.       "version": "raw-version",
  19.       "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"
  20.     }
  21.   ]
  22. }

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.       "name": "pt-1",
  6.       "mesh": "mesh-1",
  7.       "selectors": [
  8.         {
  9.           "match": {
  10.               "app": "backend"
  11.           }
  12.         }
  13.       ],
  14.       "imports": [
  15.         "default-proxy"
  16.       ],
  17.       "resources": [
  18.         {
  19.           "name": "raw-name",
  20.           "version": "raw-version",
  21.           "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"
  22.         }
  23.       ]
  24.     }
  25.   ]
  26. }

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.   "name": "tp-1",
  4.   "mesh": "mesh-1",
  5.   "rules": [
  6.     {
  7.       "sources": [
  8.         {
  9.           "match": {
  10.             "service": "web"
  11.           }
  12.         }
  13.       ],
  14.       "destinations": [
  15.         {
  16.           "match": {
  17.             "service": "backend"
  18.           }
  19.         }
  20.       ]
  21.     },
  22.     {
  23.       "sources": [
  24.         {
  25.           "match": {
  26.             "service": "backend",
  27.             "version": "1"
  28.           }
  29.         }
  30.       ],
  31.       "destinations": [
  32.         {
  33.           "match": {
  34.             "service": "redis",
  35.             "version": "1"
  36.           }
  37.         }
  38.       ]
  39.     },
  40.     {
  41.       "sources": [
  42.         {
  43.           "match": {
  44.             "service": "backend",
  45.             "version": "2"
  46.           }
  47.         }
  48.       ],
  49.       "destinations": [
  50.         {
  51.           "match": {
  52.             "service": "redis",
  53.             "version": "2"
  54.           }
  55.         }
  56.       ]
  57.     }
  58.   ]
  59. }

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.   "rules": [
  6.     {
  7.       "sources": [
  8.         {
  9.           "match": {
  10.             "service": "web"
  11.           }
  12.         }
  13.       ],
  14.       "destinations": [
  15.         {
  16.           "match": {
  17.             "service": "backend"
  18.           }
  19.         }
  20.       ]
  21.     },
  22.     {
  23.       "sources": [
  24.         {
  25.           "match": {
  26.             "service": "backend",
  27.             "version": "1"
  28.           }
  29.         }
  30.       ],
  31.       "destinations": [
  32.         {
  33.           "match": {
  34.             "service": "redis",
  35.             "version": "1"
  36.           }
  37.         }
  38.       ]
  39.     },
  40.     {
  41.       "sources": [
  42.         {
  43.           "match": {
  44.             "service": "backend",
  45.             "version": "2"
  46.           }
  47.         }
  48.       ],
  49.       "destinations": [
  50.         {
  51.           "match": {
  52.             "service": "redis",
  53.             "version": "2"
  54.           }
  55.         }
  56.       ]
  57.     }
  58.   ]
  59. }

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.       "name": "tp-1",
  6.       "mesh": "mesh-1",
  7.       "rules": [
  8.         {
  9.           "sources": [
  10.             {
  11.               "match": {
  12.                 "service": "web"
  13.               }
  14.             }
  15.           ],
  16.           "destinations": [
  17.             {
  18.               "match": {
  19.                 "service": "backend"
  20.               }
  21.             }
  22.           ]
  23.         },
  24.         {
  25.           "sources": [
  26.             {
  27.               "match": {
  28.                 "service": "backend",
  29.                 "version": "1"
  30.               }
  31.             }
  32.           ],
  33.           "destinations": [
  34.             {
  35.               "match": {
  36.                 "service": "redis",
  37.                 "version": "1"
  38.               }
  39.             }
  40.           ]
  41.         },
  42.         {
  43.           "sources": [
  44.             {
  45.               "match": {
  46.                 "service": "backend",
  47.                 "version": "2"
  48.               }
  49.             }
  50.           ],
  51.           "destinations": [
  52.             {
  53.               "match": {
  54.                 "service": "redis",
  55.                 "version": "2"
  56.               }
  57.             }
  58.           ]
  59.         }
  60.       ]
  61.     }
  62.   ]
  63. }

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.   "rules": [
  6.     {
  7.       "sources": [
  8.         {
  9.           "match": {
  10.             "service": "web",
  11.             "version": "1.0"
  12.           }
  13.         }
  14.       ],
  15.       "destinations": [
  16.         {
  17.           "match": {
  18.             "env": "dev",
  19.             "service": "backend"
  20.           }
  21.         }
  22.       ],
  23.       "conf": {
  24.         "backend": "file"
  25.       }
  26.     },
  27.     {
  28.       "sources": [
  29.         {
  30.           "match": {
  31.             "service": "backend"
  32.           }
  33.         }
  34.       ],
  35.       "destinations": [
  36.         {
  37.           "match": {
  38.             "service": "redis"
  39.           }
  40.         }
  41.       ]
  42.     }
  43.   ]
  44. }

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.   "rules": [
  6.     {
  7.       "sources": [
  8.         {
  9.           "match": {
  10.             "service": "web",
  11.             "version": "1.0"
  12.           }
  13.         }
  14.       ],
  15.       "destinations": [
  16.         {
  17.           "match": {
  18.             "env": "dev",
  19.             "service": "backend"
  20.           }
  21.         }
  22.       ],
  23.       "conf": {
  24.         "backend": "file"
  25.       }
  26.     },
  27.     {
  28.       "sources": [
  29.         {
  30.           "match": {
  31.             "service": "backend"
  32.           }
  33.         }
  34.       ],
  35.       "destinations": [
  36.         {
  37.           "match": {
  38.             "service": "redis"
  39.           }
  40.         }
  41.       ]
  42.     }
  43.   ]
  44. }

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.       "rules": [
  8.         {
  9.           "sources": [
  10.             {
  11.               "match": {
  12.                 "service": "web",
  13.                 "version": "1.0"
  14.               }
  15.             }
  16.           ],
  17.           "destinations": [
  18.             {
  19.               "match": {
  20.                 "env": "dev",
  21.                 "service": "backend"
  22.               }
  23.             }
  24.           ],
  25.           "conf": {
  26.             "backend": "file"
  27.           }
  28.         },
  29.         {
  30.           "sources": [
  31.             {
  32.               "match": {
  33.                 "service": "backend"
  34.               }
  35.             }
  36.           ],
  37.           "destinations": [
  38.             {
  39.               "match": {
  40.                 "service": "redis"
  41.               }
  42.             }
  43.           ]
  44.         }
  45.       ]
  46.     }
  47.   ]
  48. }

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

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