kong 学习（二）

配置参考

配置加载

Kong附带有一个默认配置文件，/etc/kong/kong.conf.default,如果您通过其中一个官方软件包安装了Kong ，则可以找到该文件 。要开始配置Kong，您可以复制以下文件：

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

如果注释掉了配置中的所有值，则Kong将使用默认设置运行。开始时，Kong查找可能包含配置文件的几个默认位置：

1
2
/etc/kong/kong.conf
/etc/kong.conf

可以通过使用-c 或者 --conf 参数为配置文件指定自定义路径来覆盖此行为:

kong start -c /etc/kong/kong.conf

kong reload --conf /etc/kong/kong.conf

配置格式很简单：只需取消注释任何属性（注释由#字符定义），然后根据需要进行修改即可。为了方便，可以将布尔值指定为on/ off或true/ false。

验证配置

可以通过以下命令来验证kong的配置是否正确

1
2
3
kong check /etc/kong/kong.conf

configuration at /etc/kong/kong.conf is valid

环境变量

从配置文件中加载属性时，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_将注入到server处理Kong代理端口的block指令中。
  • 前缀为的条目nginx_admin_将注入到server处理Kong的Admin API端口的block指令中。

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

nginx_proxy_large_client_header_buffers=16 128k

这个将会在Kong中Nginx的server中添加：

large_client_header_buffers 16 128k;

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

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

例如，如果您创建一个my-server.kong.conf具有以下内容的文件：

1
2
3
4
5
6
7
8
9
# 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时，该server文件中的部分将添加到该文件中，这意味着其中定义的自定义服务器将与常规Kong端口一起响应：

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

请注意，如果在nginx_http_include属性中使用相对路径，则该路径将相对于文件prefix属性kong.conf的值（或在启动Kong时使用它覆盖前缀的-p标志的值kong start）进行解释，所以建议使用绝对路径

更多配置参考kong官方文档

kong 命令行的一些参数

全局可使用参数

  • --help：打印命令的帮助消息
  • --v：启用详细模式
  • --vv：启用调试模式

其他可选命令

kong check

检查配置文件是否正确

1
kong check /etc/kong/kong.conf

kong config

1
2
3
4
5
6
7
8
9
#声明式的使用Kong的配置文件
#可使用的命令如下：
 init    #生成一个示例配置文件来启动。
 db_import <file>  #将声明性配置文件导入到Kong数据库中。
 db_export <file>  #将Kong数据库导出到一个声明性配置文件中。
 parse <file>  # 解析声明性配置文件(检查其语法)，但不要将其加载到Kong中。
# 可选参数
-c,--conf  #配置文件
 -p,--prefix # 覆盖原有的Kong目录前缀

kong health

检查kong的状态

kong migrations

kong数据库迁移相关的

命令：

1
2
3
4
5
6
7
8
9
10
11
bootstrap  # 引导数据库并运行所有迁移。

up #运行新的迁移文件

finish  # 在“up”之后，运行所有挂起的迁移。

list  #列出执行的迁移

reset #重置数据库

 migrate-apis  # 将API实体迁移到路由和服务。

kong prepra

这个命令准备Kong前缀文件夹及其子文件夹和文件。

例如：

1
2
3
kong migrations up
 kong prepare -p /usr/local/kong -c kong.conf
 nginx -p /usr/local/kong -c /usr/local/kong/nginx.conf

kong quit

退出正在运行的kong节点

kong reload

重载kong 节点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Usage: kong reload [OPTIONS]

Reload a Kong node (and start other configured services
if necessary) in given prefix directory.

This command sends a HUP signal to Nginx, which will spawn
new workers (taking configuration changes into account),
and stop the old ones when they have finished processing
current requests.

Options:
 -c,--conf        (optional string) configuration file
 -p,--prefix      (optional string) prefix Kong is running at
 --nginx-conf     (optional string) custom Nginx configuration template

kong restart

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Usage: kong restart [OPTIONS]

Restart a Kong node (and other configured services like Serf)
in the given prefix directory.

This command is equivalent to doing both 'kong stop' and
'kong start'.

Options:
 -c,--conf        (optional string)   configuration file
 -p,--prefix      (optional string)   prefix at which Kong should be running
 --nginx-conf     (optional string)   custom Nginx configuration template
 --run-migrations (optional boolean)  optionally run migrations on the DB
 --db-timeout     (default 60)
 --lock-timeout   (default 60)


重启

kong start

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Usage: kong start [OPTIONS]

Start Kong (Nginx and other configured services) in the configured
prefix directory.

