Careful!

You are browsing documentation for a version of Kuma that is not the latest release.

HTTP API

Kuma ships with a RESTful HTTP interface that you can use to retrieve the state of your configuration and policies on every environment, and when running on Universal mode it will also allow to make changes to the state. On Kubernetes, you will use native CRDs to change the state in order to be consistent with Kubernetes best practices.

CI/CD: The HTTP API can be used for infrastructure automation to either retrieve data, or to make changes when running in Universal mode. The kumactl CLI is built on top of the HTTP API, which you can also access with any other HTTP client like curl.

By default the API Server is listening on port 5681 (HTTP) and on 5682 (HTTPS). The endpoints available are:

/config
/versions
/meshes
/mesh-insights
/mesh-insights/{name}
/dataplanes
/dataplanes+insights
/health-checks
/proxytemplates
/traffic-logs
/traffic-permissions
/traffic-routes
/fault-injections
/service-insights
/retries
/secrets
/global-secrets
/global-secrets/{name}
/meshes/{name}
/meshes/{mesh}/dataplanes
/meshes/{mesh}/dataplanes/{name}
/meshes/{mesh}/dataplanes/{name}/policies
/meshes/{mesh}/dataplanes/{name}/xds
/zoneingresses/{name}/xds
/zoneegresses/{name}/xds
/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}/{policy-type}/{policy-name}/dataplanes
/meshes/{mesh}/meshgateways/{gateway-name}/dataplanes
/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/dataplane
/tokens/zone-ingress
/zones
/zones/{name}
/zones+insights
/zones+insights/{name}
/zone-ingresses
/zone-ingresses/{name}
/zoneingresses+insights
/zoneingresses+insights/{name}
/zoneegresses
/zoneegresses/{name}
/zoneegressoverviews
/zoneegressoverviews/{name}
/global-insights

You can use GET requests to retrieve the state of Kuma on both Universal and Kubernetes, and PUT and DELETE requests on Universal to change the state.

Pagination

Every resource list in Kuma is paginated. To use pagination, you can use following query parameters:

size - size of the page (default - 100, maximum value - 1000).
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": 4,
  "offline": 2,
  "partiallyDegraded": 2
 },
 "dataplanesByType": {
  "standard": {
   "total": 2,
   "offline": 1,
   "partiallyDegraded": 1
  },
  "gateway": {
   "total": 2,
   "offline": 1,
   "partiallyDegraded": 1
  }
 },
 "policies": {
  "Secret": {
   "total": 1
  },
  "TrafficPermission": {
   "total": 1
  },
  "TrafficRoute": {
   "total": 1
  }
 },
 "dpVersions": {
  "kumaDp": {
   "1.0.0-rc2-119-g50e35395": {
    "total": 1,
    "online": 1,
    "partiallyDegraded": 1
   },
   "1.0.4": {
    "total": 1,
    "online": 1,
    "partiallyDegraded": 1
   },
   "unknown": {
    "total": 1,
    "online": 1,
    "partiallyDegraded": 1
   }
  },
  "envoy": {
   "1.15.0": {
    "total": 2,
    "online": 2,
    "partiallyDegraded": 1
   },
   "unknown": {
    "total": 1,
    "online": 1,
    "partiallyDegraded": 1
   }
  }
 },
 "mTLS": {
   "issuedBackends": {
     "ca-1": {
       "total": 1,
       "online": 1,
       "partiallyDegraded": 1
     }
   },
   "supportedBackends": {
     "ca-1": {
       "total": 1,
       "online": 1,
       "partiallyDegraded": 1
     }
   }
 },
 "services": {
  "total": 3,
  "internal": 2,
  "external": 1
 }
}

List Mesh Insights

Request: GET /mesh-insights

Response: 200 OK with body of Mesh Insight entities

Example:

curl http://localhost:5681/mesh-insights

{
 "total": 2,
 "items": [
  {
   "type": "MeshInsight",
   "name": "default",
   "creationTime": "0001-01-01T00:00:00Z",
   "modificationTime": "0001-01-01T00:00:00Z",
   "lastSync": "2020-11-17T12:24:11.905350Z",
   "dataplanes": {
    "total": 4,
    "offline": 2,
    "partiallyDegraded": 2
   },
   "dataplanesByType": {
    "standard": {
     "total": 2,
     "offline": 1,
     "partiallyDegraded": 1
    },
    "gateway": {
     "total": 2,
     "offline": 1,
     "partiallyDegraded": 1
    }
   },
   "policies": {
    "Secret": {
     "total": 1
    },
    "TrafficPermission": {
     "total": 1
    },
    "TrafficRoute": {
     "total": 1
    }
   },
   "dpVersions": {
    "kumaDp": {
     "1.0.0-rc2-119-g50e35395": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     },
     "1.0.4": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     },
     "unknown": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     }
    },
    "envoy": {
     "1.15.0": {
      "total": 2,
      "online": 2,
      "partiallyDegraded": 1
     },
     "unknown": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     }
    }
   },
   "mTLS": {
     "issuedBackends": {
       "ca-1": {
         "total": 1,
         "online": 1,
         "partiallyDegraded": 1
       }
     },
     "supportedBackends": {
       "ca-1": {
         "total": 1,
         "online": 1,
         "partiallyDegraded": 1
       }
     }
   }, 
   "services": {
    "total": 3,
    "internal": 2,
    "external": 1
   }
  },
  {
   "type": "MeshInsight",
   "name": "mymesh1",
   "creationTime": "0001-01-01T00:00:00Z",
   "modificationTime": "0001-01-01T00:00:00Z",
   "lastSync": "2020-11-17T12:24:11.941534Z",
   "dataplanes": {
    "total": 4,
    "offline": 2,
    "partiallyDegraded": 2
   },
   "dataplanesByType": {
    "standard": {
     "total": 2,
     "offline": 1,
     "partiallyDegraded": 1
    },
    "gateway": {
     "total": 2,
     "offline": 1,
     "partiallyDegraded": 1
    }
   },
   "policies": {
    "Secret": {
     "total": 1
    },
    "TrafficPermission": {
     "total": 1
    },
    "TrafficRoute": {
     "total": 1
    }
   },
   "dpVersions": {
    "kumaDp": {
     "1.0.0-rc2-119-g50e35395": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     },
     "1.0.4": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     },
     "unknown": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     }
    },
    "envoy": {
     "1.15.0": {
      "total": 2,
      "online": 2,
      "partiallyDegraded": 1
     },
     "unknown": {
      "total": 1,
      "online": 1,
      "partiallyDegraded": 1
     }
    }
   },
   "mTLS": {
     "issuedBackends": {
       "ca-1": {
         "total": 1,
         "online": 1,
         "partiallyDegraded": 1
       }
     },
     "supportedBackends": {
       "ca-1": {
         "total": 1,
         "online": 1,
         "partiallyDegraded": 1
       }
     }
   },
   "services": {
    "total": 3,
    "internal": 2,
    "external": 1
   }
  }
 ],
 "next": null
}

