Kong插件向导

2019-10-03 本文已影响0人 fossilman

鉴权插件

Basic Authentication

配置信息

基本描述

属性	描述
认证方式	基本认证、用户名密码登录
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`basic-auth`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
config.hide_credentials	是否隐藏请求中的凭证信息（如`Authorization`头），默认是false
config.anonymous	在验证失败后是否启用匿名消费者，值可以配置为消费者Id

使用详情

创建消费者

curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/

创建凭证

curl -X POST http://kong:8001/consumers/{consumer}/basic-auth --data "username=Aladdin" --data "password=OpenSesame"

使用凭证

curl http://kong:8000/{path matching a configured Route} -H 'Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l'

凭证接口

查看所有basic-auths凭证信息

curl -X GET http://kong:8001/basic-auths

查看指定basic-auths凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/basic-auths

HMAC Authentication

配置信息

基本描述

属性	描述
认证方式	HMAC 签名认证
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`hmac-auth`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
config.hide_credentials	是否隐藏请求中的凭证信息（如`Authorization`头），默认是false
config.clock_skew	时间偏移量，默认是300s
config.anonymous	在验证失败后是否启用匿名消费者，值可以配置为消费者Id
config.validate_request_body	是否启用Body体校验，默认是false
config.enforce_headers	请求中必须包含的头部信息
config.algorithms	HMAC 算法支持的列表，默认值是`hmac-sha1,hmac-sha256,hmac-sha384,hmac-sha512`

使用详情

创建服务

curl -i -X POST http://localhost:8001/services -d "name=example-service" -d "url=http://example.com"

创建路由

curl -i -f -X POST http://localhost:8001/services/example-service/routes -d "paths[]=/"

创建插件

curl -i -X POST http://localhost:8001/services/example-service/plugins -d "name=hmac-auth" -d "config.enforce_headers=date, request-line" -d "config.algorithms=hmac-sha1, hmac-sha256"

创建消费者

curl -i -X POST http://localhost:8001/consumers/ -d "username=alice"

创建凭证

curl -i -X POST http://localhost:8001/consumers/alice/hmac-auth -d "username=alice123" -d "secret=secret"

使用凭证

curl -i -X GET http://localhost:8000/requests -H "Host: hmac.com" -H "Date: Thu, 22 Jun 2017 17:15:21 GMT" -H 'Authorization: hmac username="alice123", algorithm="hmac-sha256", headers="date request-line", signature="ujWCGHeec9Xd6UD2zlyxiNMCiXnDOWeVFMu5VeRUxtw="'

凭证接口

查看所有hmac-auths凭证信息

curl -X GET http://kong:8001/hmac-auths

查看指定hmac-auths凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/hmac-auths

JWT

配置信息

基本描述

属性	描述
认证方式	JWT（JSON Web Tokens）认证
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`jwt`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
config.uri_param_names	jwt的参数列表，默认值是jwt
config.cookie_names	cookie中jwt的参数列表
config.claims_to_verify	JWT声明中的验证，可接受的值exp、nbf
config.key_claim_name	创建凭证时响应体中的key字段必须需要传递，默认参数值iss
config.secret_is_base64	JWT是否启用Base64加密，默认是false
config.anonymous	在验证失败后是否启用匿名消费者，值可以配置为消费者Id
config.run_on_preflight	是否在 `OPTIONS` 类型的请求上启用鉴权
config.maximum_expiration	JWT的最大失效时间，config.key_claim_name必须设置为exp，0代表永不是失效，默认值为0

使用详情

创建消费者

curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/

创建凭证

curl -X POST http://kong:8001/consumers/{consumer}/jwt -H "Content-Type: application/x-www-form-urlencoded"

参数	描述
{consumer}	消费者的Id或者用户名
key	JWT凭证的key名，如果不指定，会自动生成
algorithm	校验token的算法，可以是HS256、HS384、HS512、RS256或者ES256，默认是HS256
rsa_public_key	如果算法使用RS256或者ES256，需要上传公钥，pem格式
secret	如果算法使用RS256或者ES256，JWT签名的secret，如果不指定，会自动生成

使用凭证

curl http://kong:8000/{route path} -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4'

或者

curl http://kong:8000/{route path}?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4

或者

curl --cookie  jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4 http://kong:8000/{route path}

删除凭证

curl -X DELETE http://kong:8001/consumers/{consumer}/jwt/{id}

查询凭证

curl -X GET http://kong:8001/consumers/{consumer}/jwt

加密详情

使用HS256签名

# 请求头
{
    "typ": "JWT",
    "alg": "HS256"
}

{
    "iss": "a36c3049b36249a3c9f8891cb127243c"
}

# token值
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhMzZjMzA0OWIzNjI0OWEzYzlmODg5MWNiMTI3MjQzYyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.AhumfY35GFLuEEjrOXiaADo7Ae6gt_8VLwX7qffhQN4

使用公私钥签名（RS256 or ES256）

# 创建凭证
curl -X POST http://kong:8001/consumers/{consumer}/jwt -F "rsa_public_key=@/path/to/public_key.pem"

# 请求头
{
    "typ": "JWT",
    "alg": "RS256"
}

{
    "iss": "a36c3049b36249a3c9f8891cb127243c"
}

