配置详解 - 玩转Kong网关

配置加载

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

您可以通过在CLI中使用-c / -conf参数自定义配置文件路径来覆盖此默认配置：

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

配置格式很简单：注释由字符 # 定义。布尔值可以被指定为 on/off 或者true/false。

验证您的配置

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

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

这个命令，将检测您当前设置的环境变量，并且在您的设置错误时报错。

此外，您还可以在调试模式下使用CLI，以便更深入地了解正在启动的属性：

$ 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实例的一个重要部分，因为它允许您优化其性能，或者将Kong嵌入到已经运行的OpenResty实例中。

• 自定义Nginx配置

Kong可以用 --nginx-conf 的参数启动，重新加载和重新启动，该参数必须指定Nginx配置模板。这样的模板使用了Penlight模板引擎，它是使用给定的Kong配置编译的，然后在开始Nginx之前被保存到您的Kong前缀目录中。

默认模板可以在https://github.com/Kong/kong/tree/master/kong/templates
找到。它分为两个Nginx配置文件：nginx.lua 和 nginx_kong.lua。前者是运行Kong的最低的配置要求，其会包括后者。当Kong开始运行时，在开始Nginx之前，它将这两个文件复制到前缀目录中，看起来是这样的：

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

如果您希望在Nginx配置中包含其他服务模块，或者您必须调整不受Kong配置影响的全局设置，这里有一个建议：

# ---------------------
# 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 强制的
error_log logs/error.log ${
    {LOG_LEVEL}}; # can be set by kong.conf

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

http {
    # include default Kong Nginx config
    include 'nginx-kong.conf';

    # custom server
    server {
        listen 8888;
        server_name custom_server;

        location / {
          ... # etc
        }
    }
}

你可以这样启动Kong：

$ kong start -c kong.conf --nginx-conf custom_nginx.template

如果您希望自定义Kong的Nginx子配置文件，最终添加其他Lua处理程序或定制lua_*指令，您可以在custom_nginx.template内联nginx_kong.lua这个配置。模板示例文件如下:

# ---------------------
# 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 {
  resolver ${
    {DNS_RESOLVER}} ipv6=off;
  charset UTF-8;
  error_log logs/error.log ${
    {LOG_LEVEL}};
  access_log logs/access.log;

  ... # etc
}

• 在OpenResty里嵌入Kong

如果您正在运行您自己的OpenResty服务器，您也可以通过使用include指令（类似于上一节的示例）来轻松地嵌入Kong。如果您有一个有效的顶级NGINX配置，那么就可以简单的引入Kong的配置：

# my_nginx.conf

http {
    include 'nginx-kong.conf';
}

你可以像这样开始你的实例：

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

这样Kong就会运行在你的实例中。（Kong的配置在nginx-kong.conf里）

• Kong为网站和你的api提供服务

API提供者的一个常见用例是让Kong在代理端口上同时服务于一个网站和API本身——在生产中有80或443。例如：https://my-api.com（网站）和https://my-api.com/api/v1（API）。

为了实现这一点，我们不能简单地声明一个新的虚拟服务模块，就像我们在上一节中所做的那样。一个好的解决方案是使用一个定制的Nginx配置模板，该模板可以内联nginx_kong.lua。添加一个新的location块，与Kong代理location块一起服务于网站：

# ---------------------
# custom_nginx.te