Dataplanes

Get Dataplane

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

Response: 200 OK with Mesh entity

Example:

curl http://localhost:5681/meshes/mesh-1/dataplanes/backend-1

{
  "type": "Dataplane",
  "name": "backend-1",
  "mesh": "mesh-1",
  "creationTime": "2020-05-12T12:31:45.606217+02:00",
  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
  "networking": {
    "address": "127.0.0.1",
    "inbound": [
      {
        "port": 11011,
        "servicePort": 11012,
        "tags": {
          "service": "backend",
          "version": "2.0",
          "env": "production"
        }
      }
    ],
    "outbound": [
      {
        "port": 33033,
        "service": "database"
      },
      {
        "port": 44044,
        "service": "user"
      }
    ]
  }
}

Create/Update Dataplane

Request: PUT /meshes/{mesh}/dataplanes/{name} with Dataplane entity in body

Response: 201 Created when the resource is created and 200 OK when it is updated

Example:

curl -XPUT http://localhost:5681/meshes/mesh-1/dataplanes/backend-1 --data @dataplane.json -H'content-type: application/json'

{
  "type": "Dataplane",
  "name": "backend-1",
  "mesh": "mesh-1",
  "networking": {
    "address": "127.0.0.1",
    "inbound": [
      {
        "port": 11011,
        "servicePort": 11012,
        "tags": {
          "kuma.io/service": "backend",
          "version": "2.0",
          "env": "production"
        }
      }
    ],
    "outbound": [
      {
        "port": 33033,
        "tags": {
          "kuma.io/service": "database"
        }
      },
      {
        "port": 44044,
        "tags": {
          "kuma.io/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": {
              "kuma.io/service": "backend",
              "version": "2.0",
              "env": "production"
            }
          }
        ],
        "outbound": [
          {
            "port": 33033,
            "tags": {
              "kuma.io/service": "database"
            }
          },
          {
            "port": 44044,
            "tags": {
              "kuma.io/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",
      "kuma.io/service": "backend",
      "version": "2.0"
     }
    }
   ],
   "outbound": [
    {
     "port": 33033,
     "tags": {
      "kuma.io/service": "database"
     }
    }
   ]
  }
 },
 "dataplaneInsight": {
  "mTLS": {
    "certificateExpirationTime": "2019-10-24T14:04:57.832482Z", 
    "lastCertificateRegeneration": "2019-10-24T12:04:57.832482Z",
    "certificateRegenerations": 3,
    "issuedBackend": "ca-1",
    "supportedBackends": ["ca-1"]
  },
  "subscriptions": [
   {
    "id": "426fe0d8-f667-11e9-b081-acde48001122",
    "controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
    "connectTime": "2019-10-24T14:04:56.820350Z",
    "status": {
     "lastUpdateTime": "2019-10-24T14:04:57.832482Z",
     "total": {
      "responsesSent": "3",
      "responsesAcknowledged": "3"
     },
     "cds": {
      "responsesSent": "1",
      "responsesAcknowledged": "1"
     },
     "eds": {
      "responsesSent": "1",
      "responsesAcknowledged": "1"
     },
     "lds": {
      "responsesSent": "1",
      "responsesAcknowledged": "1"
     },
     "rds": {}
    }
   }
  ]
 }
}

List Dataplane Overviews

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

Response: 200 OK with Dataplane entities including insight

Example:

curl http://localhost:5681/meshes/default/dataplanes+insights

{
  "items": [
    {
     "type": "DataplaneOverview",
     "mesh": "default",
     "name": "example",
     "creationTime": "2020-05-12T12:31:45.606217+02:00",
     "modificationTime": "2020-05-12T12:31:45.606217+02:00",
     "dataplane": {
      "networking": {
       "address": "127.0.0.1",
       "inbound": [
        {
         "port": 11011,
         "servicePort": 11012,
         "tags": {
          "env": "production",
          "kuma.io/service": "backend",
          "version": "2.0"
         }
        }
       ],
       "outbound": [
        {
         "port": 33033,
         "tags": {
          "kuma.io/service": "database"
         }
        }
       ]
      }
     },
     "dataplaneInsight": {
      "mTLS": {
        "certificateExpirationTime": "2019-10-24T14:04:57.832482Z",
        "lastCertificateRegeneration": "2019-10-24T12:04:57.832482Z",
        "certificateRegenerations": 3,
        "issuedBackend": "ca-1",
        "supportedBackends": ["ca-1"]
      },
      "subscriptions": [
       {
        "id": "426fe0d8-f667-11e9-b081-acde48001122",
        "controlPlaneInstanceId": "06070748-f667-11e9-b081-acde48001122",
        "connectTime": "2019-10-24T14:04:56.820350Z",
        "status": {
         "lastUpdateTime": "2019-10-24T14:04:57.832482Z",
         "total": {
          "responsesSent": "3",
          "responsesAcknowledged": "3"
         },
         "cds": {
          "responsesSent": "1",
          "responsesAcknowledged": "1"
         },
         "eds": {
          "responsesSent": "1",
          "responsesAcknowledged": "1"
         },
         "lds": {
          "responsesSent": "1",
          "responsesAcknowledged": "1"
         },
         "rds": {}
        }
       }
      ]
     }
    }
  ],
  "total": 2,
  "next": "http://localhost:5681/meshes/default/dataplanes+insights?offset=1"
}

Health Check

Get Health Check

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

