kong 插件应用（一）

插件优先顺序

插件将始终运行一次，并且每个请求只能运行一次。但是它将运行的配置取决于为其配置的实体。

可以为各种实体，实体组合甚至全局配置插件。这很有用，例如，当您希望以某种方式为大多数请求配置插件，但使经过身份验证的请求的行为略有不同时。

因此，将插件应用于具有不同配置的不同实体时，存在运行该插件的优先顺序。其规则是：插件关于配置了多少个实体越具体，其优先级越高。

多次配置插件后，完整的优先级顺序为： (1优先级最高，8优先级最低)

  1. 在以下各项的组合上配置的插件：Route，Service和Consumer。（Consumer意味着必须对请求进行身份验证）。
  2. 在Route和Consumer的组合上配置的插件。（Consumer意味着必须对请求进行身份验证）。
  3. 在Service和Consumer的组合上配置的插件。（Consumer意味着必须对请求进行身份验证）。
  4. 在Route和Service的组合上配置的插件。
  5. 在Consumer配置的插件。（Consumer意味着必须对请求进行身份验证）。
  6. 在Route上配置的插件。
  7. 在Service上配置的插件。
  8. 配置为全局运行的插件。

file-log

兼容的协议

该插件兼容以下协议：

  • http
  • https
  • grpc
  • grpcs

在Services上启用

1
2
3
4
$ curl -X POST  \
--url http://localhost:8001/services/{service}/plugins \
--data 'name=file-log' \
--data 'config.path=/var/log/konglogs/logs.log'

其中 {service}是service的id或者name

在Routes上启用

1
2
3
4
$ curl -X POST  \
--url http://localhost:8001/routes/{route}/plugins \
--data 'name=file-log' \
--data 'config.path=/var/log/konglogs/logs.log'

其中 {route}是route的id或者name

在Consumers上启用

1
2
3
4
$ curl -X POST  \
--url http://localhost:8001/consumers/{consumer}/plugins \
--data 'name=file-log' \
--data 'config.path=/var/log/konglogs/logs.log'

其中 {consumer}是consumer的id或者username

全局启用

1
2
3
4
$ curl -X POST  \
--url http://localhost:8001/plugins \
--data 'name=file-log' \
--data 'config.path=/var/log/konglogs/logs.log'

参数

参数 解释
name 要使用的插件名称，本处为file-log
service.id service的id
route.id route的id
consumer.id consumer的id
enabled 默认为true 这个插件是否被应用
config.path 日志存放的文件，该文件必须可以为kong可写
config.reopen 默认false 在Kong 0.10.2中引入。 确定是否在每次请求时关闭并重新打开日志文件。 如果文件没有重新打开，并且已被删除/旋转，则插件将继续写入陈旧的文件描述符，从而丢失信息。 （该处我没明白）