# 使用凭证
curl http://kong:8000/{route path} -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIxM2Q1ODE0NTcyZTc0YTIyYjFhOWEwMDJmMmQxN2MzNyJ9.uNPTnDZXVShFYUSiii78Q-IAfhnc2ExjarZr_WVhGrHHBLweOBJxGJlAKZQEKE4rVd7D6hCtWSkvAAOu7BU34OnlxtQqB8ArGX58xhpIqHtFUkj882JQ9QD6_v2S2Ad-EmEx5402ge71VWEJ0-jyH2WvfxZ_pD90n5AG5rAbYNAIlm2Ew78q4w4GVSivpletUhcv31-U3GROsa7dl8rYMqx6gyo9oIIDcGoMh3bu8su5kQc5SQBFp1CcA5H8sHGfYs-Et5rCU2A6yKbyXtpHrd1Y9oMrZpEfQdgpLae0AfWRf6JutA9SPhst9-5rn4o3cdUmto_TBGqHsFmVyob8VQ'

凭证接口

查看所有jwt凭证信息

curl -X GET http://kong:8001/jwts

查看指定jwt凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/jwts

Key Authentication

配置信息

基本描述

属性	描述
认证方式	Key认证
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`key-auth`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
config.key_names	key的参数列表，默认值是apikey
config.key_in_body	参数key是否可以存放在请求体中，默认是false
config.hide_credentials	是否隐藏请求中的凭证信息，默认是false
config.anonymous	在验证失败后是否启用匿名消费者，值可以配置为消费者Id
config.run_on_preflight	是否在 `OPTIONS` 类型的请求上启用鉴权

使用详情

创建消费者

curl -d  "username=user123&custom_id=SOME_CUSTOM_ID" http://kong:8001/consumers/

创建凭证

curl -X POST http://kong:8001/consumers/{consumer}/key-auth -d ''

使用凭证

curl http://kong:8000/{proxy path}?apikey=<some_key>

或者

curl http://kong:8000/{proxy path} -H 'apikey: <some_key>'

删除凭证

curl -X DELETE http://kong:8001/consumers/{consumer}/key-auth/{id}

凭证接口

查看所有key-auths凭证信息

curl -X GET http://kong:8001/key-auths

查看指定key-auths凭证信息

curl -X GET http://kong:8001/consumers/{username or id}/key-auth

LDAP Authentication

配置信息

基本描述

属性	描述
认证方式	LDAP认证
插件作用域	路由
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`ldap-auth`
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
config.hide_credentials	是否隐藏请求中的凭证信息，默认是false
config.ldap_host	LDAP服务器的地址
config.ldap_port	LDAP服务器的端口
config.start_tls	是否启用TLS，默认是false
config.base_dn	基准DN（Distinguished Name）
config.verify_ldap_host	是否启用LDAP服务器验证，默认是false
config.attribute	搜索用户使用的属性
config.cache_ttl	缓存的失效时间，默认是60s
config.timeout	连接LDAP服务器超时时间，默认10000ms
config.keepalive	LDAP服务器保持连接时间，默认60000ms
config.anonymous	在验证失败后是否启用匿名消费者，值可以配置为消费者Id
config.header_type	请求头参数名，默认是ldap

OAuth2.0 Authentication

配置信息

基本描述

属性	描述
认证方式	HMAC 签名认证
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`key-auth`
service_id	绑定的服务Id
enabled	是否启用该插件，默认是true
config.scopes	描述终端用户可以访问的范围
config.mandatory_scope	是否告诉插件至少给终端用户分配一个访问范围，默认是false
config.token_expiration	token的过期时间，默认是7200s，设置为0时token不过期
config.enable_authorization_code	是否启用Authorization Code模式，默认是false
config.enable_client_credentials	是否启用Client Credentials模式，默认是false
config.enable_implicit_grant	是否启用Implicit Grant模式，默认是false
config.enable_password_grant	是否启用Password Grant模式，默认是false
config.auth_header_name	携带access token的头信息，默认值是authorization
config.hide_credentials	是否隐藏请求中的凭证信息，默认是false
config.accept_http_if_already_terminated
config.anonymous	在验证失败后是否启用匿名消费者，值可以配置为消费者Id
config.global_credentials	是否启用通用OAuth2.0服务
config.refresh_token_ttl	refresh_token的过期时间，默认为两周，设置为0时token不过期

使用详情

OAuth2端点

端点	描述
/oauth2/authorize	授权服务器的端点，用于为Authorization Code模式提供authorization code，或为Implicit Grant模式提供access token，仅支持POST方法
/oauth2/token	令牌服务器的端点，也作为Client Credentials模式和Password Grant模式唯一的端点，仅支持POST方法

创建消费者

curl -X POST http://kong:8001/consumers/ --data "username=user123" --data "custom_id=SOME_CUSTOM_ID"

创建OAuth2.0应用

curl -X POST http://kong:8001/consumers/{consumer_id}/oauth2 --data "name=Test%20Application" --data "client_id=SOME-CLIENT-ID" --data "client_secret=SOME-CLIENT-SECRET" --data "redirect_uris=http://some-domain/endpoint/"

参数	描述
name	新建OAuth2.0应用的名称
client_id	clientId，如果不指定，会自动生成
client_secret	clientSecrct，如果不指定，会自动生成
redirect_uris	授权完成之后的跳转地址

OAuth2.0 Client Credentials模式

Client Credentials模式开箱即用，无需构建任何授权页面，客户端需要使用 /oauth2/token 端点获取access token

OAuth2.0 Authorization Code模式

