Kong API Gateway 配置文件详解

2018-09-24 /  Linuxops

版权说明:本文为博主原创,如果转载请注明来源。作为学习笔记,不能保证所有知识点是完全正确以及表达无误,用于生产环境配置时请斟酌。如有错误或建议请联系。侵删联系:linuxops@qq.com。感谢各位!

一、前言

Kong配置文件是Kong服务的核心文件,它配置了Kong以怎么的方式运行,并且依赖于这个配置生成Nginx的配置文件,本文通过解读Kong配置文件,以了解Kong的运行和配置。

在成功安装Kong以后,会有一个名为kong.conf.default默认的配置文件示例,如果是通过包管理器安装的,通常位于/etc/kong/kong.conf.default,我们要将其复制为kong.conf以便于我们修改使用他。

在Kong的配置文件中,约定了以下的几条规则:

  • 配置文件中以#开头的行均为注释行,程序不会读取这些内容。
  • 在官方提供的默认配置文件中,以#开头的有值的配置项目均为默认配置。
  • 所有的配置项,均可以在系统环境变量中配置,但是必须要加上KONG_为前缀。
  • 值为布尔型的配置,可以使用on/off或者true/false
  • 值为列表的,必须使用半角逗号分割。

Kong的配置,大概分为几种,分别是:

  • 常规配置:配置服务运行目录,插件加载,日志等等
  • NGINX配置:配置Nginx注入,例如监听IP和端口配置等等,用于Kong在启动的时候生成Nginx配置文件
  • 数据库存储配置:配数据库类型,地址、用户名密码等等信息
  • 数据库缓存配置:配置数据的缓存规则,Kong会缓存诸如API信息、用户、凭证等信息,以减少访问数据库次数提高性能
  • DNS解析器配置:默认情况会使用系统设置,如hostsresolv.conf的配置,你也可以通过DNS的解析器配置来修改
  • 其他杂项配置:继承自lua-nginx模块的其他设置允许更多的灵活性和高级用法。

下面我们一个模块一个模块解释一下各项的配置。

二、常规配置

在常规配置中,主要是控制Kong一些运行时的一些配置,主要有如下配置:

配置项默认值说明
prefix/usr/local/kong/配置Kong的工作目录,相当于Nginx的工作目录,这个目录存放运行时的临时文件和日志,包括Kong启动的时候自动生成的Nginx的配置文件。
每一个Kong经常必须有一个单独的工作目录
log_levelnoticeNginx的日志级别。日志存放/logs/error.log
proxy_access_loglogs/access.log代理端口请求的日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。
如果设置了相对路径,则日志文件会保存在的目录下
proxy_error_loglogs/error.log代理端口请求的错误日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。
如果设置了相对路径,则日志文件会保存在的目录下
admin_access_loglogs/admin_access.logKong管理的API端口请求的日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。
如果设置了相对路径,则日志文件会保存在的目录下
admin_error_loglogs/error.logKong管理的API端口请求的错误日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。
如果设置了相对路径,则日志文件会保存在的目录下
pluginsbundledKong启动的时候加载的插件,如果多个必须要使用半角逗号分割。默认情况下,只有捆绑官方发行版本的插件通过 bundled 这个值来加载。
加载插件只是Kong在启动的时候载入插件的代码,但是并不会使用它,如果要使用他,还必须要通过管理API来配置
当然,如果你不想加载任何插件,可以使用off来关闭它,值得强调的一点bundled值可以和其他插件名称一起使用,bundled并不是一个插件名称,它代表了随官方发行的所有插件。
anonymous_reportson如果Kong进程发生了错误,会以匿名的方式将错误提交给Kong官方, 以帮助改善Kong。

在常规的配置中,主要配置了Kong运行的目录日志等信息。

无论如何,配置的文件或者目录Kong必须要用权限访问,否则会报错。

三、Nginx注入配置

Kong基于Nginx,当然需要配置Nginx来满足Kong的运行要求,Kong提供了Nginx的注入配置,使得我们更轻松控制。

在Nginx注入配置中,有如下配置:

配置项默认值说明
proxy_listen0.0.0.0:8000, 0.0.0.0:8443 ssl配置Kong代理监听的地址和端口,这个是Kong的入口,API调用都将通过这个端口请求。这个配置和Ngxin中的配置一致,通过SSL可以指定接受https的请求
支持IPv4和IPv6
admin_listen127.0.0.1:8001, 127.0.0.1:8444 ssl配置Kong的管理API监听的端口,和proxy_listen配置一样,但是这个配置不建议监听在公网IP上。
nginx_usernobody nobody配置Nginx的用户名和用户组,和Nginx的配置规则一样
nginx_worker_processesauto设置Nginx的进程书,通常等于CPU核心数
nginx_daemonon是否以daemon的方式运行Ngxin
mem_cache_size128m内存的缓存大小,可以使用km为单位
ssl_cipher_suitemodern定义Nginx提供的TLS密码,可以配置的值有:modern,intermediateoldcustom.
ssl_ciphers 定义Nginx提供的TLS密码的列表,参考Nginx的配置
ssl_cert 配置SSL证书的crt路径,必须是要绝对路径
ssl_cert_key 设置SSL证书的key文件,必须是绝对路径
client_ssloff.....
client_ssl_cert .....
client_ssl_cert_key .....
admin_ssl_cert .....
admin_ssl_cert_key .....
headersserver_tokens, latency_tokens设置再相应客户端时候应该注入的头部,可以设置的值如下: 
server_tokens: 注入'Via'和'Server'头部.
latency_tokens: 注入'X-Kong-Proxy-Latency'和'X-Kong-Upstream-Latency' 头部.
X-Kong-<header-name>: 只有在适当的时候注入特定的头部
这个配置可以被设置为off。当然,即便设置了off以后,插件依然可以注入头部
trusted_ips 定义可信的IP地址段,通常不建议在此处限制请求,应该再插件中过滤
real_ip_headerX-Real-IP获取客户端真实的IP,将值通过同步的形式传递给后端
real_ip_recursiveoff这个值在Nginx配置中设置了同名的ngx_http_realip_module指令
client_max_body_size0配置Nginx接受客户端最大的body长度,如果超过此配置 将返回413。
设置为0则不检查长度
client_body_buffer_size8k设置读取缓冲区大小,如果超过内存缓冲区大小,那么NGINX会缓存在磁盘中,降低性能。
error_default_typetext/plain当请求' Accept '头丢失,Nginx返回请求错误时使用的默认MIME类型。可以配置的值为:
text/plain,text/htmlapplication/jsonapplication/xml.

在Nginx注入配置中,配置了Nginx的基本的参数,这些参数大部分和NGINX的配置值是一样的,可以通过Nginx的配置文档了解一下。

四、 数据库存储配置

数据库配置的模块配置数据库相关的连接信息等等。主要有如下配置:

配置项默认值说明
databasepostgres设置数据库类型,Kong支持两种数据库,一种是postgres,一种是cassandra
PostgreSQL配置 如果database设置为postgres以下配置生效
pg_host127.0.0.1设置PostgreSQL的连接地址
pg_port5432设置PostgreSQL的端口
pg_userkong设置PostgreSQL的用户名
pg_password 设置PostgreSQL的密码
pg_databasekong设置数据库名称
pg_ssloff是否开启ssl连接
pg_ssl_verifyoff如果启用了' pg_ssl ',则切换服务器证书验证。
cassandra配置 如果database设置为cassandra以下配置生效
cassandra_contact_points127.0.0.1.....
cassandra_port9042.....
cassandra_keyspacekong.....
cassandra_timeout5000.....
cassandra_ssloff.....
cassandra_ssl_verifyoff.....
cassandra_usernamekong.....
cassandra_password .....
cassandra_consistencyONE.....
cassandra_lb_policyRoundRobin.....
cassandra_local_datacenter .....
cassandra_repl_strategySimpleStrategy.....
cassandra_repl_factor1.....
cassandra_data_centersdc1:2,dc2:3.....
cassandra_schema_consensus_timeout10000.....

推荐使用PostgreSQL数据库作为生产环境的存储,PostgreSQL具有良好的性能和稳定性,是一个非常优秀的开源数据库。

五、 数据库缓存配置

在上一节中,配置了Kong持久化存储,显然如果每次的请求都需要去查询数据库中的相关信息那无疑是非常消耗资源,性能和稳定性也会大大降低,作为一个API网关肯定是不能忍的,解决这个问题的办法就是缓存,Kong将数据缓存在内存中,这样会大大提高性能,本节介绍Kong的缓存配置。

配置项默认值说明
db_update_frequency5节点更新数据库的时间,以秒为单位。
这个配置设置了节点查询数据库的时间,假如有3台Kong服务器节点ABC,如果再A节点增加了一个API网关,那么B和C节点最多需要等待db_update_frequency时间才能被更新到。
db_update_propagation0数据库节点的更新时间。
如果使用了Cassandra数据库集群,那么如果数据库有更新,最多需要db_update_propagation时间来同步所有的数据库副本。
如果使用PostgreSQL或者单数据库,这个值可以被设置为0
db_cache_ttl0缓存生效时间,单位秒。如果设置为0表示永不过期
Kong从数据库中读取数据并且缓存,在ttl过期后会删除这个缓存然后再一次读取数据库并缓存
db_resurrect_ttl30缓存刷新时间,单位秒。当数据存储中的陈旧实体无法刷新时(例如,数据存储不可访问),应该对其进行恢复。当这个TTL过期时,将尝试刷新陈旧的实体。

