标签归档:Kong教程

微服务 API 网关 Kong 单元测试中文文档

原文链接: https://docs.konghq.com/1.0.x/plugin-development/tests/ (如有翻译的不准确或错误之处,欢迎留言指出)
集成测试:https://docs.konghq.com/1.0.x/plugin-development/tests/#write-integration-tests

介绍

如果你认真对待你写的插件,你可能想为它编写一些测试。Lua的单元测试很简单,并且可以使用许多测试框架。但是,您可能还想编写集成测试。Kong可以再次为您提供支援。

编写集成测试

Kong的首选测试框架是busted,它与resty-cli解释器一起运行,但如果您愿意,可以自由使用另一个。在Kong存储库中,可以在bin/busted找到 busted 的可执行文件。

Kong为您提供了一个帮助程序,可以在测试套件中从Lua启动和停止它:spec.helpers。此助手还提供了在运行测试之前在数据存储区中插入fixtures的方法,以及删除,以及各种其他helper。

如果您在自己的存储库中编写插件,则需要复制以下文件,直到Kong测试框架发布:

  • bin/busted: 与resty-cli解释器一起运行的 busted 的可执行文件
  • spec/helpers.lua:Kong的helper函数 可以从busted中 启动/关闭kong
  • spec/kong_tests.conf:使用helpers模块运行的Kong实例的配置文件

假设您的LUA_PATH中有spec.helpers模块,您可以使用以下Lua代码来启动和停止Kong:

local helpers = require "spec.helpers"

for _, strategy in helpers.each_strategy() do
  describe("my plugin", function()

    local bp = helpers.get_db_utils(strategy)

    setup(function()
      local service = bp.services:insert {
        name = "test-service",
        host = "httpbin.org"
      }

      bp.routes:insert({
        hosts = { "test.com" },
        service = { id = service.id }
      })

      -- start Kong with your testing Kong configuration (defined in "spec.helpers")
      assert(helpers.start_kong( { plugins = "bundled,my-plugin" }))

      admin_client = helpers.admin_client()
    end)

    teardown(function()
      if admin_client then
        admin_client:close()
      endhttps://github.com/Kong/kong/tree/master/spec/03-plugins/09-key-auth

      helpers.stop_kong()
    end)

    before_each(function()
      proxy_client = helpers.proxy_client()
    end)

    after_each(function()
      if proxy_client then
        proxy_client:close()
      end
    end)

    describe("thing", function()
      it("should do thing", function()
        -- send requests through Kong
        local res = proxy_client:get("/get", {
          headers = {
            ["Host"] = "test.com"
          }
        })

        local body = assert.res_status(200, res)

        -- body is a string containing the response
      end)
    end)
  end)
end

提醒:通过test Kong配置文件,Kong运行在代理监听端口9000(HTTP),9443 (HTTPS)和端口9001上的Admin API。

如果想看一下真实的例子,可以来这里看一看 Key-Auth plugin specs

微服务 API 网关 Kong 命令行中文文档

原文链接: https://docs.konghq.com/1.0.x/cli/
(如有翻译的不准确或错误之处,欢迎留言指出)

介绍

提供的CLI(命令行界面Command Line Interface)允许启动,停止和管理Kong实例。CLI可以管理本地节点(如在当前计算机上)。

如果您还没有使用,我们建议您阅读配置参考

通用标志参数

所有命令都将一组特殊的可选标志作为参数:

  • --help:打印此命令的帮助信息
  • --v:启用详细模式
  • --vv:启用调试模式(很多输出)

可用命令

kong check

Usage: kong check <conf>

检查给定Kong配置文件的有效性。

<conf> (default /etc/kong/kong.conf) 配置文件

kong health

Usage: kong health [OPTIONS]

验证Kong 的服务组件是否正常运行

Options:
 -p,--prefix      (可选参数) Kong运行位置的前缀

kong migrations

Usage: kong migrations COMMAND [OPTIONS]

管理数据库迁移。

可用的命令如下:
  bootstrap                         引导数据库并运行全部迁移(初始化)。

  up                                运行新迁移。

  finish                            完成正在等待中的迁移命令,在执行`up`后。

  list                              列出已执行的迁移。

  reset                             重置数据库。

Options(可选):
 -y,--yes                           假设提示“yes”,并运行非交互模式

 -q,--quiet                         忽略所有输出

 -f,--force                         依旧执行迁移,即使数据库报告已经执行过了。

 --db-timeout     (default 60)      超时时间,以秒为单位,所有数据库操作通用(包括Cassandra的schema consensus)。

 --lock-timeout   (default 60)      超时时间,以秒为单位, 节点等待领导节点迁移完成。

 -c,--conf        (optional string) 配置文件。

kong prepare

此命令用来准备Kong前缀文件夹及其子文件夹和文件。

Usage: kong prepare [OPTIONS]

在配置的前缀目录中准备Kong前缀。这个命令可以用于从nginx二进制文件启动Kong而不使用`kong start`命令。

Example usage:
  kong migrations up
  kong prepare -p /usr/local/kong -c kong.conf
  nginx -p /usr/local/kong -c /usr/local/kong/nginx.conf

Options:
  -c,--conf       (optional string) 配置文件
  -p,--prefix     (optional string) 覆盖前缀目录
  --nginx-conf    (optional string) 自定义Nginx配置模板

kong quit

Usage: kong quit [OPTIONS]

优雅地退出一个正在运行的Kong节点(Nginx和其他节点)在给定的前缀目录中配置的服务。

此命令将会向Nginx发送SIGQUIT信号,表示全部请求将在关闭之前完成处理。
如果达到超时延迟,则该节点将被强制执行停止(SIGTERM)

Options:
 -p,--prefix      (optional string) kong正在运行的前缀
 -t,--timeout     (default 10) 强制停止前的超时

kong reload

Usage: kong reload [OPTIONS]

重新加载Kong节点(并启动其他已配置的服务)在给定的前缀目录中。

此命令将HUP信号发送到Nginx,它将生成workers(告知account配置变更),当他们处理完成当前的请求后就停止旧的。

Options:
  -c,--conf       (optional string) 配置文件
  -p,--prefix     (optional string) 覆盖前缀目录
  --nginx-conf    (optional string) 自定义Nginx配置模板

kong restart

Usage: kong restart [OPTIONS]

重新启动Kong节点(以及其他配置的服务,如Serf)在给定的前缀目录中。

这个命令相当于同时执行`kong stop`和`kong start`。

Options:
 -c,--conf        (optional string)   配置文件
 -p,--prefix      (optional string)   Kong运行的前缀
 --nginx-conf     (optional string)   自定义Nginx配置模板
 --run-migrations (optional boolean)  可选地在DB上运行迁移
 --db-timeout     (default 60)
 --lock-timeout   (default 60)

kong start

Usage: kong start [OPTIONS]

在配置中启动Kong(Nginx和其他配置的服务)。

Options:
 -c,--conf        (optional string)   配置文件。

 -p,--prefix      (optional string)   覆盖前缀目录。

 --nginx-conf     (optional string)   自定义Nginx配置模板。

 --run-migrations (optional boolean)  在开始之前运行迁移。

 --db-timeout     (default 60)      超时时间,以秒为单位,所有数据库操作通用(包括Cassandra的schema consensus)。

 --lock-timeout   (default 60)      超时时间,以秒为单位, 节点等待领导节点迁移完成。

kong stop

Usage: kong stop [OPTIONS]

停止给定的正在运行的Kong节点(Nginx和其他已配置的服务)在指定的前缀目录。

此命令将SIGTERM信号发送到Nginx。

Options:
 -p,--prefix      (optional string) Kong运行的前缀

kong version

Usage: kong version [OPTIONS]

打印kong的版本。
使用-a选项,将打印所有底层依赖项的版本。

Options:
 -a,--all         获取所有依赖项的版本

微服务 API 网关 Kong File Log 插件中文文档

原文链接: https://docs.konghq.com/hub/kong-inc/file-log
(如有翻译的不准确或错误之处,欢迎留言指出)

将请求和响应数据写入磁盘上的日志文件中。不建议在生产中使用此插件,在生产环境下,最好使用另一个日志插件,例如syslog。由于系统限制,此插件使用阻塞文件i/o,将会损害性能,因此是Kong安装的反面模式。
注意:此插件的功能与0.10.2之前的Kong版本捆绑在一起,与此处记录的不同。 有关详细信息,请参阅CHANGELOG

配置

在服务上启用插件

通过发出以下请求在服务上配置此插件:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=file-log"  \
    --data "config.path=/tmp/file.log"

service:此插件配置将绑定的服务的ID或名称。

在路由上启用插件

Route上配置此插件:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=file-log"  \
    --data "config.path=/tmp/file.log"

route_id:此插件配置将绑定的路由的ID。

在Consumer上启用插件

您可以使用 http://localhost:8001/plugins 端点在特定的Consumers上启用此插件:

$ curl -X POST http://kong:8001/plugins \
    --data "name=file-log" \
    --data "consumer_id={consumer_id}"  \
    --data "config.path=/tmp/file.log"

其中,consumer_id是我们想要与此插件关联的消费者的ID。您可以组合consumer_idservice_id。在同一个请求中,进一步缩小插件的范围。

全局插件

可以使用http://kong:8001/plugins/ 配置所有插件。与任何服务,路由或消费者(或API,如果您使用旧版本的Kong)无关的插件被视为“全局”,并将在每个请求上运行。有关更多信息,请阅读插件参考插件优先级部分。

参数

以下是可在此插件配置中使用的所有参数的列表:

参数名称 默认值 描述
name 要使用的插件的名称,在本例中为file-log
service_id 此插件将关联的服务的ID。
route_id 此插件将关联的路由的ID。
enabled true 是否将应用此插件。
consumer_id 此插件将定位的绑定的id。
config.path 输出日志文件的文件路径。
如果该文件尚不存在,该插件将创建该文件。
确保Kong对此文件具有写入权限。
config.reopen false 在kong0.10.2引入。确定是否关闭日志文件并在每个请求时重新打开。 如果文件未重新打开,并且已被删除/循环,则插件将继续写入过时的文件描述符,从而丢失信息。

日志格式

每个请求将分别记录在由新行\n分隔的JSON对象中,格式如下:

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",cuowu
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

关于上述JSON对象的一些注意事项:

  • request 包含有关客户端发送的请求的属性
  • response 包含有关发送到客户端的响应的属性
  • tries 包含负载均衡器为此请求进行的(重新)尝试(成功和失败)列表
  • route 包含有关所请求的特定路线的Kong属性
  • service 包含与所请求的路线相关联的服务的Kong属性
  • authenticated_entity 包含有关经过身份验证的凭据的Kong属性(如果已启用身份验证插件)
  • workspaces 包含与请求的路由关联的工作空间的Kong属性。仅限Kong Enterprise版本> = 0.34
  • consumer 包含经过身份验证的使用者(如果已启用身份验证插件)
  • latencies 包含一些有关延迟的数据:
    • proxy 是最终服务处理请求所花费的时间
    • kong 是运行所有插件所需的内部Kong延迟
    • request 是从客户端读取的第一个字节之间以及最后一个字节发送到客户端之间经过的时间。用于检测慢速客户端。
  • client_ip 包含原始客户端IP地址
  • started_at 包含开始处理请求的UTC时间戳。

Kong执行错误

此日志记录插件仅记录HTTP请求和响应数据。 如果您正在寻找Kong进程错误文件(这是nginx错误文件),那么您可以在以下路径找到它:{prefix}/logs/error.log

微服务 API 网关 Kong CORS 插件中文文档

原文地址:https://docs.konghq.com/hub/kong-inc/cors/ (不能保证所有的翻译都是准确无误的,所有如有翻译的不准确或错误之处,请一定记得查看原文,并欢迎留言指出)。

通过启用此插件,轻松将跨源资源共享(CORS)添加到 Service, Route 。

配置

在 Service 上启用插件

通过发出以下请求在 Service 上配置此插件:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=cors"  \
    --data "config.origins=http://mockbin.com" \
    --data "config.methods=GET, POST" \
    --data "config.headers=Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token" \
    --data "config.exposed_headers=X-Auth-Token" \
    --data "config.credentials=true" \
    --data "config.max_age=3600"
  • service:此插件配置将绑定的服务的ID或名称。

在 Route 上启用插件

通过发出以下请求在 Route 上配置此插件:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=cors"  \
    --data "config.origins=http://mockbin.com" \
    --data "config.methods=GET, POST" \
    --data "config.headers=Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token" \
    --data "config.exposed_headers=X-Auth-Token" \
    --data "config.credentials=true" \
    --data "config.max_age=3600"

