Kong配置參考

kong配置的官網說明：https://docs.konghq.com/1.0.x/configuration/

1. 配置加載

　　如果您通過其中一個官方軟件包安裝了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

　　您可以通過使用CLI中的-c / --conf 命令，自定義配置文件的路徑來覆蓋此行為：

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

　　配置格式很簡單：只需取消注釋任何屬性（注釋由＃字符定義），並根據您的需要進行修改。布爾值可以指定為on / off或true / false，使用起來很方便。

2. 驗證您的配置

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

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

　　此命令將驗證您當前設置的環境變量，如果您的設置無效，將會出錯。此外，您還可以在調試模式下使用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] cluster_listen = "0.0.0.0:7946"
2016/08/11 14:53:36 [debug] cluster_listen_rpc = "127.0.0.1:7373"
2016/08/11 14:53:36 [debug] cluster_profile = "wan"
2016/08/11 14:53:36 [debug] cluster_ttl_on_failure = 3600
2016/08/11 14:53:36 [debug] database = "postgres"
2016/08/11 14:53:36 [debug] log_level = "notice"
[...]

3. 環境變量

　　從配置文件中加載屬性時，Kong還會查找同名的環境變量。這允許您通過配置環境變量實現完全的配置Kong，這對於譬如基於容器或其他的一些基礎架構來說，是非常方便的。所有以KONG_為前綴的，格式為大寫並且命名相同的環境變量設置將會被覆蓋。

　　例如： log_level = debug # in kong.conf

　　可以重寫為： $ export KONG_LOG_LEVEL=error

4. 自定義 Nginx 配置 & 嵌入式的KONG配置

　　調整Nginx配置是設置Kong實例的重要組成部分，它允許您優化其基礎架構的性能，或者將Kong嵌入到已經運行的OpenResty實例中。

　　自定義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
}

5. 在OpenResty中嵌入Kong

　　如果您運行自己的OpenResty服務器，還可以通過使用include指令（包括上述的示例）添加Kong Nginx的子配置文件來輕松嵌入Kong。但是，您將需要最終配置文件而不是模板。為此，請使用compile命令，該命令將完整的編譯Nginx子配置並輸出到stdout：

$ bin/kong compile --conf kong.conf > /usr/local/openresty/conf/nginx-kong.conf

# now start OpenResty with a configuration that "includes" nginx-kong.conf
$ nginx -c /usr/local/openresty/conf/nginx.conf

　　NOTE：當以這種方式嵌入Kong時，您將必須確保：正確配置了用於編譯Nginx子配置的kong.conf並正常開啟了配置所需的第三方服務。這些服務包括數據庫等。

6. 配置屬性說明

　　Kong相關：

　　　　prefix：工作目錄。相當於Nginx的根目錄，其中包含臨時文件和日志文件。每個Kong進程必須有一個單獨的工作目錄。默認為 /usr/local/kong。

　　　　log_level：Nginx服務器的日志級別。日志可以在 <prefix> /logs/error.log 中找到。可用的配置參數，詳見 http://nginx.org/en/docs/ngx_core_module.html#error_log。默認為notice。

　　　　custom_plugins：該節點用於加載的附加插件列表，插件名稱用逗號分隔開。使用此屬性可以加載用戶自定義的、Kong未提供的插件。插件將從 kong.plugins {name}.* 形式的命名空間加載。默認為空，插件列表類似於my-plugin,hello-world,custom-rate-limiting的形式。

　　　　anonymous_reports：發送匿名的KONG使用數據，如錯誤堆棧等，以幫助改善Kong。默認為開啟on。

　　Nginx相關：

　　　　proxy_listen：Kong用來接收HTTP請求的地址和端口。這是Kong服務的公共入口點，您的用戶可以通過這個入口向KONG發送請求。可用的配置參數，詳見  http://nginx.org/en/docs/http/ngx_http_core_module.html#listen。默認為 0.0.0.0:8000。

　　　　proxy_listen_ssl：如果啟用ssl，此配置就是KONG用來接收HTTP請求的地址和端口。默認值為 0.0.0.0:8443。

　　　　admin_listen：Kong針對管理員提供的入口地址和端口。該API允許您配置和管理Kong，應該配置為持私的，並確保其是安全的。默認值為 0.0.0.0:8001。

　　　　admin_listen_ssl：在啟用ssl的情況下的管理員對kong進行管理的入口。默認值為 0.0.0.0:8444。

　　　　nginx_worker_processes：配置Nginx服務開啟后，可以產生的工作進程數。詳情參考 http://nginx.org/en/docs/ngx_core_module.html#worker_processes。默認為 auto。

