标签归档:Kong插件

Kong 1.4 发布!自动检测Cassandra Topology 更改,自定义Host Header以及更多功能!

原文地址:https://konghq.com/blog/kong-gateway-1-4-released-auto-detect-cassandra-topology-changes-custom-host-header-much/

我们很高兴地宣布1.4系列的第一个版本已经发布! 我们的工程团队和出色的社区成员在此版本中添加了许多新功能,改进和修复。

请阅读以下内容,了解Kong Gateway 1.4中最相关的更改以及如何充分利用这些新增功能。 有关完整的详细信息,请参阅更改日志;有关如何从以前的Kong版本进行升级的说明,请参阅升级路径

自动检测Cassandra Topology 更改

从Kong Gateway 1.4开始,将自动检测对Apache Cassandra群集拓扑所做的任何更改,从而避免Kong重新启动。

如何利用此新功能:

新的配置cassandra_refresh_frequency设置在检查Cassandra集群拓扑结构更改之前,Kong必须等待多长时间。默认频率是每60秒检查一次,但是可以根据需要增加、减少甚至禁用这个值。

上游的Hostname属性

Kong中定义的任何上游现在都可以使用一个名为hostname的可选属性,该属性定义在通过Kong服务器代理连接时将使用的Host header。

主要优点:

服务器通常会监听与解析名称不同的服务器名称,并且此新属性可以保证Kong在代理连接和积极检查主机的运行状况时将使用正确的名称。

DAO属性的新变更

新的属性转换已添加到DAO模式中,使开发人员能够添加在插入或更新数据库条目时运行的函数

新的状态接口

通过新的状态接口,插件可以将端点添加到已经存在的/status端点,从而公开不敏感的健康数据,从而避免公开Kong的管理API。

主要优点

  • 用户可以同时公开Kong的健康数据并保护Kong的Admin API。
  • 对于使用禁用的管理界面运行的Kong节点,执行基于HTTP的运行状况检查更加容易。

Kong Gateway 1.4中的其他新功能

新的Admin API响应headerX-Kong-Admin-Latency

  • 这个新的响应header报告了对Kong的Admin API的每个请求处理了多长时间。

新的配置选项router_update_frequency

  • 这个新的配置选项允许设置检查路由器和插件更改的频率。
  • 这样可以避免在频繁更改Kong路由或插件时性能下降。
  • 此选项使管理员可以选择延迟路由器和插件配置更改的可用性,还是增加数据库负载。

限速插件中的Service-level 支持

  • 除了使用者,凭证和IP级别外,限速插件现在还具有服务级别的支持。

Kong Gateway 1.4中的其他改进和错误修复

Kong Gateway 1.4还改善了限速插件内存的使用,使用共享字典的TTL终止了其local策略计数器,以避免在内存中保留不必要的计数器。

此版本中存在一些重要的错误修复,例如服务网格弃用的开始,它将被替换为Kuma(kuma.io)向前发展。 已知服务网格会导致向上游的HTTPS请求忽略proxy_ssl *指令,因此在Kong Gateway的下一个主要版本中将停止使用该服务网格。 在此版本中,默认情况下禁用此功能,以避免出现此问题,并且仍可以使用新的配置选项service_mesh启用它。

另一个相关的修复与使用日志插件记录NGINX产生的错误有关,该错误过去曾错误地将某些请求属性报告为请求方法,并且现在可以正常工作。

我们还解决了一个问题,即在删除所有Kong workers时,目标不能在所有Kong员工中正确更新的情况下,在频繁使用情况下,将流量与这些被删除目标进行了平衡。

与往常一样,此处提供Kong Gateway 1.4的文档。 此外,我们将在后续帖子和社区电话中讨论1.4中的关键功能,敬请期待!

感谢我们的用户,贡献者和核心维护者社区,感谢您对Kong开源平台的持续支持。

请尝试一下Kong Gateway 1.4,并确保让我们知道您的想法

Kong社区

像往常一样,随时在我们的社区论坛Kong Nation上提问。 从您的反馈中吸取教训,将使我们能够更好地了解关键任务用例并不断改进Kong。

Happy Konging!

在 CentOS 安装 Kong

安装包

首先下载配置的相应软件包:

企业试用用户应从其欢迎电子邮件中下载其包,并在步骤1之后将其许可保存到/etc/kong/license.json

YUM Repositories

你也可以通过YUM安装Kong;按照下面“Set Me Up”部分中的说明进行操作。

注意:确保生成的.repo文件的baseurl字段包含您的CentOS版本;例如:

baseurl=https://kong.bintray.com/kong-rpm/centos/6

或者

baseurl=https://kong.bintray.com/kong-rpm/centos/7

安装

  1. 安装Kong 如果要下载程序包,请执行:
     $ sudo yum install epel-release
     $ sudo yum install kong-1.3.0.*.noarch.rpm --nogpgcheck
    

    如果您正在使用存储库,请执行:

      $ sudo yum update -y
      $ sudo yum install -y wget
      $ wget https://bintray.com/kong/kong-rpm/rpm -O bintray-kong-kong-rpm.repo
      $ export major_version=`grep -oE '[0-9]+\.[0-9]+' /etc/redhat-release | cut -d "." -f1`
      $ sed -i -e 's/baseurl.*/&\/centos\/'$major_version''/ bintray-kong-kong-rpm.repo
      $ sudo mv bintray-kong-kong-rpm.repo /etc/yum.repos.d/
      $ sudo yum update -y
      $ sudo yum install -y kong
    
  2. 准备数据库或声明性配置文件 无论是否有数据库,Kong都可以运行。使用数据库时,您将使用 kong.conf 配置文件在启动时设置Kong的配置属性,并将数据库用作所有已配置实体的存储,例如Kong代理所在的 Routes 和 Services 。

    不使用数据库时,您将使用kong.conf的配置属性和kong.yml文件来将实体指定为声明性配置。

    使用数据库

    配置Kong以便它可以连接到您的数据库。Kong支持PostgreSQL 9.5+Cassandra 3.x.x作为其数据存储。

    如果您使用Postgres,请在开始Kong之前配置数据库和用户,即:

     CREATE USER kong; CREATE DATABASE kong OWNER kong;
    
    然后执行Kong的数据迁移:
    
      $ kong migrations bootstrap [-c /path/to/kong.conf]
    

    对于Kong 小于0.15的注意事项:如果Kong版本低于0.15(最高0.14),请使用up子命令而不是bootstrap。另请注意,如果Kong 小于0.15,则不应同时进行迁移;只有一个Kong节点应该一次执行迁移。对于0.15,1.0及以上的Kong,此限制被取消。

    不使用数据库

    如果要在无DB模式下运行Kong,则应首先生成声明性配置文件。以下命令将在当前文件夹中生成kong.yml文件。它包含有关如何填写它的说明。

     $ kong config init
    

    填写kong.yml文件后,编辑您的kong.conf文件。将数据库选项设置为off,将declarative_config选项设置为kong.yml文件的路径:

     database = off
      declarative_config = /path/to/kong.yml
    
  3. 启动Kong
     $ kong start [-c /path/to/kong.conf]
    
  4. 使用Kong Kong正在运行
      $ curl -i http://localhost:8001/

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