全局插件

可以使用http://kong:8001/plugins/ 配置所有插件。与任何Service, Route 或者 Consumer(或API,如果您使用旧版本的Kong)无关的插件被视为“全局”,并将在每个请求上运行。有关更多信息,请阅读插件参考插件优先级部分。

参数

以下是可在此插件配置中使用的所有参数的列表:

参数名称 默认值 描述
name 要使用的插件的名称,在本例中为cors
service_id 此插件将绑定的 Service 的ID。
route_id 此插件将绑定的 Route 的ID。
enabled true 是否将应用此插件。
config.origins 
optional
Access-Control-Allow-Origin标头的允许域,用逗号分割,如果想允许所有,就使用*。接受的值可以是flat strings 或PCRE正则表达式。 
注意:在Kong 0.10.x之前,此参数是config.origin(请注意s的更改),并且只接受单个值或*特殊值。
config.methods 
optional
GET, HEAD, PUT, PATCH,POST Access-Control-Allow-Methods header的值,使用逗号分隔的字符串(例如GETPOST)。
config.headers 
optional
Access-Control-Request-Headers请求header的值 Access-Control-Allow-Headers header的值,使用逗号分割(例如OriginAuthorization)。
config.exposed_headers 
optional
Access-Control-Expose-Headers header 的值,使用逗号分割(例如OriginAuthorization),如果未指定,则不会开放自定义header。
config.credentials 
optional
false 用于确定是否应使用true作为值发送Access-Control-Allow-Credentialsheader。
config.max_age 
optional
指示可以缓存预检请求的结果的时间长度(以秒为单位)。
config.preflight_continue
optional
false 一个布尔值,指示插件将OPTIONS预检请求代理到上游服务。

相关问题

以下是此插件的已知问题或限制的列表。

CORS限制

如果客户端是浏览器,则由于CORS规范的限制导致此插件存在已知问题,该限制不允许在预检OPTIONS请求中指定自定义header。
由于此限制,此插件仅适用于已使用路径设置配置的路由,并且对于使用自定义DNS(hosts属性)解析的路由不起作用。
要了解如何为Route配置路径,请阅读代理参考

微服务 API 网关 Kong 插件开发添加自定义配置文件

由于在 Kong 的插件开发中,需要添加一些自定义的配置文件,而且是一些插件公用的配置,但是又不方便都写在插件的 schema.lua 中,那么就考虑引入常规的配置文件,这里以.env文件为例,写一下添加和使用过程。

首先需要了解的是,Kong 的插件使用了一个叫 Classic 的 class 机制。所有的插件都是从 base_plugin.lua 基类上继承而来。base_plugin.lua 定义了插件在各个阶段被执行的方法名:,所以我们就从这里入手,以添加redis配置信息为例。

添加配置文件

进入到插件目录,我这里是/usr/local/share/lua/5.1/kong/plugins,然后新建一个.env文件,写入:

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=
REDIS_PORT=6379

添加获取配置文件内容方法

然后编辑base_plugin.lua,(需要注意的是,这里可能会有权限问题),在

return BasePlugin

这一行上加上获取.env的方法

-- 获取配置文件
function BasePlugin:load_ini()

    if config_data then
        return config_data
    end

    config_data = {}

    local info = debug.getinfo(1, "S")
    local path = info.source
    path = string.sub(path, 2, -1) -- 去掉开头的"@"
    path = string.match(path, "^.*/") -- 捕获最后一个 "/" 之前的部分 就是我们最终要的目录部分

    local conf, err = resty_ini.parse_file(path .. ".env")

    if not conf then
        ngx_log( ngx.ERR, "[ -- can not find file .env -- ]" .. tostring(err))
        return
    end

    for section, values in pairs(conf) do
        for k, v in pairs(values) do
            config_data[k] = v
        end
    end

    return config_data
end

把配置文件中的内容以键值对的形式放在一个名为config_data的table中。

使用配置内容

base_plugin.lua里加好了之后,回到自己的自定义插件开发中。获取配置文件内容如下:

local ini_conf = BasePlugin:load_ini()
if not ini_conf then
    ngx.log(ngx.ERR, "[ -- redis-log -- ] failed to read .env ", err)
end

使用配置文件的内容来链接并验证redis

function connectme()

    local red = redis:new()

    red:set_timeout(1000)

    if not ini_conf then
        ngx_log(ngx.ERR, "[ -- redis-log -- ] failed to read .env ", err)
    end

    local redis_host = ini_conf['REDIS_HOST']
    local redis_port = ini_conf['REDIS_PORT']
    local redis_password = ini_conf['REDIS_PASSWORD']

    local ok, err = red:connect(redis_host, redis_port)

    if not ok then
        ngx_log(ngx.ERR, "[ -- redis-log -- ] failed to connect to Redis: ", err)
        return
    end

    if redis_password then
        local ok, err = red:auth(redis_password)
        if not ok then
            ngx_log(ngx.ERR, "[ -- redis-log -- ] failed to auth to Redis: ", err)
            return
        end
    end

    return red
end

最后需要说明的是,每次修改了配置文件,需要重新加载一下整个插件,也就是可能需要重新启动一下kong。如果有更好更更合理的方法,欢迎留言~

微服务 API 网关 Kong 插件开发套件PDK 中文文档

原文地址:https://docs.konghq.com/1.0.x/pdk/(不能保证所有的翻译都是准确无误的,所有如有翻译的不准确或错误之处,请一定记得查看原文,并欢迎留言指出)。

插件开发工具包 Plugin Development Kit(或“PDK”)是一组Lua函数和变量,插件可以使用这些函数和变量来实现自己的逻辑。PDK是一个语义版本的组件,最初在Kong 0.14.0中发布。PDK将保证从1.0.0版本开始向前兼容。

截至本版本,PDK尚未达到1.0.0,但插件作者已经可以依赖它来使用安全可靠的方式进行请求、响应或者做一些核心组件。

可以从kong全局变量访问插件开发工具包,并在此表下命名各种功能,例如kong.requestkong.log等…

kong.version

一个可以直观阅读的字符串,包含当前正在运行的节点的版本号。

用法

print(kong.version) -- "0.14.0"
Back to TOC

kong.version_num

表示当前运行节点的版本号的整数,用于比较和特征存在检查。

用法

if kong.version_num < 13000 then -- 000.130.00 -> 0.13.0
  -- no support for Routes & Services
end

kong.pdk_major_version

表示当前PDK主要版本的数字(例如1)。 对于作为PDK用户的特征存在检查或向后兼容行为很有用。

用法

if kong.pdk_version_num < 2 then
  -- PDK is below version 2
end
Back to TOC

kong.pdk_version

一个可以直观阅读的字符串,包含当前PDK的版本号。

用法

print(kong.pdk_version) -- "1.0.0"

kong.configuration

包含当前Kong节点配置的只读表,基于配置文件和环境变量。 有关详细信息,请参阅kong.conf.default。 该文件中以逗号分隔的列表将被提升为此表中的字符串数组。

用法

print(kong.configuration.prefix) -- "/usr/local/kong"
-- this table is read-only; the following throws an error:
kong.configuration.prefix = "foo"

kong.db

Kong的DAO实例(kong.db模块)。 包含各种实体的访问者对象。

用法

kong.db.services:insert()
kong.db.routes:select()

将来可以提供有关此DAO和新模式定义的更全面的文档。

kong.dns

Kong的DNS解析器实例,来自lua-resty-dns-c模块的客户端对象。 注意:此模块的使用目前保留给核心或高级用户。

kong.worker_events

Kong的IPC模块实例,用于来自lua-resty-worker-events模块的员工间通信。 注意:此模块的使用目前保留给核心或高级用户。

kong.cluster_events

用于节点间通信的Kong的集群事件模块的实例。 注意:此模块的使用目前保留给核心或高级用户。 回到TOC

kong.cache

来自kong.cache模块的Kong数据库缓存对象的实例。 注意:此模块的使用目前保留给核心或高级用户。

微服务 API 网关 Kong 配置文件中文详解

原文地址:https://docs.konghq.com/1.0.x/configuration/ (不能保证所有的翻译都是准确无误的,所有如有翻译的不准确或错误之处,请一定记得查看原文,并欢迎留言指出)。

配置加载

如果您通过官方软件包安装Kong,则可以在/etc/kong/kong.conf.default找到默认配置文件。 要开始配置Kong,您可以复制此配置文件文件:

$ cp /etc/kong/kong.conf.default /etc/kong/kong.conf

如果您的配置文件中的所有值都被注释掉,Kong将使用默认设置运行。 启动时,Kong会自动查找可能包含配置文件的多个默认位置:

/etc/kong/kong.conf
/etc/kong.conf

您可以通过使用CLI中的-c / --conf参数,为配置文件指定自定义路径:

$ kong start --conf /path/to/kong.conf

配置文件格式修改很简单:只需取消注释任何属性(注释由#字符定义)并根据需要进行修改。为方便起见,可以将布尔值指定为on / offtrue / false

校验配置

您可以使用check命令验证设置的完整性:

$ kong check <path/to/kong.conf>
configuration at <path/to/kong.conf> is valid

此命令将考虑您当前设置的环境变量,并在设置无效时报错。此外,您还可以在调试模式下使用CLI,以便更深入地了解Kong的启动属性

$ kong start -c <kong.conf> --vv
2016/08/11 14:53:36 [verbose] no config file found at /etc/kong.conf
2016/08/11 14:53:36 [verbose] no config file found at /etc/kong/kong.conf
2016/08/11 14:53:36 [debug] admin_listen = "0.0.0.0:8001"
2016/08/11 14:53:36 [debug] database = "postgres"
2016/08/11 14:53:36 [debug] log_level = "notice"
[...]

环境变量

从配置文件中加载属性时,Kong还将查找具有相同名称的环境变量。 您可以通过环境变量完全配置Kong,这对于基于容器的基础结构非常方便。要使用环境变量覆盖设置,请使用设置名称声明环境变量,前缀为KONG_并大写。例:

log_level = debug # in kong.conf

可以被如下系统环境变量覆盖:

$ export KONG_LOG_LEVEL=error

注入 Nginx 指令

通过调整Kong实例的Nginx配置,您可以优化其基础架构的性能。当Kong启动时,它会构建一个Nginx配置文件。您可以通过Kong配置直接将自定义Nginx指令注入此文件。

注入单个 Nginx 指令

添加到kong.conf文件中的任何以nginx_http_nginx_proxy_nginx_admin_为前缀的条目将通过删除前缀并添加到Nginx配置的相应部分而转换为等效的Nginx指令。

  • 带有nginx_http_前缀的条目将被注入整个http块指令。
  • 带有nginx_proxy_前缀的条目将被注入到处理Kong的代理端口的Service块指令中。
  • 带有nginx_admin_前缀的条目将被注入到处理Kong的Admin API端口的服务器块指令中。

例如,如果将以下行添加到kong.conf文件中:

nginx_proxy_large_client_header_buffers=16 128k

它会将以下指令添加到Kong的Nginx配置的代理Service块中:

large_client_header_buffers 16 128k;

与kong.conf中的任何其他条目一样,也可以使用环境变量指定这些指令,如上所示。 例如,如果您声明一个这样的环境变量:

export KONG_NGINX_HTTP_OUTPUT_BUFFERS="4 64k"

这样将以下Nginx指令添加到http模块

output_buffers 4 64k;

与往常一样,请注意shell的引用规则,指定包含空格的值。有关Nginx配置文件结构和块指令的更多详细信息,请参阅https://nginx.org/en/docs/beginners_guide.html#conf_structure。 但请注意,某些指令依赖于特定的Nginx模块,其中一些模块可能不包含在Kong的官方版本中。

通过注入的Nginx指令包含文件

对于更复杂的配置方案,例如添加整个新Servic块,您可以使用上述方法将include指令注入Nginx配置,指向包含其他Nginx设置的文件。

或者,如果使用以下内容创建名为my-server.kong.conf的文件:

# custom server
server {
  listen 2112;
  location / {
    # ...more settings...
    return 200;
  }
}

您可以通过在kong.conf文件中添加以下条目来使Kong节点服务于此端口:

nginx_http_include = /path/to/your/my-server.kong.conf

或者,通过环境变量配置它:

$ export KONG_NGINX_HTTP_INCLUDE="/path/to/your/my-server.kong.conf"

现在,当你启动Kong时,该文件中的服务器部分将被添加到该文件中,这意味着其中定义的自定义服务器将与常规Kong端口一起响应:

$ curl -I http://127.0.0.1:2112
HTTP/1.1 200 OK
...

请注意,如果在nginx_http_include属性中使用相对路径,则该路径将相对于kong.conf文件的prefix属性的值进行解释(如果使用它来覆盖kong start-p标志的值) 开始Kong时的前缀)。