　　　　nginx_daemon：配置Nginx是作為守護進程還是作為前台進程運行。主要用於開發或在Docker環境中運行Kong時。詳見 http://nginx.org/en/docs/ngx_core_module.html#daemon。默認為on。

　　　　mem_cache_size：數據庫緩存大小的配置。可使用的單位是k和m，最小推薦值為幾MB。默認值為 128M。

　　　　ssl：確定Nginx是否應該在proxy_listen_ssl地址上偵聽HTTP請求。如果禁用，Nginx將僅在proxy_listen上綁定，所有關於SSL的設置將被忽略。默認為開啟on。

　　　　ssl_cert：如果啟用ssl，則為proxy_listen_ssl地址的SSL證書的絕對路徑。如果沒有指定並啟用ssl，Kong將自動生成默認證書和密鑰。

　　　　ssl_cert_key：如果啟用ssl，則為proxy_listen_ssl地址的SSL密鑰的絕對路徑。

　　　　admin_ssl：配置Nginx是否監聽admin_listen_ssl地址上的HTTP請求。如果禁用，Nginx將僅在admin_listen上綁定，所有SSL設置將被忽略。默認為開啟on。

　　　　admin_ssl_cert：如果啟用了admin_ssl，則為admin_listen_ssl地址的SSL證書的絕對路徑。如果沒有指定，並且啟用了admin_ssl，Kong將生成默認證書和密鑰。

　　　　admin_ssl_key：如果啟用了admin_ssl，則為admin_listen_ssl地址的SSL密鑰的絕對路徑。

　　　　upstream_keepalive：設置保存在每個工作進程的緩存中的上游服務器的連接池的最大數值。超過此值時，則將最近使用的連接關閉。

　　數據庫相關：

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

　　　　database：配置此節點來指定KONG使用哪個數據庫（PostgreSQL或Cassandra）作為其數據存儲。可選的數據庫只有postgres和cassandra。默認為 postgres。

　　　　　　Postgres的設置：

　　　　　　　　pg_host：Postgres的服務器的主機地址

　　　　　　　　pg_port：Postgres的服務器的端口

　　　　　　　　pg_user：Postgres用戶名

　　　　　　　　pg_password：Postgres的用戶密碼

　　　　　　　　pg_database：要連接的數據庫實例名，必須存在

　　　　　　　　pg_ssl：是否啟用與服務器的SSL連接

　　　　　　　　pg_ssl_verify：如果啟用了pg_ssl，則切換服務器證書驗證。請參閱lua_ssl_trusted_certificate設置。

　　　　　　Cassandra的設置：

　　　　　　　　cassandra_contact_points：集群名稱列表，以逗號分隔

　　　　　　　　cassandra_port：您的節點正在監聽的端口

　　　　　　　　cassandra_keyspace：您在群集中使用的密鑰空間，如果不存在將被自動創建

　　　　　　　　cassandra_consistency：設置讀寫操作的一致性

　　　　　　　　cassandra_timeout：讀寫操作的超時設定，單位為毫秒ms

　　　　　　　　cassandra_ssl：配置啟用SSL連接

　　　　　　　　cassandra_ssl_verify：如果啟用cassandra_ssl，則切換服務器證書驗證。請參閱lua_ssl_trusted_certificate設置

　　　　　　　　cassandra_username：使用PasswordAuthenticator方案時的用戶名

　　　　　　　　cassandra_password：使用PasswordAuthenticator方案時的用戶密碼

　　　　　　　　cassandra_consistency：讀/寫Cassandra群集時使用的一致性設置

　　　　　　　　cassandra_lb_policy：在Cassandra群集中分發查詢時使用的負載均衡策略。接受的值是RoundRobin和DCAwareRoundRobin。當且僅當您使用多數據中心集群時方可配置，此時，請同時配置cassandra_local_datacenter選項

　　　　　　　　cassandra_local_datacenter：當使用DCAwareRoundRobin策略時，必須在KONG節點中指定本地集群的名稱

　　　　　　　　cassandra_repl_strategy：如果是首次創建密鑰空間，請指定復制策略

　　　　　　　　cassandra_repl_factor：指定SimpleStrategy的復制條件

　　　　　　　　cassandra_data_centers：指定NetworkTopologyStrategy的數據中心

　　節點相關：

　　　　除了指向同一個數據庫之外，每個Kong節點都必須加入同一個集群。Kong的節點工作在IP層（主機名不被支持，只有IP），並且為平面網絡拓撲，但數據中心之間沒有任何NAT（網絡地址轉換）。一種常見的模式是在兩個數據中心之間創建一個VPN，這樣就不會違反平面網絡原則。有關更多信息，請參閱  https://getkong.org/docs/latest/clustering/。