配置完消费者并且与OAuth2.0凭证关联之后，需要正确了解OAuth2.0的授权流程，与大多数Kong插件不同，OAuth2.0插件需要一些额外的工作才能运转正常
用户必须在Web应用中实现授权页面，该页面与插件的服务器端通信，用户需要在网站或文档中解释清楚如何使用受OAuth2.0保护的服务，这个开发者可以知道如何实现客户端程序
构建授权页面是插件无法开箱即用的部分，因为它需要检查用户是否已正确登录，此操作与用户身份校验的实现密切相关
授权页面由两部分组成：

用户看到的前端的页面，这将允许他授权客户端应用程序访问他的数据
后端将处理HTML表单中显示的信息，这个表单会与Kong上的OAuth2.0插件进行通信，并最终将用户重定向到第三方URL上

完整流程如下：

客户端应用会将终端用户重定向到用户实现的授权页面上，并将 client_id、response_type 和 scope（如果需要的话）作为参数传递过来；
在展示真实的授权页面前，应用程序需要确保该用户已经正常登录了；
客户端应用会通过参数将 client_id 传递给应用程序，应用程序向Kong发送指令取回OAuth2.0应用名和开发者名：

curl kong:8001/oauth2?client_id=XXX

如果终端用户授权了客户端程序，表单将使用 POST 请求将 client_id、response_type 和 scope 提交到后端；
后端在发送 POST 请求时还需要加入 provision_key 和 authenticated_userid 参数，如果客户端带入了 Authorization 头，请求也需要透传，其中 provision_key 是插件添加到服务时生成的密钥，authenticated_userid 是授予权限的用户的Id，请求大致如下：

curl https://your.service.com/oauth2/authorize --header "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" --data "client_id=XXX" --data "response_type=XXX" --data "scope=XXX" --data "provision_key=XXX" --data "authenticated_userid=XXX"

Kong响应大致如下，200 OK 或者 400 Bad Request 响应码取决请求是否成功：

{
   "redirect_uri": "http://some/url"
}

无论哪种情况，忽略响应状态码，只需将用户重定向到 redirect_uri 属性返回的URI上；
客户端应用将在此处获取它，并将继续使用Kong，而不与用户的应用进行其他交互；
当获取到access token之后，客户端应用可以作为用户，向上游服务发起请求；
access token是会过期的，当发生这种情况时，客户端应用程序需要使用Kong续订访问令牌

在这些步骤中，用户需要实现的步骤有：

登录页（步骤2）
授权页面，以及后端简单地收集信息，向Kong发送请求，并重定向到Kong返回的URL上

Password Grant模式

Password Grant模式是一个比较简单的模式，但仍需要后端授权（无前端）才能正常工作：

第一个请求中，客户端应用向应用程序发送请求，携带一些OAuth2的参数，包含用户名和密码；
应用程序的后端会校验客户端发送的用户名和密码，如果校验成功，会将 provision_key、authenticated_userid 和 grant_type 这些参数添加到客户端最初发送的参数中，并向Kong的 /oauth2/token 端点发送 POST 请求，其中 provision_key 是插件添加到服务时生成的密钥，authenticated_userid 是授予权限的用户的Id，请求大致如下：

curl https://your.service.com/oauth2/token --header "Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW" --data "client_id=XXX" --data "client_secret=XXX" --data "grant_type=password" --data "scope=XXX" --data "provision_key=XXX" --data "authenticated_userid=XXX" --data "username=XXX" --data "password=XXX"

Kong返回一个JSON响应；
Kong的响应必须原样发送回客户端，如果操作成功，响应中会包含access token，否则会包含错误

在这些步骤中，用户需要实现的步骤有：
后端端点将处理原始请求并验证客户端发送的用户名和密码，如果验证成功，则向Kong发出请求并返回客户端，无论Kong响应什么内容

刷新Token

当用户的access token过期时，用户可以使用refresh token生成新的access token

curl -X POST https://your.service.com/oauth2/token --data "grant_type=refresh_token" --data "client_id=XXX" --data "client_secret=XXX" --data "refresh_token=XXX"

安全插件

CORS

配置信息

基本描述

属性	描述
安全策略	跨域资源共享
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`cors`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
config.origins	Access-Control-Allow-Origin头允许的域列表，使用 * 代表允许所有域，值可以是普通值；也可以是正则表达式
config.methods	Access-Control-Allow-Methods头的值，默认为GET, HEAD, PUT, PATCH, POST
config.headers	Access-Control-Allow-Headers头的值，默认为Access-Control-Request-Headers头的值
config.exposed_headers	Access-Control-Expose-Headers的值，如果不指定，不暴露自定义的头
config.credentials	是否发送Access-Control-Allow-Credentials请求头，默认是false
config.max_age	预检请求的缓存时间
config.preflight_continue	是否将 OPTIONS 请求代理到上游服务

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=cors" --data "config.origins=http://mockbin.com" --data "config.methods=GET" --data "config.methods=POST" --data "config.headers=Accept" --data "config.headers=Accept-Version" --data "config.headers=Content-Length" --data "config.headers=Content-MD5" --data "config.headers=Content-Type" --data "config.headers=Date" --data "config.headers=X-Auth-Token" --data "config.exposed_headers=X-Auth-Token" --data "config.credentials=true" --data "config.max_age=3600"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=cors" --data "config.origins=http://mockbin.com" --data "config.methods=GET" --data "config.methods=POST" --data "config.headers=Accept" --data "config.headers=Accept-Version" --data "config.headers=Content-Length" --data "config.headers=Content-MD5" --data "config.headers=Content-Type" --data "config.headers=Date" --data "config.headers=X-Auth-Token" --data "config.exposed_headers=X-Auth-Token" --data "config.credentials=true" --data "config.max_age=3600"