日志格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
{
    "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 包含有关请求的特定路线的Kong属性
  • service 包含与所请求路线相关的服务的Kong属性
  • authenticated_entity 包含有关已认证凭据的Kong属性（如果已启用身份验证插件）
  • workspaces包含与所请求路线关联的工作区的Kong属性。仅在Kong Enterprise版本> = 0.34中。
  • consumer 包含经过身份验证的使用者（如果已启用身份验证插件）
  • latencies 包含有关延迟的一些数据：
    • proxy 是最终服务处理请求所花费的时间
    • kong 是运行所有插件所需的内部Kong延迟
    • request是从客户端读取第一个字节到将最后一个字节发送到客户端之间经过的时间。对于检测慢速客户端非常有用。
  • client_ip 包含原始客户端IP地址
  • started_at 包含开始处理请求的时间的UTC时间戳。

注意事项

此日志记录插件将仅记录HTTP请求和响应数据。

zipkin

兼容的协议

该插件兼容以下协议：

  • http
  • https
  • grpc
  • grpcs
  • tcp
  • tls

在Service 上启用

1
2
3
4
5
curl -X POST http://localhost:8001/services/{service}/plugins \
    --data "name=zipkin"  \
    --data "config.http_endpoint=http://your.zipkin.collector:9411/api/v2/spans" \
    --data "config.sample_ratio=0.001" \
    --data "config.include_credential=true"

其中{service} 可以是service的id或者name

在Route上启用

1
2
3
4
5
curl -X POST http://localhost:8001/routes/{route}/plugins \
    --data "name=zipkin"  \
    --data "config.http_endpoint=http://your.zipkin.collector:9411/api/v2/spans" \
    --data "config.sample_ratio=0.001" \
    --data "config.include_credential=true"

其中{route} 可以是route的id或者name

在Consumer上启用

1
2
3
4
5
curl -X POST http://localhost:8001/consumers/{consumer}/plugins \
    --data "name=zipkin"  \
    --data "config.http_endpoint=http://your.zipkin.collector:9411/api/v2/spans" \
    --data "config.sample_ratio=0.001" \
    --data "config.include_credential=true"

其中{consumer} 可以是consumer的id或者name

全局启用

1
2
3
4
5
6
curl -X POST \
--url http://localhost:8001/plugins \
    --data "name=zipkin"  \
    --data "config.http_endpoint=http://your.zipkin.collector:9411/api/v2/spans" \
    --data "config.sample_ratio=0.001" \
    --data "config.include_credential=true"

参数详解

参数 解释
name 该处只为zipkin
service.id Service的id
route.id Route的id
consumer.id Consumer的id
enabled 默认为true 是否启用
config.http_endpoint kong上报到zipkin的完整http(https)地址
config.sample_ratio 默认为0.001 是否进行采样，0是不采样，1是完整采样
config.default_service_name zipkin的服务名称设置。
config.include_credential 默认为true 当前经过身份验证的消费者的凭据是否应该包含在发送到Zipkin服务器的元数据中

工作原理

当启用时，此插件以与zipkin兼容的方式跟踪请求。

代码是围绕opentrace核心构建的，使用opentrace -lua库来收集Kong每个阶段请求的定时数据。插件使用兼容opentrace -lua的提取器、注入器和报告器来实现Zipkin的协议。

提取器和注入器

一个开放式的“提取器”从传入的请求中收集信息。 如果传入请求中不存在任何跟踪ID，则根据sample_ratio配置值可能会生成一个跟踪ID。

开放式跟踪“注入器”将跟踪信息添加到外发请求中。 目前，仅由kong代理请求注入者； 它尚未用于数据库请求或其他插件（例如http-log插件）的请求。

此插件遵循Zipkin的B3规范，说明要使用的HTTP标头。 此外，它还支持Jaegar风格的uberctx-标头，用于传播包。

上报

开放式跟踪“报告器”是将跟踪数据报告给另一个系统的方式。 该插件记录给定请求的跟踪数据，并使用Zipkin v2 API将其批量发送到Zipkin服务器。 请注意，需要zipkin 1.31或更高版本。

http_endpoint配置变量必须包含完整的uri，包括协议，主机，端口和路径部分（即uri可能以/api/v2/spans结尾）。

response-transformer

兼容协议

  • http
  • https

在 Service上启用

1
2
3
4
5
6
7
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"

{service}可以是Service的id或者name

在 Route上启用

1
2
3
4
5
6
7
curl -X POST http://kong:8001/routes/{routes}/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"

{routes}可以是Routes的id或者name

在 Consumers上启用

1
2
3
4
5
6
7
curl -X POST http://kong:8001/consumers/{consumers}/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"

{consumers}可以是Consumers的id或者name

全局启用

1
2
3
4
5
6
7
curl -X POST http://kong:8001/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"

参数详解

参数 解释
name 插件名称，此处为response-transformer
service.id service的id
route.id route的id
consumer.id consumer的id
enabled 默认为true 是否启用该插件
config.remove.headers 需要取消的header的名字列表
config.remove.json 需要移除的json的名字列表
config.rename.headers 需要重命名header的列表, 格式为：original_header_name: new_header_name,如果original_header存在，则重命名，否则忽略。这个是重命名header的name
config.replace.headers 需要替换header的列表,格式为header_name: header_value ,如果header_name存在，则替换，不存在忽略。这个替换的是header的value
config.replace.json 需要替换的json列表，格式为：josn_key: josn_value， 如果json_key存在，则将该josn_key的value替换成json_value，不存在，忽略。
config.add.headers 需要新增的header的列表，格式为：header_name: header_value， 如果header_name存在，忽略，不存在则新增。
config.add.json 需要新增的json的列表，格式为：json_name: json_value， 如果json_name存在，则忽略，不存在则新增。
config.append.headers 需要新增的header的列表，格式为：header_name: header_value， 如果header_name存在，替换，不存在则新增。
config.append.json 需要新增的json的列表，格式为：json_name: json_value， 如果json_name存在，则替换，不存在则新增。

注意：如果value中包含 , ，不能使用分割符，必须使用数组

执行顺序

插件按照以下顺序执行响应转换:

remove –> rename –> replace –> add –> append

示例

新增响应头

分别键值对方式

1
2
3
4
curl -X POST http://localhost:8001/routes/{route}/plugins \
  --data "name=response-transformer" \
  --data "config.add.headers[1]=h1:v1" \
  --data "config.add.headers[2]=h2:v1"

header返回对比

upstream response headers proxied response headers
h1: v1 h1: v1
h2: v1

逗号分隔符方式

1
2
3
4
curl -X POST http://localhost:8001/routes/{route}/plugins \
  --data "name=response-transformer" \
  --data "config.add.headers=h1:v1,h2:v2"

header返回对比

upstream response headers proxied response headers
h1: v1 h1: v1
h2: v1

json方式

1
2
3
4
curl -X POST http://localhost:8001/routes/{route}/plugins \
  --header 'content-type: application/json' \
  --data '{"name": "response-transformer", "config": {"add": {"headers": ["h1:v2", "h2:v1"]}}}'

header返回对比

upstream response headers proxied response headers
h1: v1 h1: v1
h2: v1

添加body属性和header

1
2
3
4
5
curl -X POST http://localhost:8001/routes/{route}/plugins \
  --data "name=response-transformer" \
  --data "config.add.json=p1:v1,p2=v2" \
  --data "config.add.headers=h1:v1"

header返回对比

upstream response headers proxied response headers
h1: v2 h1: v2
h2: v1
h3: v1 h1: v1
h2: v1
h3: v1

body返回对比

upstream response JSON body proxied response body
{} {“p1” : “v1”, “p2”: “v2”}
{“p1” : “v2”} {“p1” : “v2”, “p2”: “v2”}

添加多个header并删除body

1
2
3
4
curl -X POST http://localhost:8001/routes/{route}/plugins \
  --header 'content-type: application/json' \
  --data '{"name": "response-transformer", "config": {"append": {"headers": ["h1:v2", "h2:v1"]}, "remove": {"json": ["p1"]}}}'

header返回对比

upstream response headers proxied response headers
h1: v1 h1: v1
h1: v2
h2: v1

body返回对比

upstream response JSON body proxied response body
{“p2”: “v2”} {“p2”: “v2”}
{“p1” : “v1”, “p2” : “v1”} {“p2”: “v2”}

Rate Limiting

支持协议

  • http
  • https

在Services上启用

1
2
3
4
5
curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=rate-limiting"  \
    --data "config.second=5" \
    --data "config.hour=10000" \
    --data "config.policy=local"

{service} 可以代表service的id或者name

在Route上启用

1
2
3
4
5
curl -X POST http://kong:8001/routes/{route}/plugins \
    --data "name=rate-limiting"  \
    --data "config.second=5" \
    --data "config.hour=10000" \
    --data "config.policy=local"

{route} 可以代表route的id或者name

在Consumer上启用

1
2
3
4
5
curl -X POST http://kong:8001/consumers/{consumers}/plugins \
    --data "name=rate-limiting"  \
    --data "config.second=5" \
    --data "config.hour=10000" \
    --data "config.policy=local"

{consumers} 可以代表consumers的id或者name

全局启用

1
2
3
4
5
curl -X POST http://kong:8001/plugins \
    --data "name=rate-limiting"  \
    --data "config.second=5" \
    --data "config.hour=10000" \
    --data "config.policy=local"
Linux
#kong #kong plugins
kong 插件应用（一）
https://randzz.cn/805ec6e8a911/kong-插件应用（一）/
作者
Ezreal Rao
发布于
2020年6月10日
许可协议