配置参考
配置加载
Kong附带有一个默认配置文件,/etc/kong/kong.conf.default
,如果您通过其中一个官方软件包安装了Kong ,则可以找到该文件 。要开始配置Kong,您可以复制以下文件:
cp /etc/kong/kong.conf.default /etc/kong/kong.conf
如果注释掉了配置中的所有值,则Kong将使用默认设置运行。开始时,Kong查找可能包含配置文件的几个默认位置:
/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
的配置是否正确
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
具有以下内容的文件:
# 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
端口一起响应:
$ 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
检查配置文件是否正确
kong check /etc/kong/kong.conf
kong config
#声明式的使用Kong的配置文件
#可使用的命令如下:
init #生成一个示例配置文件来启动。
db_import <file> #将声明性配置文件导入到Kong数据库中。
db_export <file> #将Kong数据库导出到一个声明性配置文件中。
parse <file> # 解析声明性配置文件(检查其语法),但不要将其加载到Kong中。
# 可选参数
-c,--conf #配置文件
-p,--prefix # 覆盖原有的Kong目录前缀
kong health
检查kong
的状态
kong migrations
kong
数据库迁移相关的
命令:
bootstrap # 引导数据库并运行所有迁移。
up #运行新的迁移文件
finish # 在“up”之后,运行所有挂起的迁移。
list #列出执行的迁移
reset #重置数据库
migrate-apis # 将API实体迁移到路由和服务。
kong prepra
这个命令准备Kong前缀文件夹及其子文件夹和文件。
例如:
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
节点
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
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
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
实例
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
查看版本
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
,则会报告一条错误消息:
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
收到其无法与任何已配置的路由匹配的请求(或者如果未配置任何路由),它将以以下方式响应:
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
)
请注意,这些字段并不是都必须的,但是必须得填写其中一项。
对于需要匹配的路由:
- 该请求必须包含所有已配置的字段
- 请求中字段的值必须至少与配置的值之一匹配(虽然字段配置接受一个或多个值,但请求仅需要将其中一个值视为匹配项)
如果路由设置如下:
{
"hosts": ["example.com", "foo-service.com"],
"paths": ["/foo", "/bar"],
"methods": ["GET"]
}
这将匹配到下列请求:
GET /foo HTTP/1.1
Host: example.com
GET /bar HTTP/1.1
Host: foo-service.com
GET /foo/hello/world HTTP/1.1
Host: example.com
所有这三个请求均满足在路由定义中设置的所有条件。
但是,以下请求将不符合配置的条件:
#请求路径不匹配
GET / HTTP/1.1
Host: example.com
#请求方式不匹配
POST /foo HTTP/1.1
Host: example.com
#请求host不匹配
GET /foo HTTP/1.1
Host: foo.com
preserve_host
代理时,Kong
的默认行为是将上游请求的Host
标头设置为Service
的中指定的主机名host
。该 preserve_host
字段接受一个布尔型标志,禁止或者允许Kong
来发送或者不发送主机名。
默认情况下preserve_host
设置的是false
{
"hosts": ["service.com"],
"service": {
"id": "..."
}
}
客户对Kong的可能请求可能是:
GET / HTTP/1.1
Host: service.com
Kong
将从Service
的host
属性中提取Host
标头值,并将发送以下上游请求:
GET / HTTP/1.1
Host: <my-service-host.com>
但是,通过显式配置Route
preserve_host=true
:
{
"hosts": ["service.com"],
"preserve_host": true,
"service": {
"id": "..."
}
}
并假设来自客户端的相同请求:
GET / HTTP/1.1
Host: service.com
Kong将保留客户端请求上的主机,并改为发送以下上游请求:
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