Options:
 -c,--conf        (optional string)   Configuration file.

 -p,--prefix      (optional string)   Override prefix directory.

 --nginx-conf     (optional string)   Custom Nginx configuration template.

 --run-migrations (optional boolean)  Run migrations before starting.

 --db-timeout     (default 60)        Timeout, in seconds, for all database
                                      operations (including schema consensus for
                                      Cassandra).

 --lock-timeout   (default 60)        When --run-migrations is enabled, timeout,
                                      in seconds, for nodes waiting on the
                                      leader node to finish running migrations.


kong stop

停止运行的kong实例

1
2
3
4
5
6
7
8
9
10
Usage: kong stop [OPTIONS]

Stop a running Kong node (Nginx and other configured services) in given
prefix directory.

This command sends a SIGTERM signal to Nginx.

Options:
 -p,--prefix      (optional string) prefix Kong is running at

kong version

查看版本

1
2
3
4
5
6
7
8
9
Usage: kong version [OPTIONS]

Print Kong's version. With the -a option, will print
the version of all underlying dependencies.

Options:
 -a,--all         get version of all dependencies


代理设置

介绍

Kong公开了几个接口，可以通过两个配置属性对其进行调整

  • proxy_listen，它定义了一个地址/端口列表，Kong将在这些地址/端口上接受来自客户端的公共流量并将其代理到您的上游服务（8000默认情况下）。
  • admin_listen，它还定义了地址和端口的列表，但是应该限制这些地址和端口只能由管理员访问，因为它们会显示Kong的配置功能：Admin API（8001默认情况下）。

注意：从1.0.0开始，API实体已被删除。本文档将涵盖与新的路线和服务实体的代理。 相关文档可以参考kong docs

术语

  • client：指下游客户端向Kong的代理端口发出请求。
  • upstream service：指位于Kong后面的您自己的API 服务，客户端请求将转发到该API 服务。
  • Service：服务实体，顾名思义，是您自己的每个上游服务的抽象。服务的示例将是数据转换微服务，计费API等。
  • Route：这指的是Kong Routes实体。路由是进入Kong的入口点，它定义了要匹配的请求的规则，并路由到给定的服务。
  • Plugin：这是指Kong“插件，它们是在代理生命周期中运行的业务逻辑。可以通过Admin API配置插件-可以全局（所有传入流量）或在特定的路由和服务上进行配置。

概述

从高层次的角度来看，kong将监听来自配置端口的HTTP流量（默认情况下8000和8443）。Kong将根据您配置的路由评估任何传入的HTTP请求，并尝试查找匹配的请求。如果给定请求符合特定路线的规则，则Kong将处理代理请求。

因为每个路由都对应着服务，kong将运行您在路由及其相关服务上配置的插件，然后在上游代理请求。您可以通过Kong的Admin API管理路线。不同的route的请求会有不同的route属性，kong支持这些协议：HTTP/HTTPS, gRPC/gRPCS, 和 TCP/TLS。

不同协议的请求下的route属性：

  • http: methods, hosts, headers, paths (如果是https，还有snis)
  • tcp: sources, destinations (如果是tls，还有snis)
  • grpc: hosts, headers, paths (如果是grpcs，还有snis)

如果尝试使用不支持的路由属性配置路由,例如，http带有sources或destinations，则会报告一条错误消息：

1
2
3
4
5
6
7
8
9
10
11
12
13
HTTP/1.1 400 Bad Request
Content-Type: application/json
Server: kong/<x.x.x>

{
    "code": 2,
    "fields": {
        "sources": "cannot set 'sources' when 'protocols' is 'http' or 'https'"
    },
    "message": "schema violation (sources: cannot set 'sources' when 'protocols' is 'http' or 'https')",
    "name": "schema violation"
}

如果Kong收到其无法与任何已配置的路由匹配的请求（或者如果未配置任何路由），它将以以下方式响应：

1
2
3
4
5
6
7
HTTP/1.1 404 Not Found
Content-Type: application/json
Server: kong/<x.x.x>

{
    "message": "no route and no Service found with those values"
}

路由和匹配能力

Kong支持HTTP / HTTPS，TCL / TLS和GRPC / GRPCS协议的本地代理；如前所述，这些协议中的每一个都接受一组不同的路由属性：

  • http: methods, hosts, headers, paths (如果是https，还有snis)
  • tcp: sources, destinations (如果是tls，还有snis)
  • grpc: hosts, headers, paths (如果是grpcs，还有snis)

请注意，这些字段并不是都必须的，但是必须得填写其中一项。

