无数据库模式 Admin API

无数据库模式 Admin API

本文原文链接：https://docs.konghq.com/1.1.x/db-less-admin-api/

此页面指的是用于运行Kong的Admin API，该API配置为无数据库，通过声明性配置管理内存中的实体。有关将Kong的Admin API与数据库一起使用的信息，请参阅数据库模式的Admin API页面。

支持的 Content Types
Routes 信息
- 检索节点信息
- 检索节点状态
声明式配置
- 重新加载声明性配置
标签
- 列出所有标签
- 按标签列出实体ID
Service 对象
- Service 列表
- Service 检索
Route 对象
- Route 列表
- Route 检索
Consumer 对象
- Consumer 列表
- Consumer 检索
插件对象
证书对象
- 证书列表
- 证书检索
SNI 对象
- SNI 列表
- SNI 检索
Upstream 对象
Target 对象

支持的 Content Types

Admin API在每个端点上接受2种内容类型：

application/x-www-form-urlencoded
application/json

Routes 信息

检索节点信息

检索有关节点的常规详细信息。

GET /

响应

HTTP 200 OK

{
    "hostname": "",
    "node_id": "6a72192c-a3a1-4c8d-95c6-efabae9fb969",
    "lua_version": "LuaJIT 2.1.0-beta3",
    "plugins": {
        "available_on_server": [
            ...
        ],
        "enabled_in_cluster": [
            ...
        ]
    },
    "configuration" : {
        ...
    },
    "tagline": "Welcome to Kong",
    "version": "0.14.0"
}

node_id：表示正在运行的Kong节点的UUID。Kong启动时会随机生成此UUID，因此该节点在每次重新启动时将具有不同的node_id。
available_on_server：节点上安装的插件的名称。
enabled_in_cluster：启用/配置的插件名称。也就是说，当前所有数据节点共享的数据存储中的插件配置。

检索节点状态

检索有关节点的使用情况信息，以及一些有关基础nginx进程正在处理的连接的基本信息，数据库连接的状态以及节点的内存使用情况。

如果要监视Kong进程，由于Kong是在nginx之上构建的，因此可以使用每个现有的nginx监视工具或代理。

GET /status

响应

HTTP 200 OK

{
    "database": {
      "reachable": true
    },
    "memory": {
        "workers_lua_vms": [{
            "http_allocated_gc": "0.02 MiB",
            "pid": 18477
          }, {
            "http_allocated_gc": "0.02 MiB",
            "pid": 18478
        }],
        "lua_shared_dicts": {
            "kong": {
                "allocated_slabs": "0.04 MiB",
                "capacity": "5.00 MiB"
            },
            "kong_db_cache": {
                "allocated_slabs": "0.80 MiB",
                "capacity": "128.00 MiB"
            },
        }
    },
    "server": {
        "total_requests": 3,
        "connections_active": 1,
        "connections_accepted": 1,
        "connections_handled": 1,
        "connections_reading": 0,
        "connections_writing": 1,
        "connections_waiting": 0
    }
}

memory：有关内存使用情况的指标。
- workers_lua_vms：包含Kong节点的所有worker的数组，其中每个条目包含：
- http_allocated_gc：由collectgarbage（“ count”）报告的HTTP子模块的Lua虚拟机的内存使用情况信息，适用于每个活动的worker程序，即在最近10秒钟内收到代理调用的工作程序。
- pid：工作进程id号
- lua_shared_dicts：与Kong节点中所有工作人员共享的词典信息的数组，其中每个数组节点包含有多少内存专用于特定的共享字典（capacity）以及有多少所述内存正在使用（allocated_slabs）。
  这些共享字典具有最新使用（LRU）的清楚功能，因此allocated_slab == capacity所在的完整字典将正常工作。但是对于某些字典，例如缓存HIT/MISS共享字典，增加它们的大小对整体来说是有益的。
- 可以使用querystring参数unit和scale更改内存使用单位和精度：
  - unit：b/B，k/K，m/M，g/G中，它将分别以bytes、kibibytes、mebibytes或gibibytes返回结果。当请求“bytes”时，响应中的内存值将使用数字类型而不是字符串。默认为m。
  - scale：在人类可读的存储字符串（“bytes”以外的单位）示值时小数点右边的位数。默认值为2。您可以通过以下操作获得以kibibytes为单位的共享字典内存使用情况(精度为4位):get/status?unit=k&scale=4
