apigateway-kong(七)配置說明

　　這一部分應該在最開始介紹，但是我覺得在對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 設置

名稱	描述
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的數據中心
cassandra_schema_consensus_timeout	定義Cassandra節點之間每個模式共識等待期的超時（以毫秒為單位）。該值僅在遷移過程中使用。

 

4.數據緩存部分

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

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

db_update_frequency (默認 5s )

用數據存儲檢查更新實體的頻率（以秒為單位）。當節點通過管理API創建，更新或刪除實體時，其他節點需要等待下一輪（由該值配置）最終清除舊緩存實體並開始使用新實例。

db_update_propagation (默認 0s)

用於將數據存儲中的實體傳播到其他數據中心的副本節點(replica nodes)的時間（以秒為單位）。在分布式環境（如多數據中心Cassandra群集）中，此值應為Cassandra將行傳播(propagate)到其他數據中心所花費的最大秒數。設置后，該屬性將增加Kong傳播實體更改所花費的時間。單數據中心設置或PostgreSQL服務器應該不會出現這種延遲，並且該值可以安全地設置為0。

db_cache_ttl (默認3600s,即1h)

當由此節點緩存時，實體從數據存儲區生存的時間（以秒為單位）。根據此設置，數據庫未命中（無實體）也被緩存。如果設置為0，則此類緩存的實體/未命中將永不過期。

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)的字段條目。

dns_resolver (默認 None)

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

dns_hostsfile (默認 /etc/hosts)

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

dns_order (默認 LAST,SRV,A,CNAME )

解析不同記錄類型的順序。 LAST類型表示上次成功查找的類型（用於指定的名稱）。格式是一個（不區分大小寫）逗號分隔的列表。

dns_stale_ttl (默認 4s)

以秒為單位定義記錄在超過TTL時將保留在緩存中的時間。這個值將在后台獲取新的DNS記錄時使用。陳舊的數據將在記錄到期時使用，直到刷新查詢完成或經過了dns_stale_ttl秒數。

dns_not_found_ttl (默認 30s)

TTL在幾秒鍾內為空DNS響應和“（3）name error”響應。

dns_error_ttl (默認 1s)

錯誤響應的TTL。

dns_no_sync (默認 off)

如果啟用，則在緩存未命中時，每個請求都會觸發其自己的dns查詢。禁用時，對同一name/type的多個請求將同步到單個查詢。

6.開發&雜項

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

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

lua_ssl_trusted_certificate (默認 None)

PEM格式的Lua cosockets的證書頒發機構文件的絕對路徑。當啟用pg_ssl_verify或cassandra_ssl_verify時，此證書將用於驗證Kong的數據庫連接。參見文檔
lua_ssl_verify_depth (默認 1)

設置由lua_ssl_trusted_certificate設置的Lua套接字使用的服務器證書鏈中的驗證深度。
這包括為Kong的數據庫連接配置的證書。 參見文檔

lua_package_path （默認 None）

設置Lua模塊搜索路徑（LUA_PATH）。在開發或使用未存儲在默認搜索路徑中的自定義插件時非常有用。參見 文檔

lua_package_cpath （默認 None）

設置Lua C模塊搜索路徑（LUA_CPATH）參見文檔

lua_socket_pool_size (默認 30)

指定與每個遠程服務器關聯的每個Cosocket連接池的大小限制。參見文檔

 

累死寶寶了，終於結束了～