IP Restriction

配置信息

基本描述

属性	描述
安全策略	IP限制
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`ip-restriction`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.whitelist	白名单列表，白名单或黑名单必须配置一个
config.blacklist	黑名单列表，白名单或黑名单必须配置一个

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=ip-restriction" --data "config.whitelist=54.13.21.1" --data "config.whitelist=143.1.0.0/24"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=ip-restriction" --data "config.whitelist=54.13.21.1" --data "config.whitelist=143.1.0.0/24"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=ip-restriction" --data "config.whitelist=54.13.21.1" --data "config.whitelist=143.1.0.0/24"

注意，白名单 和 黑名单模型在使用中是互斥的，它们提供了互补的方法，也就是说，用户无法既用白名单 ，又用黑名单配置插件，白名单提供了积极的安全模型，只允许配置范围内的ip访问资源，其他全部拒绝；黑名单提供了被动的安全模型，只拒绝配置范围内的ip访问资源，其他全部允许

流量控制插件

ACL

配置信息

基本描述

属性	描述
限流策略	ACL组限制
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`acl`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
config.whitelist	白名单组列表，白名单或黑名单必须配置一个
config.blacklist	黑名单组列表，白名单或黑名单必须配置一个
config.hide_groups_header	是否将`X-Consumer-Groups`头发送给上游服务

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=acl" --data "config.whitelist=group1" --data "config.whitelist=group2" --data "config.hide_groups_header=true"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=acl" --data "config.whitelist=group1" --data "config.whitelist=group2" --data "config.hide_groups_header=true"

在消费者上添加ACL组属性

curl -X POST http://kong:8001/consumers/{consumer}/acls --data "group=group1"

凭证接口

查询所有消费者的ACL组

curl -X GET http://kong:8001/acls

查询指定消费者的ACL组

curl -X GET http://kong:8001/consumers/{username or id}/acls

查询ACL组Id关联的消费者

curl -X GET http://kong:8001/acls/{id}/consumer

Proxy Caching

配置信息

基本描述

属性	描述
限流策略	终止请求限制
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`proxy-cache`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
api_id	绑定的API Id，已经废弃
config.response_code	上游服务可以作为缓存的状态码，默认值为200, 301, 404
config.request_method	下游服务可以作为缓存的方法，默认为GET, HEAD
config.content_type	可以作为缓存的 content type
config.vary_headers	用于生成缓存Key的头部信息，如果不指定，所有头部信息都不作为数据源
config.vary_query_params	用于生成缓存Key的查询参数，如果不指定，所有查询参数都作为数据源
config.cache_ttl	缓存的TTL时间，默认是300s
config.cache_control	是否启用Cache-Control行为，默认是false
config.storage_ttl	数据在存储引擎中的TTL时间
config.strategy	缓存策略，可以取 `memory` 或 `redis`
config.memory.dictionary_name	当选用 `memory` 策略时，用于保存缓存实体的 shared dictionary 的名称，这个 shared dictionary 必须在Kong的Nginx模板中手动定义，默认是kong_cache
config.redis.host	redis服务器地址
config.redis.port	redis服务器端口
config.redis.timeout	连接redis服务器超时时间
config.redis.password	redis服务器密码
config.redis.database	redis数据库
config.redis.sentinel_master	redis哨兵模式master节点地址
config.redis.sentinel_role	redis哨兵模式角色
config.redis.sentinel_addresses	redis哨兵模式哨兵地址

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=proxy-cache" --data "config.strategy=memory"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=proxy-cache" --data "config.strategy=memory"

在消费者上添加插件

curl -X POST http://kong:8001/apis/{api}/plugins --data "name=proxy-cache" --data "config.strategy=memory"

缓存策略

模式	描述
memory	内存模式，是一个lua_shared_dict，默认的kong_cache也被Kong的其他插件用于缓存其他数据，使用这种方式比较简单，但不推荐在大规模场景中使用，因为大量使用会对Kong数据缓存操作造成压力
redis	支持redis和redis哨兵模式

缓存Key
Kong基于请求方法、完整的客户端请求（路径和请求参数）和绑定在请求上的API或消费者UUID来生成缓存 Key，所以各个API或消费者之间的缓存都是不同的，目前缓存Key的格式是硬编码的，无法调整，缓存的组成方式如下：

key = md5(UUID | method | request)

其中 method 是通过 ngx.req.get_method() 方法获得的，request 是根据 Nginx $request 变量获得的，Kong会在响应的 X-Cache-Key 头中返回缓存Key值，如上所述，可以预先计算缓存Key

缓存控制
当启用 cache_control 时，Kong将遵守 Cache-Control 头的使用规范，有一些例外情况：

不支持缓存重新验证
类似地，no-cache 排除缓存存在
不支持根据 Vary 计算二级缓存

缓存状态
Kong通过 X-Cache-Status 头表示缓存行为的状态：

状态	描述
Miss	请求可以缓存，但是缓存中没有数据，数据从代理的服务中获取
Hit	缓存命中，数据从缓存中获取
Refresh	缓存命中，但因为缓存控制行为或者达到了cache_ttl设置的阈值
Bypass	不能使用缓存

存储TTL
Kong可以在存储引擎中存储数据，存储时间超过 cache_ttl 或 Cache-Control 阈值所限定的时间，这使得Kong在资源过期后，还能维持一份资源的缓存副本，这样客户端在必要时可以使用 max-age 或 max-stale 头请求过期的数据