自定义Nginx模板和嵌入Kong

对于绝大多数用例,使用上面解释的Nginx指令注入系统应该足以定制Kong的Nginx实例的行为。这样,您可以从单个kong.conf文件(以及可选的自己包含的文件)管理Kong节点的配置和调优,而无需处理自定义Nginx配置模板。

有两种情况您可能希望直接使用自定义Nginx配置模板:

  • 在极少数情况下,您可能需要修改一些不能通过其标准kong.conf属性调整的Kong的默认Nginx配置,您仍然可以修改Kong使用的模板来生成其Nginx配置并使用您的自定义模板启动Kong。
  • 如果您需要在已经运行的OpenResty实例中嵌入Kong,则Nginx section Permalink可以重用Kong生成的配置并将其包含在现有配置中。

自定义Nginx模板

可以使用--nginx-conf参数启动,重新加载和重新启动Kong,该参数必须指定Nginx配置模板。这样的模板使用Penlight模板引擎,该引擎使用给定的Kong配置进行编译,然后在启动Nginx之前将其转储到您的Kong前缀目录中。

可以在以下网址找到默认模板:https://github.com/kong/kong/tree/master/kong/templates。 它分为两个Nginx配置文件:nginx.luanginx_kong.lua。前者是简约的,包括后者,其中包含了运行所需要的一切。 当kong start运行时,就在启动Nginx之前,它会将这两个文件复制到前缀目录中,如下所示:

/usr/local/kong
├── nginx-kong.conf
└── nginx.conf

如果你必须调整由Kong定义但不能通过kong.conf中的Kong配置调整的全局设置,你可以将nginx_kong.lua配置模板的内容内联到一个自定义模板文件(在这个例子中称为custom_nginx.template),例如:

# ---------------------
# custom_nginx.template
# ---------------------

worker_processes ${{NGINX_WORKER_PROCESSES}}; # can be set by kong.conf
daemon ${{NGINX_DAEMON}};                     # can be set by kong.conf

pid pids/nginx.pid;                      # this setting is mandatory
error_log logs/error.log ${{LOG_LEVEL}}; # can be set by kong.conf

events {
    use epoll;          # a custom setting
    multi_accept on;
}

http {

  # contents of the nginx_kong.lua template follow:

  resolver ${{DNS_RESOLVER}} ipv6=off;
  charset UTF-8;
  error_log logs/error.log ${{LOG_LEVEL}};
  access_log logs/access.log;

  ... # etc
}

然后你可以这样启动你的Nginx实例:

$ nginx -p /usr/local/openresty -c my_nginx.conf

并且Kong将在该实例中运行(在nginx-kong.conf中配置)。

使用Kong来给一个网站和APIs提供服务

API提供方的一个常见用例是使Kong通过代理端口(80或443)在生产中同时为网站和API提供服务。例如,https://example.net(Website)和https://example.net/api/v1(API)。

为实现这一目标,我们不能简单地声明一个新的虚拟服务器块,就像我们在上一节中所做的那样。

一个好的解决方案是使用自定义的Nginx配置模板,该模板内联nginx_kong.lua并添加一个新的位置块,为Kong Proxy location 提供服务:

# ---------------------
# custom_nginx.template
# ---------------------

worker_processes ${{NGINX_WORKER_PROCESSES}}; # can be set by kong.conf
daemon ${{NGINX_DAEMON}};                     # can be set by kong.conf

pid pids/nginx.pid;                      # this setting is mandatory
error_log logs/error.log ${{LOG_LEVEL}}; # can be set by kong.conf
events {}

http {
  # here, we inline the contents of nginx_kong.lua
  charset UTF-8;

  # any contents until Kong's Proxy server block
  ...

  # Kong's Proxy server block
  server {
    server_name kong;

    # any contents until the location / block
    ...

    # here, we declare our custom location serving our website
    # (or API portal) which we can optimize for serving static assets
    location / {
      root /var/www/example.net;
      index index.htm index.html;
      ...
    }

    # Kong's Proxy location / has been changed to /api/v1
    location /api/v1 {
      set $upstream_host nil;
      set $upstream_scheme nil;
      set $upstream_uri nil;

      # Any remaining configuration for the Proxy location
      ...
    }
  }

  # Kong's Admin server block goes below
  # ...
}

属性参考

通用部分

Prefix

工作目录。 相当于Nginx的前缀路径,包含临时文件和日志。每个Kong流程必须有一个单独的工作目录。

默认:/usr/local/kong

log_level

Nginx服务器的日志级别。可以在 <prefix>/logs/error.log中找到日志有关可接受值的列表,请参见http://nginx.org/en/docs/ngx_core_module.html#error_log。

proxy_access_log

代理端口请求访问日志的路径。 将此值设置为off可禁用日志记录代理请求。 如果此值是相对路径,则它将位于prefix位置下

默认:logs/access.log

proxy_error_log

代理端口请求错误日志的路径。 这些日志的粒度由log_level指令调整。
默认:logs/error.log

admin_access_log

Admin API请求访问日志的路径。 将此值设置为off可禁用日志记录Admin API请求。 如果此值是相对路径,则它将位于prefix位置下。

默认:logs/admin_access.log

admin_error_log

Admin API请求错误日志的路径。 这些日志的粒度由log_level指令调整。

默认:logs/error.log

plugins

此节点应加载的插件名称的逗号分隔列表。 列表中的每个项目可以是:

  • 插件名称。这里接受默认捆绑插件(例如key-auth)和自定义插件(例如自定义速率限制)。
  • 关键字bundled。这与包含与Kong捆绑的所有插件(来自kong.plugins。{name}.*命名空间)具有相同的含义。
  • 关键字off。如果指定,Kong将不会加载任何插件,并且任何插件都不能通过Admin API进行配置。

请注意,如果以前配置了一些插件(即在数据库中有行)并且未在此列表中指定,则Kong将无法启动。 在禁用插件之前,请确保在重新启动Kong之前删除它的所有实例。

默认:bundled

例子:

  • plugins=bundled,custom-auth,custom-log 将会包含已经捆绑的默认插件,和两个自定义插件
  • plugins=custom-auth,custom-log 将会包含只 custom-auth  custom-log两个插件
  • plugins=off 不会包含任何插件

提示:限制可用插件的数量可以在数据库缓存中遇到LRU搅动时(即配置的mem_cache_size已满时)提高P99延迟。

anonymous_reports

发送匿名使用数据,例如错误堆栈跟踪,以帮助改善Kong。 默认:on

Nginx部分

proxy_listen

代理服务器应侦听的以逗号分隔的地址和端口列表。代理服务器是Kong的公共入口点,它将来自您的消费者的流量代理到您的后端服务。proxy_listen值接受IPv4,IPv6和主机名。

可以为每对指定一些后缀: 发送匿名使用数据,例如错误堆栈跟踪,以帮助改善Kong。 默认:on

Nginx部分

proxy_listen

发送匿名使用数据,例如错误堆栈跟踪,以帮助改善Kong。 默认:on

Nginx部分

proxy_listen

  • ssl 将要求通过特定地址/端口建立的所有连接都是在启用TLS的情况下进行的。
  • http2 将允许客户端打开到Kong的代理服务器的HTTP / 2连接。
  • proxy_protocol 将为给定的地址/端口启用PROXY协议的使用。

此节点的代理端口,启用“控制平面”模式(无流量代理功能),可以配置连接到同一数据库的节点集群。有关此参数的值和其他* _listen值的可接受格式的说明,请参见http://nginx.org/en/docs/http/ngx_http_core_module.html#listen。

默认:0.0.0.0:8000, 0.0.0.0:8443 ssl
例子:0.0.0.0:80, 0.0.0.0:81 http2, 0.0.0.0:443 ssl, 0.0.0.0:444 http2 ssl

stream_listen

流模式应侦听的以逗号分隔的地址和端口列表。此值接受IPv4,IPv6和主机名。

可以为每对指定一些后缀:

  • proxy_protocol 将为给定的地址/端口启用PROXY协议的使用。
  • transparent 将会使kong监听您在iptables中配置的任何和所有IP地址和端口并进行响应。

请注意,不支持ssl后缀,并且每个地址/端口都将接受启用或未启用TLS的TCP。

例子:

stream_listen = 127.0.0.1:7000
stream_listen = 0.0.0.0:989, 0.0.0.0:20
stream_listen = [::1]:1234

默认情况下,此值设置为off,从而禁用此节点的mesh proxy 端口

admin_listen

管理员界面应监听的以逗号分隔的地址和端口列表。Admin界面是允许您配置和管理Kong的API。访问此界面应仅限于Kong管理员。此值接受IPv4,IPv6和主机名。 可以为每对指定一些后缀:

  • ssl 将要求通过特定地址/端口建立的所有连接都是在启用TLS的情况下完成的。
  • http2 将允许客户端打开到Kong的代理服务器的HTTP / 2连接。
  • proxy_protocol 将为给定的地址/端口启用PROXY协议的使用。

此值可以设置为off,从而禁用此节点的Admin接口,启用“数据平面”模式(无配置功能)从数据库中提取其配置更改。

默认:127.0.0.1:8001, 127.0.0.1:8444 ssl

例子:127.0.0.1:8444 http2 ssl

nginx_user

定义工作进程使用的用户和组凭据。如果省略group,则使用名称等于user的组。

默认:nobody nobody

例子:nginx www

nginx_worker_processes

确定Nginx生成的工作进程数。有关此指令的详细用法和可接受值的说明,请参见http://nginx.org/en/docs/ngx_core_module.html#worker_processes。

默认:auto

nginx_daemon

确定Nginx是作为守护程序还是作为前台进程运行。主要用于开发或在Docker环境中运行Kong时。参见:http://nginx.org/en/docs/ngx_core_module.html#daemon。

默认:on

mem_cache_size

数据库实体的内存高速缓存大小。接受的单位是k和m,最小推荐值为几MB。

默认:128m

ssl

确定Nginx是否应该在proxy_listen_ssl地址上监听HTTPS流量。 如果禁用,Nginx将仅在proxy_listen上绑定自己,并且将忽略所有SSL设置。

默认:on

ssl_cipher_suite

定义Nginx提供的TLS密码。可接受的值包括modern, intermediate, old, 或者 custom。有关每个密码套件的详细说明,请参阅https://wiki.mozilla.org/Security/Server_Side_TLS。

ssl_ciphers

定义由Nginx提供的自定义TLS密码列表。此列表必须符合openssl ciphers定义的模式。如果ssl_cipher_suite不是自定义的,则忽略此值。

默认:无

ssl_cert

如果启用了ssl,则为proxy_listen_ssl地址的SSL证书的绝对路径。 如果未指定且启用了ssl,则Kong将生成默认证书和密钥。

默认:无

ssl_cert_key

如果启用了ssl,则为proxy_listen_ssl地址的SSL密钥的绝对路径。

默认:无

http2

proxy_listen_ssl地址上启用对HTTPS流量的HTTP2支持。

默认:off

client_ssl

确定代理请求时Nginx是否应发送客户端SSL证书。

默认:off

client_ssl_cert

如果启用了client_ssl,则proxy_ssl_certificate指令的客户端SSL证书的绝对路径。 请注意,此值是在节点上静态定义的,目前无法基于每个API进行配置。

默认:无

client_ssl_cert_key

如果启用了client_ssl,则为proxy_ssl_certificate_key地址的客户端SSL密钥的绝对路径。 请注意,此值是在节点上静态定义的,并且当前无法基于每个API进行配置。

默认:无

admin_ssl

确定Nginx是否应该在admin_listen_ssl地址上侦听HTTPS流量。 如果禁用,Nginx将仅在admin_listen上绑定自身,并且将忽略所有SSL设置。

默认:on

admin_ssl_cert

如果启用了admin_ssl,则为admin_listen_ssl地址的SSL证书的绝对路径。 如果未指定且启用了admin_ssl,则Kong将生成默认证书和密钥。

默认:无

admin_ssl_cert_key

如果启用了admin_ssl,则为admin_listen_ssl地址的SSL密钥的绝对路径。