对于需要匹配的路由：

  • 该请求必须包含所有已配置的字段
  • 请求中字段的值必须至少与配置的值之一匹配（虽然字段配置接受一个或多个值，但请求仅需要将其中一个值视为匹配项）

如果路由设置如下：

1
2
3
4
5
{
    "hosts": ["example.com", "foo-service.com"],
    "paths": ["/foo", "/bar"],
    "methods": ["GET"]
}

这将匹配到下列请求：

1
2
GET /foo HTTP/1.1
Host: example.com
1
2
3
GET /bar HTTP/1.1
Host: foo-service.com

1
2
3
GET /foo/hello/world HTTP/1.1
Host: example.com

所有这三个请求均满足在路由定义中设置的所有条件。

但是，以下请求将不符合配置的条件：

1
2
3
4
#请求路径不匹配
GET / HTTP/1.1
Host: example.com

1
2
3
4
#请求方式不匹配
POST /foo HTTP/1.1
Host: example.com

1
2
3
4
#请求host不匹配
GET /foo HTTP/1.1
Host: foo.com

preserve_host

代理时，Kong的默认行为是将上游请求的Host标头设置为Service的中指定的主机名host。该 preserve_host字段接受一个布尔型标志，禁止或者允许Kong来发送或者不发送主机名。

默认情况下preserve_host设置的是false

1
2
3
4
5
6
{
    "hosts": ["service.com"],
    "service": {
        "id": "..."
    }
}

客户对Kong的可能请求可能是：

1
2
GET / HTTP/1.1
Host: service.com

Kong将从Service的host属性中提取Host标头值，并将发送以下上游请求：

1
2
GET / HTTP/1.1
Host: <my-service-host.com>

但是，通过显式配置Route preserve_host=true：

1
2
3
4
5
6
7
{
    "hosts": ["service.com"],
    "preserve_host": true,
    "service": {
        "id": "..."
    }
}

并假设来自客户端的相同请求：

1
2
3
GET / HTTP/1.1
Host: service.com

Kong将保留客户端请求上的主机，并改为发送以下上游请求：

1
2
GET / HTTP/1.1
Host: service.com

代理

代理和上游超时

Kong执行完所有必要的逻辑（包括插件）后，便可以将请求转发到上游服务。这是通过Nginx的ngx_http_proxy_module完成的 。您可以通过以下服务属性为Kong和给定的上游之间的连接配置所需的超时：

  • upstream_connect_timeout：以毫秒为单位定义与上游服务建立连接的超时时间。默认为60000。
  • upstream_send_timeout：以毫秒为单位定义两次连续写操作之间的超时，用于将请求传输到上游服务。默认为60000。
  • upstream_read_timeout：以毫秒为单位定义两次连续读取操作之间的超时，以从上游服务接收请求。默认为60000。

Kong将通过HTTP / 1.1发送请求，并设置以下标头：

  • Host: ，如本文档先前所述。
  • Connection: keep-alive，以允许重用上游连接。
  • X-Real-IP: <remote_addr>，其中$remote_addr变量的名称与ngx_http_core_module提供的名称相同 。请注意， $remote_addr可能被ngx_http_realip_module覆盖 。
  • X-Forwarded-For: <address>，其中ngx_http_realip_module提供 $realip_remote_addr``<address>的内容 以相同的名称附加到请求标头中。
  • X-Forwarded-Proto: <protocol>，<protocol>显示使用什么协议。如果$realip_remote_addr是受信任 地址之一，则提供相同名称的请求标头将被转发。否则，将使用ngx_http_core_module的$scheme提供的变量 的值。
  • X-Forwarded-Host: <host>，<host>是客户端发送的主机名。如果$realip_remote_addr是受信任 地址之一，则提供相同名称的请求标头将被转发。否则，将使用ngx_http_core_module``$host提供的变量 的值。
  • X-Forwarded-Port: <port>，<port>是接受请求的服务器的端口。如果$realip_remote_addr是 受信任地址之一，则提供相同名称的请求标头将被转发。否则，将使用ngx_http_core_module``$server_port提供的变量 的值。

其他所有请求标头均由Kong按原样转发。

使用WebSocket协议时，对此有一个例外。如果是这样，Kong将设置以下标头以允许在客户端和上游服务之间升级协议：

  • Connection: Upgrade
  • Upgrade: websocket
Linux
#kong
kong 学习（二）
https://randzz.cn/7121a05e5e01/kong-学习（二）/
作者
Ezreal Rao
发布于
2020年6月7日
许可协议