Kong配置项向导

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 start -c <kong.conf> --vv

环境变量

在加载配置文件中的变量时，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指令：

1. nginx_http_ 前缀的配置会注入 http 块；
2. nginx_proxy_ 前缀的配置会注入 server 块，处理Kong的代理配置；
3. nginx_admin_ 前缀的配置会注入 server 块，处理Kong的Admin API配置。
   举例说明，用户在 kong.conf 文件中配置：

nginx_proxy_large_client_header_buffers=16 128k

Kong会在Nginx配置文件中的 server 块中添加以下指令：

large_client_header_buffers 16 128k;

用户同样可以在环境变量中配置Nginx指令：

export KONG_NGINX_HTTP_OUTPUT_BUFFERS="4 64k"

Kong会在Nginx配置文件中的 http 块中添加以下指令：

output_buffers 4 64k;

通过文件注入Nginx指令

对于更复杂的配置方案，例如添加几个新 server 块，用户可以使用下述方式将配置引入Nginx
举例说明，这里创建一个名为 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"

现在启动Kong时，文件中的server块会添加到Nginx配置文件中。
如果 nginx_http_include 的配置项使用相对路径，需要结合 kong.conf 文件中的 prefix 配置

自定义Nginx模板 & 嵌入Kong

大多数情况下，使用上述的方法注入Nginx指令可以满足自定义Kong中Nginx实例的需求，用户无需自定义Nginx配置模板来管理Kong节点的配置和调优，但以下两种情况，推荐用户使用自定义Nginx配置模板：

• 极少数情况下，用户需要修改一些不能通过修改 kong.conf 文件改变的Nginx配置，这样可以修改Kong用于生成Nginx配置文件的模板；
• 另外一种情况，需要在运行中的OpenResty实例中嵌入Kong，用户可以重用Kong生成的配置并将它包含在现有的配置中

自定义Nginx模板

Kong在启动和重启时可以使用 --nginx-conf 参数指定Nginx配置模板，这个模板使用Penlight模板引擎，会在启动Nginx之前，结合Kong中的配置项进行编译，默认的配置在https://github.com/kong/kong/tree/master/kong/templates，总共有两份Nginx配置文件：nginx.lua 和 nginx_kong.lua，当启动Kong时，系统会在启动Nginx前，将这两个文件复制到 prefix配置对用的目录：

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

用户可以在自定义的模板文件中内联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 {
    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：

# my_nginx.conf
# ...your nginx settings...
http {
    include 'nginx-kong.conf';
    # ...your nginx settings...
}

用户可以这样启动Nginx实例：

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

Kong会运行在这份实例中，配置文件采用 nginx-kong.conf

Kong同时提供站点和网关服务

通常情况下，我们会使用Kong服务器，通过 80 或 443 端口，同时提供站点和网关服务，比如 https://example.net (站点) 和 https://example.net/api/v1 (接口)
为了实现这一目标，我们不能简单的声明一个新的server块，比较好的做法是使用自定义的Nginx配置模板内联 nginx_kong.lua，并且添加一个新的 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
  # ...
}