Response: 200 OK with Health Check entity

Example:

curl http://localhost:5681/meshes/mesh-1/health-checks/web-to-backend

{
 "type": "HealthCheck",
 "mesh": "mesh-1",
 "name": "web-to-backend",
 "creationTime": "2020-05-12T12:31:45.606217+02:00",
 "modificationTime": "2020-05-12T12:31:45.606217+02:00",
 "sources": [
  {
   "match": {
    "kuma.io/service": "web"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "kuma.io/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": {
    "kuma.io/service": "web"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "kuma.io/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": {
      "kuma.io/service": "web"
     }
    }
   ],
   "destinations": [
    {
     "match": {
      "kuma.io/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": {
    "kuma.io/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": {
          "kuma.io/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": {
      "kuma.io/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": {
    "kuma.io/service": "backend"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "kuma.io/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": {
        "kuma.io/service": "backend"
      }
    }
  ],
  "destinations": [
    {
      "match": {
        "kuma.io/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": {
      "kuma.io/service": "backend"
     }
    }
   ],
   "destinations": [
    {
     "match": {
      "kuma.io/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": {
    "kuma.io/service": "web",
    "version": "1.0"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "kuma.io/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": {
        "kuma.io/service": "web",
        "version": "1.0"
      }
    }
  ],
  "destinations": [
    {
      "match": {
        "kuma.io/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": {
      "kuma.io/service": "web",
      "version": "1.0"
     }
    }
   ],
   "destinations": [
    {
     "match": {
      "kuma.io/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",
    "kuma.io/service": "web",
    "version": "v10"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "kuma.io/service": "backend"
   }
  }
 ],
 "conf": {
  "split": [
    {
     "weight": 90,
     "destination": {
      "region": "us-east-1",
      "kuma.io/service": "backend",
      "version": "v2"
     }
    },
    {
     "weight": 10,
     "destination": {
      "kuma.io/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",
    "kuma.io/service": "web",
    "version": "v10"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "kuma.io/service": "backend"
   }
  }
 ],
 "conf": {
    "split": [
    {
     "weight": 90,
     "destination": {
      "region": "us-east-1",
      "kuma.io/service": "backend",
      "version": "v2"
     }
    },
    {
     "weight": 10,
     "destination": {
      "kuma.io/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",
      "kuma.io/service": "web",
      "version": "v10"
     }
    }
   ],
   "destinations": [
    {
     "match": {
      "kuma.io/service": "backend"
     }
    }
   ],
   "conf": {
    "split": [
       {
        "weight": 90,
        "destination": {
         "region": "us-east-1",
         "kuma.io/service": "backend",
         "version": "v2"
        }
       },
       {
        "weight": 10,
        "destination": {
         "kuma.io/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": {
    "kuma.io/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": {
    "kuma.io/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": {
      "kuma.io/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",
    "kuma.io/service": "frontend",
    "version": "0.1"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "protocol": "http",
    "kuma.io/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": {
        "kuma.io/service": "frontend",
        "version": "0.1",
        "protocol": "http"
      }
    }
  ],
  "destinations": [
    {
      "match": {
        "kuma.io/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",
      "kuma.io/service": "frontend",
      "version": "0.1"
     }
    }
   ],
   "destinations": [
    {
     "match": {
      "protocol": "http",
      "kuma.io/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",
    "kuma.io/service": "frontend",
    "version": "0.1"
   }
  }
 ],
 "destinations": [
  {
   "match": {
    "protocol": "http",
    "kuma.io/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": {
        "kuma.io/service": "frontend",
        "version": "0.1",
        "protocol": "http"
      }
    }
  ],
  "destinations": [
    {
      "match": {
        "kuma.io/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",
      "kuma.io/service": "frontend",
      "version": "0.1"
     }
    }
   ],
   "destinations": [
    {
     "match": {
      "protocol": "http",
      "kuma.io/service": "backend"
     }
    }
   ],
   "conf": {
    "http": {
     "numRetries": 5,
     "perTryTimeout": "0.2s",
     "backOff": {
      "baseInterval": "0.02s",
      "maxInterval": "1s"
     },
     "retriableStatusCodes": [500, 504]
    },
    "grpc": {
     "numRetries": 5,
     "perTryTimeout": "0.3s",
     "backOff": {
      "baseInterval": "0.03s",
      "maxInterval": "1.2s"
     },
     "retryOn": [
      "cancelled",
      "deadline_exceeded",
      "internal",
      "resource_exhausted",
      "unavailable"
     ]
    },
    "tcp": {
     "maxConnectAttempts": 4
    }
   }
  }
 ],
 "next": "http://localhost:5681/meshes/default/retries?offset=1"
}

Delete Retry

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

Response: 200 OK

Example:

curl -XDELETE http://localhost:5681/meshes/default/retries/r1

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

Timeout

Get Timeout

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

Response: 200 OK with Timeout entity

Example:

curl http://localhost:5681/meshes/default/timeouts/default-timeouts-web

{
  "type": "Timeout",
  "mesh": "default",
  "name": "default-timeouts-web",
  "creationTime": "2021-02-16T18:41:26.016089+07:00",
  "modificationTime": "2021-02-16T18:41:26.016089+07:00",
  "sources": [
    {
      "match": {
        "kuma.io/service": "*"
      }
    }
  ],
  "destinations": [
    {
      "match": {
        "kuma.io/service": "web"
      }
    }
  ],
  "conf": {
    "connectTimeout": "10s",
    "grpc": {
      "streamIdleTimeout": "4s",
      "maxStreamDuration": "15s"
    }
  }
}

Create/Update Timeout

Request: PUT /meshes/{mesh}/timeouts/{name} with Timeout entity in body

Response: 201 Created when the resource is created and 200 OK when it is updated

Example:

curl -XPUT http://localhost:5681/meshes/default/timeouts/fi1 --data @timeout.json -H'content-type: application/json'

{
  "type": "Timeout",
  "mesh": "default",
  "name": "default-timeouts-web",
  "sources": [
    {
      "match": {
        "kuma.io/service": "*"
      }
    }
  ],
  "destinations": [
    {
      "match": {
        "kuma.io/service": "web"
      }
    }
  ],
  "conf": {
    "connectTimeout": "10s",
    "grpc": {
      "streamIdleTimeout": "4s",
      "maxStreamDuration": "15s"
    }
  }
}

List Timeouts

Request: GET /meshes/{mesh}/retries

Response: 200 OK with body of Timeout entities

Example:

curl http://localhost:5681/meshes/default/timeouts

{
  "total": 2,
  "items": [
    {
      "type": "Timeout",
      "mesh": "default",
      "name": "default-timeouts-web",
      "creationTime": "2021-02-16T18:41:26.016089+07:00",
      "modificationTime": "2021-02-16T18:41:26.016089+07:00",
      "sources": [
        {
          "match": {
            "kuma.io/service": "*"
          }
        }
      ],
      "destinations": [
        {
          "match": {
            "kuma.io/service": "web"
          }
        }
      ],
      "conf": {
        "connectTimeout": "10s",
        "grpc": {
          "streamIdleTimeout": "4s",
          "maxStreamDuration": "15s"
        }
      }
    },
    {
      "type": "Timeout",
      "mesh": "default",
      "name": "timeout-all-default",
      "creationTime": "2021-02-16T14:01:53.532599+07:00",
      "modificationTime": "2021-02-16T14:01:53.532599+07:00",
      "sources": [
        {
          "match": {
            "kuma.io/service": "*"
          }
        }
      ],
      "destinations": [
        {
          "match": {
            "kuma.io/service": "*"
          }
        }
      ],
      "conf": {
        "connectTimeout": "5s",
        "tcp": {
          "idleTimeout": "3600s"
        },
        "http": {
          "requestTimeout": "15s",
          "idleTimeout": "3600s"
        },
        "grpc": {
          "streamIdleTimeout": "300s"
        }
      }
    }
  ],
  "next": null
}

Delete Timeout

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

Response: 200 OK

Example:

curl -XDELETE http://localhost:5681/meshes/default/timeouts/t1

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

Zones

Get Zone

Request: GET /zones/{name}

Response: 200 OK with Zone entity

Example:

curl http://localhost:5681/zones/cluster-1

{
 "type": "Zone",
 "name": "cluster-1",
 "creationTime": "2020-07-28T13:14:48Z",
 "modificationTime": "2020-07-28T13:14:48Z",
 "enabled": true
}

Create/Update Zone

Request: PUT /zones/{name} with Zone entity in body

Response: 201 Created when the resource is created and 200 OK when it is updated

Example:

curl -XPUT http://localhost:5681/zones/cluster-1 --data @zone.json -H'content-type: application/json'

{
 "type": "Zone",
 "name": "cluster-1",
 "enabled": true
}

List Zones

Request: GET /zones

Response: 200 OK with body of Zone entities

Example:

curl http://localhost:5681/zones

{
 "total": 2,
 "items": [
  {
   "type": "Zone",
   "name": "cluster-1",
   "creationTime": "2020-07-28T13:14:48Z",
   "modificationTime": "2020-07-28T13:14:48Z",
   "enabled": true
  },
  {
   "type": "Zone",
   "name": "cluster-2",
   "creationTime": "2020-07-28T13:14:50Z",
   "modificationTime": "2020-07-28T13:14:50Z",
   "enabled": false
  }
 ],
 "next": null
}

Delete Zone

Request: DELETE /zones/{name}

Response: 200 OK

Example:

curl -XDELETE http://localhost:5681/zones/cluster-1

Zone Overview

Get Zone Overview

Request: GET /zones+insights/{name}

Response: 200 OK with Zone entity including insight

Example:

curl http://localhost:5681/zones+insights/cluster-1

{
 "type": "ZoneOverview",
 "mesh": "default",
 "name": "cluster-1",
 "creationTime": "2020-07-28T23:08:22.317322+07:00",
 "modificationTime": "2020-07-28T23:08:22.317322+07:00",
 "zone": {
   "enabled": true
 },
 "zoneInsight": {
  "subscriptions": [
   {
    "config": "\"whole /config from zone\"",
    "id": "466aa63b-70e8-4435-8bee-a7146e2cdf11",
    "globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
    "connectTime": "2020-07-28T16:08:09.743141Z",
    "disconnectTime": "2020-07-28T16:08:09.743194Z",
    "status": {
     "total": {}
    },
    "version": {
      "kumaCp": {
       "version": "1.2.0-rc2-211-g823fe8ce",
       "gitTag": "1.0.0-rc2-211-g823fe8ce",
       "gitCommit": "823fe8cef6430a8f75e72a7224eb5a8ab571ec42",
       "buildDate": "2021-02-18T13:22:30Z"
     }
    }
   },
   {
    "config": "\"whole /config from zone\"",
    "id": "f586f89c-2c4e-4f93-9a56-f0ea2ff010b7",
    "globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
    "connectTime": "2020-07-28T16:08:24.760801Z",
    "status": {
     "lastUpdateTime": "2020-07-28T16:08:25.770774Z",
     "total": {
      "responsesSent": "11",
      "responsesAcknowledged": "11"
     },
     "stat": {
      "CircuitBreaker": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "Dataplane": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "FaultInjection": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "HealthCheck": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "Mesh": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "ProxyTemplate": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "Secret": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "TrafficLog": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "TrafficPermission": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "TrafficRoute": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      },
      "TrafficTrace": {
       "responsesSent": "1",
       "responsesAcknowledged": "1"
      }
     }
    }
   }
  ]
 }
}

List Zone Overview

Request: GET /zones+insights

Response: 200 OK with Zone entities including insight

Example:

curl http://localhost:5681/zones+insights

{
  "total": 1,
  "items": [
  {
   "type": "ZoneOverview",
   "mesh": "default",
   "name": "cluster-1",
   "creationTime": "2020-07-28T23:08:22.317322+07:00",
   "modificationTime": "2020-07-28T23:08:22.317322+07:00",
   "zone": {
     "enabled": true
   },
   "zoneInsight": {
    "subscriptions": [
     {
      "config": "\"whole /config from zone\"",
      "id": "466aa63b-70e8-4435-8bee-a7146e2cdf11",
      "globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
      "connectTime": "2020-07-28T16:08:09.743141Z",
      "disconnectTime": "2020-07-28T16:08:09.743194Z",
      "status": {
       "total": {}
      },
      "version": {
       "kumaCp": {
         "version": "1.2.0-rc2-211-g823fe8ce",
         "gitTag": "1.0.0-rc2-211-g823fe8ce",
         "gitCommit": "823fe8cef6430a8f75e72a7224eb5a8ab571ec42",
         "buildDate": "2021-02-18T13:22:30Z"
        }
      }
     },
     {
      "config": "\"whole /config from zone\"",
      "id": "f586f89c-2c4e-4f93-9a56-f0ea2ff010b7",
      "globalInstanceId": "66309679-ee95-4ea8-b17f-c715ca03bb38",
      "connectTime": "2020-07-28T16:08:24.760801Z",
      "status": {
       "lastUpdateTime": "2020-07-28T16:08:25.770774Z",
       "total": {
        "responsesSent": "11",
        "responsesAcknowledged": "11"
       },
       "stat": {
        "CircuitBreaker": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "Dataplane": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "FaultInjection": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "HealthCheck": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "Mesh": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "ProxyTemplate": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "Secret": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "TrafficLog": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "TrafficPermission": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "TrafficRoute": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        },
        "TrafficTrace": {
         "responsesSent": "1",
         "responsesAcknowledged": "1"
        }
       }
      },
      "version": {
       "kumaCp": {
         "version": "1.2.0-rc2-211-g823fe8ce",
         "gitTag": "1.0.0-rc2-211-g823fe8ce",
         "gitCommit": "823fe8cef6430a8f75e72a7224eb5a8ab571ec42",
         "buildDate": "2021-02-18T13:22:30Z"
        }
      }
     }
    ]
   }
  }
  ],
 "next": null
}

Zone Ingresses

List Zone Ingresses

Request: GET /zone-ingresses

Response: 200 OK with ZoneIngresses entities

Example:

curl http://localhost:5681/zone-ingresses

{
 "total": 2,
 "items": [
  {
   "type": "ZoneIngress",
   "name": "zi-1",
   "creationTime": "2022-04-01T18:33:41Z",
   "modificationTime": "2022-04-01T18:33:41Z",
   "zone": "kuma-4",
   "networking": {
    "address": "192.168.64.9",
    "advertisedAddress": "192.168.64.9",
    "port": 30685,
    "advertisedPort": 30685
   },
   "availableServices": [
    {
     "tags": {
      "kuma.io/service": "zone4-demo-client",
      "kuma.io/zone": "kuma-4",
      "team": "client-owners"
     },
     "instances": 1,
     "mesh": "default"
    },
    {
     "tags": {
      "kuma.io/protocol": "http",
      "kuma.io/service": "external-service-in-zone4",
      "kuma.io/zone": "kuma-4",
      "mesh": "default"
     },
     "instances": 1,
     "mesh": "default",
     "externalService": true
    }
   ]
  },
  {
   "type": "ZoneIngress",
   "name": "zi-2",
   "creationTime": "2022-04-01T18:33:15Z",
   "modificationTime": "2022-04-01T18:33:15Z",
   "networking": {
    "address": "10.42.0.6",
    "advertisedAddress": "192.168.64.4",
    "port": 10001,
    "advertisedPort": 31882
   },
   "availableServices": [
    {
     "tags": {
      "app": "demo-client",
      "k8s.kuma.io/namespace": "kuma-test",
      "kuma.io/instance": "demo-client-6794456845-fr4gf",
      "kuma.io/protocol": "tcp",
      "kuma.io/service": "demo-client_kuma-test_svc",
      "kuma.io/zone": "kuma-1-zone",
      "pod-template-hash": "6794456845"
     },
     "instances": 1,
     "mesh": "default"
    },
    {
     "tags": {
      "kuma.io/protocol": "http",
      "kuma.io/service": "external-service-in-zone1",
      "kuma.io/zone": "kuma-1-zone",
      "mesh": "default"
     },
     "instances": 1,
     "mesh": "default",
     "externalService": true
    }
   ]
  }
 ],
 "next": null
}

Get Zone Ingress

Request: GET /zone-ingress/{name}

Response: 200 OK with ZoneIngress entity

Example:

curl http://localhost:5681/zone-ingresses/ze-1

{
 "type": "ZoneIngress",
 "name": "zi-1",
 "creationTime": "2022-04-01T18:33:41Z",
 "modificationTime": "2022-04-01T18:33:41Z",
 "zone": "kuma-4",
 "networking": {
  "address": "192.168.64.9",
  "advertisedAddress": "192.168.64.9",
  "port": 30685,
  "advertisedPort": 30685
 },
 "availableServices": [
  {
   "tags": {
    "kuma.io/service": "zone4-demo-client",
    "kuma.io/zone": "kuma-4",
    "team": "client-owners"
   },
   "instances": 1,
   "mesh": "default"
  },
  {
   "tags": {
    "kuma.io/protocol": "http",
    "kuma.io/service": "external-service-in-zone4",
    "kuma.io/zone": "kuma-4",
    "mesh": "default"
   },
   "instances": 1,
   "mesh": "default",
   "externalService": true
  }
 ]
}

Zone Ingress Overviews

List Zone Ingress Overviews

Request: GET /zoneingresses+insights

Response: 200 OK with ZoneIngressOverview entities (which are combination of ZoneIngress and ZoneIngressInsight entities)

Example:

curl http://localhost:5681/zoneingresses+insights

{
 "total": 2,
 "items": [
  {
   "type": "ZoneIngressOverview",
   "name": "zi-1",
   "creationTime": "2022-04-01T19:45:11Z",
   "modificationTime": "2022-04-01T19:45:11Z",
   "zoneIngress": {
    "zone": "kuma-4",
    "networking": {
     "address": "192.168.64.9",
     "advertisedAddress": "192.168.64.9",
     "port": 30685,
     "advertisedPort": 30685
    },
    "availableServices": [
     {
      "tags": {
       "kuma.io/service": "zone4-demo-client",
       "kuma.io/zone": "kuma-4",
       "team": "client-owners"
      },
      "instances": 1,
      "mesh": "default"
     },
     {
      "tags": {
       "kuma.io/protocol": "http",
       "kuma.io/service": "external-service-in-zone4",
       "kuma.io/zone": "kuma-4",
       "mesh": "default"
      },
      "instances": 1,
      "mesh": "default",
      "externalService": true
     }
    ]
   }
  },
  {
   "type": "ZoneIngressOverview",
   "name": "zi-2",
   "creationTime": "2022-04-01T19:44:46Z",
   "modificationTime": "2022-04-01T19:44:46Z",
   "zoneIngress": {
    "networking": {
     "address": "10.42.0.6",
     "advertisedAddress": "192.168.64.2",
     "port": 10001,
     "advertisedPort": 30103
    },
    "availableServices": [
     {
      "tags": {
       "app": "demo-client",
       "k8s.kuma.io/namespace": "kuma-test",
       "kuma.io/instance": "demo-client-59ff94f647-8wqw7",
       "kuma.io/protocol": "tcp",
       "kuma.io/service": "demo-client_kuma-test_svc",
       "kuma.io/zone": "kuma-1-zone",
       "pod-template-hash": "59ff94f647"
      },
      "instances": 1,
      "mesh": "default"
     },
     {
      "tags": {
       "kuma.io/protocol": "http",
       "kuma.io/service": "external-service-in-zone1",
       "kuma.io/zone": "kuma-1-zone",
       "mesh": "default"
      },
      "instances": 1,
      "mesh": "default",
      "externalService": true
     }
    ]
   },
   "zoneIngressInsight": {
    "subscriptions": [
     {
      "id": "e92113b3-f01c-43cf-a21e-2b7064eb5bf8",
      "controlPlaneInstanceId": "kuma-control-plane-7cc9ffd8f9-s79r8-5b83",
      "connectTime": "2022-04-01T19:44:52.306011636Z",
      "status": {
       "lastUpdateTime": "2022-04-01T19:45:14.389007660Z",
       "total": {
        "responsesSent": "8",
        "responsesAcknowledged": "9"
       },
       "cds": {
        "responsesSent": "3",
        "responsesAcknowledged": "3"
       },
       "eds": {
        "responsesSent": "2",
        "responsesAcknowledged": "3"
       },
       "lds": {
        "responsesSent": "3",
        "responsesAcknowledged": "3"
       },
       "rds": {}
      },
      "version": {
       "kumaDp": {
        "version": "dev-d66126389",
        "gitTag": "1.5.0-rc1-156-gd66126389",
        "gitCommit": "d66126389d1842fb459b4db399e2db82781527bf",
        "buildDate": "2022-04-01T19:43:19Z"
       },
       "envoy": {
        "version": "1.21.1",
        "build": "af50070ee60866874b0a9383daf9364e884ded22/1.21.1/Clean/RELEASE/BoringSSL",
        "kumaDpCompatible": true
       }
      },
      "generation": 18
     }
    ]
   }
  }
 ],
 "next": null
}

Get Zone Ingress Overview

Request: GET /zoneingresses+insights/{name}

Response: 200 OK with ZoneIngressOverview entity (which is a combination of ZoneIngress and ZoneIngressInsight entities)

Example:

curl http://localhost:5681/zoneingresses+insights/zi-1

{
 "type": "ZoneIngressOverview",
 "name": "zi-1",
 "creationTime": "2022-04-01T19:45:11Z",
 "modificationTime": "2022-04-01T19:45:11Z",
 "zoneIngress": {
  "zone": "kuma-4",
  "networking": {
   "address": "192.168.64.9",
   "advertisedAddress": "192.168.64.9",
   "port": 30685,
   "advertisedPort": 30685
  },
  "availableServices": [
   {
    "tags": {
     "kuma.io/service": "zone4-demo-client",
     "kuma.io/zone": "kuma-4",
     "team": "client-owners"
    },
    "instances": 1,
    "mesh": "default"
   },
   {
    "tags": {
     "kuma.io/protocol": "http",
     "kuma.io/service": "external-service-in-zone4",
     "kuma.io/zone": "kuma-4",
     "mesh": "default"
    },
    "instances": 1,
    "mesh": "default",
    "externalService": true
   }
  ]
 },
 "zoneIngressInsight": {}
}

Zone Egresses

List Zone Egresses

Request: GET /zoneegresses

Response: 200 OK with ZoneEgress entities

Example:

curl http://localhost:5681/zoneegresses

{
 "total": 2,
 "items": [
  {
   "type": "ZoneEgress",
   "name": "kuma-1-zone.kuma-egress-6f7c8bbcc9-rzxnw.kuma-system",
   "creationTime": "2022-02-18T13:39:39Z",
   "modificationTime": "2022-02-18T13:39:39Z",
   "zone": "kuma-1-zone",
   "networking": {
    "address": "10.42.0.6",
    "port": 10002
   }
  },
  {
   "type": "ZoneEgress",
   "name": "kuma-3.egress",
   "creationTime": "2022-02-18T13:40:30.086380212Z",
   "modificationTime": "2022-02-18T13:40:30.086380212Z",
   "zone": "kuma-3",
   "networking": {
    "address": "172.21.0.11",
    "port": 30685
   }
  }
 ],
 "next": null
}

Get Zone Egress

Request: GET /zoneegresses/{name}

Response: 200 OK with ZoneEgress entity

Example:

curl http://localhost:5681/zoneegresses/ze-1

{
 "type": "ZoneEgress",
 "name": "ze-1",
 "creationTime": "2022-02-18T13:40:30.086380212Z",
 "modificationTime": "2022-02-18T13:40:30.086380212Z",
 "zone": "zone-1",
 "networking": {
  "address": "172.21.0.11",
  "port": 30685
 }
}

Zone Egress Overviews

List Zone Egress Overviews

Request: GET /zoneegressoverviews

Response: 200 OK with ZoneEgressOverview entities (which are combination of ZoneEgress and ZoneEgressInsight entities)

Example:

curl http://localhost:5681/zoneegressoverviews

{
 "total": 2,
 "items": [
  {
   "type": "ZoneEgressOverview",
   "name": "kuma-1-zone.kuma-egress-6f7c8bbcc9-rzxnw.kuma-system",
   "creationTime": "2022-02-18T13:39:39Z",
   "modificationTime": "2022-02-18T13:39:39Z",
   "zoneEgress": {
    "zone": "kuma-1-zone",
    "networking": {
     "address": "10.42.0.6",
     "port": 10002
    }
   },
   "zoneEgressInsight": {
    "subscriptions": [
     {
      "id": "bb56359c-5b1c-4a9e-af3f-0982e1f37b74",
      "controlPlaneInstanceId": "kuma-control-plane-b799fb878-w2d9l-97fb",
      "connectTime": "2022-02-18T13:39:48.312313103Z",
      "status": {
       "lastUpdateTime": "2022-02-18T13:40:41.338203595Z",
       "total": {
        "responsesSent": "11",
        "responsesAcknowledged": "13"
       },
       "cds": {
        "responsesSent": "4",
        "responsesAcknowledged": "4"
       },
       "eds": {
        "responsesSent": "3",
        "responsesAcknowledged": "5"
       },
       "lds": {
        "responsesSent": "4",
        "responsesAcknowledged": "4"
       },
       "rds": {}
      },
      "version": {
       "kumaDp": {
        "version": "dev-60984ad8d",
        "gitTag": "1.5.0-rc1-18-g60984ad8d",
        "gitCommit": "60984ad8d66a59b269b3493172a6a22edc310515",
        "buildDate": "2022-02-18T13:38:45Z"
       },
       "envoy": {
        "version": "1.21.0",
        "build": "a9d72603c68da3a10a1c0d021d01c7877e6f2a30/1.21.0/Clean/RELEASE/BoringSSL"
       }
      }
     }
    ]
   }
  },
  {
   "type": "ZoneEgressOverview",
   "name": "kuma-3.egress",
   "creationTime": "2022-02-18T13:40:30.086380212Z",
   "modificationTime": "2022-02-18T13:40:30.086380212Z",
   "zoneEgress": {
    "zone": "kuma-3",
    "networking": {
     "address": "172.21.0.11",
     "port": 30685
    }
   },
   "zoneEgressInsight": {
    "subscriptions": [
     {
      "id": "9f3766b3-f560-422f-b2ab-d8276f67d6d0",
      "controlPlaneInstanceId": "69150c6bc245-f8ba",
      "connectTime": "2022-02-18T13:40:30.084188804Z",
      "status": {
       "lastUpdateTime": "2022-02-18T13:40:39.129293439Z",
       "total": {
        "responsesSent": "6",
        "responsesAcknowledged": "7"
       },
       "cds": {
        "responsesSent": "2",
        "responsesAcknowledged": "2"
       },
       "eds": {
        "responsesSent": "2",
        "responsesAcknowledged": "3"
       },
       "lds": {
        "responsesSent": "2",
        "responsesAcknowledged": "2"
       },
       "rds": {}
      },
      "version": {
       "kumaDp": {
        "version": "dev-60984ad8d",
        "gitTag": "1.5.0-rc1-18-g60984ad8d",
        "gitCommit": "60984ad8d66a59b269b3493172a6a22edc310515",
        "buildDate": "2022-02-18T13:38:45Z"
       },
       "envoy": {
        "version": "1.21.0",
        "build": "a9d72603c68da3a10a1c0d021d01c7877e6f2a30/1.21.0/Clean/RELEASE/BoringSSL"
       }
      }
     }
    ]
   }
  }
 ],
 "next": null
}

Get Zone Egress Overview

Request: GET /zoneegressoverviews/{name}

Response: 200 OK with ZoneEgressOverview entity (which is a combination of ZoneEgress and ZoneEgressInsight entities)

Example:

curl http://localhost:5681/zonesegressoverviews/ze-1

{
 "type": "ZoneEgressOverview",
 "name": "ze-1",
 "creationTime": "2022-02-18T13:40:30.086380212Z",
 "modificationTime": "2022-02-18T13:40:30.086380212Z",
 "zoneEgress": {
  "zone": "zone-1",
  "networking": {
   "address": "172.21.0.11",
   "port": 30685
  }
 },
 "zoneEgressInsight": {
  "subscriptions": [
   {
    "id": "9f3766b3-f560-422f-b2ab-d8276f67d6d0",
    "controlPlaneInstanceId": "69150c6bc245-f8ba",
    "connectTime": "2022-02-18T13:40:30.084188804Z",
    "status": {
     "lastUpdateTime": "2022-02-18T13:40:39.129293439Z",
     "total": {
      "responsesSent": "6",
      "responsesAcknowledged": "7"
     },
     "cds": {
      "responsesSent": "2",
      "responsesAcknowledged": "2"
     },
     "eds": {
      "responsesSent": "2",
      "responsesAcknowledged": "3"
     },
     "lds": {
      "responsesSent": "2",
      "responsesAcknowledged": "2"
     },
     "rds": {}
    },
    "version": {
     "kumaDp": {
      "version": "dev-60984ad8d",
      "gitTag": "1.5.0-rc1-18-g60984ad8d",
      "gitCommit": "60984ad8d66a59b269b3493172a6a22edc310515",
      "buildDate": "2022-02-18T13:38:45Z"
     },
     "envoy": {
      "version": "1.21.0",
      "build": "a9d72603c68da3a10a1c0d021d01c7877e6f2a30/1.21.0/Clean/RELEASE/BoringSSL"
     }
    }
   }
  ]
 }
}

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/dataplane 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/dataplane

Zone Ingress Tokens

Generate token which zone ingress can use to authenticate itself.

Requires authentication to the control plane by the user.

For details, see zone ingress authentication.

Generate Zone Ingress Token

Example:

curl -XPOST \
  -H "Content-Type: application/json" \
  --data '{"zone": "us-east", "validFor": "720h"}' \
  http://localhost:5681/tokens/zone-ingress

Global Insights

Get Global Insights

Request: GET /global-insights

Response: 200 OK with Global Insights entity

Example:

curl localhost:5681/global-insights

{
 "type": "GlobalInsights",
 "creationTime": "2021-11-05T08:11:37.880477+01:00",
 "resources": {
  "GlobalSecret": {
   "total": 3
  },
  "Mesh": {
   "total": 1
  },
  "Zone": {
   "total": 0
  },
  "ZoneIngress": {
   "total": 0
  }
 }
}

Inspect API

Get policies matched for the data plane proxy

Request: GET /meshes/{mesh}/dataplanes/{dataplane}/policies

Example:

curl localhost:5681/meshes/default/dataplanes/backend-1/policies

{
 "total": 3,
 "kind": "SidecarDataplane",
 "items": [
  {
   "type": "inbound",
   "name": "127.0.0.1:10010:10011",
   "matchedPolicies": {
    "TrafficPermission": [
     {
      "type": "TrafficPermission",
      "mesh": "default",
      "name": "allow-all-default",
      ...  
     }
    ]
   }
  },
  {
   "type": "outbound",
   "name": "127.0.0.1:10006",
   "matchedPolicies": {
    "Timeout": [
     {
      "type": "Timeout",
      "mesh": "default",
      "name": "timeout-all-default",
      ...
     }
    ]
   }
  },
  {
   "type": "service",
   "name": "gateway",
   "matchedPolicies": {
    "CircuitBreaker": [
     {
      "type": "CircuitBreaker",
      "mesh": "default",
      "name": "circuit-breaker-all-default",
      ...
     }
    ],
    "HealthCheck": [
     {
      "type": "HealthCheck",
      "mesh": "default",
      "name": "gateway-to-backend",
      ...
     }
    ],
    "Retry": [
     {
      "type": "Retry",
      "mesh": "default",
      "name": "retry-all-default",
      ...
     }
    ]
   }
  }
 ]
}

MeshGateway-configured Dataplane example:

curl localhost:5681/meshes/default/dataplanes/gateway-1/policies

{
 "gateway": {
  "mesh": "default",
  "name": "foo-gateway.default"
 },
 "kind": "MeshGatewayDataplane",
 "listeners": [
  {
   "hosts": [
    {
     "hostName": "go.com",
     "routes": [
      {
       "destinations": [
        {
         "policies": {
          "CircuitBreaker": {
           "type": "CircuitBreaker"
           "mesh": "default",
           "name": "circuit-breaker-all-default",
           ...
          },
          "Retry": {
           "type": "Retry"
           "mesh": "default",
           "name": "retry-all-default",
           ...
          },
          "Timeout": {
           "type": "Timeout"
           "mesh": "default",
           "name": "timeout-all-default",
           ...
          }
         },
         "tags": {
          "kuma.io/service": "demo-app_kuma-demo_svc_5000"
         }
        },
        {
         "policies": {
          "CircuitBreaker": {
           "type": "CircuitBreaker"
           "mesh": "default",
           "name": "circuit-breaker-all-default",
           ...
          },
          "Retry": {
           "type": "Retry"
           "mesh": "default",
           "name": "retry-all-default",
           ...
          },
          "Timeout": {
           "type": "Timeout"
           "mesh": "default",
           "name": "timeout-all-default",
           ...
          }
         },
         "tags": {
          "kuma.io/service": "httpbin"
         }
        }
       ],
       "route": "default-foo-gateway-hw6n5"
      }
     ]
    }
   ],
   "port": 80,
   "protocol": "HTTP"
  }
 ]
}

Get data plane proxies affected by policy

Request: GET /meshes/{mesh}/{policy-type}/{policy}/dataplanes

Example:

curl localhost:5681/meshes/default/circuit-breakers/circuit-breaker-all-default/dataplanes

{
 "total": 2,
 "items": [
  {
   "kind": "SidecarDataplane",
   "dataplane": {
    "mesh": "default",
    "name": "demo-app-1"
   },
   "attachments": [
    {
     "type": "service",
     "name": "demo-app_kuma-demo_svc_5000",
     "service": "demo-app_kuma-demo_svc_5000"
    }
   ]
  },
  {
   "kind": "MeshGatewayDataplane",
   "dataplane": {
    "mesh": "default",
    "name": "gateway-1"
   },
   "gateway": {
    "mesh": "default",
    "name": "edge-gateway"
   },
   "listeners": [
    {
     "port": 80,
     "protocol": "HTTP",
     "hosts": [
      {
       "hostName": "go.com",
       "routes": [
        {
         "route": "default-gateway",
         "destinations": [
          {
           "kuma.io/service": "demo-app_kuma-demo_svc_5000"
          }
         ]
        }
       ]
      }
     ]
    }
   ]
  }
 ]
}

Get data plane proxies configured by `MeshGateway`

Request: GET /meshes/{mesh}/meshgateways/{meshgateway}/dataplanes

Example:

curl localhost:5681/meshes/default/meshgateways/edge-gateway/policies

{
 "items": [
  {
   "dataplane": {
    "mesh": "default",
    "name": "gateway-1"
   }
  }
 ],
 "total": 1
}

Get envoy config dump for data plane proxy

Request: GET /meshes/{mesh}/dataplanes/{dataplane}/xds

Example:

curl localhost:5681/meshes/default/dataplane/backend-1/xds

{
 "configs": [
  {
   "@type": "type.googleapis.com/envoy.admin.v3.BootstrapConfigDump",
   "bootstrap": {
    "node": {
     "id": "default.backend-1",
     "cluster": "backend",
     "metadata": {
       "dataplane.admin.port": "6606"
     }
    }
   }
  }
 ]
}

Get envoy config dump for ZoneIngress

Request: GET /zoneingresses/{name}/xds

Example:

curl localhost:5681/zoneingresses/zi-1/xds

{
 "configs": [
  {
   "@type": "type.googleapis.com/envoy.admin.v3.BootstrapConfigDump",
   "bootstrap": {
    "node": {
     "id": "default.zi-1",
     "cluster": "zi",
     "metadata": {
       "dataplane.admin.port": "6606"
     }
    }
   }
  }
 ]
}

Get envoy config dump for ZoneEgress

Request: GET /zoneegresses/{name}/xds

Example:

curl localhost:5681/zoneegresses/ze-1/xds

{
 "configs": [
  {
   "@type": "type.googleapis.com/envoy.admin.v3.BootstrapConfigDump",
   "bootstrap": {
    "node": {
     "id": "default.ze-1",
     "cluster": "ze",
     "metadata": {
       "dataplane.admin.port": "6606"
     }
    }
   }
  }
 ]
}

← Service Health Probes Annotations and labels in Kubernetes mode →