从Kong调用 AWS Lambda函数。它可以与其他请求插件结合使用以保护,管理或扩展功能。

注意:此插件与0.14.0之前的Kong版本和0.34之前的Kong Enterprise捆绑在一起的功能与此处记录的功能不同。 有关详细信息,请参阅CHANGELOG

术语

  • plugin: 在请求被代理到上游API之前或之后,在Kong内部执行操作的插件。
  • Service: 表示外部 upstream API或微服务的Kong实体。
  • Route: 表示将下游请求映射到上游服务的方法的Kong实体。
  • Consumer: 代表使用API的开发人员或机器的Kong实体。当使用Kong时,Consumer 仅与Kong通信,其代理对所述上游API的每次调用。
  • Credential: 与Consumer关联的唯一字符串,也称为API密钥。
  • upstream service: 这是指位于Kong后面的您自己的 API/service,转发客户端请求。

配置

此插件与具有以下协议的请求兼容:

  • http
  • https

此插件与无DB模式兼容。

在 Service 上启用插件

使用数据库:

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

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=aws-lambda"  \
    --data-urlencode "config.aws_key=AWS_KEY" \
    --data-urlencode "config.aws_secret=AWS_SECRET" \
    --data "config.aws_region=AWS_REGION" \
    --data "config.function_name=LAMBDA_FUNCTION_NAME"

不使用数据库:

通过添加此部分在服务上配置此插件执行声明性配置文件:

plugins:
- name: aws-lambda
  service: {service}
  config: 
    aws_key: AWS_KEY
    aws_secret: AWS_SECRET
    aws_region: AWS_REGION
    function_name: LAMBDA_FUNCTION_NAME

在这两种情况下,{service}是此插件配置将定位的RouteID或名称。

在 Route 上启用插件

使用数据库:

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

$ curl -X POST http://kong:8001/routes/{route}/plugins \
    --data "name=aws-lambda"  \
    --data-urlencode "config.aws_key=AWS_KEY" \
    --data-urlencode "config.aws_secret=AWS_SECRET" \
    --data "config.aws_region=AWS_REGION" \
    --data "config.function_name=LAMBDA_FUNCTION_NAME"

不使用数据库:

通过添加此部分在 Route 上配置此插件执行声明性配置文件:

plugins:
- name: aws-lambda
  route: {route}
  config: 
    aws_key: AWS_KEY
    aws_secret: AWS_SECRET
    aws_region: AWS_REGION
    function_name: LAMBDA_FUNCTION_NAME

在这两种情况下,,{route}是此插件配置将定位的 route 的idname

在 Consumer 上启用插件

使用数据库:

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

$ curl -X POST http://kong:8001/consumers/{consumer}/plugins \
    --data "name=aws-lambda" \
     \
    --data-urlencode "config.aws_key=AWS_KEY" \
    --data-urlencode "config.aws_secret=AWS_SECRET" \
    --data "config.aws_region=AWS_REGION" \
    --data "config.function_name=LAMBDA_FUNCTION_NAME"

不使用数据库:

通过添加此部分在Consumer上配置此插件执行声明性配置文件:

plugins:
- name: aws-lambda
  consumer: {consumer}
  config: 
    aws_key: AWS_KEY
    aws_secret: AWS_SECRET
    aws_region: AWS_REGION
    function_name: LAMBDA_FUNCTION_NAME

在这两种情况下,{consumer}都是此插件配置将定位的Consumeridusername
您可以组合consumer_idservice_id 。 在同一个请求中,进一步缩小插件的范围。

全局插件

  • 使用数据库:可以使用http://kong:8001/plugins/配置所有插件。
  • 不使用数据库:可以通过plugins:配置所有插件:声明性配置文件中的条目。

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

参数

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

