這一部分應該在最開始介紹，但是我覺得在對kong有一定了解後再回頭看下配置，會理解的更深刻。接下來對這個配置文件裏的參數做個詳細對解釋便於更好的使用或優化kong網關。

目錄

• 一.配置加載
• 二.驗證配置
• 三.環境變量
• 四.自定義 Nginx 配置 & 嵌入式的Kong配置
• 1.自定義nginx配置
• 2.在OpenResty中嵌入Kong
• 3.為Kong提供WEB和API

• 五.屬性配置
  
  • 1.通用部分
  • 2.nginx部分
  • 3.數據存儲部分
  • 4.數據緩存部分
  • 5.DNS解析部分
  • 6.開發&雜項

配置加載

　　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

配置格式非常簡單：只需取消註釋任何屬性（註釋由＃字符定義）並將其修改為自己需要的值。為方便起見，布爾值可以指定為on/off或true/false

驗證配置

　　可以使用check命令驗證設置的完整性：

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

該命令將考慮您當前設置的環境變量，並且在您的設置無效的情況下會出錯。此外，還可以在debug模式下使用CLI來更深入地了解Kong正在啟動的屬性：

$ 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實例中。

1.自定義Nginx配置

　　Kong可以使用--nginx-conf參數執行啟動、重新加載、重新啟動的操作，該參數必須指定Nginx配置模板。此模板使用Penlight引擎，它使用指定的Kong配置進行編譯，並在啟動Nginx之前，將其轉儲到您的Kong前綴目錄中。

　　默認的模板文件為：https://github.com/Mashape/kong/tree/master/kong/templates。它分為兩個Nginx配置文件：nginx.lua和nginx_kong.lua。nginx_kong.lua包含了KONG啟動時的所有配置，nginx.lua則包含了nginx_kong.lua在內的所有配置。在啟動Nginx之前，請將這兩個文件復制到kong的根目錄下，類似與這樣：

/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 mandatory
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
}

2.在OpenResty中嵌入Kong

　　如果你運行自己的OpenResty服務器，還可以通過使用include指令（類似上一節例子）添加Kong Nginx的子配置文件來輕松嵌入Kong。如果你有一個有效的、只包含Kong特定配置的、top-level的NGINX配置：

# my_nginx.conf

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

你可以如下啟動你的實例：

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

Kong將在該實例中運行（如在nginx-kong.conf中配置一樣）。

3.為Kong提供WEB和API

　　API提供者的一個常見用例是讓Kong通過代理端口 - 服務器端口80或443服務於網站和API。例如，https://my-api.com（網站）和https://my-api.com/api/v1（API）。

為了實現這一點，我們不能簡單地聲明一個新的虛擬服務器模塊，就像我們在前一節中所做的那樣。一個好的解決方案是使用一個自定義的Nginx配置模板，該模板內聯nginx_kong.lua，並添加一個新的位置塊，用於服務該網站以及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 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/my-api.com;
      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
}

屬性配置

1.通用部分

