Deck CLI#
decK 是为 API 生命周期自动化(APIOps)开发的命令行工具。开发和运维团队可以用它从开发到部署全流程管理 API,确保 API 集成的一致性、可靠性和速度。
decK 命令具备以下功能和特点:
导出(备份)
将现有 Kong 配置导出为 YAML 格式的配置文件
导入(还原)
使用导出的或手写的配置文件应用到 Kong 配置
差异和同步
decK 可以比较文件中的配置和 Kong 数据库中的配置,并进行同步,也可以检测配置差异
反向同步
如果 Kong 数据库中有而文件中没有的配置,也可以反向同步到文件
校验
校验配置文件的语法错误
重置
删除 Kong 数据库中的所有实体
并发操作
对 Kong Admin API 的调用会并发执行,利用多线程加速同步过程
Kong 认证
通过 --headers Kong-Admin-Token:test
这种方式在 HTTP 头中加入认证信息,可访问需要认证的 Kong
多文件管理 Kong 配置
可以根据实体间共享的一组标签,将 Kong 配置拆分为多个文件管理
配置管理自动化
decK 设计为 CI 流水线的一部分,不仅能推送配置到 Kong,还能检测配置漂移
下面按子命令举例说明
事前准备#
以下 Kong 配置文件为基础示例。包含一个 Service 和一个 Route。
1
2
3
4
5
6
7
8
9
10
11
| _format_version: "3.0"
services:
- host: httpbin.org
name: uuid-generator
path: /
protocol: http
routes:
- name: uuid-generator
paths:
- ~/uuid$
strip_path: false
|
deck gateway 相关#
deck gateway ping#
首先用 ping 检查连通性
1
2
3
| deck gateway ping --headers Kong-Admin-Token:test
Successfully connected to Kong!
Kong version: 3.4.3.5
|
如果不指定 Kong Admin API 的地址,默认会连接到 localhost:8001
。
如需检查非本地 Kong 的连通性,用 --kong-addr
指定地址。
1
2
3
| deck gateway ping --kong-addr http://18.178.66.113:8001 --headers Kong-Admin-Token:test
Successfully connected to Kong!
Kong version: 3.4.3.5
|
deck gateway validate#
校验配置文件语法。无问题时无输出,有语法错误会显示行号和错误内容。
该命令会连接 Kong Admin API 进行校验,耗时较长但能发现严重错误。如只需本地校验可用 deck file validate
。
校验过程中不会修改 Kong 数据库。
1
2
3
| deck gateway validate kong.yaml --headers Kong-Admin-Token:test
Error: 1 errors occurred:
reading file kong.yaml: validating file content: unmarshaling file content: error converting YAML to JSON: yaml: line 7: could not find expected ':'
|
deck gateway sync#
将上述配置文件应用到 Kong Gateway。默认从标准输入读取配置。
1
2
3
4
5
6
7
| $ cat kong.yaml | deck gateway sync --headers Kong-Admin-Token:test
creating service uuid-generator
creating route uuid-generator
Summary:
Created: 2
Updated: 0
Deleted: 0
|
deck gateway diff#
更新文件后,执行 deck gateway diff
,检查 Kong 数据库和文件配置的差异。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| $ sed -i 's/protocol: http/protocol: https/g' kong.yaml
$ deck gateway diff kong.yaml --headers Kong-Admin-Token:test
updating service uuid-generator {
"connect_timeout": 60000,
"enabled": true,
"host": "httpbin.org",
"id": "033e20b1-9a83-4f80-a75e-ee4f9b354676",
"name": "uuid-generator",
"path": "/",
"port": 80,
- "protocol": "http",
+ "protocol": "https",
"read_timeout": 60000,
"retries": 5,
"write_timeout": 60000
}
Summary:
Created: 0
Updated: 1
Deleted: 0
|
如需应用文件配置,再次执行 deck gateway sync。
deck gateway dump#
如需将数据库配置反映到文件或做备份,可用 dump。
之后再 diff 一次确认数据库配置已写入文件。
1
2
3
4
5
6
7
8
| $ deck gateway dump -o kong.yaml --headers Kong-Admin-Token:test
File 'kong.yaml' already exists. Do you want to overwrite it? yes
$ deck gateway diff kong.yaml --headers Kong-Admin-Token:test
Summary:
Created: 0
Updated: 0
Deleted: 0
|
deck gateway reset#
删除 Kong 数据库中的所有配置。
1
2
3
4
5
6
7
8
9
| deck gateway reset --headers Kong-Admin-Token:test
This will delete all configuration from Kong's database.
> Are you sure? yes
deleting route uuid-generator
deleting service uuid-generator
Summary:
Created: 0
Updated: 0
Deleted: 2
|
deck file 相关#
deck file 主要处理 Kong 配置文件相关操作。
deck file validate#
类似 deck gateway validate
,但只校验本地文件语法,不与 Kong Admin API 通信,速度更快。
1
2
3
| deck file validate kong.yaml
Error: 1 errors occurred:
reading file kong.yaml: validating file content: unmarshaling file content: error converting YAML to JSON: yaml: line 7: could not find expected ':'
|
deck file kong2kic#
将 Kong 配置文件转换为 Kubernetes 可用格式。
例如,以下 kong.yaml 配置文件:
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
| _format_version: "3.0"
services:
- connect_timeout: 60000
enabled: true
host: httpbin.org
name: uuid-generator
path: /
port: 80
protocol: http
read_timeout: 60000
retries: 5
routes:
- https_redirect_status_code: 426
name: uuid-generator
path_handling: v0
paths:
- ~/uuid$
preserve_host: false
protocols:
- http
- https
regex_priority: 0
request_buffering: true
response_buffering: true
strip_path: false
write_timeout: 60000
|
HTTPRoute + Service(默认)#
要生成 HTTPRoute + Service 资源,执行以下命令:
1
| deck file kong2kic -s kong.yaml
|
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
| apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
annotations:
konghq.com/https-redirect-status-code: "426"
konghq.com/path-handling: v0
konghq.com/preserve-host: "false"
konghq.com/regex-priority: "0"
konghq.com/request-buffering: "true"
konghq.com/response-buffering: "true"
konghq.com/strip-path: "false"
name: uuid-generator-uuid-generator
spec:
parentRefs:
- name: kong
---
apiVersion: v1
kind: Service
metadata:
annotations:
konghq.com/connect-timeout: "60000"
konghq.com/path: /
konghq.com/protocol: http
konghq.com/read-timeout: "60000"
konghq.com/retries: "5"
konghq.com/write-timeout: "60000"
name: uuid-generator
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: uuid-generator
---
|
Ingress + Service#
如需生成 Ingress + Service 资源,加 –ingress 参数再执行命令。
1
| deck file kong2kic -s kong.yaml --ingress
|
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
| apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
konghq.com/https-redirect-status-code: "426"
konghq.com/path-handling: v0
konghq.com/preserve-host: "false"
konghq.com/protocols: http,https
konghq.com/regex-priority: "0"
konghq.com/request-buffering: "true"
konghq.com/response-buffering: "true"
konghq.com/strip-path: "false"
name: uuid-generator-uuid-generator
spec:
ingressClassName: kong
rules:
- http:
paths:
- backend:
service:
name: uuid-generator
port:
number: 80
path: /~/uuid$
pathType: ImplementationSpecific
---
apiVersion: v1
kind: Service
metadata:
annotations:
konghq.com/connect-timeout: "60000"
konghq.com/path: /
konghq.com/protocol: http
konghq.com/read-timeout: "60000"
konghq.com/retries: "5"
konghq.com/write-timeout: "60000"
name: uuid-generator
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: uuid-generator
---
|
deck file openapi2kong#
将 OpenAPI 规范(OAS)转换为 Kong 配置文件。
例如,以下 OAS 文件不仅包含 Service 和 Route,还有 Plugin。
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
| openapi: 3.0.0
tags:
- description: Creates a random UUID and returns it in a JSON structure
name: Generate UUID
- description: Returns a delayed response (max of 10 seconds).
name: Delayed Response
info:
contact:
email: [email protected]
url: https://konghq.com/
description: A simple service returning a UUID based on https://httpbin.org
title: UUID generator based on httpbin.org
version: 1.0.8
paths:
/uuid:
get:
operationId: uuid
summary: Return a UUID.
description: Return a UUID
responses:
"200":
description: A UUID4.
tags:
- Generate UUID
x-kong-plugin-rate-limiting:
enabled: true
config:
minute: 5
x-kong-plugin-proxy-cache:
enabled: true
config:
strategy: memory
servers:
- url: https://httpbin.org/
|
用如下命令一键转换,插件配置也会被正确转换。
1
| deck file openapi2kong -s openapi.yaml
|
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
| _format_version: "3.0"
services:
- host: httpbin.org
id: 50f943d2-3299-5315-adf6-7da92729c8ce
name: uuid-generator-based-on-httpbin-org
path: /
plugins: []
port: 443
protocol: https
routes:
- id: c58bf17c-dfd9-544d-965b-cc3e26be87f1
methods:
- GET
name: uuid-generator-based-on-httpbin-org_uuid
paths:
- ~/uuid$
plugins:
- config:
strategy: memory
enabled: true
id: fc364f07-919d-5fd5-b9fe-ac6540848e4f
name: proxy-cache
tags: []
- config:
minute: 5
enabled: true
id: ff5cb72c-3698-5403-9420-3beb6c2fb26c
name: rate-limiting
tags: []
regex_priority: 200
strip_path: false
tags: []
tags: []
upstreams: []
|
deck file add-plugins#
为 Kong 配置文件添加插件定义。
以如下常见配置为例:
1
2
3
4
5
6
7
8
9
10
11
12
| _format_version: "3.0"
services:
- host: httpbin.org
name: uuid-generator
path: /
port: 80
protocol: http
routes:
- name: uuid-generator
paths:
- ~/uuid$
strip_path: false
|
执行如下命令,像 --selector='services[*]'
这样写,--config
定义的插件会加到所有 Service 上。
如果把 --selector
改成 ='route[*]'
,插件会加到所有 Route 上。
1
| cat kong.yaml | deck file add-plugins --selector='services[*]' --config='{"plugins":[{"config":{"strategy":"memory"},"enabled":true,"name":"proxy-cache"}]}'
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| _format_version: "3.0"
services:
- host: httpbin.org
name: uuid-generator
path: /
plugins:
- plugins:
- config:
strategy: memory
enabled: true
name: proxy-cache
port: 80
protocol: http
routes:
- name: uuid-generator
paths:
- ~/uuid$
strip_path: false
|
上述方法中,--selector
和 --config
都写在命令行上,命令会很长。
也可以把这两个参数保存到文件再应用。例如如下内容保存为 JSON 文件:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| { "_format_version": "1.0",
"add-plugins": [
{ "selectors": [
"service[*]"
],
"overwrite": false,
"plugins": [
{ "name": "proxy-cache",
"config": {
"strategy": "memory"
}
}
]
}
]
}
|
然后 add-plugins 后面加这个文件,STDIN 里的配置内容会被追加插件。
1
| cat kong.yaml | deck file add-plugins proxy-cache.json
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| _format_version: "3.0"
services:
- host: httpbin.org
name: uuid-generator
path: /
plugins:
- config:
strategy: memory
name: proxy-cache
port: 80
protocol: http
routes:
- name: uuid-generator
paths:
- ~/uuid$
strip_path: false
|
还有更多子命令,前半部分先介绍到这里。
- deck file add-tags - 给 decK 文件中的对象添加标签
- deck file convert - 不同格式文件互转
- deck file lint - 按规则集校验文件
- deck file list-tags - 列出 decK 文件中对象的标签
- deck file merge - 合并多个 decK 文件
- deck file namespace - 路由路径加前缀实现命名空间
- deck file patch - 给 decK 文件打补丁
- deck file remove-tags - 移除 decK 文件对象的标签
- deck file render - 合并多个完整配置文件渲染为一个 Kong 声明式配置文件。