server：有关Nginx HTTP/S服务器的指标。
- total_requests：客户端请求总数。
- connections_active：当前活动的客户端连接数，包括等待连接数。
- connections_accepted：接受的客户端连接总数。
- connections_handled：已处理的连接总数。通常，除非已达到某些资源限制，否则参数值与接受的值相同。
- connections_reading：Kong正在读取请求header的当前连接数。
- connections_writing：nginx正在将响应写回到客户端的当前连接数。
- connections_waiting：当前等待请求的空闲客户端连接数。
database：数据库指标
- reachable：反映数据库连接状态的布尔值。请注意，此标志不反映数据库本身的运行状况。

声明式配置

可以通过两种方式将实体的声明性配置加载到Kong中：在启动时，通过declarative_config属性，或者在运行时，通过使用/ config端点的Admin API。

要开始使用声明式配置，您需要一个包含实体定义的文件（YAML或JSON格式）。您可以使用以下命令生成示例声明式配置：

kong config init

它会在当前目录中生成一个名为kong.yml的文件，其中包含适当的结构和示例。

重新加载声明性配置

该端点允许使用新的声明性配置数据文件重置无数据库的Kong。所有先前的内容将从内存中删除，并且在给定文件中指定的实体将取代其位置。

要了解有关文件格式的更多信息，请阅读声明性配置文档。

POST /config

属性	描述
`config` required	要加载的配置数据（YAML或JSON格式）。

响应

HTTP 200 OK

{
    { "services": [],
      "routes": []
    }
}

响应包含从输入文件中解析的所有实体的列表。

单个请求中最多可以同时使用，或/来查询5个标签。
不支持混合运算符：如果尝试在同一查询字符串中将,与/混合，则会收到错误消息。
从命令行使用某些字符时，可能需要引用和/或转义一些字符。
外键关系端点不支持按标签过滤。例如，在诸如GET /services/foo/routes?tags=a,b之类的请求中，tags参数将被忽略。
如果更改或删除了tags参数，则不能保证offset参数会起作用

列出所有标签

返回系统中所有标签的分页列表。

实体列表将不限于单个实体类型：所有标记了标签的实体都将出现在此列表中。

如果一个实体被多个标签标记，则该实体的entity_id将在结果列表中出现多次。同样，如果几个实体已使用同一标签标记，则该标签将出现在此列表的多个项目中。

GET /tags

响应

HTTP 200 OK

{
    {
      "data": [
        { "entity_name": "services",
          "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
          "tag": "s1",
        },
        { "entity_name": "services",
          "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
          "tag": "s2",
        },
        { "entity_name": "routes",
          "entity_id": "60631e85-ba6d-4c59-bd28-e36dd90f6000",
          "tag": "s1",
        },
        ...
      ],
      "offset" = "c47139f3-d780-483d-8a97-17e9adc5a7ab",
      "next" = "/tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab",
    }
}

按标签列出实体ID

返回已被指定标签标记的实体。

实体列表将不限于单个实体类型：所有标记了标签的实体都将出现在此列表中。

GET /tags/:tags

响应

HTTP 200 OK

{
    {
      "data": [
        { "entity_name": "services",
          "entity_id": "c87440e1-0496-420b-b06f-dac59544bb6c",
          "tag": "example",
        },
        { "entity_name": "routes",
          "entity_id": "8a99e4b1-d268-446b-ab8b-cd25cff129b1",
          "tag": "example",
        },
        ...
      ],
      "offset" = "1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
      "next" = "/tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
    }
}

Service 对象

顾名思义，Service实体是您自己的每个上游服务的抽象。服务的示例将是数据转换微服务，计费API等。

Service的主要属性是其URL（Kong应该将流量代理到此URL），可以将其设置为单个字符串，也可以通过单独指定其protocol，host，port和path来设置。

Service与Routes关联（一个Service可以有许多与之关联的Routes）。Routes是Kong中的入口点，并定义规则以匹配客户请求。 Route匹配后，Kong将请求代理到其关联的服务。有关Kong代理流量的详细说明，请参阅代理参考。

Service可以通过标签进行标记和过滤

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"}
}

Service 列表

列出所有Service

GET /services

列出与特定Certificate相关的Service

