HTTP API
External Services
Service Insights
- Get Service Insight
- List Service Insights
Secrets
Global Secrets
Multi-zone
- Zones status
Dataplane Proxy Tokens
- Generate dataplane proxy token

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}/zones
/meshes/{mesh}/zones/{name}
/meshes/{mesh}/zones+insights
/meshes/{mesh}/zones+insights/{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

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:

{
  "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": 1,
  "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
   }
  }
 }
}

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": 1,
    "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
     }
    }
   }
  },
  {
   "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": 1,
    "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
     }
    }
   }
  }
 ],
 "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": {
  "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": {
      "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": {}
        }
       }
      ]
     }
    }
  ],
  "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",
 "ingress": {
  "address": "192.168.64.17:31172"
 }
}

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",
 "ingress": {
  "address": "192.168.64.17:31172"
 }
}

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",
   "ingress": {
    "address": "192.168.64.17:31172"
   }
  },
  {
   "type": "Zone",
   "name": "cluster-2",
   "creationTime": "2020-07-28T13:14:50Z",
   "modificationTime": "2020-07-28T13:14:50Z",
   "ingress": {
    "address": "192.168.64.18:32089"
   }
  }
 ],
 "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": {
  "ingress": {
   "address": "127.0.0.1:10000"
  }
 },
 "zoneInsight": {
  "subscriptions": [
   {docs/docs/1.2.1/deployments/multi-zone.md
    "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": {}
    }
   },
   {
    "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

{
  "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": {
    "ingress": {
     "address": "127.0.0.1:10000"
    }
   },
   "zoneInsight": {
    "subscriptions": [
     {
      "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": {}
      }
     },
     {
      "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"
        }
       }
      }
     }
    ]
   }
  }
  ],
 "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.

Requires authentication to the control plane by the user.

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