默认:无

admin_http2

admin_listen_ssl地址上启用对HTTPS流量的HTTP2支持。

upstream_keepalive

设置在每个工作进程的缓存中保留的上游服务器的最大空闲keepalive连接数。
超过此数量时,将关闭最近最少使用的连接。
值为0将完全禁用此行为,强制每个上游请求打开新连接。

默认:60

headers

Kong应该在客户端响应中注入的,以逗号分隔的headers列表。
可接受的值是:

  • Server:Kong产生的响应上注入Server:kong / x.y.z (例如Admin API,来自auth插件的拒绝请求等)。
  • ViaVia:kong / x.y.z注入成功代理的请求。
  • X-Kong-Proxy-Latency:Kong在代理上游请求之前处理请求并运行所有插件所花费的时间(以毫秒为单位)
  • X-Kong-Upstream-Latency:上游服务发送响应头所花费的时间(以毫秒为单位)
  • X-Kong-Upstream-Status:上游服务返回的HTTP状态码。如果插件有重写响应的话,这对于客户端区分上游状态特别有用。
  • server_tokens:与指定ServerVia相同。
  • latency_tokens:与指定X-Kong-Proxy-LatencyX-Kong-Upstream-Latency相同。

除此之外,这个值可以设置为off,这可以防止Kong注入任何上述headers。 请注意,这不会阻止插件注入自己的headers。

例子:headers = via, latency_tokens
默认:server_tokens, latency_tokens

trusted_ips

定义已知可以发送正确的X-Forwarded-*headers的可信IP地址块。来自可靠IP的请求,Kong会向上游转发了他们的原本X-Forwarded- *headers。不可信的请求使Kong插入自己的X-Forwarded-*headers。

real_ip_header

定义请求header字段,其值将用于替换客户端地址。 此值设置Nginx配置中同名的ngx_http_realip_module指令。

如果这个值收到proxy_protocol

  • 至少有一个proxy_listen条目必须启用proxy_protocol标志。
  • proxy_protocol参数将附加到Nginx模板的listen指令。

有关此指令的说明,请查看http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header

real_ip_recursive

此值设置Nginx配置中同名的ngx_http_realip_module指令。

有关此指令的说明,请查看http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive

默认:off

client_max_body_size

定义由Kong代理的请求所允许的最大请求主体大小,在Content-Length请求标头中指定。如果请求超过此限制,Kong将回复413(请求实体太大)。将此值设置为0将禁用检查请求正文大小。

默认:0

client_body_buffer_size

定义用于读取请求正文的缓冲区大小。 如果客户端请求正文大于此值,则正文将缓冲到磁盘。 请注意,当主体缓冲到磁盘时,访问或操作请求主体的插件可能无法正常工作,因此建议将此值设置得尽可能高(例如,将其设置为与client_max_body_size一样高,以强制保留请求主体 在缓存中)。请注意,高并发环境将需要大量内存分配来处理许多并发的大型请求主体。

error_default_type

缺少请求Acceptheader且Nginx返回请求错误时要使用的默认MIME类型。可接受的值是text/plaintext/htmlapplication/jsonapplication/xml

默认:text/plain

Datastore section

Kong将把所有数据(例如路由,服务,消费者和插件)存储在Cassandra或PostgreSQL中,并且属于同一群集的所有Kong节点必须将它们自己连接到同一个数据库。

Kong支持以下数据库版本:

  • PostgreSQL:9.5及以上。
  • Cassandra:2.2及以上。

database

确定此节点将使用哪个PostgreSQL或Cassandra作为其数据存储区。 可接受的值是postgrescassandra

默认值:postgres

Postgres settings

NAME DESCRIPTION DEFAULT
pg_port Postgres服务器的主机。 127.0.0.1
pg_host Postgres服务器的端口。 5432
pg_user Postgres用户。 kong
pg_password Postgres用户的密码。
pg_database 要连接的数据库。 kong
pg_ssl 启用与服务器的SSL连接。 off
pg_ssl_verify 如果启用了pg_ssl,则切换服务器证书验证。请参阅lua_ssl_trusted_certificate设置。 off

Cassandra settings

NAME DESCRIPTION DEFAULT
cassandra_contact_points 以逗号分隔的联系人列表指向的Cassandra群集。 127.0.0.1
cassandra_port 节点正在侦听的端口。的所有节点和联系点必须在同一端口上监听 9042
cassandra_keyspace Keyspace可以在您的群集中使用。如果它不存在,将被创建。 kong
cassandra_consistency 读取/写入Cassandra集群时使用的一致性设置 ONE
cassandra_timeout 定义读取和写入的超时(以毫秒为单位) 5000
cassandra_ssl 切换Kong和Cassandra之间的客户端到节点TLS连接。 off
cassandra_ssl_verify 如果启用了cassandra_ssl,则切换服务器证书验证。
请参阅lua_ssl_trusted_certificate以指定证书颁发机构。
off
cassandra_username 使用PasswordAuthenticator方案时的用户名。 kong
cassandra_password 使用PasswordAuthenticator方案时的密码。
cassandra_lb_policy 在Cassandra集群中分发查询时使用的负载平衡策略。
可接受的值是RoundRobinRequestRoundRobin
DCAwareRoundRobinRequestDCAwareRoundRobin
以“Request”为前缀的策略可以在整个同一请求中有效地使用已建立的连接。
当且仅当您使用多数据中心群集时,首选“DCAware”策略。
cassandra_local_datacenter 使用DCAwareRoundRobinRequestDCAwareRoundRobin平衡策略时,
必须指定与此Kong节点本地(最近)的集群的名称。
cassandra_repl_strategy 在第一次迁移时,Kong将使用此设置来创建密钥空间。
可接受的值是SimpleStrategyNetworkTopologyStrategy
SimpleStrategy
cassandra_repl_factor 在第一次迁移时,Kong将在使用SimpleStrategy时使用此复制因子创建keyspace。 1
cassandra_data_centers 在第一次迁移时,Kong将在使用NetworkTopologyStrategy时使用此设置。格式是以逗号分隔的列表,由<dc_name>:<repl_factor>组成。 dc1:2,dc2:3
cassandra_schema_consensus_timeout 定义Cassandra节点之间每个模式共识的等待时间的超时(以毫秒为单位)。此值仅在迁移期间使用。 10000

Datastore cache section

为了避免与数据存储区进行不必要的通信,Kong将实体(例如API,消费者,凭证等)缓存一段可配置的时间。 如果更新了这样的实体,它还会处理失效。 本节允许配置Kong关于此类配置实体的缓存的行为。

db_update_frequency

使用数据存储区检查更新实体的频率(以秒为单位)。 当节点通过Admin API创建,更新或删除实体时,其他节点需要等待下一轮询(由此值配置)以最终清除旧的缓存实体并开始使用新的实体。

默认:5

db_update_propagation

数据存储中的实体传输到另一个数据中心的副本节点所用的时间(以秒为单位)。 在分布式环境(如多数据中心Cassandra集群)中,此值应为Cassandra将行传播到其他数据中心所花费的最大秒数。 设置后,此属性将增加Kong传输实体更改所用的时间。 单数据中心设置或PostgreSQL服务器应该没有这样的延迟,并且该值可以安全地设置为0。

默认:0

db_cache_ttl

此节点缓存时实体从数据存储区的生存时间(以秒为单位)。 数据库未命中(无实体)也根据此设置进行缓存。 如果设置为0(默认值),则此类缓存实体或未命中永不过期。

默认:0(不过期)

db_resurrect_ttl

数据存储区中的陈旧实体在无法刷新时(例如,数据存储区无法访问)的时间(以秒为单位)。 当此TTL到期时,将进行刷新陈旧实体的新尝试。

DNS 解析器部分

默认情况下,DNS解析器将使用标准配置文件/etc/hostsetc/resolv.conf。 如果已设置环境变量LOCALDOMAINRES_OPTIONS,则后一个文件中的设置将被覆盖。

Kong会将主机名解析为SRVA记录(按此顺序,CNAME记录将在此过程中取消引用)。 如果名称被解析为SRV记录,它还将通过从DNS服务器接收的端口字段内容覆盖任何给定的端口号。

DNS选项SEARCHNDOTS(来自/etc/resolv.conf文件)将用于将短名称扩展为完全限定名称。 因此,它将首先尝试SRV类型的整个SEARCH列表,如果失败则会尝试搜索ASEARCH列表等。

ttl的持续时间内,内部DNS解析器将对通过DNS记录中的条目获得的每个请求进行负载均衡。 对于SRV记录,weight权重字段将被接受,但它将仅使用记录中的最低优先级priority字段条目。

dns_resolver

以逗号分隔的名称服务器列表,每个条目都采用ip [:port]格式供Kong使用。 如果未指定,将使用本地resolv.conf文件中的名称服务器。 如果省略,端口默认为53。 接受IPv4和IPv6地址。

默认:无

dns_hostsfile

要使用的hosts文件。 此文件只读一次,其内容在内存中是静态的。 要在修改文件后再次读取文件,必须重新加载Kong。

默认:/etc/hosts

dns_order

解析不同记录类型的顺序。 LAST类型表示上次成功查找的类型(对于指定的名称)。 格式是(不区分大小写)逗号分隔列表。

默认值:LASTSRVACNAME

dns_valid_ttl

默认情况下,使用响应的TTL值缓存DNS记录。 如果此属性收到一个值(以秒为单位),它将覆盖所有记录的TTL。

默认:无

dns_stale_ttl

以秒为单位定义记录在缓存中保留的时间长度超过其TTL。 在后台获取新DNS记录时将使用此值。 过期数据将从记录到期时使用,直到刷新查询完成或dns_stale_ttl秒数已过。

dns_not_found_ttl