GET /certificates/{certificate name or id}/services

属性	描述
`certificate name or id` required	要检索其Services的Certificate的唯一标识符或`name`属性。使用此端点时，将仅列出与指定证书关联的服务。

响应

HTTP 200 OK

{
"data": [{
    "id": "a5fb8d9b-a99d-40e9-9d35-72d42a62d83a",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"}
}, {
    "id": "fc73f2af-890d-4f9b-8363-af8945001f7f",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/another_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["admin", "high-priority", "critical"],
    "client_certificate": {"id":"4506673d-c825-444c-a25b-602e3c2ec16e"}
}],
    "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Service 检索

检索Service

GET /services/{name or id}

属性	描述
`name or id` required	要检索的Service的唯一标识符或名称。

检索与特定Route关联的Service

GET /routes/{route name or id}/service

属性	描述
`route name or id` required	与要检索的服务关联的唯一标识符或route的名称。

检索与特定插件相关的Service

GET /plugins/{plugin id}/service

属性	描述
`plugin id` required	与要检索的Service关联的插件的唯一标识符。。

响应

HTTP 200 OK

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"}
}

Route 对象

Route 实体定义规则以匹配客户端请求。每个 Route 都与 Service 关联，并且一个 Service 可能具有与其关联的多个 Route。匹配给定路线的每个请求都将被代理到其关联的 Service。

Route 和 Service 的组合（以及它们之间的关注点分离）提供了一种强大的路由机制，通过它可以在Kong中定义细粒度的入口点，从而导致基础结构的不同上游服务。

您需要至少一个匹配规则，该规则适用于路由要匹配的协议。取决于配置为与路由匹配的协议（如协议字段所定义），这意味着必须设置以下属性中的至少一个：

对于http，至少是methods，hosts，headers,paths其中之一；
对于https，至少是methods，hosts，headers,paths,snis其中之一；
对于tcp，至少是sources，destinations其中之一
对于tls，至少是sources，destinations，snis其中之一
对于grpc，hosts，headers,paths其中之一；
对于grpcs，hosts，headers,paths，snis其中之一。

Routes 可以通过标签进行标记和过滤。

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

Route 列表

列出所有 Route

GET /routes

列出与特定Service关联的 Route

GET /services/{service name or id}/routes

属性	描述
`service name or id` required	要检索其Route的service的唯一标识符或`name`属性。使用此端点时，仅列出与指定service关联的Route。

响应

HTTP 200 OK

{
"data": [{
    "id": "a9daa3ba-8186-4a0d-96e8-00d80ce7240b",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"127dfc88-ed57-45bf-b77a-a9d3a152ad31"}
}, {
    "id": "9aa116fd-ef4a-4efa-89bf-a0b17c4be982",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["tcp", "tls"],
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "snis": ["foo.test", "example.com"],
    "sources": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
    "destinations": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
    "tags": ["admin", "high-priority", "critical"],
    "service": {"id":"ba641b07-e74a-430a-ab46-94b61e5ea66b"}
}],
    "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Route 检索

检索 route

GET /routes/{name or id}

属性	描述
`name or id` required	要检索的唯一标识符或路线名称。

检索与特定插件关联的route

GET /plugins/{plugin id}/route

属性	描述
`plugin id` required	与要检索的路线相关联的插件的唯一标识符。

响应

HTTP 200 OK

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-another-header":["bla"], "x-my-header":["foo", "bar"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

Consumer 对象

Consumer对象代表服务的消费者或用户。您可以依靠Kong作为主要数据存储，也可以将使用者列表与数据库进行映射，以保持Kong和现有主要数据存储之间的一致性。

Consumer 可以通过标签进行标记和过滤。

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

Consumer 列表

列出所有 Consumers

GET /consumers

响应

HTTP 200 OK

{
"data": [{
    "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "01c23299-839c-49a5-a6d5-8864c09184af",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["admin", "high-priority", "critical"]
}],
    "next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Consumer 检索

检索 Consumers

GET /consumers/{username or id}

属性	描述
`username or id` required	要检索的consumer的唯一标识符或用户名。

检索与特定插件相关的使用者

属性	描述
`plugin id` required	与要检索的consumer相关联的插件的唯一标识符。

响应

HTTP 200 OK

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

插件对象

插件实体表示将在HTTP请求/响应生命周期内执行的插件配置。通过这种方法，您可以为在Kong后面运行的服务添加功能，例如身份验证或速率限制。您可以通过访问Kong Hub来找到有关如何安装以及每个插件采用什么值的更多信息。

当向service添加插件配置时，客户端对该service的每个请求都将运行所述插件。如果某个插件需要针对某些特定使用者调整为不同的值，则可以通过在service和使用者字段中创建一个单独的插件实例来指定service和consumer，从而做到这一点。

插件可以通过标签进行标记和过滤。

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "run_on": "first",
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"]
}