参数 默认值 描述
name 要使用的插件的名称,在本例中为aws-lambda
service_id 此插件将定位的 Service 的ID。
route_id 此插件将定位的 Route 的ID。
enabled true 是否将应用此插件。
consumer_id 此插件将定位的Consumer的id
config.aws_key 调用功能时要使用的AWS密钥凭证。
config.aws_secret 调用功能时要使用的AWS秘密凭证
config.aws_region Lambda函数所在的AWS区域。支持的区域是:us-east-1,us-east-2, ap-northeast-1,ap-northeast-2, ap-southeast-1, ap-southeast-2, eu-central-1, eu-west-1
config.function_name 要调用的AWS Lambda函数名称
config.qualifier 
optional
调用功能时要使用的 Qualifier 
config.invocation_type 
optional
RequestResponse 调用函数时要使用的 InvocationType。可用类型为RequestResponseEventDryRun
config.log_type 
optional
Tail 调用函数时要使用的LogType。默认情况下,不支持noneTail
config.timeout 
optional
60000 调用该函数时的可选超时(以毫秒为单位)
config.keepalive 
optional
60000 可选值(以毫秒为单位),用于定义空闲连接在关闭之前将存活多长时间
config.unhandled_status 
optional
200,202  204 Unhandled Function Error时使用的响应状态代码(而不是默认的200202204
config.forward_request_body 
optional
false 一个可选值,用于定义是否在JSON编码请求的request_body字段中发送请求正文。如果可以解析正文参数,则将在请求的单独的request_body_args字段中发送它们。正文参数可以针对application/jsonapplication/x-www-form-urlencodedmultipart/form-data内容类型进行解析。
config.forward_request_headers
optional
false 一个可选值,用于定义是否将原始HTTP请求标头作为映射发送到JSON编码请求的request_headers字段中。
config.forward_request_method
optional
false 一个可选值,用于定义是否在JSON编码请求的request_method字段中发送原始HTTP请求方法动词。
config.forward_request_uri 
optional
false 一个可选值,用于定义是否在JSON编码请求的request_uri字段中发送原始HTTP请求URI。请求URI参数(如果有)将在JSON主体的单独的request_uri_args字段中发送。
config.is_proxy_integration 
optional
false 一个可选值,它定义是否将从Lambda接收的响应格式转换为此格式。请注意,未实现参数isBase64Encoded

提醒: 默认情况下,curl将发送带有application/x-www-form-urlencoded MIME类型的有效负载,该负载自然会由Kong进行URL解码。 为确保正确解码可能出现在您的AWS密钥或机密中的特殊字符(如+),您必须对其进行URL编码,因此如果使用curl,请使用--data-urlencode。 这种方法的替代方法是使用其他MIME类型(例如application/json)发送有效负载,或使用其他HTTP客户端。

发送参数

与请求一起发送的任何表单参数也将作为参数发送到AWS Lambda函数。

已知的问题

使用伪造的上游服务

使用AWS Lambda插件时,响应将由插件本身返回,而无需将请求代理到任何上游服务。 这意味着服务的host, port, path属性将被忽略,但仍必须为由Kong验证的实体指定。 主机属性尤其必须是IP地址,或者是由名称服务器解析的主机名。

响应插件

系统中存在一个已知限制,该限制会阻止执行某些响应插件。 我们计划将来删除此限制。

分步指南

步骤

  1. 以允许用户使用lambda函数操作以及创建用户和角色的用户身份访问AWS Console。
  2. 在AWS中创建执行角色
  3. 创建一个将通过Kong调用该功能的用户,对其进行测试。
  4. 在Kong中创建一个Service&Route,添加链接到我们的aws函数的aws-lambda插件并执行它。

配置

  1. 首先,让我们为lambda函数创建一个称为LambdaExecutor的执行角色。在IAM控制台中创建一个选择AWS Lambda服务的新角色,将没有任何策略,因为本示例中的函数将简单地执行自身,从而返回硬编码JSON作为响应,而无需访问其他AWS资源
  2. 现在,我们创建一个名为KongInvoker的用户,由我们的Kong API网关用来调用该函数。在IAM控制台中,创建一个新用户,必须通过访问和秘密密钥向其提供编程访问权限;然后将直接附加现有策略,尤其是预定义的AWSLambdaRole。确认用户创建后,将访问密钥和秘密密钥存储在安全的地方。
  3. 现在我们需要创建lambda函数本身,将在弗吉尼亚北部地区(代码us-east-1)进行。在Lambda Management中,创建一个新函数Mylambda,将没有蓝图,因为我们将在下面粘贴代码。对于执行角色,我们选择一个以前专门创建的LambdaExecutor角色使用下面的内联代码来返回简单的JSON响应,请注意,这是Python 3.6解释器的代码。
      import json
    def lambda_handler(event, context):
      """
        If is_proxy_integration is set to true :
        jsonbody='''{"statusCode": 200, "body": {"response": "yes"}}'''
      """
      jsonbody='''{"response": "yes"}'''
      return json.loads(jsonbody)
    

    从AWS控制台测试lambda函数,并确保执行成功。

  4. 最后,我们在Kong中设置了Service&Route,并将其链接到刚刚创建的功能。

使用数据库

curl -i -X POST http://{kong_hostname}:8001/services \
--data 'name=lambda1' \
--data 'url=http://localhost:8000' \

该Service并不需要真正的URL,因为我们不会对上游进行HTTP调用,而需要由函数生成的响应。

还要为 Service 创建一条 Route :

curl -i -X POST http://{kong_hostname}:8001/services/lambda1/routes \
--data 'paths[1]=/lambda1'

添加插件

curl -i -X POST http://{kong_hostname}:8001/services/lambda1/plugins \
--data 'name=aws-lambda' \
--data-urlencode 'config.aws_key={KongInvoker user key}' \
--data-urlencode 'config.aws_secret={KongInvoker user secret}' \
--data 'config.aws_region=us-east-1' \
--data 'config.function_name=MyLambda'

不使用数据库

将 Service, Route and Plugin 添加到声明性配置文件中:

services:
- name: lambda1
  url: http://localhost:8000

routes:
- service: lambda1
  paths: [ "/lambda1" ]

plugins:
- service: lambda1
  name: aws-lambda
  config:
    aws_key: {KongInvoker user key}
    aws_secret: {KongInvoker user secret}
    aws_region: us-east-1
    function_name: MyLambda

创建所有内容后,请调用服务并验证正确的调用,执行和响应:

curl http://{kong_hostname}:8000/lambda1

附加标题:

x-amzn-Remapped-Content-Length, X-Amzn-Trace-Id, x-amzn-RequestId

JSON响应:

{"response": "yes"}

充分利用AWS Lambda在Kong的强大功能,尽享乐趣!

使用源码安装 Kong

无论是否有数据库,Kong都可以运行。

使用数据库时,您将使用kong.conf配置文件在启动时设置Kong的配置属性,并将数据库用作所有已配置实体的存储,例如Kong代理所在的 Routes 和 Services 。

不使用数据库时,您将使用kong.conf的配置属性和kong.yml文件来将实体指定为声明性配置。

使用数据库

  1. 安装依赖项OpenResty 1.15.8.1。作为一个OpenResty应用程序,您必须遵循OpenResty安装说明。您将需要OpenSSL和PCRE来编译OpenResty,并至少使用以下编译选项:
      $ ./configure \
        --with-pcre-jit \
        --with-http_ssl_module \
        --with-http_realip_module \
        --with-http_stub_status_module \
        --with-http_v2_module
    

    您可能必须指定--with-openssl,并且可以添加任何其他您想要的选项,例如其他Nginx模块或自定义--prefix目录。

    OpenResty可以方便地捆绑LuaJITresty-cli,它们对于Kong来说是必不可少的。将nginx和resty可执行文件添加到$ PATH

      $ export PATH="$PATH:/usr/local/openresty/bin"
    

    Luarocks 3.1.3,使用与OpenResty捆绑的LuaJIT版本编译(请参阅--with-lua--with-lua-include配置选项)。例:

      ./configure \
        --lua-suffix=jit \
        --with-lua=/usr/local/openresty/luajit \
        --with-lua-include=/usr/local/openresty/luajit/include/luajit-2.1
    
  2. 安装 Kong现在已经安装了OpenResty,我们可以使用Luarocks来安装Kong的Lua源:
      $ luarocks install kong 1.3.0-0
    

    或者

      $ git clone git@github.com:Kong/kong.git
      $ cd kong
      $ [sudo] make install # this simply runs the `luarocks make kong-*.rockspec` command
    
  3. 添加kong.conf

    注意:如果您使用的是Cassandra,则需要执行此步骤;它是Postgres用户的可选项。

    默认情况下,Kong配置为与本地Postgres实例通信。 如果您使用的是Cassandra,或者需要修改任何设置,请下载kong.conf.default文件并根据需要进行调整。 然后,以root身份将其添加到/etc

      $ sudo mkdir -p /etc/kong
       $ sudo cp kong.conf.default /etc/kong/kong.conf
    
  4. 准备数据库配置Kong以便它可以连接到您的数据库。Kong支持PostgreSQL 9.5+Cassandra 3.x.x作为其数据存储。如果您使用的是Postgres,请在启动Kong之前配置数据库和用户:
     CREATE USER kong; CREATE DATABASE kong OWNER kong;
    

    接下来,运行Kong迁移:

      $ kong migrations bootstrap [-c /path/to/kong.conf]
    

    对于Kong < 0.15的注意事项:如果Kong版本低于0.15(最高0.14),请使用up子命令而不是bootstrap。另请注意,如果Kong < 0.15,则不应同时进行迁移;只有一个Kong节点应该一次执行迁移。对于0.15,1.0及以上的Kong,此限制被取消。

  5. 启动Kong
     $ kong start [-c /path/to/kong.conf]
    
  6. 使用KongKong正在运行
      $ curl -i http://localhost:8001/
    

不使用数据库

  1. 按照上面的列表中的步骤1和2(安装依赖项,安装Kong)。
  2. 写声明性配置文件以下命令将在当前文件夹中生成kong.yml文件。它包含有关如何填写它的说明。执行此操作时,请遵循[声明配置格式]:/1.3.x/db-less-and-declarative-config/#the-declarative-configuration-format说明。
      $ kong config init
    

    我们假设该文件名为kong.yml

  3. 添加kong.conf下载kong.conf.default文件并根据需要进行调整。特别是,确保将database配置选项设置为off,并将declarative_config选项设置为kong.yml的绝对路径
      database = off
      ...
      declarative_config = /path/to/kong.yml
    
  4. 启动Kong
     $ kong start [-c /path/to/kong.conf]
    
  5. 使用KongKong正在运行
      $ curl -i http://localhost:8001/

如何在 Kong 和 OpenResty 中使用环境变量 os.getenv()

在项目中有时会遇到使用系统环境变量的问题,但是直接使用 os.getenv() 是不可行的,不仅是在 Kong 中,在 OpenResty 也都是不可以的,原因是 Kong 是基于 OpenResty ,OpenResty 是基于 Nginx 的,而Nginx在启动的时候,会把环境中所有的环境变量都清除掉,我们可以从Nginx的官方文档中看到这段描述:http://nginx.org/en/docs/ngx_core_module.html#env 

By default, nginx removes all environment variables inherited from its parent process except the TZ variable.

具体可以参考春哥在这个issue下的回复:https://github.com/openresty/lua-nginx-module/issues/601

所以需要在你的nginx.conf文件中把你需要的环境变量声明一下:

events{
  ...
}

env PATH;
env USERNAME;

然后重启一下Nginx,就可以直接在你的 Lua 代码中使用 os.getenv("USERNAME") 获取环境变量。

在 Kong 中使用 os.getenv()

那如果我想在kong的插件中是使用os.getenv()要怎么操作呢?

在 Kong 里面,我们看到Kong生成的 Nginx配置文件是不可修改的,即使你修改了,Kong 还是会生成恢复成修改前,那么这个时候就要用到 Kong 的一个自定义 Nginx 配置文件功能。详情可以看这俩issue:

那么实际操作起来就很简单了,新建一个custom-nginx.conf文件,里面和上文一样,把你需要使用到的环境变量写到这个配置文件中。

events{
  ...
}

env PATH;
env USERNAME;

接着重启 Kong 即可。不过这里要注意的是,重启的时候,需要带上一个参数--nginx-conf。不过不要搞错的是-c参数是kong的配置文件参数,--nginx-conf 是自定义Nginx模板配置参数

 kong restart -c kong.conf --nginx-conf custom-nginx.conf

重启成功之后,就可以在 Kong 的插件中使用代码中使用 os.getenv("USERNAME") 来获取环境变量了。

使用 Docker 安装 Kong

有关如何在Docker中使用Kong的详细信息可以在镜像图像的DockerHub存储库中找到:kong。 我们还有一个Docker Compose template,内置编排和可扩展性。

使用数据库

这是一个快速示例,显示如何将Kong容器连接到Cassandra或PostgreSQL容器。

  1. 创建一个Docker network

    您需要创建一个自定义网络,以允许容器相互发现和通信。在此示例中,kong-net是网络名称,您可以使用任何名称。

     $ docker network create kong-net
    
  2. 启动数据库

    如果您想使用Cassandra容器:

      $ docker run -d --name kong-database \
                --network=kong-net \
                -p 9042:9042 \
                cassandra:3
    

    如果您想使用PostgreSQL容器:

      $ docker run -d --name kong-database \
                --network=kong-net \
                -p 5432:5432 \
                -e "POSTGRES_USER=kong" \
                -e "POSTGRES_DB=kong" \
                postgres:9.6
    
  3. 准备数据库

    使用临时Kong容器运行迁移:

      $ docker run --rm \
      --network=kong-net \
      -e "KONG_DATABASE=postgres" \
      -e "KONG_PG_HOST=kong-database" \
      -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \
      kong:latest kong migrations bootstrap
    

    在上面的示例中,配置了Cassandra和PostgreSQL,但您应该使用cassandrapostgres更新KONG_DATABASE环境变量。
    对于Kong 小于0.15的注意事项:如果Kong版本低于0.15(最高0.14),请使用up子命令而不是bootstrap。另请注意,如果Kong 版本小于0.15,则不应同时进行迁移;只有一个Kong节点应该一次执行迁移。对于0.15,1.0及以上的Kong,此限制被取消。

  4. 启动Kong

    迁移运行并且数据库准备就绪后,启动一个将连接到数据库容器的Kong容器,就像临时迁移容器一样:

      $ docker run -d --name kong \
      --network=kong-net \
      -e "KONG_DATABASE=postgres" \
      -e "KONG_PG_HOST=kong-database" \
      -e "KONG_CASSANDRA_CONTACT_POINTS=kong-database" \
      -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
      -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
      -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
      -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
      -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
      -p 8000:8000 \
      -p 8443:8443 \
      -p 8001:8001 \
      -p 8444:8444 \
      kong:latest
    
  5. 使用Kong

    Kong正在运行:

      $ curl -i http://localhost:8001/
    

    通过5分钟的快速入门快速学习如何使用Kong。

无数据库模式

在无DB模式下启动Kong所涉及的步骤如下:

  1. 创建一个Docker network

    这与Pg / Cassandra指南中的相同。我们也使用kong-net作为网络名称,它也可以改为其他东西。

      $ docker network create kong-net
    

    在无DB模式下运行Kong并不严格需要此步骤,但如果您希望将来添加其他内容(如Redis群集备份的速率限制插件),这是一个很好的预防措施。

  2. 创建Docker volume

    对于本指南的目的,Docker卷是主机内的一个文件夹,可以将其映射到容器中的文件夹中。卷有一个名称。在这种情况下,我们将命名我们的kong-vol

      $ docker volume create kong-vol
    

    您现在应该能够检查volume:

      $ docker volume inspect kong-vol
    

    结果应该类似于:

      [
          {
              "CreatedAt": "2019-05-28T12:40:09Z",
              "Driver": "local",
              "Labels": {},
              "Mountpoint": "/var/lib/docker/volumes/kong-vol/_data",
              "Name": "kong-vol",
              "Options": {},
              "Scope": "local"
          }
      ]
    

    注意MountPoint条目。我们将在下一步中使用该路径。

  3. 准备声明性配置文件

    声明性配置格式指南中描述了语法和属性。

    添加您需要的任何核心实体(服务,路由,插件,消费者等)。

    在本指南中,我们假设您将其命名为kong.yml。

    将其保存在上一步中提到的MountPoint路径中。

    就本指南而言,这将是/var/lib/docker/volumes/kong-vol/_data/kong.yml

  4. 在无DB模式中启动Kong

    虽然可以仅使用KONG_DATABASE=off来启动Kong容器,但通常还需要通过KONG_DECLARATIVE_CONFIG变量名称将声明性配置文件作为参数包含在内。为此,我们需要从容器中使文件“visible”。我们使用-v标志来实现这一点,它将kong-vol卷映射到容器中的/usr/local/kong/declarative文件夹。

      $ docker run -d --name kong \
      --network=kong-net \
      -v "kong-vol:/usr/local/kong/declarative" \
      -e "KONG_DATABASE=off" \
      -e "KONG_DECLARATIVE_CONFIG=/usr/local/kong/declarative/kong.yml" \
      -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
      -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
      -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
      -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
      -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
      -p 8000:8000 \
      -p 8443:8443 \
      -p 8001:8001 \
      -p 8444:8444 \
      kong:latest
    
  5. 使用Kong

    Kong应该正在运行,它应该包含一些以Kong .yml添加的实体。

      $ curl -i http://localhost:8001/
    

    例如,获取服务列表:

      $ curl -i http://localhost:8001/services

 

Kong 1.3发布!支持原生gRPC代理,上游双向TLS认证,以及更多功能

原文地址:https://konghq.com/blog/kong-1-3-released/

今天,我们很高兴地宣布推出Kong 1.3!我们的工程团队和出色的社区为此版本提供了许多功能和改进。基于1.2版本的成功,Kong 1.3是Kong的第一个版本,它本身支持gRPC代理,上游相互TLS身份验证,以及一系列新功能和性能改进。

请阅读以下内容,了解有关Kong 1.3的新功能,改进和修复的更多信息,以及如何利用这些令人兴奋的变化。 请花几分钟时间阅读我们的更新日志以及升级路径以获取更多详细信息。

原生gRPC代理

我们观察到越来越多的用户转向微服务架构,并听到用户表达他们对本机gRPC代理支持的兴趣。Kong 1.3通过支持gRPC本地代理来解决这个问题,为支持gRPC的基础架构带来更多控制和可见性。

主要优点:

  • 简化运营流程。
  • 为gRPC服务添加A / B测试,自动重试和断路,以提高可靠性和正常运行时间。
  • 更多的可观测性
  • 针对gRPC服务的日志记录,分析或Prometheus集成?Kong让你满意。

主要功能:

  • 新协议:Route和Service实体的protocol属性现在可以设置为grpcgrpcs,这对应于通过明文HTTP/2(h2c)的gRPC和通过TLS HTTP/ 2(h2)的gRPC。

上游双向TLS认证

Kong长期以来一直支持与上游服务的TLS连接。 在1.3中,我们添加了对Kong的支持,以提供特定证书,同时与上游握手以提高安全性。

主要优点:

  • 能够使用证书与上游服务握手使得Kong在需要强大的身份验证保证的行业中更加出色,例如金融和医疗保健服务。
  • 安全性更好
  • 通过提供可信证书,上游服务将确定传入请求是由Kong转发的,而不是恶意客户端。
  • 对开发人员更友好
  • 您可以使用Kong将需要相互TLS身份验证的服务转换为与开发人员无关的方法(例如OAuth)。

主要功能:

  • 新配置属性:Service实体具有新字段client_certificate。如果设置,当Kong尝试与服务握手时将使用相应的证书。

Sessions 插件

在Kong 1.3中,我们开放了Sessions插件(之前仅在Kong Enterprise中提供)供所有用户使用。 结合其他身份验证插件,它允许Kong记住之前已经过身份验证的浏览器用户。 您可以在此处阅读详细的文档

NGINX CVE修复

Kong 1.3附带NGINX HTTP/2模块(CVE-2019-9511CVE-2019-9513CVE-2019-9516)的修复程序。 我们还发布了Kong 1.0.4,1.1.3,1.2.2来修补旧版Kong中的漏洞,以防不能立即升级到1.3。

OpenResty Version Bump

OpenResty的版本已经发布到最新的OpenResty版本 - 1.15.8.1,该版本基于Nginx 1.15.8。 此版本的OpenResty在关闭上游keepalive连接,ARM64架构支持和LuaJIT GC64模式时带来了更好的性能。 最引人注目的变化是,由于LuaJIT编译器生成更多本机代码,OpenResty更有效地存储请求上下文数据,因此使用密钥身份验证在基线代理基准测试中,Kong现在运行速度提高约10%。 

Kong 1.3的其他新功能

按任何请求 header 路由

  • Kong的路由器现在能够通过任何请求头(不仅是Host)匹配路由。
  • 这允许对服务之间路由传入流量的方式进行精细控制。
  • 参阅此处的文档

最少连接负载平衡

  • Kong现在可以将流量发送到连接数最少的上游服务。
  • 在某些用例中改善上游负载分配。
  • 参阅此处的文档

数据库导出

  • 新添加的kong config db_export CLI命令可用于创建数据库内容转储到YAML文件中,该文件适用于声明性配置或稍后导回数据库。
  • 这样可以更轻松地创建声明性配置文件。
  • 这使得Kong配置的备份和版本控制变得更加容易
  • 参阅此处的文档

主动关闭上游keepalive连接

  • 在旧版本的Kong中,上游连接永远不会被Kong关闭。这可能导致竞争条件,因为Kong可能会尝试重新使用keepalived连接,而上游尝试关闭它。
  • 如果您在Kong error.log中看到“upstream prematurely closed connection”错误,则此版本应显着减少甚至消除部署中的此错误。
  • 添加了新的配置指令来控制此行为,请阅读完整的更新日志以了解更多信息。

更多的监听标志支持

  • 特别是reuseport标志,如果Kong worker数量很大,可用于改善负载分配和延迟抖动。
  • 还添加了deferredbind标志支持。您可以查看NGINX listen指令文档以了解使用它们的效果。

其他改进和错误修复

Kong 1.3还包含有关存储CA证书(没有私钥的证书),Admin API接口和更多PDK功能的新实体的改进。 我们还修复了很多错误。由于此版本中有大量新功能,因此我们无法在此博客文章中介绍所有这些内容,而是鼓励您在此处阅读完整的更新日志

我们还在kong.conf模板中添加了一个新的部分,以更好地解释注入NGINX指令的功能。 对于具有仅添加几个NGINX指令的自定义模板的用户,我们建议切换使用注入的NGINX指令,以获得更好的可升级性。

与往常一样,Kong 1.3的文档可在此处获得。 此外,如上所述,我们将在后续帖子和社区电话中讨论1.3中的主要功能,敬请期待!

感谢我们的用户,贡献者和核心维护者社区,感谢您对Kong的开源平台的持续支持。 请试试Kong 1.3,一定要告诉我们您的想法

Kong社区

像往常一样,随时可以就我们的社区论坛Kong Nation提出任何问题。 从您的反馈中学习将使我们能够更好地理解任务关键用例并不断改进Kong。

微服务 API 网关 Kong 插件 Kubernetes Sidecar 注入插件中文文档

Kubernetes Sidecar 注入插件

该插件将注入Kong数据平面节点并在Kubernetes之上形成服务网格

介绍

Kong 0.15.0 / 1.0.0增加了代理和路由原始tcptls流的能力,并使用服务网格Sidecar模式和Kong节点之间的相互tls来部署Kong。本教程将引导您使用我们的 Kubernetes Sidecar 注入插件在Kubernetes上设置Kong服务网格。

准备条件

您需要在Kubernetes上运行Kong 1.0.0或更高版本,包括存储为可用于Kong控制平面的机密的SSL证书。来自Kong Kubernetes Repository的Make任务run_cassandrarun_postgres将完全配置必备数据存储,Kong控制平面,Kong数据平面和SSL机密。

或者,按照Kong Kubernetes Install Instructions页面中的任何设置说明进行操作,然后设置SSL证书/密码:

cd $(mktemp -d)

### Create a key+certificate for the control plane
cat <<EOF | kubectl create -f -
apiVersion: certificates.k8s.io/v1beta1
kind: CertificateSigningRequest
metadata:
  name: kong-control-plane.kong.svc
spec:
  request: $(openssl req -new -nodes -batch -keyout privkey.pem -subj /CN=kong-control-plane.kong.svc | base64 | tr -d '\n')
  usages:
  - digital signature
  - key encipherment
  - server auth
EOF
kubectl certificate approve kong-control-plane.kong.svc
kubectl -n kong create secret tls kong-control-plane.kong.svc --key=privkey.pem --cert=<(kubectl get csr kong-control-plane.kong.svc -o jsonpath='{.status.certificate}' | base64 --decode)
kubectl delete csr kong-control-plane.kong.svc
rm privkey.pem

或使用以下简便脚本:

curl -fsSL https://raw.githubusercontent.com/Kong/kong-dist-kubernetes/master/setup_certificate.sh | bash

安装步骤

导出一些变量以访问Kong Admin API和Proxy:

$ export HOST=$(kubectl get nodes --namespace default -o jsonpath='{.items[0].status.addresses[0].address}')
$ export ADMIN_PORT=$(kubectl get svc --namespace kong kong-control-plane  -o jsonpath='{.spec.ports[0].nodePort}')

通过Kong Admin API启用Sidecar Injector插件:

curl $HOST:$ADMIN_PORT/plugins -d name=kubernetes-sidecar-injector -d config.image=kong

打开Kubernets Sidecar Injection:

cat <<EOF | kubectl create -f -
apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration
metadata:
  name: kong-sidecar-injector
webhooks:
- name: kong.sidecar.injector
  rules:
  - apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
    operations: [ "CREATE" ]
  failurePolicy: Fail
  namespaceSelector:
    matchExpressions:
    - key: kong-sidecar-injection
      operator: NotIn
      values:
      - disabled
  clientConfig:
    service:
      namespace: kong
      name: kong-control-plane
      path: /kubernetes-sidecar-injector
    caBundle: $(kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[].cluster.certificate-authority-data}')
EOF

或使用以下简便脚本:

curl -fsSL https://raw.githubusercontent.com/Kong/kong-dist-kubernetes/master/setup_sidecar_injector.sh | bash

使用

接下来,任何开始使用Kong Sidecar的pods都会自动注入,而来自该pods容器的所有数据都将通过Kong Sidecar。 例如,如果我们使用Istio中的bookinfo.yaml示例:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.1/samples/bookinfo/platform/kube/bookinfo.yaml

我们看到所有pods都收到了Kong Sidecar:

kubectl get all
NAME                 READY   STATUS
pod/details-v1       2/2     Running
pod/productpage      2/2     Running
pod/ratings-v1       2/2     Running
pod/reviews-v1       2/2     Running
pod/reviews-v2       2/2     Running
pod/reviews-v3       2/2     Running

继续配置服务。

微服务 API 网关 Kong 中文文档发布

由于项目的原因,最近的几个月一直在学习微服务的API网关 Kong ,在这里做一个简单介绍,是一个云原生,高效,可扩展的分布式 API 网关。 自 2015 年在 github 开源后,广泛受到关注,目前已收获 1.68w+ 的 star,其核心价值在于高性能和可扩展性。由于对项目的积极维护,Kong被广泛用于从初创公司到全球5000强以及政府机构的生产中。从技术角度来说,Kong是基于Openresty的一个莹莹,Openresty是基于Nginx的,使用的语言是Lua。

所以在学习过程中,首要是需要看官方文档,由于项目比较新,所以暂时没有中文文档,我就想着,反正文档总是要全部看一遍的,不如自己翻译一份好了,于是乎就有了这个项目:Kong的文档中文版。欢迎大家star&fork。

由于自己不是英语专业,而且主要目的是学习Kong,所以采用的是人工+机翻结合的方式,如果有遇到翻译的不够通顺,或者对于翻译的语句有歧义的地方,麻烦一定点击官网英文文档https://docs.konghq.com/ 查看,并且欢迎提 PR 提修改意见。另,由于kong的文档本身也在不断增加和完善当中,如果有遇到没有即使更新翻译的状况欢迎提issue,我会不断补充的。

todo:

  • 目前文档中的超链接都是链接的英文原文,后续会慢慢改成中文内链。
  • 会在每一页文档里面附上单独的英文原文链接,以便做对照。
  • 会添加kong自带的插件文档。

本文档是基于 https://docs.konghq.com/1.1.x/ 1.1.x 版本,目前官网已经更新至 1.2.x 版本,如果使用的最新版本,请查看 https://docs.konghq.com 并注意差别。

微服务 API 网关 Kong 插件开发 – 插件配置

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

简介

大多数情况下,您的插件可以配置为满足您的所有用户需求。当插件被执行的时候,您的插件的配置存储在Kong的数据存储区中,以检索它并将其传递给handler.lua方法。

配置由Kong中的Lua表组成,我们称之为 schema。它包含用户在通过Admin API启用插件时将设置的键/值属性。Kong为您提供了一种验证用户插件配置的方法。

当用户向Admin API发出请求以启用或更新给定Service,Route和/或Consumer上的插件时,将根据您的架构schema插件的配置。

例如,用户执行以下请求:

$ curl -X POST http://kong:8001/services/<service-name-or-id>/plugins/ \
    -d "name=my-custom-plugin" \
    -d "config.foo=bar"

如果配置对象的所有config都根据您的模式有效,则API将返回201 Created,并且插件将与其配置一起存储在数据库中(在这种情况下为{foo =“bar”})。如果配置无效,Admin API将返回400 Bad Request和相应的错误消息。

模块

kong.plugins.<plugin_name>.schema

schema.lua规范

此模块将返回一个Lua表,其中包含将定义用户以后如何配置插件的属性的属性。 可用的属性是:

属性名称 Lua type 默认值 描述
no_consumer Boolen false 如果为true,则无法将此插件应用于特定的Consumer。此插件必须仅应用于服务和路由。例如:身份验证插件。
fields Table {} 你插件的schema,可用属性及其规则的键/值表。
self_check Function nil 如果要在接受插件配置之前执行任何自定义验证,则要实现的功能。

self_check函数必须按如下方式实现:

-- @param `schema` 描述插件配置的架构(规则)的表。
-- @param `config` 当前插件配置的键/值表。
-- @param `dao` DAO的一个实例 (查看 DAO 章节).
-- @param `is_updating` 一个布尔值,指示是否在更新的上下文中执行此检查。
-- @return `valid` 一个布尔值,指示插件的配置是否有效。
-- @return `error` 一个 DAO 错误 (查看 DAO 章节)

以下是一个可能的schema.lua文件的示例:

return {
  no_consumer = true, -- 此插件仅适用于服务或路由,
  fields = {
    -- 在此处描述您的插件配置架构。
  },
  self_check = function(schema, plugin_t, dao, is_updating)
    -- 执行任何自定义验证
    return true
  end
}

描述您的配置schema

schema.lua文件的fields自选描述了插件配置的schema。它是一个灵活的键/值表,其中每个键都是插件的有效配置属性,每个键都是一个描述该属性规则的表。例如:

 fields = {
    some_string = {type = "string", required = true},
    some_boolean = {type = "boolean", default = false},
    some_array = {type = "array", enum = {"GET", "POST", "PUT", "DELETE"}}
  }

以下是属性的规则列表:

规则 LUA TYPE(S) 可使用的值 描述
type string “id”, “number”, “boolean”, “string”, 
“table”, “array”, “url”, “timestamp”
验证属性的类型。
required boolean 默认值:false。
如果为true,则该属性必须存在于配置中。
unique boolean 默认值:false。
如果为true,则该值必须是唯一的(请参阅下面的注释)。
default any 如果未在配置中指定该属性,则将该属性设置为给定值。
immutable boolean 默认值:false。
如果为true,则在创建插件配置后将不允许更新该属性。
enum table 属性的可接受值列表。不接受此列表中未包含的任何值。
regex string 用于验证属性值的正则表达式。
schema table 如果属性的类型是table,则定义用于验证这些子属性的模式。
func function 用于对属性执行任何自定义验证的函数。请参阅后面的示例,了解其参数和返回值。
  • type:将转换从请求参数中检索的值。如果类型不是本机Lua类型之一,则会对其执行自定义验证:
    • id:必须是string
    • timestamp:必须是nember
    • uri:必须是有效的URL
    • array:必须是整数索引表(相当于Lua中的数组)。在Admin API中,可以通过在请求的正文中使用不同值的属性键的多次来发送这样的数组,或者通过单个body参数以逗号分隔。
  • unique:此属性对插件配置没有意义,但在插件需要在数据存储区中存储自定义实体时使用。
  • schema:如果您需要对嵌套属性进行深化验证,则此字段允许您创建嵌套模式。模式验证是递归的。任何级别的嵌套都是有效的,但请记住,这会影响插件的可用性。
  • 附加到配置对象但schema中不存在的任何属性也将使所述配置无效。

例子

key-auth插件的schema.lua文件定义了API密钥的可接受参数名称的默认列表,以及默认设置为false的布尔值:

-- schema.lua
return {
  no_consumer = true,
  fields = {
    key_names = {type = "array", required = true, default = {"apikey"}},
    hide_credentials = {type = "boolean", default = false}
  }
}

于是,当在handler.lua中实现插件的access()函数并且用户使用默认值启用插件时,您可以如下:

-- handler.lua
local BasePlugin = require "kong.plugins.base_plugin"
local CustomHandler = BasePlugin:extend()

function CustomHandler:new()
  CustomHandler.super.new(self, "my-custom-plugin")
end

function CustomHandler:access(config)
  CustomHandler.super.access(self)

  kong.log.inspect(config.key_names)        -- {"apikey"}
  kong.log.inspect(config.hide_credentials) -- false
end

return CustomHandler

请注意,上面的示例使用插件开发工具包(PDK)kong.log.inspect函数将这些值打印到Kong日志中。

一个更复杂的示例,可用于最终日志记录插件:

-- schema.lua

local function server_port(given_value, given_config)
  -- 自定义验证
  if given_value > 65534 then
    return false, "port value too high"
  end

  -- 如果环境是“开发”,8080将是默认端口
  if given_config.environment == "development" then
    return true, nil, {port = 8080}
  end
end

return {
  fields = {
    environment = {type = "string", required = true, enum = {"production", "development"}}
    server = {
      type = "table",
      schema = {
        fields = {
          host = {type = "url", default = "http://example.com"},
          port = {type = "number", func = server_port, default = 80}
        }
      }
    }
  }
}

这样的配置将允许用户将配置发布到您的插件,如下所示:

curl -X POST http://kong:8001/services/<service-name-or-id>/plugins \
    -d "name=my-custom-plugin" \
    -d "config.environment=development" \
    -d "config.server.host=http://localhost"

以下内容将在handler.lua中提供:

-- handler.lua
local BasePlugin = require "kong.plugins.base_plugin"
local CustomHandler = BasePlugin:extend()

function CustomHandler:new()
  CustomHandler.super.new(self, "my-custom-plugin")
end

function CustomHandler:access(config)
  CustomHandler.super.access(self)

  kong.log.inspect(config.environment) -- "development"
  kong.log.inspect(config.server.host) -- "http://localhost"
  kong.log.inspect(config.server.port) -- 8080
end

return CustomHandler

您还可以在Key-Auth插件源代码中查看schema的真实示例。

微服务 API 网关 Kong 插件开发 – 文件结构

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

本章假定你已经会使用Lua语言

介绍

将您的插件视为一组Lua模块。本章中描述的每个文件都被视为一个单独的模块。如果他们的名字遵循这个约定,Kong将检测并加载你的插件的模块:

kong.plugins.<plugin_name>.<module_name>

您的模块当然需要通过package.path变量访问,可以通过lua_package_path配置属性调整您的需求。但是,安装插件的首选方法是通过LuaRocks,它与Kong本身集成。有关LuaRocks安装的插件的更多信息,请参阅本指南后面的内容。

为了让Kong意识到必须查找插件的模块,你必须将它添加到配置文件中的plugins属性中,这是一个以逗号分隔的列表。例如

plugins = bundled,my-custom-plugin # 你的插件名称

或者,如果您不想加载任何自带的插件:

plugins = my-custom-plugin  # 你的插件名称

现在,Kong将尝试从以下命名空间加载几个Lua模块:

kong.plugins.my-custom-plugin.<module_name>

其中一些模块是必需的(例如handler.lua),有些是可选的,并且允许插件实现一些额外的功能(例如api.lua以扩展Admin API)。现在让我们准确描述您可以实现的模块以及它们的用途。

基本插件模块

在最基本的形式中,插件包含两个必需的模块:

simple-plugin
├── handler.lua
└── schema.lua
  • 每个函数将在请求的生命周期中的所需时刻运行。
  • 由用户。此模块保存该配置的模式并在其上定义规则,以便用户只能输入有效的配置值。

高级插件模块

有些插件可能需要与Kong更深入地集成:在数据库中拥有自己的表,在Admin API中公开端点等等……每个插件都可以通过向插件添加新模块来完成。如果它实现了所有可选模块,那么插件的结构如下:

complete-plugin
├── api.lua
├── daos.lua
├── handler.lua
├── migrations
│   ├── cassandra.lua
│   └── postgres.lua
└── schema.lua

以下是要实施的可能模块的完整列表以及其目的的简要说明。 本指南将详细介绍,让您掌握其中的每一个文件。

模块文件名称 是否必须 描述
api.lua No 定义Admin API中可用的端点列表,以与插件处理的实体自定义实体进行交互。
daos.lua No 定义DAO(数据库访问对象)列表,这些DAO是插件所需并存储在数据存储区中的自定义实体的抽象。
handler.lua Yes 一个接口的实现。每个函数都由Kong在请求的生命周期中的所需时刻运行。
migrations/xxxx.lua No 给定数据存储的相应迁移。只有当您的插件必须在数据库中存储自定义实体并通过daos.lua定义的其中一个DAO与它们进行交互时,才需要进行迁移。
schema.lua Yes 保存插件配置的架构,以便用户只能输入有效的配置值。

Key-Auth 插件是具有此文件结构的插件的示例。 有关详细信息,请参阅其源代码

微服务 API 网关 Kong 插件开发 – 安装/卸载插件

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

介绍

Kong的自定义插件由Lua源文件组成,这些源文件需要位于每个Kong节点的文件系统中。本指南将为您提供逐步说明,使Kong节点了解您的自定义插件。这些步骤应该应用于Kong集群中的每个节点,以确保每个节点上都有自定义插件。

打包源

您可以使用常规打包策略(例如tar),也可以使用LuaRocks包管理器为您执行此操作。我们推荐使用LuaRocks,因为它在使用其中一个官方分发包时与Kong一起安装。

使用LuaRocks时,您必须创建一个rockspec文件,用来指定包的内容。有关示例,请参阅Kong插件模板,有关该格式的更多信息,请参阅有关rockspecs的LuaRocks文档

使用以下命令打包你的rock(来自插件仓库):

# install it locally (based on the `.rockspec` in the current directory)
$ luarocks make

# 打包已安装的rock
$ luarocks pack <plugin-name> <version>

假设你的插件rockspec的名字为kong-plugin-myPlugin-0.1.0-1.rockspec,上面就会变成:

$ luarocks pack kong-plugin-myPlugin 0.1.0-1

LuaRocks pack命令现在已经创建了一个.rock文件(这只是一个包含安装rock所需内容的zip文件)。

如果您不使用或不能使用LuaRocks,则使用tar将插件所包含的.lua文件打包到.tar.gz存档中。 如果目标系统上有LuaRocks,也可以包含.rockspec文件。

该插件的内容应该接近以下内容:

$ tree <plugin-name>
<plugin-name>
├── INSTALL.txt
├── README.md
├── kong
│   └── plugins
│       └── <plugin-name>
│           ├── handler.lua
│           └── schema.lua
└── <plugin-name>-<version>.rockspec

安装插件

要使Kong节点能够使用自定义插件,必须在主机的文件系统上安装自定义插件的Lua源。有多种方法:通过LuaRocks,或手动。 选择一个,然后跳转到第3部分。

  1. 来自新建的’rock’的LuaRocks。
    .rock文件是一个自包含的软件包,可以在本地安装,也可以从远程服务器安装。
    如果您的系统中安装了luarocks实用程序(如果使用其中一个官方安装包,可能就是这种情况),您可以在LuaRocks树(LuaRocks安装Lua模块的目录)中安装“rock”。
    它可以通过以下方式安装:

     $ luarocks install <rock-filename>
    

    文件名可以是本地名称,或任何支持的方法。
    例如:http://myrepository.lan/rocks/myplugin-0.1.0-1.all.rock

  2. 从源档案中通过LuaRocks安装。 如果您的系统中安装了luarocks实用程序(如果使用其中一个官方安装包,可能就是这种情况),您可以在LuaRocks树(LuaRocks安装Lua模块的目录)中安装Lua源代码。
    您可以通过将当前目录更改为提取的存档来实现,其中rockspec文件是:

     $ cd <plugin-name>
    

    然后运行以下命令:

     $ luarocks make
    

    这将在系统的LuaRocks树中的kong/plugins/<plugin-name>中安装Lua源代码,其中所有的Kong源都已存在。

  3. 手动
    安装插件源的一种更保守的方法是避免“污染”LuaRocks树,而是将Kong指向包含它们的目录。
    这是通过调整Kong配置的lua_package_path属性来完成的。如果你熟悉它,那么这个属性是Lua VM的LUA_PATH变量的别名。
    这些属性包含以分号分隔的目录列表,用于搜索Lua源。它应该在您的Kong配置文件中设置如下:

     lua_package_path = /<path-to-plugin-location>/?.lua;
    

    继续:
    4./<path-to-plugin-location>是包含提取的存档的目录的路径。它应该是归档中kong目录的位置。
    5.?是一个占位符,将被kong.plugins替换。<plugin-name>当Kong将尝试加载你的插件。
    6.;;“默认Lua路径”的占位符。不要改变它。
    例如:
    插件位于文件系统上,使处理程序文件为:

     /usr/local/custom/kong/plugins/<something>/handler.lua
    

    kong目录的位置是:/usr/local/custom,因此正确的路径设置将是:

     lua_package_path = /usr/local/custom/?.lua;;
    

    多个插件:

    如果您希望以这种方式安装两个或更多自定义插件,可以将变量设置为:

      lua_package_path = /path/to/plugin1/?.lua;/path/to/plugin2/?.lua;;
    
     7.`;`是目录之间的分隔符。
     8.`;;`仍然意味着“默认的Lua路径”。
    

    注意:您还可以通过其等效的环境变量KONG_LUA_PACKAGE_PATH设置此属性。

提醒:无论您使用哪种方法来安装插件的源,您仍必须为Kong群集中的每个节点执行此操作。

加载插件

您现在必须将自定义插件的名称添加到Kong配置中的插件列表中(在每个Kong节点上):

plugins = bundled,<plugin-name>

或者,如果您不想包含默认捆绑的插件:

plugins = <plugin-name>

或者

plugins = plugin1,plugin2

注意:您还可以通过其等效的环境变量KONG_PLUGINS来设置此属性。 提醒:不要忘记更新Kong群集中每个节点的plugins指令。 提醒:插件重启后会生效:

kong restart

但是,如果你想在kong永不停止时应用插件,你可以使用:

kong prepare
kong reload

验证加载插件

你现在应该能够毫无问题地启动Kong。 请参阅自定义插件有关如何在服务,路由或消费者实体上启用/配置插件的说明。

为确保您的插件由Kong加载,您可以使用调试日志级别启动Kong:

log_level = debug

或者

KONG_LOG_LEVEL=debug

然后,您应该看到正在加载的每个插件的以下日志:

[debug] Loading plugin <plugin-name>

删除插件

完全删除插件有三个步骤。

  1. 从您的Kong Service或Route配置中删除插件。确保它不再适用于全局,也不适用于任何服务,路由或使用者。对于整个Kong集群,只需执行一次,不需要重新启动/重新加载。此步骤本身将使插件不再使用。但它仍然可用,仍然可以重新应用插件。
  2. plugins指令中删除插件(在每个Kong节点上)。确保在执行此操作之前已完成步骤1。在此步骤之后,任何人都无法将插件重新应用于任何Kong Service,Route,Consumer甚至全局。此步骤需要重新启动/重新加载Kong节点才能生效。
  3. 要彻底删除插件,请从每个Kong节点中删除与插件相关的文件。在删除文件之前,请确保已完成步骤2,包括重新启动/重新加载Kong。如果你使用LuaRocks来安装插件,你可以使用luarocks remove <plugin-name>来删除它。

分发插件

这样做的首选方法是使用LuaRocks,Lua模块的包管理器。它称这些模块为“rocks”。 您的模块不必存在于Kong存储库中,但如果您希望维护Kong设置,则可能就是这样。

通过在rockspec文件中定义模块(及其最终依赖项),您可以通过LuaRocks在您的平台上安装这些模块。

您也可以在LuaRocks上传模块并将其提供给所有人!

有关示例,请参阅Kong插件模板,有关该格式的更多信息,请参阅有关rockspecs的LuaRocks文档

故障排除

由于以下几个原因,配置错误的自定义插件可能无法启动:

  • “plugin is in use but not enabled” -> 您从另一个节点配置了一个自定义插件,并且该插件配置在数据库中,但您尝试启动的当前节点在其plugins指令中没有它。要解决此问题,请将插件的名称添加到节点的plugins指令中。
  • “plugin is enabled but not installed” -> 插件的名称出现在plugins指令中,但是Kong无法从文件系统加载handler.lua源文件。要解决此问题,请确保正确设置lua_package_path指令以加载此插件的Lua源。
  • “no configuration schema found for plugin” -> 插件已在plugins指令中安装,但是Kong无法从文件系统加载schema.lua源文件。要解决此问题,请确保schema.lua文件与插件的handler.lua文件一起存在。