空DNS响应和“((3) name error”响应的TTL,以秒为单位。

默认:无

dns_error_ttl

错误响应的TTL,以秒为单位。

默认:1

dns_no_sync

如果启用,则在缓存未命中时,每个请求都将触发自己的dns查询。 禁用时,同一名称/类型的多个请求将同步到单个查询。

默认:off

发展和杂项部分

从lua-nginx-module继承的其他设置允许更多的灵活性和高级用法。 有关更多信息,请参阅lua-nginx-module文档:https://github.com/openresty/lua-nginx-module

lua_ssl_trusted_certificate

PEM格式的Lua cosockets的证书颁发机构文件的绝对路径。当启用pg_ssl_verifycassandra_ssl_verify时,此证书将用于验证Kong的数据库连接。

默认:无

lua_ssl_verify_depth

设置Lua cosockets使用的服务器证书链中的验证深度,由lua_ssl_trusted_certificate设置。 这包括为Kong的数据库连接配置的证书。

默认:1

lua_package_path

设置Lua模块搜索路径(LUA_PATH)。   在开发或使用未存储在默认搜索路径中的自定义插件时很有用。

查看:https://github.com/openresty/lua-nginx-module#lua_ssl_verify_depth

默认:无

lua_package_cpath

设置Lua C模块搜索路径(LUA_CPATH)。

查看:https://github.com/openresty/lua-nginx-module#lua_package_cpath

lua_socket_pool_size

指定与每个远程服务器关联的每个cosocket连接池的大小限制。

请参阅https://github.com/openresty/lua-nginx-module#lua_socket_pool_size

默认值:30

附加配置

origins

原始配置在复杂的网络配置中非常有用,并且在Kong用于服务网格(service mesh)时通常是必需的。

origin是一个以逗号分隔的成对对象列表,该对的每一半用=符号分隔。每对左侧的原点被右侧的原点覆盖。此覆盖发生在访问阶段之后和上游解析之前。它具有导致Kong将流向左侧原点的流量发送到右侧原点的效果。

术语origin(单数)是指特定 scheme/host 或 IP address/port 三元组,如RFC 6454(https://tools.ietf.org/html/rfc6454#section-3.2 )中所述。在kong的origin配置项中,必须是http, https, tcp, or tls其中之一。在每对源中,该方案必须是类似的类型 – 因此http可以与https配对,并且tcp可以与tls配对,但http和https不能与tcp和tls配对。

当左侧原点的加密方案(如tls或https)与右侧来源中的tcp或http等未加密方案配对时,Kong将在与左侧原点匹配的传入连接上终止TLS,然后将未加密的流量路由到指定的右侧源。当通过TLS与Kong节点建立连接时,这很有用,但本地服务(Kong代理流量)不会或不能终止TLS。类似地,如果左侧原点是tcphttp且右侧原点是tlshttps,则Kong将接受未加密的传入流量,然后在将其路由到出站时将该流量包装在TLS中。这种能力是Kong Mesh的重要推动。

与所有Kong配置设置一样,可以在Kong.conf文件中声明origin设置 - 但是建议Kong管理员不要这样做。 相反,应使用环境变量在每个节点上设置origin。因此,kong.conf.default中不存在origins。在Kubernetes部署中,建议不要“手动”配置和维护起源 – 相反,每个Kong节点的起源应由Kubernetes身份模块(KIM)管理。

默认值:无

Examples

如果给定的Kong节点具有以下源的配置:

http://upstream-foo-bar:1234=http://localhost:5678

Kong节点不会尝试解析upstream-foo-bar,而是将该节点路由到localhost:5678。 在Kong的服务网格部署中,这种覆盖是必要的,以使临近upstream-foo-bar应用程序实例的Kong边车将流量路由到该本地实例,而不是试图将流量通过网络路由回到upstream-foo-bar的非本地实例。

在另一个典型的边车部署中,其中Kong节点部署在同一主机,虚拟机或Kubernetes Pod上,作为Kong作为代理的服务的一个实例,起源将配置为:

https://service-b:9876=http://localhost:5432

这种设置将导致该Kong节点仅接受端口9876上的HTTPS连接,终止TLS,然后将现在未加密的流量转发到localhost端口5432。

以下是一个由两对组成的示例,演示正确使用没有空格的分隔符:

https://foo.bar.com:443=http://localhost:80,tls://dog.cat.org:9999=tcp://localhost:8888

此配置将导致Kong仅接受端口443上的HTTPS流量,并且仅接受端口9999上的TLS流量,在两种情况下都终止TLS,然后分别将流量转发到localhost端口80和8888。 假设localhost端口80和8888每个都与一个单独的服务相关联,当Kong充当节点代理时,可能会发生这种配置,这是一个代表多个服务的本地代理(与sidecar代理不同, 其中本地代理仅代表单个本地服务)。

微服务 API 网关 Kong Route 中文文档

原文地址:https://docs.konghq.com/1.0.x/admin-api/#route-object (不能保证所有的翻译都是准确无误的,所有如有翻译的不准确或错误之处,请一定记得查看原文,并欢迎留言指出)。

route 路由

路由实体定义规则以匹配客户端请求。每个Route与一个服务相关联,一个服务可能有多个与之关联的路由。匹配给定路由的每个请求都将代理到其关联的服务。
Routes 和 Services 的组合(以及它们之间的关注点分离)提供了一种强大的路由机制,通过它可以在 Kong 中定义细粒度的入口点,从而导致基础架构的不同上游服务。

{
    "id": "173a6cee-90d1-40a7-89cf-0329eca780a6",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],Service 服务
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {"id":"f5a9c0ca-bdbb-490f-8928-2ca95836239a"}
}

添加 route

创建一个route

POST:/routes

创建与特定服务关联的路由

POST:/services/{service name or id}/routes
参数 描述
service name or id 
required
应与新创建的路由关联的服务的唯一标识符或名称属性。

请求体

参数 描述
name 
optional
Route 名称
protocols 此路由应允许的协议列表。设置为[“https”]时,将通过请求升级到HTTPS来回答HTTP请求。默认为[“http”,“https”]
methods 
semi-optional
与此Route匹配的HTTP方法列表。使用http或https协议时,必须至少设置一个hosts, paths, or methods
hosts 
semi-optional
与此路由匹配的域名列表。使用httphttps协议时,必须至少设置一个hosts, paths, 或者 methods。使用表单编码时,符号是hosts [] = example.com&hosts [] = foo.test。使用JSON,使用Array。
paths 
semi-optional
与此路由匹配的路径列表。使用httphttps协议时,必须至少设置一个必须至少设置一个hosts, paths, 或者methods。使用表单编码时,符号是paths [] = / foo&paths [] = / bar。使用JSON,使用数组。
regex_priority
optional
用于选择哪条路由解析给定请求的数字,当多条路由同时使用正则表达式匹配时。当两条路径匹配路径并具有相同的regex_priority时,将使用较旧的路径(最低的created_at)。请注意,非正则表达式路由的优先级不同(较长的非正则表达式路由在较短的路由之前匹配)。默认为0
strip_path 
optional
通过其中一条path匹配Route时,从上游请求URL中删除匹配的前缀。默认为true
preserve_host 
optional
通过其中一个主机域名匹配Route时,请使用上游请求标头中的请求主机头。如果设置为false,则上游主机头将是服务主机的头。
snis 
semi-optional
使用流路由时与此路由匹配的SNI列表。使用tcptls协议时,必须至少设置一个snissourcesdestinations PUT
sources 
semi-optional
使用流路由时与此路由匹配的传入连接的IP源列表。每个条目都是一个对象,其字段为“ip”(可选地为CIDR范围表示法)和/或“port”。使用tcptls协议时,必须至少设置一个snissourcesdestinations
destinations 
semi-optional
使用流路由时,与此路由匹配的传入连接的IP目标列表。每个条目都是一个对象,其字段为“ip”(可选地为CIDR范围表示法)和/或“port”。使用tcptls协议时,必须至少设置一个snissourcesdestinations
service 此路由所关联的服务。这是Route代理流量的地方,使用表单encode。表示法是service.id = <service_id>。使用JSON,使用“service”:{“id”:“<service_id>”}

响应

HTTP 201 Created
{
    "id": "173a6cee-90d1-40a7-89cf-0329eca780a6",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {"id":"f5a9c0ca-bdbb-490f-8928-2ca95836239a"}
}

路由列表

所有路由列表

GET:/routes

列出与特定服务关联的路由列表

GET:/services/{service name or id}/routes
参数 描述
service name or id 
required
要检索其路由的服务的唯一标识符或name属性。仅列出与指定服务关联的路由。

响应

HTTP 200 OK
{
"data": [{
    "id": "885a0392-ef1b-4de3-aacf-af3f1697ce2c",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {"id":"a3395f66-2af6-4c79-bea2-1b6933764f80"}
}, {
    "id": "4fe14415-73d5-4f00-9fbc-c72a0fccfcb2",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["tcp", "tls"],
    "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}],
    "service": {"id":"ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6"}
}],

    "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

查询路由

查询路由

GET:/routes/{name or id}
参数 描述
service name or id 
required
要检索其路由的服务的唯一标识符或name属性。仅列出与指定服务关联的路由。

查询与特定插件关联的路由

GET:/plugins/{plugin id}/route
参数 描述
plugin id 
required
与要更新的路由关联的插件的唯一标识符。

响应

HTTP 200 OK
{
    "id": "173a6cee-90d1-40a7-89cf-0329eca780a6",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {"id":"f5a9c0ca-bdbb-490f-8928-2ca95836239a"}
}

PUT

更新路由

更新路由

PATCH:/routes/{name or id}
参数 描述
name or id 
required
唯一标识符或要更新的路由的名称。

更新与特定插件关联的路由

PATCH:/plugins/{plugin id}/route
参数 描述
plugin id 
required
与要更新的路由关联的插件的唯一标识符。

请求体

参数 描述
name 
optional
Route 名称
protocols 此路由应允许的协议列表。设置为[“https”]时,将通过请求升级到HTTPS来回答HTTP请求。默认为[“http”,“https”]
methods 
semi-optional
与此Route匹配的HTTP方法列表。使用http或https协议时,必须至少设置一个hosts, paths, or methods
hosts 
semi-optional
与此路由匹配的域名列表。使用httphttps协议时,必须至少设置一个hosts, paths, 或者 methods。使用表单编码时,符号是hosts [] = example.com&hosts [] = foo.test。使用JSON,使用Array。
paths 
semi-optional
与此路由匹配的路径列表。使用httphttps协议时,必须至少设置一个必须至少设置一个hosts, paths, 或者methods。使用表单编码时,符号是paths [] = / foo&paths [] = / bar。使用JSON,使用数组。
regex_priority
optional
用于选择哪条路由解析给定请求的数字,当多条路由同时使用正则表达式匹配时。当两条路径匹配路径并具有相同的regex_priority时,将使用较旧的路径(最低的created_at)。请注意,非正则表达式路由的优先级不同(较长的非正则表达式路由在较短的路由之前匹配)。默认为0
strip_path 
optional
通过其中一条path匹配Route时,从上游请求URL中删除匹配的前缀。默认为true
preserve_host 
optional
通过其中一个主机域名匹配Route时,请使用上游请求标头中的请求主机头。如果设置为false,则上游主机头将是服务主机的头。
snis 
semi-optional
使用流路由时与此路由匹配的SNI列表。使用tcptls协议时,必须至少设置一个snissourcesdestinations
sources 
semi-optional
使用流路由时与此路由匹配的传入连接的IP源列表。每个条目都是一个对象,其字段为“ip”(可选地为CIDR范围表示法)和/或“port”。使用tcptls协议时,必须至少设置一个snissourcesdestinations
destinations 
semi-optional
使用流路由时,与此路由匹配的传入连接的IP目标列表。每个条目都是一个对象,其字段为“ip”(可选地为CIDR范围表示法)和/或“port”。使用tcptls协议时,必须至少设置一个snissourcesdestinations
service 此路由所关联的服务。这是Route代理流量的地方,使用表单encode。表示法是service.id = <service_id>。使用JSON,使用“service”:{“id”:“<service_id>”}

响应

HTTP 200 OK
{
    "id": "173a6cee-90d1-40a7-89cf-0329eca780a6",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {"id":"f5a9c0ca-bdbb-490f-8928-2ca95836239a"}
}
参数 描述
plugin id 
required
与要更新的路由关联的插件的唯一标识符。

更新或创建路由

更新或创建一个路由

PUT:/routes/{name or id}
| 参数 | 描述 |
| ---- | ---- |
| `name or id` <br> ** required ** | 要创建或更新的路由的唯一标识符或名称。 |

创建或更新与特定插件关联的路由

PUT:/plugins/{plugin id}/route
参数 描述
plugin id 
required
与要更新的路由关联的插件的唯一标识符。

请求体

参数 描述
name 
optional
Route 名称
protocols 此路由应允许的协议列表。设置为[“https”]时,将通过请求升级到HTTPS来回答HTTP请求。默认为[“http”,“https”]
methods 
semi-optional
与此Route匹配的HTTP方法列表。使用http或https协议时,必须至少设置一个hosts, paths, or methods
hosts 
semi-optional
与此路由匹配的域名列表。使用httphttps协议时,必须至少设置一个hosts, paths, 或者 methods。使用表单编码时,符号是hosts [] = example.com&hosts [] = foo.test。使用JSON,使用Array。
paths 
semi-optional
与此路由匹配的路径列表。使用httphttps协议时,必须至少设置一个必须至少设置一个hosts, paths, 或者methods。使用表单编码时,符号是paths [] = / foo&paths [] = / bar。使用JSON,使用数组。
regex_priority
optional
用于选择哪条路由解析给定请求的数字,当多条路由同时使用正则表达式匹配时。当两条路径匹配路径并具有相同的regex_priority时,将使用较旧的路径(最低的created_at)。请注意,非正则表达式路由的优先级不同(较长的非正则表达式路由在较短的路由之前匹配)。默认为0
strip_path 
optional
通过其中一条path匹配Route时,从上游请求URL中删除匹配的前缀。默认为true
preserve_host 
optional
通过其中一个主机域名匹配Route时,请使用上游请求标头中的请求主机头。如果设置为false,则上游主机头将是服务主机的头。
snis 
semi-optional
使用流路由时与此路由匹配的SNI列表。使用tcptls协议时,必须至少设置一个snissourcesdestinations
sources 
semi-optional
使用流路由时与此路由匹配的传入连接的IP源列表。每个条目都是一个对象,其字段为“ip”(可选地为CIDR范围表示法)和/或“port”。使用tcptls协议时,必须至少设置一个snissourcesdestinations
destinations 
semi-optional
使用流路由时,与此路由匹配的传入连接的IP目标列表。每个条目都是一个对象,其字段为“ip”(可选地为CIDR范围表示法)和/或“port”。使用tcptls协议时,必须至少设置一个snissourcesdestinations
service 此路由所关联的服务。这是Route代理流量的地方,使用表单encode。表示法是service.id = <service_id>。使用JSON,使用“service”:{“id”:“<service_id>”}

使用请求提中指定的参数插入(或替换)请求资源下的路由。Route将通过nameid属性进行标识。
nameid属性具有UUID的结构时,插入/替换的Route将由其id标识。否则将通过其name识别。
在创建新路由而不指定id(既不在URL中也不在主体中)时,它将自动生成。
请注意,不允许在URL中指定name,在请求正文中指定其他名称。

响应

HTTP 201 Created or HTTP 200 OK

参考 POST 和 PATCH 的响应。

删除路由

删除一个路由

DELETE:/routes/{name or id}
| 参数 | 描述 |
| ---- | ---- |
| `name or id` <br> ** required ** | 要删除的路由的唯一标识符或名称。 |

响应

HTTP 204 No Content

微服务 API 网关 Kong Service 中文文档

原文地址:https://docs.konghq.com/1.0.x/admin-api/#service-object (不能保证所有的翻译都是准确无误的,所有如有翻译的不准确或错误之处,请一定记得查看原文,并欢迎留言指出)。

Service 服务

顾名思义,服务实体是每个上游服务的抽象。举个例子,services 可以是一个数据转换微服务,一个计费api等等。

Service 的主要属性是其URL(Kong应该将流量代理到的地方),可以设置为单个字符串,也可以单独指定其protocol, host, port  path

Service 与 router 相关联(一个 Service 可以有许多与之关联的 router)。router 是Kong的入口点,并定义匹配客户端请求的规则。一旦 router 匹配,Kong就会将请求代理到其关联的服务。有关Kong代理流量的详细说明,请参阅代理参考

{
    "id": "0c61e164-6171-4837-8836-8f5298726d53",
    "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
}

Permalink

添加一个 Service

创建一个service

POST:/services

请求体

参数 描述
name
optional
Service 名称
retries
optional
代理失败时要执行的重试次数。默认为 5
protocol 用于与上游通信的协议。它可以是httphttps之一。默认为“http”。
host 上游服务的 host
port 上游服务端口。默认为80。
path
optional
在上游服务器的请求中使用的路径。
connect_timeout
optional
建立与上游服务器的连接的超时时间(以毫秒为单位)。默认为 60000
write_timeout
optional
用于向上游服务器发送请求的两次连续写操作之间的超时(以毫秒为单位)。默认为60000
read_timeout
optional
用于向上游服务器发送请求的两次连续读取操作之间的超时(以毫秒为单位)。默认为60000
url
shorthand-attribute
用于同时设置protocolhostport  path 的速记属性。此属性是只写的(Admin API永远不会“返回”该URL)。

响应

HTTP 201 Created
{
    "id": "0c61e164-6171-4837-8836-8f5298726d53",
    "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
}

Services 列表

查询所有的 Services

GET:/services

响应

HTTP 200 OK
{
"data": [{
    "id": "f00c6da4-3679-4b44-b9fb-36a19bd3ae83",
    "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
}, {
    "id": "bdab0e47-4e37-4f0b-8fd0-87d95cc4addc",
    "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
}],
    "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

查询 Services

查询

GET:/services/{name or id}
参数 描述
name or id
required
要检索的服务的唯一标识符或名称。

查询与特定路由关联的服务

GET:/routes/{route name or id}/service
参数 描述
route name or id
required
与要检索的服务关联的唯一标识符或Route的名称。

查询特定插件关联的服务

GET:/plugins/{plugin id}/service
参数 描述
plugin id
required
与要检索的服务关联的插件的唯一标识符。

响应

HTTP 200 OK
{
    "id": "0c61e164-6171-4837-8836-8f5298726d53",
    "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
}

更新 service

更新

PATCH:/services/{name or id}
参数 描述
name or id
required
要更新的服务的唯一标识符或名称。

更新与特定路由关联的服务

PATCH:/routes/{route name or id}/service
参数 描述
route name or id
required
与要更新的服务关联的唯一标识符或Route的名称。

更新与特定插件关联的服务

PATCH:/plugins/{plugin id}/service
参数 描述
plugin id
required
与要更新的服务关联的插件的唯一标识符。

请求体

参数 描述
name
optional
Service 名称
retries
optional
代理失败时要执行的重试次数。默认为 5
protocol 用于与上游通信的协议。它可以是httphttps之一。默认为“http”。
host 上游服务的 host
port 上游服务端口。默认为80。
path
optional
在上游服务器的请求中使用的路径。
connect_timeout
optional
建立与上游服务器的连接的超时时间(以毫秒为单位)。默认为 60000
write_timeout
optional
用于向上游服务器发送请求的两次连续写操作之间的超时(以毫秒为单位)。默认为60000
read_timeout
optional
用于向上游服务器发送请求的两次连续读取操作之间的超时(以毫秒为单位)。默认为60000
url
shorthand-attribute
用于同时设置protocolhostport  path 的速记属性。此属性是只写的(Admin API永远不会“返回”该URL)。

响应

HTTP 200 OK
{
    "id": "0c61e164-6171-4837-8836-8f5298726d53",
    "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
}

更新或创建服务

创建或更新

PUT:/services/{name or id}
参数 描述
route name or id
required
与要更新或创建的服务关联的唯一标识符或Route的名称。

创建或更新与特定路由关联的服务

PUT:/routes/{route name or id}/service
参数 描述
route name or id
required
与要更新或创建的服务关联的唯一标识符或Route的名称。

创建或更新与特定插件关联的服务

PUT:/plugins/{plugin id}/service
参数 描述
plugin id
required
与要更新或创建的服务关联的插件的唯一标识符。

请求体

参数 描述
name
optional
Service 名称
retries
optional
代理失败时要执行的重试次数。默认为 5
protocol 用于与上游通信的协议。它可以是httphttps之一。默认为“http”。
host 上游服务的 host
port 上游服务端口。默认为80。
path
optional
在上游服务器的请求中使用的路径。
connect_timeout
optional
建立与上游服务器的连接的超时时间(以毫秒为单位)。默认为 60000
write_timeout
optional
用于向上游服务器发送请求的两次连续写操作之间的超时(以毫秒为单位)。默认为60000
read_timeout
optional
用于向上游服务器发送请求的两次连续读取操作之间的超时(以毫秒为单位)。默认为60000
url
shorthand-attribute
用于同时设置protocolhostport  path 的速记属性。此属性是只写的(Admin API永远不会“返回”该URL)。

使用body中指定的参数在请求的资源下插入(或替换)服务。Service 将通过nameid属性标识。

当name或id属性具有UUID的结构时,插入/替换 的服务将由其id标识。否则将通过其名称识别。

在创建新服务而不指定id(既不在URL中也不在body中)时,它将自动生成。

请注意,请注意,URL中的name和请求体中的name名称必须一样。

响应

HTTP 201 Created or HTTP 200 OK

请参阅POST和PATCH响应

删除 service

删除

DELETE:/services/{name or id}
参数 描述
name or id
required
要删除的服务的唯一标识符或名称。

删除与特定路由关联的服务

DELETE:/routes/{route name or id}/service
参数 描述
route name or id
required
与要删除的服务关联的唯一标识符或Route的名称。

响应

HTTP 204 No Content

微服务 API 网关 Kong 1.0 GA 版本正式发布(更新详情)

原文地址:https://github.com/Kong/kong/blob/master/CHANGELOG.md#100 ,(如有翻译的不准确或错误之处,欢迎留言指出)

这个是一个非常重要的版本,引入了对Service Mesh和Stream Routing支持的新功能,以及新的迁移框架,它还包括插件开发工具包(Plugin Development Kit)的1.0.0版本,它包含大量其他功能和修复,如下所示。此外,Kong 1.0中包含的所有插件都更新为使用PDK 1.0版。

像往常一样,主要版本升级需要数据库迁移和Nginx配置文件的更改(如果您自定义了默认模板),在计划升级Kong集群之前,请花几分钟时间阅读1.0升级指南,了解有关更改和迁移的更多详细信息。

作为主要版本,在Kong 0.x中标记为已弃用的所有实体和概念现已在Kong 1.0中删除,已弃用的功能将保留在Kong 0.15中,Kong 0.x系列的最终版本,同时发布到Kong 1.0。

重大更新

Kong 1.0包括0.15的所有重大更改,以及删除已弃用的概念:

核心:

  • API实体和相关概念( 例如/apis )将被删除(自0.13版本,2018年三月起不推荐使用)。请改用路由和服务。
  • 删除旧的DAO实现以及旧的schema 验证库(apis是使用它的最后一个实体),在自定义插件中使用新的 schema format。
  • 为了简化插件的转换,1.0中的 plugin loader 包含 best-effort 的模式自动翻译器,对于许多插件来说应该足够了。
  • 在0.14.x版本的Upstreams中,Targets 和 Plugins 仍然使用旧的 DAO 和Admin API实现。在0.15.0和1.0.0上,所有核心实体都使用新的kong.db DAO,并且他们的端点已升级到新的Admin API(有关详细信息,请参阅下文)。#3689, #3739, #3778
  • 新的迁移框架( migration framework),#3802
  • luaossl 版本跳提升到20181207#4067
  •  kong.resty.getssl 模块 #3681
  • 时间戳现在允许毫秒精度#3660
  • OpenSSL 已经提升到至 1.1.1a #4005
  • luasec 提升到 to 0.7
  • PDK函数 kong.request.get_body 现在将返回nilerrmime,当body是有效的JSON但是既不是对象也不是数组#4063

New Admin API引入的更改摘要:

  • 分页已包含在所有“multi-record”端点中,分页控制字段与0.14.x中的不同。
  • 现在通过URL路径更改(/consumers/x/plugins)而不是querystring字段(/plugins?consumer_id = x)进行过滤。
  • Array values不能与逗号分隔的字符串相交。它们必须是JSON请求上的“正确”JSON值,或者在form-url-encoded或multipart请求上使用新语法。
  • 错误消息已经从头开始重新设计,更加一致,准确和提供信息。
  • PUT方法已经使用幂等行为重新实现,并且已添加到一些没有它的实体中。

有关New Admin API的更多详细信息请访问官方文档https://docs.konghq.com/

配置

  • 删除了custom_plugins指令(自2018年7月的0.14.0起不推荐使用)。请改用plugins

插件

  • 删除了galileo插件(自0.13.0起不推荐使用)
  • 在0.14.0中引入插件开发工具包(PDK)之前,插件作者偶尔使用的一些内部模块现已被删除:
    • kong.tools.ip 模块已被删除。请改用PDK中的kong.ip
    • kong.tools.public 模块已被删除。请使用PDK中的各种等效功能。
    • kong.tools.responses 模块已被删除。请改用PDK中的 kong.response.exit。您可能还想使用kong.log.err来记录内部服务器错误。
    • kong.api.crud_helpers模块已删除(自0.13.0中引入新DAO以来已弃用)。如果需要自定义自动生成的端点,请使用kong.api.endpoints
  • 在插件模式中,no_routeno_serviceno_consumer注释被制作为相应字段的#decection#3739;在0.15中,它们在schema.lua table 中作为ad-hoc字段提供,作为旧的no_consumer选项。
  • 所有自带的插件模式和自定义实体都已更新为新的kong.db,并且他们的API已更新为New Admin API,因此得到了改进,但是仍有不同的行为,如上一节所述#3766, #3774, #3778, #3839
  • 所有插件迁移都已转换为新的迁移框架。自定义插件需要使用0.15以上的新迁移框架。

附加

Service Mesh 和 Stream Routes

  • 这些新功能需要修补版本的OpenResty,但Kong仍然可以在非修补的OpenResty for HTTP(S)API网关方案中正常工作
  • 通过stream_listen配置选项支持TCP和TLSStream Routes #4009
  • 新的origins配置属性允许覆盖来自kong的主机 #3679
  • Kong实例现在可以创建共享内部Certificate Authority,,用于Service Mesh SSL流量 #3906, #3861,
  • transparent 监听允许使用 iptables 设置Service Mesh [#3884]
  • 插件的run_on字段用于控制它们在Service Mesh环境中的行为方式 #3930, #4066
  • 这里新加一个叫做preread的新阶段。这是流量路由完成的地方。

核心

  • 路由现在有一个name字段 [#3764]
  • 在新的DAO和Admin API中实现了TTL支持。特别是,PostgreSQL获得了一种新的更高效的TTL实现 #3603, #3638
  • 通过减少数据库访问量来提高路由器重建的性能 #3782
  • Schema 改进:
    • Subschemas 子模式 #3630
    • 新的实体验证器:distinctneis_regexcontainsgt
    • 实体检查仅在必要时运行 #3848
    • 条件验证器可以根据需要标记字段 6d1707c4s
    • 记录字段的部分更新 05adc40f
    • 向schema添加具有默认值的新字段不再需要迁移 #3756
  • PDK改进:
    • 新的kong.node模块 #3826
    • 新的 kong.response.get_path_with_query 模块 #3842
    • PDK getters and setters for Service, Route, Consumer & Credential #3916
    • kong.response.get_source返回error错误 #4006
    • kong.response.exit可以在header_filter阶段使用,但只能没有body #4039
  • Cluster-wide mutex 集群范围的互斥锁 #3685
  • 向Admin API添加多部分支持: #3776
  • 改进了插件迭代器的速度 #3794
  • 在活动运行状况检查中添加对HTTPS的支持 #3815

配置

  • 新字段 dns_valid_ttl #3730
  • 新字段 pg_timeout #3808
  • 设置为0时,可以禁用 upstream_keepalive (感谢 @pryorda! ) #3716
  • 新的transparent后缀也适用于proxy_listen指令

插件

  • http-log插件现在接受缓冲日志记录 #3604
  • 大多数插件逻辑都是用PDK重写的,而不是使用内部kong函数或ngx调用 #3845
  • 新的run_on选项用于控制插件在Service Mesh环境中的执行位置 #3930, #4066
  • 通常,插件对故障/意外输入更具弹性 #4006, #3947, #4038
  • AWS现在支持使用is_proxy_integration进行Lambda代理集成#3427。感谢@aloisbarreras 的补丁。

修复项

核心

插件

  • 记录字段在插件架构中不可为空 #3778
  • 修复了一些问题,其中一些插件可能包含Lapis的默认HTML响应 #4077
  • cors:
    •  Access-Control-Allow-Credentials 启用的时候 set ‘Vary: Origin’(感谢@marckhouzam #3675
    • 对于预检请求,返回HTTP 200而不是204 (感谢 @aslafy-z) #4029)
    • 现在可以安全地验证 flat strings 。0eaa9acd
  • acl:
    • 编辑ACL时会重置缓存 #3839
    • 缓存正确用于 intermediary #4040
  • correlation-id:当access阶段被跳过的时候会报错 #3924
  • aws-lambda: HTTP / 2不允许去掉header #f2ee98e2
  • ratelimiting & response-ratelimiting:修复了不必要的redis调用问题:redis:select 可以关闭连接。(感谢 @fffonion #3973

微服务 API 网关 Kong JWT插件中文文档

原文链接: https://docs.konghq.com/hub/kong-inc/jwt/
(如有翻译的不准确或错误之处,欢迎留言指出)

验证包含HS256或RS256签名JSON Web令牌的请求(如RFC 7519中所述)。每个消费者都将拥有JWT凭证(公钥和密钥),这些凭证必须用于签署其JWT。然后可以通过令牌传递如下:

  • 查询字符串参数
  • 一个cookie
  • 或者带有 Authorization 的头

如果验证了令牌的签名,Kong会将请求代理到您的上游服务,否则将丢弃该请求。Kong还可以对RFC 7519(exp和nbf)的一些注册声明进行验证。

相关术语

  • plugin:在请求被代理到上游API之前或之后,在Kong内部执行操作的插件
  • Service:表示外部上游API或微服务的Kong实体。
  • Route:Kong实体表示将下游请求映射到上游服务的方法
  • upstream service:这是指位于Kong后面的您自己的API /服务,转发客户端请求
  • API:上游服务的实例。在CE 0.13.0 and EE 0.32版本后被弃用,替换为service

配置

在service上启用插件

通过发出以下请求在service上配置此插件:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=jwt"
  • service:此插件将要代理的service的id或者name

在路由上启用插件

通过以下请求在router上配置:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=jwt"
  • rouer_id:将要启动插件的路由id

在API上启用插件

如果您正在使用老版本的 Kong(在CE 0.13.0 and EE 0.32版本后被弃用,替换为service) 。您可以通过发出以下请求在此类API之上配置此插件:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=jwt"
  • api:此插件配置将定位的API的ID或名称。

全局插件

可以使用http://kong:8001/plugins/配置所有插件,一个插件跟任何service ,router, api 或者 Consumer 没有强关联,都可以考虑把它做成全局插件,将在每个请求上运行,有关更多信息,请阅读插件参考插件优先级相关文档。

参数

以下是可在此插件配置中使用的所有参数的列表:

参数名称 默认值 描述
name 要使用的插件的名称,在本例中为jwt
service_id 此插件将定位的服务的ID。
route_id 此插件将定位的路由的ID。
enabled true 是否将应用此插件
api_id 此插件配置将定位的API的ID或名称。(在CE 0.13.0 and EE 0.32版本后被弃用,替换为service)
config.uri_param_names(可选) jwt Kong用来查询JWT字符串的uri参数列表。
config.cookie_names(可选) Kong用来查询JWT字符串的ucookies参数列表。
config.claims_to_verify(可选) 需要被验证的声明(也就是payload),支持的值为 exp, nbf
config.key_claim_name(可选) iss 需要被验证的key标示的名称,从0.13.1开始插件将尝试按此顺序从JWT有效负载和标题中读取此声明。
config.secret_is_base64(可选) false 如果为true,则插件假定凭证的秘密为base64编码。您需要为您的消费者创建base64编码的秘密,并使用原始密码签署您的JWT。
config.anonymous(可选) 如果身份验证失败,则用作“匿名”使用者的可选字符串(使用者uuid)值。如果为空(默认),请求将失败,并且身份验证失败4xx。请注意,此值必须引用Kong内部的Consumer id属性,而不是其custom_id。
config.run_on_preflight(可选) true 指示插件是否应在OPTIONS预检请求上运行(并尝试进行身份验证),如果设置为false,则始终允许OPTIONS请求。 (此参数仅适用于版本0.11.1及更高版本)
config.maximum_expiration(可选) 0 JWT的生命周期限制为将来的maximum_expiration秒的整数。任何具有更长生命周期的JWT都将被拒绝(HTTP 403)。如果指定了这个值,则还必须在claim_to_verify属性中指定exp。默认值0表示无限期。配置此值时应考虑潜在的时钟偏差。

文档

为了使用该插件,首先需要创建一个Consumer然后关联一个或多个JWT凭证(保存用于验证令牌的公钥和私钥)。 消费者代表了开发人员使用最终服务。

创建一个Consumer

您需要将credential与现有的Consumer对象相关联。要创建使用者,您可以执行以下请求:

$ curl -X POST http://kong:8001/consumers \
    --data "username=<USERNAME>" \
    --data "custom_id=<CUSTOM_ID>"
HTTP/1.1 201 Created
参数 默认值 描述
username (半可选) Consumer的用户名,custom_id和username必须至少有一个
custom_id (半可选) 用于将Consumer映射到外部数据库的自定义标识符。custom_id和username必须至少有一个

一个Consumer可以拥有许多JWT凭证。

创建一个 JWT credential

您可以通过发出以下HTTP请求来配置新的HS256 JWT凭证:

$ curl -X POST http://kong:8001/consumers/{consumer}/jwt -H "Content-Type: application/x-www-form-urlencoded"
HTTP/1.1 201 Created

{
    "consumer_id": "7bce93e1-0a90-489c-c887-d385545f8f4b",
    "created_at": 1442426001000,
    "id": "bcbfb45d-e391-42bf-c2ed-94e32946753a",
    "key": "a36c3049b36249a3c9f8891cb127243c",
    "secret": "e71829c351aa4242c2719cbfbe671c09"
}
  • consumer: 通过 id 或者 username 把 credential 关联到相对应credential
参数 默认值 描述
key(可选) 标识凭证的唯一字符串。如果不传的话将自动生成一个.
algorithm(可选) HS256 用于验证令牌签名的算法.可选值为HS256, HS384, HS512, RS256, ES256.
rsa_public_key(可选) 如果参数 algorithm  RS256 或者 ES256 ,则用于验证令牌签名的公钥(采用PEM格式)。
secret(可选) 如果参数 algorithm  RS256 或者 ES256 ,用于为此凭证签署JWT的秘钥.如果不传的话将自动生成一个.

删除一个 JWT credential

您可以通过发出以下HTTP请求来删除Consumer的JWT:

$ curl -X DELETE http://kong:8001/consumers/{consumer}/jwt/{id}
HTTP/1.1 204 No Content
  • consumer : 通过 id 或者 username 把 credential 关联到相对应credential
  • id: JWT credential 的id

JWT credential 列表

您可以通过发出以下HTTP请求列出Consumer的JWT凭证:

$ curl -X GET http://kong:8001/consumers/{consumer}/jwt
HTTP/1.1 200 OK
  • consumer: 通过 id 或者 username 把 credential 关联到相对应credential
{
    "data": [
        {
            "rsa_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgK .... -----END PUBLIC KEY-----",
            "consumer_id": "39f52333-9741-48a7-9450-495960d91684",
            "id": "3239880d-1de5-4dbc-bccf-78f7a4280f33",
            "created_at": 1491430568000,
            "key": "c5a55906cc244f483226e02bcff2b5e",
            "algorithm": "RS256",
            "secret": "b0970f7fc9564e65xklfn48930b5d08b1"
        }
    ],
    "total": 1
}

创建一个带秘钥的JWT(HS256)

既然您的消费者拥有凭证,并且假设我们想要使用HS256进行签名,那么JWT应按照以下方式制作(RFC 7519):

首先,它的header必须是

{
    "typ": "JWT",
    "alg": "HS256"
}

然后,claims参数中必须包含秘钥的key,在config.key_claim_name配置中.该声明默认为iss(发行者字段),将其值设置为我们先前创建的凭证key,claims可能包含其他值。自Kong 0.13.1起,将会在 JWT 的payload和header中都会查找该字段.

{
    "iss": "a36c3049b36249a3c9f8891cb127243c"
}

可以在https://jwt.io 中调试 JWT ,header (HS256), claims (iss, etc),秘钥字段绑定key(e71829c351aa4242c2719cbfbe671c09),你将会得到这样的一个字符串

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4

发起一个带有JWT的请求

现在,可以把JWT以添加在HEADER中的形式来发起一个请求:

$ curl http://kong:8000/{route path} \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4'

如果在配置文件中配置了config.uri_param_names字段,也可以把JWT以url参数的形式传入: 声明必须包含秘密的密钥字段(这不是用于生成令牌的私钥,而只是该配置声明中的标识符)(来自config.key_claim_name)。

curl http://kong:8000/{route path}?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4

如果在配置文件中配置了config.cookie_names,也可以cookies的形式传入:

curl --cookie jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4 http://kong:8000/{route path}

这个请求将会被kong检查,取决于验证字段是否有效

请求 是否被代理到上游服务 响应状态码
没有携带JWT串 no 401
缺失了 iss claim no 401
无效签名 no 403
有效签名 yes 代理上游的请求返回值
有效签名,但是没有 iss claim no 403

提示:当JWT有效并代理上游服务时,除了添加标识Consumer的标头之外,不会对请求进行任何修改。 JWT将会被转发给上游服务,该服务可以检验此jwt的合法性。 然后上游服务的作用是base64解码JWT然后使用。

(可选)验证claims

RFC 7519中所定义,Kong还可以对已注册的claims执行验证。要对声明claims验证,请将其添加到config.claims_to_verify属性:

可以给已经存在的jwt插件补充如下:

# 增加了对 nbf 和 exp claims的验证:
curl -X PATCH http://kong:8001/plugins/{jwt plugin id} \
    --data "config.claims_to_verify=exp,nbf"

支持的claims

claim 名称 校验
exp JWT 是否过期
nbf 校验是否过期

(可选) Base64 encoded 秘钥

如果你的秘密包含二进制数据,你可以将它们存储为Kong中的base64编码。

可以给已经存在的router补充如下:

$ curl -X PATCH http://kong:8001/routes/{route id}/plugins/{jwt plugin id} \
    --data "config.secret_is_base64=true"

或者已经存在的api:

$ curl -X PATCH http://kong:8001/apis/{api}/plugins/{jwt plugin id} \
    --data "config.secret_is_base64=true"

然后base64 encode consumers的 secrets:

# secret is: "blob data"
curl -X POST http://kong:8001/consumers/{consumer}/jwt \
  --data "secret=YmxvYiBkYXRh"

使用JWT 的 public/private keys (RS256 or ES256)

如果你想使用RS256 / ES256 来验证JWT,那么创建一个JWT的credential,选择RS256 或者 ES256 作为 algorithm,然后在rsa_public_key直接上传public key(包含 ES256 签名过的token)

$ curl -X POST http://kong:8001/consumers/{consumer}/jwt \
      -F "rsa_public_key=@/path/to/public_key.pem" \
HTTP/1.1 201 Created

{
    "consumer_id": "7bce93e1-0a90-489c-c887-d385545f8f4b",
    "created_at": 1442426001000,
    "id": "bcbfb45d-e391-42bf-c2ed-94e32946753a",
    "key": "a36c3049b36249a3c9f8891cb127243c",
    "rsa_public_key": "-----BEGIN PUBLIC KEY----- ..."
}

创建签名的时候,header 会是这样:

{
    "typ": "JWT",
    "alg": "RS256"
}

然后,claims 必须包含秘密的key字段(这不是用于生成令牌的private key,而只是该配置的claim)(来自config.key_claim_name)。 该claim 默认为iss(发行者字段),将其值设置为我们先前创建的credential的 key.claims可能包含其他值.自Kong 0.13.1起,将会在 JWT 的payload和header中都会查找该字段.

{
    "iss": "a36c3049b36249a3c9f8891cb127243c"
}

接着,然后使用您的私钥创建签名。 使用https://jwt.io 上的JWT调试器,设置正确的header(RS256),claims(iss等)和相关的 public key。 然后将结果值附加到Authorization header中,例如:

$ curl http://kong:8000/{route path} \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIxM2Q1ODE0NTcyZTc0YTIyYjFhOWEwMDJmMmQxN2MzNyJ9.uNPTnDZXVShFYUSiii78Q-IAfhnc2ExjarZr_WVhGrHHBLweOBJxGJlAKZQEKE4rVd7D6hCtWSkvAAOu7BU34OnlxtQqB8ArGX58xhpIqHtFUkj882JQ9QD6_v2S2Ad-EmEx5402ge71VWEJ0-jyH2WvfxZ_pD90n5AG5rAbYNAIlm2Ew78q4w4GVSivpletUhcv31-U3GROsa7dl8rYMqx6gyo9oIIDcGoMh3bu8su5kQc5SQBFp1CcA5H8sHGfYs-Et5rCU2A6yKbyXtpHrd1Y9oMrZpEfQdgpLae0AfWRf6JutA9SPhst9-5rn4o3cdUmto_TBGqHsFmVyob8VQ'

生成一个 public/private keys

要创建一对全新的public/private keys,可以运行以下命令:

$ openssl genrsa -out private.pem 2048

这个私钥必须保密。要生成与私钥对应的公钥,执行

$ openssl rsa -in private.pem -outform PEM -pubout -out public.pem

如果运行上述命令,则公钥将写入public.pem,而私钥将写入private.pem。

在JWT插件中使用Auth0

Auth0是一种流行的授权解决方案,并且在很大程度上依赖于JWT。 Auth0依赖于RS256,不进行base64编码,并公开托管用于签署令牌的公钥证书。 出于指南的目的,帐户名称被称为“COMPANYNAME”。

要开始,请创建service,使用该服service的router或创建API。
注意:Auth0不使用base64编码的秘密。

创建一个service:

$ curl -i -f -X POST http://localhost:8001/services \
    --data "name=example-service" \
    --data "=http://httpbin.org"

然后创建一个router

$ curl -i -X POST http://localhost:8001/apis \
    --data "name={api}" \
    --data "hosts=example.com" \
    --data "upstream_url=http://httpbin.org"

添加JWT插件 添加插件到你的router

$ curl -X POST http://localhost:8001/route/{route id}/plugins \
    --data "name=jwt"

添加插件到你的api

$ curl -X POST http://localhost:8001/apis/{api}/plugins \
    --data "name=jwt"

下载你的Auth0帐户的X509证书:

$ curl -o {COMPANYNAME}.pem https://{COMPANYNAME}.auth0.com/pem

从X509证书中提取公钥:`

$ openssl x509 -pubkey -noout -in {COMPANYNAME}.pem > pubkey.pem

使用 Auth0 public key 创建一个Consumer:

curl -i -X POST http://kong:8001/consumers \
    --data "username=<USERNAME>" \
    --data "custom_id=<CUSTOM_ID>"

curl -i -X POST http://localhost:8001/consumers/{consumer}/jwt \
    -F "algorithm=RS256" \
    -F "rsa_public_key=@./pubkey.pem" \
    -F "key=https://{COMPAYNAME}.auth0.com/" # the `iss` field

默认情况下,JWT插件会针对令牌中的iss字段验证key_claim_name。Auth0颁发的密钥将其iss字段设置为http://{COMPANYNAME}.auth0.com/.在创建Consumer时,可以使用jwt.io验证key参数的iss字段。

通过发送请求,只有Auth0签名的令牌才能正常工作:

$ curl -i http://localhost:8000 \
    -H "Host:example.com" \
    -H "Authorization:Bearer "

成功!

上游 Headers

当JWT有效时,Consumer已经过身份验证,插件会在将请求代理到上游服务之前将一些头附加到请求中,以便您可以在代码中识别Consumer:

  • X-Consumer-ID, Consumer 在 Kong 的 ID
  • X-Consumer-Custom-ID, Consumer的custom_id (如果存在)
  • X-Consumer-Username, Consumer的username (如果存在)
  • X-Anonymous-Consumer,身份验证失败时将设置为true,并设置“匿名”使用者。

您可以使用此信息来实现其他逻辑。 您可以使用X-Consumer-ID值来查询Kong Admin API并检索有关Consumer的更多信息。

通过JWT分页

提示:此功能在Kong 0.11.2中引入。

您可以使用以下请求为所有使用者分配JWT:

$ curl -X GET http://kong:8001/jwts

{
    "total": 3,
    "data": [
        {
            "created_at": 1509593911000,
            "id": "381879e5-04a1-4c8a-9517-f85fbf90c3bc",
            "algorithm": "HS256",
            "key": "UHVwIly5ZxZH7g52E0HRlFkFC09v9yI0",
            "secret": "KMWyDsTTcZgqqyOGgRWTDgZtIyWeEtJh",
            "consumer_id": "3c2c8fc1-7245-4fbb-b48b-e5947e1ce941"
        },
        {
            "created_at": 1511389527000,
            "id": "0dfc969b-02be-42ae-9d98-e04ed1c05850",
            "algorithm": "ES256",
            "key": "vcc1NlsPfK3N6uU03YdNrDZhzmFF4S19",
            "secret": "b65Rs6wvnWPYaCEypNU7FnMOZ4lfMGM7",
            "consumer_id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
        },
        {
            "created_at": 1509593912000,
            "id": "d10c6f3b-71f1-424e-b1db-366abb783460",
            "algorithm": "HS256",
            "key": "SqSNfg9ARmPnpycyJSMAc2uR6nxdmc9S",
            "secret": "CCh6ZIcwDSOIWacqkkWoJ0FWdZ5eTqrx",
            "consumer_id": "3c2c8fc1-7245-4fbb-b48b-e5947e1ce941"
        }
    ]
}

您可以使用以下查询参数过滤列表:

属性 描述
id(可选) 基于JWT credential ID字段的列表上的过滤器。
key(可选) 基于JWT credential key 字段的列表上的过滤器。
consumer_id(可选) 基于JWT credential consumer_id字段的列表上的过滤器。
size(可选) 要返回的对象数量的限制(默认100)
offset(可选) 用于分页的游标。offset是一个对象标识符,用于定义列表中的位置。

检索与JWT关联的使用者

提示:此功能在Kong 0.11.2中引入。

可以使用以下请求检索与JWT关联的 Consumer 

$ curl -X GET http://kong:8001/jwts/{key or id}/consumer

{
   "created_at":1507936639000,
   "username":"foo",
   "id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}

`key` or id: JWT的idkey属性,用于获取关联的Consumer。

Docker Kong 中文文档

Docker Kong 中文文档

原文链接: https://docs.docker-cn.com/samples/kong/
(如有翻译的不准确或错误之处,欢迎留言指出)

Kong

一个运行在Nginx上的开源微服务&API管理工具。
github项目地址:https://github.com/Mashape/kong

参考提示:
此内容从Docker官方文档导入,它是由原始上传者提供。你可以点击此页面查看Kong的Docker Store页面https://store.docker.com/images/kong.

支持的标签和相应的Dockerfile链接

有关上述每个受支持标记的已发布工件的详细信息(image metadata, transfer size, etc等),请点击the docker-library/repo-info GitHub repo 中的 the repos/kong directory 

有关这个镜像和它的历史等更多信息,请点击the relevant manifest file (library/kong) 查看。镜像更新地址为pull requests to the docker-library/official-images GitHub repo

Kong 是什么

Kong旨在保护,管理和扩展微服务和API。如果您正在开发构建一个web服务,手机服务,或者物联网服务,你可能需要在软件上实现通用功能,Kong可以充当一个网关的角色通过提供日志,认证或者其他功能的插件来给给HTTP提供任何资源。

由NGINX和Cassandra提供支持,专注于高性能和可靠性,Kong为数以万计的api服务提供支持。

Kong的文档点击getkong.org/docs查看。

Kong 镜像

如何使用这个镜像

首先,首先,Kong需要在启动之前运行Cassandra 2.2.x或PostgreSQL 9.4 / 9.5集群。 您可以使用官方的Cassandra / PostgreSQL容器,也可以使用自己的容器

1、将Kong链接到Cassandra或PostgreSQL容器

您可以自由决定使用Cassandra或PostgreSQL,Kong对于这两者都支持。

Cassandra

通过执行以下命令启动Cassandra容器:

$ docker run -d --name kong-database \
                -p 9042:9042 \
                cassandra:2.2

Postgres

通过执行以下命令启动PostgreSQL容器:

docker run -d --name kong-database \
                -p 5432:5432 \
                -e "POSTGRES_USER=kong" \
                -e "POSTGRES_DB=kong" \
                postgres:9.4

启动Kong

当数据库已经正常启动,我们可以启动一个Kong容器并将其链接到数据库容器,并使用cassandra或postgres配置KONG_DATABASE环境变量,具体取决于您决定使用的数据库。

$ docker run -d --name kong \
    --link kong-database:kong-database \
    -e "KONG_DATABASE=cassandra" \
    -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \
    -e "KONG_PG_HOST=kong-database" \
    -p 8000:8000 \
    -p 8443:8443 \
    -p 8001:8001 \
    -p 7946:7946 \
    -p 7946:7946/udp \
    kong

如果一切顺利的话,如果您使用默认端口创建容器,Kong已经已经监听了 8000端口(proxy) ,8443端口(proxy SSL),8001端口(admin api)。端口7946(cluster)由Kong的其他节点使用。

您可以阅读更多文档来学习Kong getkong.org/docs

2、使用Kong自定义配置(以及自定义Cassandra / PostgreSQL集群)

您可以使用环境变量覆盖Kong配置文件的任何属性,只需要在任何Kong的配置文件属性前加上KONG_属性。举个例子:

$ docker run -d --name kong \
    -e "KONG_LOG_LEVEL=info" \
    -e "KONG_CUSTOM_PLUGINS=helloworld" \
    -e "KONG_PG_HOST=1.1.1.1" \
    -p 8000:8000 \
    -p 8443:8443 \
    -p 8001:8001 \
    -p 7946:7946 \
    -p 7946:7946/udp \
    kong

在一个正在运行的容器中重启Kong

如果你更改了您的自定义配置,你可以重启kong(没有重启时间)用下列命令:

docker exec -it kong kong reload

它将会在这个容器中运行命令 kong reload

License

查看此映像中包含的软件的许可证信息

支持的 Docker 版本

Docker版本17.04.0-ce正式支持此镜像。
尽量支持到低版本(1.6)。
查看docker安装文档获取如何升级你的docker守护进程。

用户反馈

问题

如果您对此镜像有任何问题,请通过Githun issue联系我们,如果问题与CVE有关,请先在官方图像存储库中检查cve-tracker问题。

贡献

您可以为此镜像加入任何更新,修复,新功能,不论复杂或者简单的功能,我们一直乐于收到大家的任何请求,并会尽快处理它们。
在开始编码之前,我们建议您通过GitHub问题讨论您的计划,特别是有一些宏达的想法的时候,这样其他贡献者有机会可以为你指出正确的方向,给你设计上的反馈,并帮助您了解到是否有其他的开发者在和您做一样的事情。

文档

此镜像的文档存储在docker-library/docs GitHub repo kong/ directory 上,在尝试拉取请求之前,请务必熟悉存储库的README.md文件。