有关更多详细信息，请参见下面的“优先级”部分。

优先级

插件将始终运行一次，并且每个请求只能运行一次。但是它将运行的配置取决于为其配置的实体。

可以为各种实体，实体组合甚至全局配置插件。例如，当您希望以某种方式为大多数请求配置插件，使经过身份验证的请求的行为略有不同时。

因此，当插件被应用到具有不同配置的不同实体时，它的优先级是有顺序的。经验法则是:插件配置的实体越多，它的优先级就越高。

多次配置插件后，完整的优先级顺序为：

在以下各项的组合上配置的插件：Route，Service 和 Consumer。（Consumer 意味着必须对请求进行身份验证）。
在 Route 和 Consumer 的组合上配置的插件。（Consumer 意味着必须对请求进行身份验证）。
在 Service 和 Consumer 的组合上配置的插件。（Consumer 意味着必须对请求进行身份验证）。
在 Route 和 Service 的组合上配置的插件。
在 Consumer 者上配置的插件。（Consumer 意味着必须对请求进行身份验证）。
在 Route 上配置的插件。
在 Service 上配置的插件。
配置为全局运行的插件。

例子：如果速率限制插件应用了两次（使用不同的配置）：对于Service（插件配置A）和Consumer（插件配置B），则请求对此消Consumer者进行身份验证的请求将运行插件配置B并忽略A。但是，不验证此Consumer的请求将回退到运行插件configA。请注意，如果禁用了config B（其启用标志设置为false），则config A将应用于与config B匹配的请求。

插件列表

列出所有插件

GET /plugins

列出与指定 Route 关联的插件

GET /routes/{route id}/plugins

属性	描述
`route id` required	要获取其插件的Route的唯一标识符。使用此端点时，将仅列出与指定Route关联的插件。

列出与指定 Service 关联的插件

GET /services/{service id}/plugins

属性	描述
`service id` required	要检索其插件的service的唯一标识符。使用此端点时，将仅列出与指定service关联的插件。

列出与指定 Consumer 关联的插件

GET /consumers/{consumer id}/plugins

属性	描述
`consumer id` required	要检索其插件的Consumer的唯一标识符。使用此端点时，将仅列出与指定Consumer相关联的插件。

响应

HTTP 200 OK

{
"data": [{
    "id": "02621eee-8309-4bf6-b36b-a82017a5393e",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "run_on": "first",
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"]
}, {
    "id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "run_on": "first",
    "protocols": ["tcp", "tls"],
    "enabled": true,
    "tags": ["admin", "high-priority", "critical"]
}],
    "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

插件检索

GET /plugins/{plugin id}

属性	描述
`plugin id` required	要检索的插件的唯一标识符。

响应

HTTP 200 OK

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "run_on": "first",
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"]
}

已启用的插件检索

检索Kong节点上所有已安装插件的列表。

GET /plugins/enabled

响应

HTTP 200 OK

{
    "enabled_plugins": [
        "jwt",
        "acl",
        "cors",
        "oauth2",
        "tcp-log",
        "udp-log",
        "file-log",
        "http-log",
        "key-auth",
        "hmac-auth",
        "basic-auth",
        "ip-restriction",
        "request-transformer",
        "response-transformer",
        "request-size-limiting",
        "rate-limiting",
        "response-ratelimiting",
        "aws-lambda",
        "bot-detection",
        "correlation-id",
        "datadog",
        "galileo",
        "ldap-auth",
        "loggly",
        "statsd",
        "syslog"
    ]
}

插件schema检索

检索插件配置的schema。这有助于了解插件接受哪些字段，并且可用于与Kong的插件系统建立第三方集成。

GET /plugins/schema/{plugin name}

响应

HTTP 200 OK

