kong配置参考

加载配置

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

也可以通过-c / --conf参数指定自定义的配置文件

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

检查配置

可以通过check命令检查配置文件的正确性

kong check <path/to/kong.conf>

环境变量

除了配置文件，kong允许通过设置环境变量来覆盖配置文件中的配置项，环境变量规则为：添加KONG_前缀，并将配置项大写，比如

log_level = debug # in kong.conf

可以通过如下环境变量来覆盖上面配置文件中的配置项

export KONG_LOG_LEVEL=error

注入nginx指令

kong配置中，以nginx_http_, nginx_proxy_ or nginx_admin_开头的配置将转换成同等的nginx配置（去掉前缀），添加到nginx配置文件中适当的位置

nginx_http_将添加到http 指令块
nginx_proxy_ 将添加到server指令块处理kong代理端口
nginx_admin_将添加到server指令块处理kong的admin api端口

比如添加如下配置到kong.conf

nginx_proxy_large_client_header_buffers=16 128k

将添加如下配置到nginx配置的server 块

large_client_header_buffers 16 128k;

同样的，跟其他配置项一样也支持环境变量配置

export KONG_NGINX_HTTP_OUTPUT_BUFFERS="4 64k"

将添加如下配置项到nginx配置的http块

output_buffers 4 64k;

通过注入nginx配置指令include配置文件

比如创建了如下配置文件my-server.kong.conf

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

可以通过kong.conf或者环境变量添加配置

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

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

这时可以访问2112端口了

如果指定的包含文件是相对路径，它将相对kong.conf文件中的prefix配置值或者启动kong时通过-p参数指定的路径

自定义nginx模板并且嵌入到kong

绝大多数情况下你可以通过上续的方法定制kong的nginx实例的行为，通过单个kong.conf管理kong的配置和调优，而无需自定义nginx配置模板。但是有两种情况你可能需要用到nignx的配置模板：

在极少数情况下，无法通过kong.conf的标准属性来调整nginx配置
在已经运行的openresty实例中嵌入kong

自定义nginx模板

kong可以使用--nginx-conf参数指定一个nginx配置模板来启动、重新加载或者重启，nginx模板使用Penlight模板引擎，该引擎使用给定的Kong配置进行编译，然后在启动Nginx之前将其转储到您的Kong前缀目录中。

默认的模板可以在https://github.com/kong/kong/tree/master/kong/templates找到，它分割为了个nginx配置文件：nginx.lua 和 nginx_kong.lua，前者是简约的，并且引入了后者，包含了运行kong需要的所有东西。当kong启动的时候，nginx会优先启动，并且复制这两个文件到prefix 目录（-p指定的目录），就像如下所示：

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

如果你必须调整由kong定义但又不能通过kong.conf文件配置的全局设置，可以将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
}

然后使用如下命令启动kong

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

在openresty中嵌入kong

如果你已经运行了自己的openresty服务器，你也可以很容易的使用include指令引入kong nginx子配置来嵌入kong。如果你已经有了一个nginx配置文件，你可以简单的通过kong输出一些特定的配置到一个单独的配置文件nginx-kong.conf:

# my_nginx.conf

# ...your nginx settings...

http {
    include 'nginx-kong.conf';

    # ...your nginx settings...
}

使用如下命令启动openresty

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

然后kong将运行在这个实例中。

同时提供网站和api服务

一个常见的api服务场景是通过80或者443端口同时提供网站和api服务，比如https://example.net（网站）以及https://example.net/api/v1（api）
为了实现这个目的，我们不能像前面已经简单的定义两个新的虚拟server块，一个更好的解决方案是使用自定义nginx配置模板内联nginx_kong.lua，并添加一个新的location块为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
  # ...
}