　　　　cluster_listen：用於與群集中的其他節點通信的地址和端口。同一集群中的所有其他Kong節點必須能夠通過TCP和UDP進行通信。只支持IPv4地址。默認值為 0.0.0.0:7946。

　　　　cluster_listen_rpc：用於通過此節點上運行的代理與群集通信的地址和端口。僅包含此節點本地的TCP流量。默認為 127.0.0.1:7373。

　　　　cluster_advertise：缺省情況下，cluster-listen地址通過集群發布。如果cluster_listen主機為“0.0.0.0”，則首個本地非環回IPv4地址將通告給其他節點。然而，在某些情況下（特別是NAT穿越），可能存在無法綁定路由地址。該標志可以通知不同的地址來支持這一點(This flag enables advertising a different address to support this)。

　　　　cluster_encrypt_key：基於Base64編碼的16字節密鑰，用於加密集群通訊。

　　　　cluster_keyring_file：指定一個文件來加載密鑰環數據。 Kong能夠保持加密密鑰同步並執行密鑰回轉。在密鑰回轉過程中，可能需要一段時間才能保留多個加密密鑰，直到所有成員都收到新密鑰為止。

　　　　cluster_ttl_on_failure：當集群停止發送healthcheck ping（可能由節點或網絡故障引起）時，節點的生存時間（單位為秒）。如果節點在到期之前無法發送新的healthcheck ping，則集群中的其他節點將停止重新連接到該節點的操作。建議至少60。默認為3600秒。

　　　　cluster_profile：群集間ping和超時的時序配置文件。如果通過互聯網使用lan或local的配置文件，時序限制越緊越容易產生風險。可配置的值為local,lan,wan，默認為wan。

　　DNS解析器相關：

　　　　Kong會將主機名解析為SRV或A記錄（按此順序，CNAME記錄將在該過程中被取消引用）。如果名稱被解析為SRV記錄，它還將通過從dns服務器接收的port字段內容來覆蓋任何給定的端口號。對於ttl的持續時間，內部dns解析器將對通過dns記錄中的條目的每個請求進行負載平衡。對於SRV記錄，權重字段將被保留，但只會使用記錄中最低優先級的字段條目。

　　　　dns_resolver：由逗號分隔的服務器名稱列表，每個條目的格式為 ipv4 [：port]。如果未指定，將使用本地 resolv.conf 文件中的服務器名稱。如果省略，則默認端口號為53。

　　　　dns_hostsfile：hosts文件。該文件在啟動時被讀取一次，其在內存中是靜態的。如果要修改此文件，必須重新加載服務。默認路徑為 /etc/hosts。

　　開發者和其他相關：

　　　　從lua-nginx模塊繼承的其他設置允許更多的靈活性和更多功能。有關更多信息，請參閱  https://github.com/openresty/lua-nginx-module。

　　　　lua_ssl_trusted_certificate：用於PEM格式的Lua容器證書文件的絕對路徑。當pg_ssl_verify或cassandra_ssl_verify被啟用時，可使用此證書來驗證Kong的數據庫連接。詳參 https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate。

　　　　lua_ssl_verify_depth：通過由lua_ssl_trusted_certificate配置的Lua倉庫，並使用服務器證書鏈來設置驗證的深度(verification depth)。這里包含了Kong數據庫連接配置的證書。詳參 https://github.com/openresty/lua-nginx-module#lua_ssl_verify_depth，默認值為1。

　　　　lua_code_cache：禁用時，每個請求都將在單獨的Lua VM實例中運行：所有Lua模塊將從頭開始加載，有助於在開發插件時進行重新編譯和刷新。關閉此指令對性能有嚴重的影響。詳參 https://github.com/openresty/lua-nginx-module#lua_code_cache，默認為開啟on。

　　　　lua_package_path：設置Lua模塊搜索路徑（LUA_PATH）。當自定義的插件為存儲在默認路徑或者在進行開發時，會比較有用。詳參 https://github.com/openresty/lua-nginx-module#lua_package_path。

　　　　lua_package_cpath：設置Lua C模塊搜索路徑（LUA_CPATH）。詳參 https://github.com/openresty/lua-nginx-module#lua_package_cpath。

　　　　lua_socket_pool_size：指定與每個遠程服務器關聯的每個cosocket連接池的大小。詳參  https://github.com/openresty/lua-nginx-module#lua_socket_pool_size，默認值為30。