{
    "fields": {
        "hide_credentials": {
            "default": false,
            "type": "boolean"
        },
        "key_names": {
            "default": "function",
            "required": true,
            "type": "array"
        }
    }
}

证书对象

证书对象表示一个公共证书，可以选择与对应的私钥配对。Kong使用这些对象来处理加密请求的SSL/TLS终止，或在验证客户端/服务的对等证书时用作受信任的CA存储。证书可选地与SNI对象相关联，以将证书/密钥对绑定到一个或多个主机名。

如果除了主证书之外还需要中间证书，那么应该按照以下顺序将它们连接到一个字符串中:主证书在顶部，然后是任何中间证书。

证书可以通过标签进行标记和过滤。

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

证书列表

列出所有证书

GET /certificates

响应

HTTP 200 OK

{
"data": [{
    "id": "d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "a9b2107f-a214-47b3-add4-46b942187924",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "tags": ["admin", "high-priority", "critical"]
}],
    "next": "http://localhost:8001/certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

证书检索

GET /certificates/{certificate id}

属性	描述
`certificate id` required	要检索的证书的唯一标识符。

响应

HTTP 200 OK

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "created_at": 1422386534,
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "tags": ["user-level", "low-priority"]
}

SNI 对象

SNI 列表

列出所有 SNIs

GET /snis

列出与特定证书关联的SNIs

GET /certificates/{certificate name or id}/snis

属性	描述
`certificate name or id` required	要检索其SNI的证书的唯一标识符或`name`属性。使用此端点时，将仅列出与指定证书关联的SNI。

响应

HTTP 200 OK

{
"data": [{
    "id": "a9b2107f-a214-47b3-add4-46b942187924",
    "name": "my-sni",
    "created_at": 1422386534,
    "tags": ["user-level", "low-priority"],
    "certificate": {"id":"04fbeacf-a9f1-4a5d-ae4a-b0407445db3f"}
}, {
    "id": "43429efd-b3a5-4048-94cb-5cc4029909bb",
    "name": "my-sni",
    "created_at": 1422386534,
    "tags": ["admin", "high-priority", "critical"],
    "certificate": {"id":"d26761d5-83a4-4f24-ac6c-cff276f2b79c"}
}],
    "next": "http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

SNI 检索

检索 SNIs

GET /snis/{name or id}

属性	描述
`name or id` required	要检索的SNI的唯一标识符或名称。

响应

HTTP 200 OK

{
    "id": "7fca84d6-7d37-4a74-a7b0-93e576089a41",
    "name": "my-sni",
    "created_at": 1422386534,
    "tags": ["user-level", "low-priority"],
    "certificate": {"id":"d044b7d4-3dc2-4bbc-8e9f-6b7a69416df6"}
}

Upstream 对象

上游对象代表虚拟主机名，可用于对多个服务（目标）上的传入请求进行负载平衡。因此，例如，上游主机名为service.v1.xyz的Service对象的host机是service.v1.xyz。对该服务的请求将被代理到上游定义的目标。

上游还包括运行状况检查器，该检查器能够根据目标是否能够满足请求来启用和禁用目标。健康状况检查器的配置存储在上游对象中，并应用于其所有目标。

上游可以通过标签进行标记和过滤。

{
    "id": "91020192-062d-416f-a275-9addeeaffaf2",
    "created_at": 1422386534,
    "name": "my-upstream",
    "hash_on": "none",
    "hash_fallback": "none",
    "hash_on_cookie_path": "/",
    "slots": 10000,
    "healthchecks": {
        "active": {
            "https_verify_certificate": true,
            "unhealthy": {
                "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
                "tcp_failures": 0,
                "timeouts": 0,
                "http_failures": 0,
                "interval": 0
            },
            "http_path": "/",
            "timeout": 1,
            "healthy": {
                "http_statuses": [200, 302],
                "interval": 0,
                "successes": 0
            },
            "https_sni": "example.com",
            "concurrency": 10,
            "type": "http"
        },
        "passive": {
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [429, 500, 503],
                "tcp_failures": 0,
                "timeouts": 0
            },
            "type": "http",
            "healthy": {
                "successes": 0,
                "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
            }
        }
    },
    "tags": ["user-level", "low-priority"]
}

Upstream 列表

列出所有Upstreams

GET /upstreams

响应

HTTP 200 OK

