HTTP API

    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 CLI is built on top of the HTTP API, which you can also access with any other HTTP client like curl.

    By default the HTTP API is listening on port 5681. The endpoints available are:

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

    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.

    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:

    If next field is null there is no more pages to fetch.

    Control Plane configuration

    Request: GET /config

    Response: 200 OK with the effective configuration of the Control Plane (notice that secrets, such as database passwords, will never appear in the response)

    Example:

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

    Meshes

    Get Mesh

    Request: GET /meshes/{name}

    Response: 200 OK with Mesh entity

    Example:

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

    Create/Update Mesh

    Request: PUT /meshes/{name} with Mesh entity in body

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

    Example:

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

    List Meshes

    Request: GET /meshes

    Response: 200 OK with body of Mesh entities

    Example:

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

    Delete Mesh

    Request: DELETE /meshes/{name}

    Response: 200 OK

    Example:

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

    Dataplanes

    Get Dataplane

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

    Response: 200 OK with Mesh entity

    Example:

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

    Create/Update Dataplane

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

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

    Example:

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

    List Dataplanes

    Request: GET /meshes/{mesh}/dataplanes

    Response: 200 OK with body of Dataplane entities

    Example:

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

    Delete Dataplane

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

    Response: 200 OK

    Example:

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

    Get Dataplane Overview

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

    Response: 200 OK with Dataplane entity including insight

    Example:

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

    List Dataplane Overviews

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

    Response: 200 OK with Dataplane entities including insight

    Example:

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

    Health Check

    Get Health Check

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

    Example:

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

    Create/Update Health Check

    Request: PUT /meshes/{mesh}/health-checks/{name} with Health Check entity in body

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

    Example:

    1. {
    2.  "type": "HealthCheck",
    3.  "mesh": "mesh-1",
    4.  "name": "web-to-backend",
    5.  "sources": [
    6.   {
    7.    "match": {
    8.     "service": "web"
    9.    }
    10.   }
    11.  ],
    12.  "destinations": [
    13.   {
    14.    "match": {
    15.     "service": "backend"
    16.    }
    17.   }
    18.  ],
    19.  "conf": {
    20.    "interval": "10s",
    21.    "timeout": "2s",
    22.    "unhealthyThreshold": 3,
    23.    "healthyThreshold": 1
    24.  }
    25. }

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

    Response: 200 OK with body of Health Check entities

    Example:

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

    Delete Health Check

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

    Response: 200 OK

    Example:

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

    Proxy Template

    Get Proxy Template

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

    Response: 200 OK with Proxy Template entity

    Example:

    1. curl http://localhost:5681/meshes/mesh-1/proxytemplates/pt-1
    1. {
    2.  "type": "ProxyTemplate",
    3.  "mesh": "mesh-1",
    4.  "name": "pt-1",
    5.  "creationTime": "2020-05-12T12:31:45.606217+02:00",
    6.  "modificationTime": "2020-05-12T12:31:45.606217+02:00",
    7.  "selectors": [
    8.   {
    9.    "match": {
    10.     "service": "backend"
    11.    }
    12.   }
    13.  ],
    14.  "conf": {
    15.   "imports": [
    16.    "default-proxy"
    17.   ],
    18.   "resources": [
    19.    {
    20.     "name": "raw-name",
    21.     "version": "raw-version",
    22.     "resource": "'@type': type.googleapis.com/envoy.api.v2.Cluster\nconnectTimeout: 5s\nloadAssignment:\n  clusterName: localhost:8443\n  endpoints:\n    - lbEndpoints:\n        - endpoint:\n            address:\n              socketAddress:\n                address: 127.0.0.1\n                portValue: 8443\nname: localhost:8443\ntype: STATIC\n"
    23.    }
    24.   ]
    25.  }
    26. }

    Create/Update Proxy Template

    Request: PUT /meshes/{mesh}/proxytemplates/{name} with Proxy Template entity in body

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

    Example:

    1. curl -XPUT http://localhost:5681/meshes/mesh-1/proxytemplates/pt-1 --data @proxytemplate.json -H'content-type: application/json'
    1. {
    2.   "type": "ProxyTemplate",
    3.   "name": "pt-1",
    4.   "mesh": "mesh-1",
    5.   "selectors": [
    6.     {
    7.       "match": {
    8.           "service": "backend"
    9.       }
    10.     }
    11.   ],
    12.   "conf": {
    13.     "imports": [
    14.       "default-proxy"
    15.     ],
    16.     "resources": [
    17.       {
    18.         "name": "raw-name",
    19.         "version": "raw-version",
    20.         "resource": "'@type': type.googleapis.com/envoy.api.v2.Cluster\nconnectTimeout: 5s\nloadAssignment:\n  clusterName: localhost:8443\n  endpoints:\n    - lbEndpoints:\n        - endpoint:\n            address:\n              socketAddress:\n                address: 127.0.0.1\n                portValue: 8443\nname: localhost:8443\ntype: STATIC\n"
    21.       }
    22.     ]
    23.   }
    24. }

    List Proxy Templates

    Request: GET /meshes/{mesh}/proxytemplates

    Response: 200 OK with body of Proxy Template entities

    Example:

    1. curl http://localhost:5681/meshes/mesh-1/proxytemplates
    1. {
    2.  "items": [
    3.   {
    4.    "type": "ProxyTemplate",
    5.    "mesh": "mesh-1",
    6.    "name": "pt-1",
    7.    "creationTime": "2020-05-12T12:31:45.606217+02:00",
    8.    "modificationTime": "2020-05-12T12:31:45.606217+02:00",
    9.    "selectors": [
    10.     {
    11.      "match": {
    12.       "service": "backend"
    13.      }
    14.     }
    15.    ],
    16.    "conf": {
    17.     "imports": [
    18.      "default-proxy"
    19.     ],
    20.     "resources": [
    21.      {
    22.       "name": "raw-name",
    23.       "version": "raw-version",
    24.       "resource": "'@type': type.googleapis.com/envoy.api.v2.Cluster\nconnectTimeout: 5s\nloadAssignment:\n  clusterName: localhost:8443\n  endpoints:\n    - lbEndpoints:\n        - endpoint:\n            address:\n              socketAddress:\n                address: 127.0.0.1\n                portValue: 8443\nname: localhost:8443\ntype: STATIC\n"
    25.      }
    26.     ]
    27.    }
    28.   }
    29.  ],
    30.  "next": "http://localhost:5681/meshes/mesh-1/proxytemplates?offset=1"
    31. }

    Delete Proxy Template

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

    Response: 200 OK

    Example:

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

    Traffic Permission

    Get Traffic Permission

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

    Response: 200 OK with Traffic Permission entity

    Example:

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

    Create/Update Traffic Permission

    Request: PUT /meshes/{mesh}/trafficpermissions/{name} with Traffic Permission entity in body

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

    Example:

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

    List Traffic Permissions

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

    Response: 200 OK with body of Traffic Permission entities

    Example:

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

    Delete Traffic Permission

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

    Response: 200 OK

    Example:

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

    Get Traffic Log

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

    Response: 200 OK with Traffic Log entity

    Example:

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

    Create/Update Traffic Log

    Request: PUT /meshes/{mesh}/traffic-logs/{name} with Traffic Log entity in body

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

    Example:

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

    List Traffic Logs

    Response: 200 OK with body of Traffic Log entities

    Example:

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

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

    Response: 200 OK

    Example:

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

    Traffic Route

    Get Traffic Route

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

    Response: 200 OK with Traffic Route entity

    Example:

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

    Create/Update Traffic Route

    Request: PUT /meshes/{mesh}/traffic-routes/{name} with Traffic Route entity in body

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

    Example:

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

    List Traffic Routes

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

    Response: 200 OK with body of Traffic Route entities

    Example:

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

    Delete Traffic Route

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

    Response: 200 OK

    Example:

    1. curl -XDELETE http://localhost:5681/meshes/mesh-1/traffic-routes/web-to-backend

    Traffic Trace

    Get Traffic Trace

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

    Response: 200 OK with Traffic Trace entity

    Example:

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

    Create/Update Traffic Trace

    Request: PUT /meshes/{mesh}/traffic-traces/{name} with Traffic Trace entity in body

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

    Example:

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

    List Traffic Traces

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

    Response: 200 OK with body of Traffic Trace entities

    Example:

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

    Delete Traffic Trace

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

    Response: 200 OK

    Example:

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

    Fault Injection

    Get Fault Injection

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

    Response: 200 OK with Fault Injection entity

    Example:

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

    Create/Update Fault Injection

    Request: PUT /meshes/{mesh}/fault-injections/{name} with Fault Injection entity in body

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

    Example:

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

    List Fault Injections

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

    Response: 200 OK with body of Fault Injection entities

    Example:

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

    Delete Fault Injection

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

    Response: 200 OK

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