prefix (默認 /usr/local/kong）

工作目錄。相當於Nginx的前綴路徑，包含臨時文件和日誌。每個Kong流程都必須有一個單獨的工作目錄。

log_level (默認 notice)

Nginx服務器的日誌級別。日誌可以在<前綴> /logs/error.log找到
有關可接受值的列表，請參閱http://nginx.org/en/docs/ngx_core_module.html#error_log。

proxy_access_log (默認 logs/access.log)

代理端口請求訪問日誌的路徑。將此值設置為off以禁用日誌記錄代理請求。如果這個值是一個相對路徑，它將被放置在prefix位置下。

proxy_error_log (默認 logs/error.log)

代理端口請求錯誤日誌的路徑。這些日誌的粒度由log_level指令進行調整

admin_access_log (默認 logs/admin_access.log)

管理API請求訪問日誌的路徑。將此值設置為off以禁用記錄管理API請求。如果這個值是一個相對路徑，它將被放置在prefix位置下。

admin_error_log (默認 logs/error.log)

管理API請求錯誤日誌的路徑。這些日誌的粒度由log_level指令進行調整。

custom_plugins (默認None，舉例：my-plugin,hello-world,custom-rate-limiting)

應加載此節點的逗號分隔的其他插件列表。使用此屬性加載未與Kong捆綁的自定義插件。插件將從kong.plugins.{name}.*命名空間中加載

anonymous_reports (默認 on)

發送匿名使用數據（如錯誤堆棧跟蹤）以幫助改進Kong。

2.nginx部分

proxy_listen (默認 0.0.0.0:8000, 0.0.0.0:8443 ssl 示例：0.0.0.0:80, 0.0.0.0:81 http2, 0.0.0.0:443 ssl, 0.0.0.0:444 http2 ssl)

　　代理服務器應該偵聽的地??址和端口的逗號分隔列表。代理服務器是Kong的公共入口點，它將消費者的流量代理到後端服務。該值接受IPv4，IPv6和主機名。

可以為每一對指定一些後綴：

• ssl將要求通過特定address/port進行的所有連接都是在啟用TLS的情況下進行的。
• http2將允許客戶端打開到Kong代理服務器的HTTP/2連接。
• 最後，proxy_protocol將啟用對給定address/port使用PROXY協議。

　　該節點的代理端口，啟用可以配置連接到同一數據庫的節點集群的“control-plane”模式（無流量代理功能）。
請參閱http://nginx.org/en/docs/http/ngx_http_core_module.html#listen以獲取有關此和其他* _listen值的可接受格式的說明。

admin_listen (默認 127.0.0.1:8001, 127.0.0.1:8444 ssl 示例 127.0.0.1:8444 http2 ssl)

管理界面應該監聽的地址和端口的逗號分隔列表。 Admin界面是允許您配置和管理Kong的API。只有Kong管理員才能訪問此界面。該值接受IPv4，IPv6和主機名。可以為每一對指定一些後綴：

• ssl將要求通過特定地址/端口進行的所有連接都是在啟用TLS的情況下進行的。
• http2將允許客戶端打開到Kong代理服務器的HTTP / 2連接。
• 最後，proxy_protocol將啟用對給定地址/端口使用PROXY協議。

可以將此值設置為off，從而禁用此節點的Admin界面，啟用“data-plane”模式（無配置功能）從數據庫中提取其配置更改。

nginx_user (默認 nobody nobody 示例 nginx www)

定義工作進程使用的用戶和組憑據。如果省略組，則使用名稱等於用戶名的組。

nginx_worker_processes (默認 auto)

確定Nginx產生的工作進程的數量。請參閱http://nginx.org/en/docs/ngx_core_module.html#worker_processes了解該指令的詳細用法以及可接受值的說明。

nginx_daemon (默認 on)

確定Nginx是作為後臺進程運行還是作為前臺進程運行。主要用於開發或在Docker環境中運行Kong時使用。請參閱http://nginx.org/en/docs/ngx_core_module.html#daemon。

mem_cache_size ( 默認128M)

數據庫實體的內存緩存大小。接受的單位是k和m，最小推薦值為幾MB。

ssl_cipher_suite （默認 modern）

定義Nginx提供的TLS密碼。接受的值是modern, intermediate, old或 custom。有關每個密碼套件的詳細說明，請參閱https://wiki.mozilla.org/Security/Server_Side_TLS。

ssl_ciphers (默認 None)

定義由Nginx提供的TLS密碼的自定義列表。該列表必須符合由openssl ciphers定義的模式。如果ssl_cipher_suite不是custom的，則該值將被忽略。

ssl_cert (默認 None)

啟用了SSL的proxy_listen值的SSL證書(certificate)的絕對路徑。

ssl_cert_key (默認 None)

啟用了SSL的proxy_listen值的SSL密鑰(key)的絕對路徑。

client_ssl (默認 off)

確定Nginx在代理請求時是否應發送客戶端SSL證書。

client_ssl_cert (默認 None)

如果啟用client_ssl，則為proxy_ssl_certificate指令的客戶端SSL證書的絕對路徑。請註意，此值靜態定義在節點上，並且當前不能基於每個API進行配置。

client_ssl_cert_key (默認None)

如果啟用client_ssl，則為proxy_ssl_certificate_key地址的客戶端SSL密鑰的絕對路徑。請註意，此值在節點上靜態定義，並且當前無法在每個API基礎上配置。

admin_ssl_cert (默認 None)

啟用了SSL的admin_listen值的SSL證書的絕對路徑。

admin_ssl_cert_key (默認 None)

啟用了SSL的admin_listen值的SSL密鑰的絕對路徑。

upstream_keepalive (默認60)

設置保留在每個輔助進程緩存中的上遊服務器的最大空閑保活連接數。當這個數字被超過時，最近最少使用的連接被關閉。

server_tokens (默認 on)

啟用或禁用在錯誤頁面和Server或Via（如果請求被代理）響應頭(response header)字段中發出Kong版本。

latency_tokens (默認 on)

啟用或禁用在X-Kong-Proxy-Latency和X-Kong-Upstream-Latency響應頭域中發布Kong延遲信息。

trusted_ips (默認 None)

定義已知可發送正確的X-Forwarded-*標頭的可信IP地址塊。來自可信IP的請求使得Kong向上遊轉發他們的X-Forwarded- *報頭。不可信的請求使得Kong插入它自己的X-Forwarded- *標頭。

該屬性還可以在Nginx配置中設置set_real_ip_from指令。它接受相同類型的值（CIDR塊），但是作為逗號分隔的列表。

要信任所有/\IP，請將此值設置為0.0.0.0/0,::/0。
如果指定了特殊值unix：，則所有UNIX域套接字都將被信任。

有關set_real_ip_from指令的更多詳細信息，請參閱Nginx文檔。

real_ip_header (默認 X-Real-IP)

定義其值將用於替換客戶端地址的請求標頭字段。該值在Nginx配置中設置相同名稱的ngx_http_realip_module指令。
如果此值接收proxy_protocol，則proxy_protocol參數將被附加到Nginx模板的listen指令。

有關此指令的說明，請參閱Nginx文檔。

real_ip_recursive (默認 off)

該值在Nginx配置中設置相同名稱的ngx_http_realip_module指令。

有關此指令的說明，請參閱Nginx文檔。

client_max_body_size (默認 0)

定義由Kong代理的請求允許的最大請求主體大小，在Content-Length請求頭中指定。如果請求超過這個限制，Kong將回復413（請求實體太大）。將此值設置為0將禁用檢查請求主體大小。

註意：請參閱Nginx文檔以獲取有關此參數的進一步說明。數字值可以用k或m作為後綴，以千字節或兆字節為單位表示限制。

client_body_buffer_size (默認 8k)

定義讀取請求主體的緩沖區大小。如果客戶端請求主體大於此值，則主體將被緩沖到磁盤。請註意，當主體緩存到磁盤時訪問或操作請求主體的Kong插件可能無法工作，因此建議將此值設置為盡可能高（例如，將其設置為與client_max_body_size一樣高以強制請求主體保留在內存中）。請註意，高並發環境將需要大量的內存分配來處理許多並發的大型請求體。

註意：請參閱Nginx文檔以獲取有關此參數的進一步說明。數字值可以用k或m作為後綴，以千字節或兆字節為單位表示限制。

error_default_type (默認 text/plain)

在請求Accept頭部缺失並且Nginx正在為請求返回錯誤時使用的默認的MIME類型。接受的值是text / plain，text / html，application / json和application / xml。

3.數據存儲部分

Kong將把所有的數據（如API，消費者和插件）存儲在Cassandra或PostgreSQL中。
屬於同一集群的所有Kong節點必須將自己連接到同一個數據庫。

從Kong v0.12.0開始：

PostgreSQL 9.4支持應被視為棄用。建議升級到9.5+
Cassandra 2.1支持應該被視為棄用。建議升級到2.2+

確定Kong節點將使用哪個PostgreSQL或Cassandra作為其數據存儲。可接受的值是postgres和cassandra。

默認：postgres

Postgres 設置

Cassandra設置

4.數據緩存部分

為了避免與數據存儲區進行不必要的通信，Kong將實體（例如API，消費者，證書等）緩存一段可配置的時間。如果實體更新，它也處理失效。

本節允許配置Kong關於緩存這些配置實體的行為。

5.DNS解析部分

　　Kong會將主機名解析為SRV或A記錄（按此順序，CNAME記錄將在過程中解除引用）。如果一個名稱被解析為SRV記錄，它也將通過從DNS服務器接收的port字段內容覆蓋任何給定的端口號。

DNS選項SEARCH和NDOTS（來自/etc/resolv.conf文件）將用於將短名稱擴展為完全合格的名稱。所以它會首先嘗試整個SEARCH列表中的SRV類型，如果失敗，它會嘗試SEARCH A記錄列表等。

在ttl的持續時間內，內部DNS解析器將負載均衡其通過DNS記錄中的條目獲得的每個請求。對於SRV記錄，權重(weight)字段將被遵守，但它只會使用記錄中最低優先級(lowest priority)的字段條目。

6.開發&雜項

從lua-nginx模塊繼承的其他設置允許更多的靈活性和高級用法。

有關更多信息，請參閱lua-nginx-module文檔：https：//github.com/openresty/lua-nginx-module。

apigateway-kong(七)配置說明