{
"data": [{
    "id": "a2e013e8-7623-4494-a347-6d29108ff68b",
    "created_at": 1422386534,
    "name": "my-upstream",
    "hash_on": "none",
    "hash_fallback": "none",
    "hash_on_cookie_path": "/",
    "slots": 10000,
    "healthchecks": {
        "active": {
            "https_verify_certificate": true,
            "unhealthy": {
                "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
                "tcp_failures": 0,
                "timeouts": 0,
                "http_failures": 0,
                "interval": 0
            },
            "http_path": "/",
            "timeout": 1,
            "healthy": {
                "http_statuses": [200, 302],
                "interval": 0,
                "successes": 0
            },
            "https_sni": "example.com",
            "concurrency": 10,
            "type": "http"
        },
        "passive": {
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [429, 500, 503],
                "tcp_failures": 0,
                "timeouts": 0
            },
            "type": "http",
            "healthy": {
                "successes": 0,
                "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
            }
        }
    },
    "tags": ["user-level", "low-priority"]
}, {
    "id": "147f5ef0-1ed6-4711-b77f-489262f8bff7",
    "created_at": 1422386534,
    "name": "my-upstream",
    "hash_on": "none",
    "hash_fallback": "none",
    "hash_on_cookie_path": "/",
    "slots": 10000,
    "healthchecks": {
        "active": {
            "https_verify_certificate": true,
            "unhealthy": {
                "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
                "tcp_failures": 0,
                "timeouts": 0,
                "http_failures": 0,
                "interval": 0
            },
            "http_path": "/",
            "timeout": 1,
            "healthy": {
                "http_statuses": [200, 302],
                "interval": 0,
                "successes": 0
            },
            "https_sni": "example.com",
            "concurrency": 10,
            "type": "http"
        },
        "passive": {
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [429, 500, 503],
                "tcp_failures": 0,
                "timeouts": 0
            },
            "type": "http",
            "healthy": {
                "successes": 0,
                "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
            }
        }
    },
    "tags": ["admin", "high-priority", "critical"]
}],
    "next": "http://localhost:8001/upstreams?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Upstream 检索

检索 Upstreams

GET /upstreams/{name or id}

属性	描述
`name or id` required	要检索的Upstream的唯一标识符或名称。

检索与指定Target相关的Upstream

GET /targets/{target host:port or id}/upstream

属性	描述
`target host:port or id` required	与要检索的上游关联的目标的唯一标识符或host：port。

响应

HTTP 200 OK

{
    "id": "91020192-062d-416f-a275-9addeeaffaf2",
    "created_at": 1422386534,
    "name": "my-upstream",
    "hash_on": "none",
    "hash_fallback": "none",
    "hash_on_cookie_path": "/",
    "slots": 10000,
    "healthchecks": {
        "active": {
            "https_verify_certificate": true,
            "unhealthy": {
                "http_statuses": [429, 404, 500, 501, 502, 503, 504, 505],
                "tcp_failures": 0,
                "timeouts": 0,
                "http_failures": 0,
                "interval": 0
            },
            "http_path": "/",
            "timeout": 1,
            "healthy": {
                "http_statuses": [200, 302],
                "interval": 0,
                "successes": 0
            },
            "https_sni": "example.com",
            "concurrency": 10,
            "type": "http"
        },
        "passive": {
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [429, 500, 503],
                "tcp_failures": 0,
                "timeouts": 0
            },
            "type": "http",
            "healthy": {
                "successes": 0,
                "http_statuses": [200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]
            }
        }
    },
    "tags": ["user-level", "low-priority"]
}

显示节点的Upstream运行状况

根据特定Kong节点的透视图显示给定Upstream的所有Target的健康状态。注意，作为特定于节点的信息，对Kong集群的不同节点发出相同的请求可能会产生不同的结果。例如,Kong 的一个特定节点集群可能遇到网络问题,导致无法连接到一些Target:这些Target将由该节点标记为不健康(将此节点的流量引导到它可以成功到达的其他Target),但健康的所有其他Kong节点(使用这一Target没有问题)。

响应的data字段包含Target对象的数组。每个Target的运行状况在其health字段中返回：