六、 DNS解析器配置

默认情况下,DNS解析器将使用标准配置文件/etc/hosts/etc/resolv.conf。如果设置了环境变量LOCALDOMAINRES_OPTIONS,那么后一个文件中的设置将被覆盖。

配置项默认值说明
dns_resolver 配置DNS服务器列表,用半角逗号分割,每个条目使用ip[:port]的格式,这个配置仅提供给Kong使用,不会覆盖节点系统的配置,如果没有配置则使用系统的设置。接受IPv4和IPv6的地址。
dns_hostsfile/etc/hosts配置Kong的hosts文件,这个配置同样仅提供给Kong使用,不会覆盖节点系统的配置。
需要说明的是这个文件仅读取一次,读取的内容会缓存再内存中,如果修改了此文件,必须要重启Kong才能生效。
dns_orderLAST,SRV,A,CNAME解析不同记录类型的顺序。“LAST”类型表示最后一次成功查找的类型(用于指定的名称)
dns_stale_ttl4配置DNS记录缓存过期时间
dns_not_found_ttl30这个配置值不知道该如何理解??
dns_error_ttl1.....
dns_no_syncoff如果启用了该项,那么在DNS缓存过期之后,每一次请求都会发起DNS查询。在禁用此项时,那么相同的域名多次请求会同步到一个查询中共享返回值。

在DNS配置中,我们基本上不需要更改,官网的配置给出了最优的配置。如果我们需要在host文件中定义后端绑定的域名,一定要在编辑hosts文件后重载Kong的配置,或者重启Kong,无论hosts的文件是否是/etc/hosts,否则都不会生效的。

七、 其他杂项配置

杂项配置基本上关于LUA的配置,如果不熟悉请不要修改,按照官方默认即可。

配置项默认值说明
lua_ssl_trusted_certificate ....
lua_ssl_verify_depth1....
lua_package_path./?.lua;./?/init.lua;....
lua_package_cpath ....
lua_socket_pool_size30....

 

 

 

 

 

一、前言

Kong配置文件是Kong服务的核心文件,它配置了Kong以怎么的方式运行,并且依赖于这个配置生成Nginx的配置文件,本文通过解读Kong配置文件,以了解Kong的运行和配置。

在成功安装Kong以后,会有一个名为kong.conf.default默认的配置文件示例,如果是通过包管理器安装的,通常位于/etc/kong/kong.conf.default,我们要将其复制为kong.conf以便于我们修改使用他。

在Kong的配置文件中,约定了以下的几条规则:

  • 配置文件中以#开头的行均为注释行,程序不会读取这些内容。
  • 在官方提供的默认配置文件中,以#开头的有值的配置项目均为默认配置。
  • 所有的配置项,均可以在系统环境变量中配置,但是必须要加上KONG_为前缀。
  • 值为布尔型的配置,可以使用on/off或者true/false
  • 值为列表的,必须使用半角逗号分割。

Kong的配置,大概分为几种,分别是:

  • 常规配置:配置服务运行目录,插件加载,日志等等
  • NGINX配置:配置Nginx注入,例如监听IP和端口配置等等,用于Kong在启动的时候生成Nginx配置文件
  • 数据库存储配置:配数据库类型,地址、用户名密码等等信息
  • 数据库缓存配置:配置数据的缓存规则,Kong会缓存诸如API信息、用户、凭证等信息,以减少访问数据库次数提高性能
  • DNS解析器配置:默认情况会使用系统设置,如hostsresolv.conf的配置,你也可以通过DNS的解析器配置来修改
  • 其他杂项配置:继承自lua-nginx模块的其他设置允许更多的灵活性和高级用法。

下面我们一个模块一个模块解释一下各项的配置。

二、常规配置

在常规配置中,主要是控制Kong一些运行时的一些配置,主要有如下配置:

配置项默认值说明
prefix/usr/local/kong/配置Kong的工作目录,相当于Nginx的工作目录,这个目录存放运行时的临时文件和日志,包括Kong启动的时候自动生成的Nginx的配置文件。每一个Kong经常必须有一个单独的工作目录
log_levelnoticeNginx的日志级别。日志存放
proxy_access_loglogs/access.log代理端口请求的日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径,则日志文件会保存在
proxy_error_loglogs/error.log代理端口请求的错误日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径,则日志文件会保存在
admin_access_loglogs/admin_access.logKong管理的API端口请求的日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径,则日志文件会保存在
admin_error_loglogs/error.logKong管理的API端口请求的错误日志文件,可以设置为off来关闭日志的记录,也可以通过设置绝对路径也可以设置相对路径。如果设置了相对路径,则日志文件会保存在
pluginsbundledKong启动的时候加载的插件,如果多个必须要使用半角逗号分割。默认情况下,只有捆绑官方发行版本的插件通过 bundled 这个值来加载。加载插件只是Kong在启动的时候载入插件的代码,但是并不会使用它,如果要使用他,还必须要通过管理API来配置.当然,如果你不想加载任何插件,可以使用off来关闭它,值得强调的一点bundled值可以和其他插件名称一起使用,bundled并不是一个插件名称,它代表了随官方发行的所有插件。
anonymous_reportson如果Kong进程发生了错误,会以匿名的方式将错误提交给Kong官方, 以帮助改善Kong。

在常规的配置中,主要配置了Kong运行的目录日志等信息。

无论如何,配置的文件或者目录Kong必须要用权限访问,否则会报错。

三、Nginx注入配置

Kong基于Nginx,当然需要配置Nginx来满足Kong的运行要求,Kong提供了Nginx的注入配置,使得我们更轻松控制。

在Nginx注入配置中,有如下配置:

配置项默认值说明
proxy_listen0.0.0.0:8000, 0.0.0.0:8443 ssl配置Kong代理监听的地址和端口,这个是Kong的入口,API调用都将通过这个端口请求。这个配置和Ngxin中的配置一致,通过SSL可以指定接受https的请求. 支持IPv4和IPv6
admin_listen127.0.0.1:8001, 127.0.0.1:8444 ssl配置Kong的管理API监听的端口,和proxy_listen配置一样,但是这个配置不建议监听在公网IP上。
nginx_usernobody nobody配置Nginx的用户名和用户组,和Nginx的配置规则一样
nginx_worker_processesauto设置Nginx的进程书,通常等于CPU核心数
nginx_daemonon是否以daemon的方式运行Ngxin
mem_cache_size128m内存的缓存大小,可以使用km为单位
ssl_cipher_suitemodern定义Nginx提供的TLS密码,可以配置的值有:modern,intermediateoldcustom.
ssl_ciphers 定义Nginx提供的TLS密码的列表,参考Nginx的配置
ssl_cert 配置SSL证书的crt路径,必须是要绝对路径
ssl_cert_key 设置SSL证书的key文件,必须是绝对路径
client_ssloff
client_ssl_cert 
client_ssl_cert_key 
admin_ssl_cert 
admin_ssl_cert_key 
headersserver_tokens, latency_tokens设置再相应客户端时候应该注入的头部,可以设置的值如下:
server_tokens: 注入’Via’和’Server’头部.
latency_tokens: 注入’X-Kong-Proxy-Latency’和’X-Kong-Upstream-Latency’ 头部.
X-Kong-<header-name>: 只有在适当的时候注入特定的头部
这个配置可以被设置为off。当然,即便设置了off以后,插件依然可以注入头部
trusted_ips 定义可信的IP地址段,通常不建议在此处限制请求,应该再插件中过滤
real_ip_headerX-Real-IP获取客户端真实的IP,将值通过同步的形式传递给后端
real_ip_recursiveoff这个值在Nginx配置中设置了同名的ngx_http_realip_module指令
client_max_body_size0配置Nginx接受客户端最大的body长度,如果超过此配置 将返回413。
设置为0则不检查长度
client_body_buffer_size8k设置读取缓冲区大小,如果超过内存缓冲区大小,那么NGINX会缓存在磁盘中,降低性能。
error_default_typetext/plain当请求’ Accept '头丢失,Nginx返回请求错误时使用的默认MIME类型。可以配置的值为:
text/plain,text/htmlapplication/jsonapplication/xml.

在Nginx注入配置中,配置了Nginx的基本的参数,这些参数大部分和NGINX的配置值是一样的,可以通过Nginx的配置文档了解一下。

四、 数据库存储配置

数据库配置的模块配置数据库相关的连接信息等等。主要有如下配置:

配置项默认值说明
databasepostgres设置数据库类型,Kong支持两种数据库,一种是postgres,一种是cassandra
PostgreSQL配置 如果database设置为postgres以下配置生效
pg_host127.0.0.1设置PostgreSQL的连接地址
pg_port5432设置PostgreSQL的端口
pg_userkong设置PostgreSQL的用户名
pg_password 设置PostgreSQL的密码
pg_databasekong设置数据库名称
pg_ssloff是否开启ssl连接
pg_ssl_verifyoff如果启用了’ pg_ssl ',则切换服务器证书验证。
cassandra配置 如果database设置为cassandra以下配置生效
cassandra_contact_points127.0.0.1
cassandra_port9042
cassandra_keyspacekong
cassandra_timeout5000
cassandra_ssloff
cassandra_ssl_verifyoff
cassandra_usernamekong
cassandra_password 
cassandra_consistencyONE
cassandra_lb_policyRoundRobin
cassandra_local_datacenter 
cassandra_repl_strategySimpleStrategy
cassandra_repl_factor1
cassandra_data_centersdc1:2,dc2:3
cassandra_schema_consensus_timeout10000

推荐使用PostgreSQL数据库作为生产环境的存储,PostgreSQL具有良好的性能和稳定性,是一个非常优秀的开源数据库。

五、 数据库缓存配置

在上一节中,配置了Kong持久化存储,显然如果每次的请求都需要去查询数据库中的相关信息那无疑是非常消耗资源,性能和稳定性也会大大降低,作为一个API网关肯定是不能忍的,解决这个问题的办法就是缓存,Kong将数据缓存在内存中,这样会大大提高性能,本节介绍Kong的缓存配置。

配置项默认值说明
db_update_frequency5节点更新数据库的时间,以秒为单位。
这个配置设置了节点查询数据库的时间,假如有3台Kong服务器节点ABC,如果再A节点增加了一个API网关,那么B和C节点最多需要等待db_update_frequency时间才能被更新到。
db_update_propagation0数据库节点的更新时间。
如果使用了Cassandra数据库集群,那么如果数据库有更新,最多需要db_update_propagation时间来同步所有的数据库副本。
如果使用PostgreSQL或者单数据库,这个值可以被设置为0
db_cache_ttl0缓存生效时间,单位秒。如果设置为0表示永不过期
Kong从数据库中读取数据并且缓存,在ttl过期后会删除这个缓存然后再一次读取数据库并缓存
db_resurrect_ttl30缓存刷新时间,单位秒。当数据存储中的陈旧实体无法刷新时(例如,数据存储不可访问),应该对其进行恢复。当这个TTL过期时,将尝试刷新陈旧的实体。

六、 DNS解析器配置

默认情况下,DNS解析器将使用标准配置文件/etc/hosts/etc/resolv.conf。如果设置了环境变量LOCALDOMAINRES_OPTIONS,那么后一个文件中的设置将被覆盖。

配置项默认值说明
dns_resolver 配置DNS服务器列表,用半角逗号分割,每个条目使用ip[:port]的格式,这个配置仅提供给Kong使用,不会覆盖节点系统的配置,如果没有配置则使用系统的设置。接受IPv4和IPv6的地址。
dns_hostsfile/etc/hosts配置Kong的hosts文件,这个配置同样仅提供给Kong使用,不会覆盖节点系统的配置。
需要说明的是这个文件仅读取一次,读取的内容会缓存再内存中,如果修改了此文件,必须要重启Kong才能生效。
dns_orderLAST,SRV,A,CNAME解析不同记录类型的顺序。“LAST”类型表示最后一次成功查找的类型(用于指定的名称)
dns_stale_ttl4配置DNS记录缓存过期时间
dns_not_found_ttl30这个配置值不知道该如何理解??
dns_error_ttl1
dns_no_syncoff如果启用了该项,那么在DNS缓存过期之后,每一次请求都会发起DNS查询。在禁用此项时,那么相同的域名多次请求会同步到一个查询中共享返回值。

在DNS配置中,我们基本上不需要更改,官网的配置给出了最优的配置。如果我们需要在host文件中定义后端绑定的域名,一定要在编辑hosts文件后重载Kong的配置,或者重启Kong,无论hosts的文件是否是/etc/hosts,否则都不会生效的。

七、 其他杂项配置

杂项配置基本上关于LUA的配置,如果不熟悉请不要修改,按照官方默认即可。

配置项默认值说明
lua_ssl_trusted_certificate 
lua_ssl_verify_depth1
lua_package_path./?.lua;./?/init.lua;
lua_package_cpath 
lua_socket_pool_size30

 

文章参考:

参考:https://linuxops.org/blog/kong/config.html

 

Logo

权威|前沿|技术|干货|国内首个API全生命周期开发者社区

更多推荐