缓存API

获取缓存实体
GET /proxy-cache/:plugin_id/caches/:cache_id
GET /proxy-cache/:cache_id
删除缓存实体
DELETE /proxy-cache/:plugin_id/caches/:cache_id
DELETE /proxy-cache/:cache_id
清除所有缓存
DELETE /proxy-cache/

Rate Limiting

配置信息

基本描述

属性	描述
限流策略	ACL组限制
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`rate-limiting`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.second	每秒的限流数
config.minute	每分钟的限流数
config.hour	每小时的限流数
config.day	每天的限流数
config.month	每月的限流数
config.year	每年的限流数
config.limit_by	限制次数的衡量标准，可以取`consumer`、`credential` 或 `ip`，如果不能识别consumer或credential，都按照ip计数，默认是consumer
config.policy	限流累加器的计数策略，可以取`local`、`cluster` 或 `redis`，默认是cluster
config.fault_tolerant	当第三方数据源出错时，是否启用限流功能，取true时会禁用限流功能，默认是true
config.hide_client_headers	是否隐藏消息响应头，默认是false
config.redis_host	redis服务器地址
config.redis_port	redis服务器端口
config.redis_password	redis服务器密码
config.redis_timeout	连接redis服务器超时时间
config.redis_database	redis数据库

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=rate-limiting" --data "config.second=5" --data "config.hour=10000"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=rate-limiting" --data "config.second=5" --data "config.hour=10000"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=rate-limiting" --data "config.second=5" --data "config.hour=10000"

返回给客户端的头部信息

X-RateLimit-Limit-Second: 5
X-RateLimit-Remaining-Second: 4
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9

实施细节

模式	优点	描述
cluster	准确，不需要依赖其他组件	相对来说性能影响最大的，每个请求都会强制对底层的数据源进行读写操作
redis	准确，性能影响比cluster模式小	需要额外安装redis，相比local模式性能影响大
local	性能影响最小	不太准确，除非在Kong之前使用Hash一致性负载均衡器

事务粒度
这个场景中，不能选用 local 策略，应该在 cluster 或 redis 策略中考量，推荐是先尝试使用 cluster 策略，如果性能急速下降，则切换成 redis 策略，需要注意的是，指标数据无法从原有数据源切换到redis，通常来说，短周期指标（如秒、分）不受影响，长周期指标（月）可能会有影响，所以切换数据源时需要小心
后端保护模式
这种场景中因为准确性不太重要，可以使用 local 策略，这需要多些尝试才能找到合适的值，比如用户希望配置限流每秒100个请求，总共有5个Kong节点，设置 local 策略，每秒30个请求，大致可以满足需求，如果觉得返回的失败过于频繁，可以适当增大阈值
需要注意的是，当增加Kong节点时，会增加总请求数；同理减少Kong节点时，会降低总请求数，所以调整节点数时需要同步调整阈值
在Kong节点前使用Hash一致性负载均衡器可以避免上述的问题，因为它会保证相同的用户会路由到指定的Kong节点，保证数据准确，并且不受节点缩放的影响
通常情况下，真实的请求数会大于限流的阈值，但是它还是能有效的防止攻击，并且保持最佳性能

RequestTermination

配置信息

基本描述

属性	描述
限流策略	终止请求限制
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`request-termination`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.status_code	响应码，默认是503
config.message	响应消息
config.body	响应消息体，与响应消息互斥
config.content_type	响应体的content_type，默认值是 application/json; charset=utf-8

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=request-termination" --data "config.status_code=403" --data "config.message=So long and thanks for all the fish!"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=request-termination" --data "config.status_code=403" --data "config.message=So long and thanks for all the fish!"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=request-termination" --data "config.status_code=403" --data "config.message=So long and thanks for all the fish!"

使用场景

临时禁用某个服务（比如正在维护中）
临时禁用某个路由（比如需要禁用某个端点）
临时禁用某个消费者（比如过度消费）
阻止匿名访问

Kong Service Virtualization

配置信息

基本描述

属性	描述
限流策略	服务虚拟化
插件作用域	服务、路由、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`kong-service-virtualization`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
api_id	绑定的API Id，已经废弃
config.virtual_tests	JSON字串配置项

JSON配置项

参数	描述
name	测试用例名称
requestHttpMethod	测试用例的请求方法
requestHash	测试用例的请求参数，使用Sha256算法加密
responseHttpStatus	测试用例的响应状态码
responseContentType	测试用例的响应ContentType
response	测试用例的响应体，采用Base64编码

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=kong-service-virtualization" --data "config.virtual_tests={"name"=>"TestCase1", "requestHttpMethod"=>"POST", "requestHash"=>"0296217561490155228da9c17fc555cf9db82d159732f3206638c25f04a285c4", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkEgQmlnIFN1Y2Nlc3MhIn0="}" --data "config.virtual_tests={"name"=>"TestCase2", "requestHttpMethod"=>"GET", "requestHash"=>"e2c319e4ef41706e2c0c1b266c62cad607a014c59597ba662bef6d10a0b64a32", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkFub3RoZXIgU3VjY2VzcyEifQ=="}"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=kong-service-virtualization" --data "config.virtual_tests={"name"=>"TestCase1", "requestHttpMethod"=>"POST", "requestHash"=>"0296217561490155228da9c17fc555cf9db82d159732f3206638c25f04a285c4", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkEgQmlnIFN1Y2Nlc3MhIn0="}" --data "config.virtual_tests={"name"=>"TestCase2", "requestHttpMethod"=>"GET", "requestHash"=>"e2c319e4ef41706e2c0c1b266c62cad607a014c59597ba662bef6d10a0b64a32", "responseHttpStatus"=>"200", "responseContentType"=>"application/json", "response"=>"eyJtZXNzYWdlIjogIkFub3RoZXIgU3VjY2VzcyEifQ=="}"

安装插件

推荐安装方式

luarocks install kong-service-virtualization

其他选择安装方式

git clone https://github.com/Optum/kong-service-virtualization
cd /path/to/kong/plugins/kong-service-virtualization
luarocks make *.rockspec

virtual_tests参数详解

[
     {
        "name": "TestCase1",           
        "requestHttpMethod": "POST",
        "requestHash": "0296217561490155228da9c17fc555cf9db82d159732f3206638c25f04a285c4",
        "responseHttpStatus": "200",
        "responseContentType": "application/json",
        "response": "eyJtZXNzYWdlIjogIkEgQmlnIFN1Y2Nlc3MhIn0="
    },
    {         
        "name": "TestCase2",           
        "requestHttpMethod": "GET",
        "requestHash": "e2c319e4ef41706e2c0c1b266c62cad607a014c59597ba662bef6d10a0b64a32",
        "responseHttpStatus": "200",
        "responseContentType": "application/json",
        "response": "eyJtZXNzYWdlIjogIkFub3RoZXIgU3VjY2VzcyEifQ=="
    }
]

上述的请求相当于：

https://gateway.company.com/virtualtest
POST:
{
   "virtual": "test"
}
Response : {"message": "A Big Success!"} as base64 encoded in plugin
GET:
hello=world&service=virtualized
Response : {"message": "Another Success!"} as base4 encoded in plugin

日志插件

HTTP Log

配置信息

基本描述

属性	描述
日志策略	HTTP日志
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`http-log`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.http_endpoint	http服务器端点，数据会发送到该端点
config.method	向http服务器发送数据的方法，默认是`POST`方法，其他支持的方法是`PUT`和`PATCH`
config.timeout	发送数据的超时时间，默认是10000ms
config.keepalive	空闲连接的等待时间，默认是60000ms

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=http-log" --data "config.http_endpoint=http://mockbin.org/bin/:id" --data "config.method=POST" --data "config.timeout=1000" --data "config.keepalive=1000"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=http-log" --data "config.http_endpoint=http://mockbin.org/bin/:id" --data "config.method=POST" --data "config.timeout=1000" --data "config.keepalive=1000"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=http-log" --data "config.http_endpoint=http://mockbin.org/bin/:id" --data "config.method=POST" --data "config.timeout=1000" --data "config.keepalive=1000"

日志格式

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        },
        "tls": {
            "version": "TLSv1.2",
            "cipher": "ECDHE-RSA-AES256-GCM-SHA384",
            "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384",
            "client_verify": "NONE"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

参数	描述
request	客户端发送的请求信息
response	发送给客户端的响应信息
tries	请求负载均衡记录信息
route	请求对应的路由信息
service	请求对应的服务信息
authenticated_entity	请求对应的凭证信息
workspaces	企业版本 >= 0.34 包含的信息，可以忽略
consumer	请求对应的消费者信息
latencies.proxy	从接收到客户端请求，到查找到指定服务花的时间
latencies.kong	Kong所有插件运行的时间
latencies.request	请求的总时常
client_ip	客户端的原始IP
started_at	请求的时间戳

TCP Log

配置信息

基本描述

属性	描述
日志策略	TCP日志
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`tcp-log`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.host	服务器Ip地址
config.port	服务器端口
config.timeout	发送数据的超时时间，默认是10000ms
config.keepalive	空闲连接的等待时间，默认是60000ms

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=tcp-log" --data "config.host=127.0.0.1" --data "config.port=9999"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=tcp-log" --data "config.host=127.0.0.1" --data "config.port=9999"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=tcp-log" --data "config.host=127.0.0.1" --data "config.port=9999"

日志格式

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        },
        "tls": {
            "version": "TLSv1.2",
            "cipher": "ECDHE-RSA-AES256-GCM-SHA384",
            "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384",
            "client_verify": "NONE"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

参数	描述
request	客户端发送的请求信息
response	发送给客户端的响应信息
tries	请求负载均衡记录信息
route	请求对应的路由信息
service	请求对应的服务信息
authenticated_entity	请求对应的凭证信息
workspaces	企业版本 >= 0.34 包含的信息，可以忽略
consumer	请求对应的消费者信息
latencies.proxy	从接收到客户端请求，到查找到指定服务花的时间
latencies.kong	Kong所有插件运行的时间
latencies.request	请求的总时常
client_ip	客户端的原始IP
started_at	请求的时间戳

UDP Log

配置信息

基本描述

属性	描述
日志策略	UDP日志
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`udp-log`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.host	服务器Ip地址
config.port	服务器端口
config.timeout	发送数据的超时时间，默认是10000ms
config.keepalive	空闲连接的等待时间，默认是60000ms

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=udp-log" --data "config.host=127.0.0.1" --data "config.port=9999" --data "config.timeout=10000"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=udp-log" --data "config.host=127.0.0.1" --data "config.port=9999" --data "config.timeout=10000"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=udp-log" --data "config.host=127.0.0.1" --data "config.port=9999" --data "config.timeout=10000"

日志格式

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        },
        "tls": {
            "version": "TLSv1.2",
            "cipher": "ECDHE-RSA-AES256-GCM-SHA384",
            "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384",
            "client_verify": "NONE"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

参数	描述
request	客户端发送的请求信息
response	发送给客户端的响应信息
tries	请求负载均衡记录信息
route	请求对应的路由信息
service	请求对应的服务信息
authenticated_entity	请求对应的凭证信息
workspaces	企业版本 >= 0.34 包含的信息，可以忽略
consumer	请求对应的消费者信息
latencies.proxy	从接收到客户端请求，到查找到指定服务花的时间
latencies.kong	Kong所有插件运行的时间
latencies.request	请求的总时常
client_ip	客户端的原始IP
started_at	请求的时间戳

转换插件

Correlation ID

配置信息

基本描述

属性	描述
转换策略	关联ID
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`correlation-id`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.header_name	用来关联Id的Http头，默认是 `Kong-Request-ID`
config.generator	关联Id的生成器，可以取 `uuid`、`uuid#counter` 或 `tracker`，默认是 `uuid#counter`
config.echo_downstream	是否将 `Kong-Request-ID` 返回给客户端，默认是false

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=correlation-id" --data "config.header_name=Kong-Request-ID" --data "config.generator=uuid#counter" --data "config.echo_downstream=false"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=correlation-id" --data "config.header_name=Kong-Request-ID" --data "config.generator=uuid#counter" --data "config.echo_downstream=false"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=correlation-id" --data "config.header_name=Kong-Request-ID" --data "config.generator=uuid#counter" --data "config.echo_downstream=false"

ID生成器

uuid
格式：

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

使用这种格式时，每个请求以十六进制形式生成UUID

uuid#counter
格式：

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx#counter

使用这种格式时，基于每个 worker 生成UUID，之后的请求会在UUID之后添加一个累加器，每个计数器从0开始计数，每个 worker 之间都是独立的，这种格式性能比较高，但是比较难以存储并进一步进行处理

tracker
格式：

ip-port-pid-connection-connection_requests-timestamp

使用这种格式时，关联Id更有实际意义：

参数	描述
ip	处理请求的服务器地址
port	处理请求的服务器端口
pid	nginx worker进程
connection	连接序列号
connection_requests	连接的请求序列号
timestamp	时间戳

Request Transformer

配置信息

基本描述

属性	描述
转换策略	请求转换
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`request-transformer`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.http_method	更改请求的Http方法
config.remove.headers	删除请求头
config.remove.querystring	删除请求参数
config.remove.body	删除请求体中的参数，content-type为 `application/json`、 `multipart/form-data` 或 `application/x-www-form-urlencoded` 中的一个
config.replace.headers	替换请求头，形式为键值对
config.replace.querystring	替换请求参数，形式为键值对
config.replace.body	替换请求体中的参数，形式为键值对，content-type为 `application/json`、 `multipart/form-data` 或 `application/x-www-form-urlencoded` 中的一个
config.rename.headers	重命名请求头，形式为键值对
config.rename.querystring	重命名请求参数，形式为键值对
config.rename.body	重命名请求体中的参数，形式为键值对，content-type为 `application/json`、 `multipart/form-data` 或 `application/x-www-form-urlencoded` 中的一个
config.add.headers	添加请求头，形式为键值对，如果原请求中没有该参数，添加一个；如果原请求中已经有了，直接忽略
config.add.querystring	添加请求参数，形式为键值对，如果原请求中没有该参数，添加一个；如果原请求中已经有了，直接忽略
config.add.body	添加请求体中的参数，形式为键值对，content-type为 `application/json`、 `multipart/form-data` 或 `application/x-www-form-urlencoded` 中的一个，如果原请求中没有该参数，添加一个；如果原请求中已经有了，直接忽略
config.append.headers	追加请求头，形式为键值对，如果原请求中没有该参数，添加一个；如果原请求中已经有了，再原样添加一个
config.append.querystring	追加请求参数，形式为键值对，如果原请求中没有该参数，添加一个；如果原请求中已经有了，直接忽略
config.append.body	追加请求体中的参数，形式为键值对，content-type为 `application/json`、 `multipart/form-data` 或 `application/x-www-form-urlencoded` 中的一个，如果原请求中没有该参数，添加一个；如果原请求中已经有了，直接忽略

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=request-transformer" --data "config.remove.headers=x-toremove" --data "config.remove.headers=x-another-one" --data "config.remove.querystring=qs-old-name:qs-new-name" --data "config.remove.querystring=qs2-old-name:qs2-new-name" --data "config.remove.body=formparam-toremove" --data "config.remove.body=formparam-another-one" --data "config.rename.headers=header-old-name:header-new-name" --data "config.rename.headers=another-old-name:another-new-name" --data "config.rename.querystring=qs-old-name:qs-new-name" --data "config.rename.querystring=qs2-old-name:qs2-new-name" --data "config.rename.body=param-old:param-new" --data "config.rename.body=param2-old:param2-new" --data "config.add.headers=x-new-header:value" --data "config.add.headers=x-another-header:something" --data "config.add.querystring=new-param:some_value" --data "config.add.querystring=another-param:some_value" --data "config.add.body=new-form-param:some_value" --data "config.add.body=another-form-param:some_value"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=request-transformer" --data "config.remove.headers=x-toremove" --data "config.remove.headers=x-another-one" --data "config.remove.querystring=qs-old-name:qs-new-name" --data "config.remove.querystring=qs2-old-name:qs2-new-name" --data "config.remove.body=formparam-toremove" --data "config.remove.body=formparam-another-one" --data "config.rename.headers=header-old-name:header-new-name" --data "config.rename.headers=another-old-name:another-new-name" --data "config.rename.querystring=qs-old-name:qs-new-name" --data "config.rename.querystring=qs2-old-name:qs2-new-name" --data "config.rename.body=param-old:param-new" --data "config.rename.body=param2-old:param2-new" --data "config.add.headers=x-new-header:value" --data "config.add.headers=x-another-header:something" --data "config.add.querystring=new-param:some_value" --data "config.add.querystring=another-param:some_value" --data "config.add.body=new-form-param:some_value" --data "config.add.body=another-form-param:some_value"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=request-transformer" --data "config.remove.headers=x-toremove" --data "config.remove.headers=x-another-one" --data "config.remove.querystring=qs-old-name:qs-new-name" --data "config.remove.querystring=qs2-old-name:qs2-new-name" --data "config.remove.body=formparam-toremove" --data "config.remove.body=formparam-another-one" --data "config.rename.headers=header-old-name:header-new-name" --data "config.rename.headers=another-old-name:another-new-name" --data "config.rename.querystring=qs-old-name:qs-new-name" --data "config.rename.querystring=qs2-old-name:qs2-new-name" --data "config.rename.body=param-old:param-new" --data "config.rename.body=param2-old:param2-new" --data "config.add.headers=x-new-header:value" --data "config.add.headers=x-another-header:something" --data "config.add.querystring=new-param:some_value" --data "config.add.querystring=another-param:some_value" --data "config.add.body=new-form-param:some_value" --data "config.add.body=another-form-param:some_value"

参数执行顺序
删除 -> 重命名 -> 替换 -> 添加 -> 追加

Response Transformer

配置信息

基本描述

属性	描述
转换策略	响应转换
插件作用域	服务、路由、消费者、全局
适用协议	http、https

参数

参数	描述
name	插件名称、此处为`response-transformer`
service_id	绑定的服务Id
route_id	绑定的路由Id
enabled	是否启用该插件，默认是true
consumer_id	绑定的消费者Id
config.remove.headers	删除响应头
config.remove.json	删除响应体
config.replace.headers	替换响应头，形式为键值对
config.replace.json	替换响应体，形式为键值对
config.add.headers	添加响应头，形式为键值对，如果原响应中没有该参数，添加一个；如果原响应中已经有了，直接忽略
config.add.json	添加响应体，形式为键值对，如果原响应中没有该参数，添加一个；如果原响应中已经有了，直接忽略
config.append.headers	追加响应头，形式为键值对，如果原响应中没有该参数，添加一个；如果原响应中已经有了，再原样添加一个
config.append.json	追加响应体，形式为键值对，如果原响应中没有该参数，添加一个；如果原响应中已经有了，再原样添加一个

使用详情

在服务上添加插件

curl -X POST http://kong:8001/services/{service}/plugins --data "name=response-transformer" --data "config.remove.headers=x-toremove, x-another-one" --data "config.remove.json=json-key-toremove, another-json-key" --data "config.add.headers=x-new-header:value,x-another-header:something" --data "config.add.json=new-json-key:some_value, another-json-key:some_value" --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

在路由上添加插件

curl -X POST http://kong:8001/routes/{route}/plugins --data "name=response-transformer" --data "config.remove.headers=x-toremove, x-another-one" --data "config.remove.json=json-key-toremove, another-json-key" --data "config.add.headers=x-new-header:value,x-another-header:something" --data "config.add.json=new-json-key:some_value, another-json-key:some_value" --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

在消费者上添加插件

curl -X POST http://kong:8001/consumers/{consumer}/plugins --data "name=response-transformer" --data "config.remove.headers=x-toremove, x-another-one" --data "config.remove.json=json-key-toremove, another-json-key" --data "config.add.headers=x-new-header:value,x-another-header:something" --data "config.add.json=new-json-key:some_value, another-json-key:some_value" --data "config.append.headers=x-existing-header:some_value, x-another-header:some_value"

参数执行顺序
删除 -> 替换 -> 添加 -> 追加

Kong插件向导

鉴权插件

Basic Authentication

配置信息

使用详情

凭证接口

HMAC Authentication

配置信息

使用详情

凭证接口

JWT

配置信息

使用详情

加密详情

凭证接口

Key Authentication

配置信息

使用详情

凭证接口

LDAP Authentication

配置信息

OAuth2.0 Authentication

配置信息

使用详情

OAuth2.0 Client Credentials模式

OAuth2.0 Authorization Code模式

Password Grant模式

刷新Token

安全插件

CORS

配置信息

使用详情

IP Restriction

配置信息

使用详情

流量控制插件

ACL

配置信息

使用详情

凭证接口

Proxy Caching

配置信息

使用详情

缓存API

Rate Limiting

配置信息

使用详情

RequestTermination

配置信息

使用详情

Kong Service Virtualization

配置信息

使用详情

日志插件

HTTP Log

配置信息

使用详情

日志格式

TCP Log

配置信息

使用详情

日志格式

UDP Log

配置信息

使用详情

日志格式

转换插件

Correlation ID

配置信息

使用详情

ID生成器

Request Transformer

配置信息

使用详情

Response Transformer

配置信息

使用详情

猜你喜欢

热点阅读