如果由于DNS问题而无法在环形负载均衡器中激活目标，则其状态将显示为DNS_ERROR。
如果在上游配置中未启用运行健康检查，则活动目标的运行状况将显示为HEALTHCHECKS_OFF。
启用健康检查并自动或手动确定目标为健康后，其状态将显示为HEALTHY。这意味着此目标当前已包含在此上游的负载均衡器环中。
通过主动或被动运行状况检查（断路器）或手动禁用目标后，其状态将显示为UNHEALTHY。负载平衡器不会通过此上游将任何流量定向到该目标。

GET /upstreams/{name or id}/health/

属性	描述
`name or id` required	要为其显示目标运行状况的唯一标识符或上游名称。

响应

HTTP 200 OK

{
    "total": 2,
    "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9",
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "health": "HEALTHY",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "health": "UNHEALTHY",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }
    ]
}

Target 对象

Target 是带有端口的ip地址/主机名，该端口标识后端服务的实例。每个 Upstream 都可以有许多 Target，并且可以动态添加 Target。更改是即时进行的。

由于 Upstream 保留了 Target 更改的历史记录，因此无法删除或修改目标。要禁用 Target，请发布一个新的weight=0的 Target；或者，使用DELETE便捷方法来实现相同目的。

当前目标对象定义是最新的created_at。

Target 可以通过标签进行标记和过滤。

Target 列表

列出与指定 Upstream 相关的 Target

GET /upstreams/{upstream host:port or id}/targets

属性	描述
`upstream host:port or id` required	要检索其目标的上游的唯一标识符或host：port属性。使用此端点时，将仅列出与指定 Upstream 相关联的 Target。

响应

HTTP 200 OK

{
"data": [{
    "id": "4e8d95d4-40f2-4818-adcb-30e00c349618",
    "created_at": 1422386534,
    "upstream": {"id":"58c8ccbb-eafb-4566-991f-2ed4f678fa70"},
    "target": "example.com:8000",
    "weight": 100,
    "tags": ["user-level", "low-priority"]
}, {
    "id": "ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6",
    "created_at": 1422386534,
    "upstream": {"id":"4fe14415-73d5-4f00-9fbc-c72a0fccfcb2"},
    "target": "example.com:8000",
    "weight": 100,
    "tags": ["admin", "high-priority", "critical"]
}],
    "next": "http://localhost:8001/targets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

将Target设定为健康

在整个Kong集群中，将负载均衡器中的目标的当前健康状态设置为“健康”。

此端点可用于手动重新启用先前被上游的健康状况检查器禁用的目标。Upstreams只将请求转发给正常的节点，因此这个调用告诉Kong重新开始使用这个目标。

这将重置在Kong节点的所有工作程序中运行的运行状况检查程序的运行状况计数器，并广播整个群集的消息，以便将“健康”状态传播到整个Kong群集。

POST /upstreams/{upstream name or id}/targets/{target or id}/healthy

属性	描述
`upstream name or id` required	upstream 的唯一标识符或名称。
`target or id` required	要设置为正常的目标的host/port组合元素，或现有目标条目的`id`。

响应

HTTP 204 No Content

将Target设置为不健康

在整个Kong集群中，将负载均衡器中的目标的当前健康状态设置为“不健康”。

该端点可用于手动禁用目标并使其停止响应请求。 upstream 仅将请求转发到运行状况良好的节点，因此此调用告诉Kong开始在环平衡器算法中跳过此目标。

此调用将重置在Kong节点的所有工作程序中运行的运行状况检查程序的运行状况计数器，并广播群集范围内的消息，以便将“不健康”状态传播到整个Kong群集。

对于不健康的目标，将继续执行主动健康检查。

请注意，如果启用了主动健康检查，并且探针检测到目标实际上是健康的，它将自动再次重新启用它。要从环平衡器中永久删除目标，应改为删除目标。

POST /upstreams/{upstream name or id}/targets/{target or id}/unhealthy

属性	描述
`upstream name or id` required	upstream 的唯一标识符或名称。
`target or id` required	要设置为正常的目标的host/port组合元素，或现有目标条目的`id`。

响应

HTTP 204 No Content

所有Target列表

列出所有上游的目标。可以返回同一目标的多个目标对象，显示特定目标的更改历史。具有最新created_at的目标对象是当前定义。

GET /upstreams/{name or id}/targets/all/

属性	描述
`name or id` required	列出目标的唯一标识符或upstream名称。

响应

HTTP 200 OK

{
    "total": 2,
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }