跳到主要内容
版本:3.2.16.4.1

声明式管理 API7 企业版

API7 命令行工具 ADC(API7 Declarative CLI)提供了声明式配置 API7 企业版的方式,可替代 Admin API 或控制台。

ADC 以 YAML 文件 adc.yaml 为准配置 API7 企业版。

DevOps 团队可以将 ADC 集成到现有的版本控制系统和 CI/CD 流水线中。

本文介绍如何设置 ADC,并通过它管理 API7 企业版。你将了解如何:

  1. 配置 ADC 并连接 API7 企业版实例
  2. 将配置同步到已连接的实例
  3. 修改配置、查看改动并同步改动
备注
  1. adc convert 支持将 OpenAPI 3.0 定义文件转换为 ADC 配置文件(adc.yaml)。转换结果可能不完整,你可能需要修改转换后的配置,例如补充授权策略或绑定服务 ID。API7.ai 计划改进此功能。
  2. 无论使用何种版本控制系统或防火墙策略,只要 ADC 可以访问 Admin API,就能正常使用。本文示例在本地计算机上安装 ADC。

前提条件​

  1. 安装 API7 企业版。

安装 ADC​

ADC 提供适用于 macOS、Linux 和 Windows 的二进制文件。运行以下命令下载并安装适合你的版本:

export ADC_VERSION="0.8.0"
export ADC_OS="darwin" # or linux, windows
export ADC_ARC="arm64" # or amd64

wget "https://run.api7.ai/adc/release/adc_${ADC_VERSION}_${ADC_OS}_${ADC_ARC}.tar.gz"
tar -zxvf "adc_${ADC_VERSION}_${ADC_OS}_${ADC_ARC}.tar.gz"
mv adc /usr/local/bin/adc

运行以下命令,确认 ADC 已正确安装:

adc help

你会看到类似以下的输出:

Usage: adc [options] [command]

Options:
-V, --version output the version number
-h, --help display help for command

Commands:
ping [options] Verify connectivity with the backend
dump [options] Dump configurations from the backend
diff [options] Show the difference between local and backend configurations
sync [options] Sync local configurations to the backend
convert Convert other API specs to ADC configurations
lint [options] Check provided configuration files, local execution only, ensuring inputs meet ADC requirements
help [command] display help for command

生成 API Token​

使用 ADC 之前,需要先生成 API Token 来访问 Admin API。可以采用以下任一方式:

  1. 在控制台中生成 Token。登录后,依次打开 个人资料、Token,然后选择 生成新 Token。
  2. 通过 Admin API 生成 Token。

配置 ADC​

你可以使用命令行参数以命令式方式配置 ADC,也可以使用环境变量以声明式方式配置 ADC。

下面的示例配置控制面地址和 Token,使 ADC 能连接到 API7 企业版实例。

创建 .env 文件,填写以下内容:

ADC_BACKEND=api7ee

# 替换为你的控制面地址
ADC_SERVER=https://152.42.234.39:7443

# 替换为你的 ADC Token
ADC_TOKEN=YOUR_ADC_TOKEN

ADC also supports the ADC_CA_CERT_FILE, ADC_TLS_CLIENT_CERT_FILE, ADC_TLS_CLIENT_KEY_FILE, and ADC_TLS_SKIP_VERIFY environment variables for TLS configurations.

运行以下命令验证配置:

adc ping

你应当看到类似以下的输出:

Connected to the backend successfully!
提示

运行 adc ping -h 查看可用参数。你可以使用上文所示的环境变量,也可以使用等效的命令行参数配置 ADC。

同步配置​

API7 企业版的配置定义在 YAML 文件 adc.yaml 中,由 ADC 同步。

以下示例定义了三个服务:

adc.yaml
services:
- name: SOAP Service
description: "This Service is for SOAP requests"
upstream:
name: default
scheme: https
type: roundrobin
hash_on: vars
nodes:
- host: apps.learnwebservices.com
port: 443
weight: 1
priority: 0
retry_timeout: 0
pass_host: pass
routes:
- uris:
- /services/hello
name: SOAP proxy
methods:
- POST
- uris:
- /SayHello
name: REST to SOAP
methods:
- POST
plugins:
soap:
wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl
- name: httpbin Service
description: "This is the httpbin Services proxy service"
labels:
app: httpbin
custom_key: custom_value
routes:
- name: Generate UUID
methods:
- GET
uris:
- /uuid
- name: Anything
methods:
- GET
uris:
- /anything
plugins:
key-auth:
_meta:
disable: false
- name: Rate Limited IP
methods:
- GET
uris:
- /ip
plugins:
limit-count:
_meta:
disable: false
count: 2
time_window: 10
rejected_code: 429
policy: local
upstream:
name: default
scheme: http
type: roundrobin
hash_on: vars
nodes:
- host: httpbin.org
port: 80
weight: 1
priority: 0
retry_timeout: 0
pass_host: pass
- name: SSE Service
labels:
service: sse
upstream:
scheme: https
nodes:
- host: www.esegece.com
port: 2053
weight: 1
priority: 0
type: roundrobin
pass_host: node
plugins:
proxy-buffering:
disable_proxy_buffering: true
routes:
- name: SSE API
uris:
- /sse
methods:
- GET
consumers:
- username: tom
plugins:
key-auth:
key: tomskey
ssls: []
global_rules: {}

运行以下命令,将配置同步到已连接的实例:

adc sync -f adc.yaml

同步成功后会看到类似以下的输出:

✔ Load local configuration
✔ Load remote configuration
✔ Diff configuration
✔ Sync configuration

向路由发送请求,测试已创建的 httpbin Service:

curl "152.42.234.39:9080/uuid" -v
* Trying 152.42.234.39:9080...
* Connected to 152.42.234.39 (152.42.234.39) port 9080
> GET /uuid HTTP/1.1
> Host: 152.42.234.39:9080
> User-Agent: curl/8.4.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 53
< Connection: keep-alive
< Date: Wed, 17 Apr 2024 09:56:22 GMT
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Server: API7/3.2.8
<

{
"uuid": "22b888f4-9e96-4d09-93a2-408b14e772fe"
}

* Connection #0 to host 152.42.234.39 left intact

/anything 路由启用了 key-auth 插件。尝试向该路由发送不带密钥的请求:

curl "152.42.234.39:9080/anything"

此请求无法完成,你会收到以下消息:

{ "message": "Missing API key found in request" }

将密钥添加到请求头:

curl "152.42.234.39:9080/anything" -H "apikey: tomskey"

请求通过身份认证,你会收到预期的响应:

{
"args": {},
"data": "",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Apikey": "tomskey",
"Host": "152.42.234.39",
"User-Agent": "curl/8.4.0",
"X-Amzn-Trace-Id": "Root=1-661f9d57-42c4a66b07b361713713da44",
"X-Forwarded-Host": "152.42.234.39"
},
"json": null,
"method": "GET",
"origin": "182.255.32.50, 152.42.234.39",
"url": "http://152.42.234.39/anything"
}

修改配置​

如需修改配置,更新 adc.yaml 即可。此文件是唯一的配置来源,你所做的修改会同步并应用到已连接的实例。

以下示例在 httpbin Service 中添加了一条 /headers 路由:

services:
- name: SOAP Service
description: ""
upstream:
name: default
scheme: https
type: roundrobin
hash_on: vars
nodes:
- host: apps.learnwebservices.com
port: 443
weight: 1
priority: 0
retry_timeout: 0
pass_host: pass
routes:
- uris:
- /services/hello
name: SOAP proxy
methods:
- POST
- uris:
- /SayHello
name: REST to SOAP
methods:
- POST
plugins:
soap:
wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl
- name: httpbin Service
description: ""
labels:
app: httpbin
custom_key: custom_value
routes:
- name: Get Headers
methods:
- GET
uris:
- /headers
- name: Generate UUID
methods:
- GET
uris:
- /uuid
- name: Anything
methods:
- GET
uris:
- /anything
plugins:
key-auth:
_meta:
disable: false
- name: Rate Limited IP
methods:
- GET
uris:
- /ip
plugins:
limit-count:
_meta:
disable: false
count: 2
time_window: 10
rejected_code: 429
policy: local
upstream:
name: default
scheme: http
type: roundrobin
hash_on: vars
nodes:
- host: httpbin.org
port: 80
weight: 1
priority: 0
retry_timeout: 0
pass_host: pass
- name: SSE Service
labels:
service: sse
upstream:
scheme: https
nodes:
- host: www.esegece.com
port: 2053
weight: 1
priority: 0
type: roundrobin
pass_host: node
plugins:
proxy-buffering:
disable_proxy_buffering: true
routes:
- name: SSE API
uris:
- /sse
methods:
- GET
consumers:
- username: tom
plugins:
key-auth:
key: tomskey
ssls: []
global_rules: {}

同步修改后的配置之前,可以使用 diff 子命令查看将要进行的改动:

adc diff -f ./adc.yaml

输出会列出本次修改将引入的具体改动:

✔ Load local configuration
✔ Load remote configuration
✔ Diff configuration
› update consumer: "tom"
update route: "REST to SOAP"
update route: "SOAP proxy"
update route: "Rate Limited IP"
update route: "Anything"
update route: "Generate UUID"
create route: "Get Headers"
update service: "SSE Service"
update route: "SSE API"
Summary: 1 will be created, 8 will be updated, 0 will be deleted
✔ Write detailed diff results to file

如输出所示,diff 子命令还会生成 diff.yaml 文件,详细列出改动:

diff.yaml
- resourceType: consumer
type: update
resourceId: tom
resourceName: tom
oldValue:
username: tom
description: ""
plugins:
key-auth:
key: tomskey
newValue:
username: tom
plugins:
key-auth:
key: tomskey
diff:
added: {}
deleted: {}
updated: {}
- resourceType: route
type: update
resourceId: bef0a3351a392e74c960f9a58c1d025d803f2aef
resourceName: REST to SOAP
oldValue:
uris:
- /SayHello
name: REST to SOAP
methods:
- POST
enable_websocket: false
plugins:
soap:
wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl
newValue:
uris:
- /SayHello
name: REST to SOAP
methods:
- POST
plugins:
soap:
wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl
diff:
added: {}
deleted: {}
updated: {}
parentId: 602dfcf4c39218f87d40c5d1df8b531b49ca88e8
- resourceType: route
type: update
resourceId: da37e65d428446d156279156ac3248c00d0a1533
resourceName: SOAP proxy
oldValue:
uris:
- /services/hello
name: SOAP proxy
methods:
- POST
enable_websocket: false
newValue:
uris:
- /services/hello
name: SOAP proxy
methods:
- POST
diff:
added: {}
deleted: {}
updated: {}
parentId: 602dfcf4c39218f87d40c5d1df8b531b49ca88e8
- resourceType: route
type: update
resourceId: b586591b59c13461ed8932228cb23e53040c09d4
resourceName: Rate Limited IP
oldValue:
uris:
- /ip
name: Rate Limited IP
methods:
- GET
enable_websocket: false
plugins:
limit-count:
_meta:
disable: false
count: 2
policy: local
rejected_code: 429
time_window: 10
newValue:
name: Rate Limited IP
methods:
- GET
uris:
- /ip
plugins:
limit-count:
_meta:
disable: false
count: 2
time_window: 10
rejected_code: 429
policy: local
diff:
added: {}
deleted: {}
updated: {}
parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302
- resourceType: route
type: update
resourceId: 5f2de5df1a292b4c8a73f0ec23271233d75707c6
resourceName: Anything
oldValue:
uris:
- /anything
name: Anything
methods:
- GET
enable_websocket: false
plugins:
key-auth:
_meta:
disable: false
newValue:
name: Anything
methods:
- GET
uris:
- /anything
plugins:
key-auth:
_meta:
disable: false
diff:
added: {}
deleted: {}
updated: {}
parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302
- resourceType: route
type: update
resourceId: ed048a2f75fe33eab67319810fbb94bb778d7d97
resourceName: Generate UUID
oldValue:
uris:
- /uuid
name: Generate UUID
methods:
- GET
enable_websocket: false
newValue:
name: Generate UUID
methods:
- GET
uris:
- /uuid
diff:
added: {}
deleted: {}
updated: {}
parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302
- resourceType: route
resourceId: 6b124aff482499cbf7bdad5a56b13205b24ba58e
resourceName: Get Headers
type: create
newValue:
name: Get Headers
methods:
- GET
uris:
- /headers
parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302
- resourceType: service
type: update
resourceId: 54154d3cdf6379ab8686890d27fabb6bf8fa3ace
resourceName: SSE Service
oldValue:
name: SSE Service
description: ""
labels:
service: sse
upstream:
name: default
scheme: https
type: roundrobin
hash_on: vars
nodes:
- host: www.esegece.com
port: 2053
weight: 1
priority: 0
retry_timeout: 0
pass_host: node
plugins:
proxy-buffering:
disable_proxy_buffering: true
newValue:
name: SSE Service
labels:
service: sse
upstream:
scheme: https
nodes:
- host: www.esegece.com
port: 2053
weight: 1
priority: 0
type: roundrobin
pass_host: node
plugins:
proxy-buffering:
disable_proxy_buffering: true
diff:
added: {}
deleted:
upstream: {}
updated: {}
subEvents:
- &a1
resourceType: route
type: update
resourceId: 6b808fa543c7c3391321b813d0dc2d658ab02c10
resourceName: SSE API
oldValue:
uris:
- /sse
name: SSE API
methods:
- GET
enable_websocket: false
newValue:
name: SSE API
uris:
- /sse
methods:
- GET
diff:
added: {}
deleted: {}
updated: {}
parentId: 54154d3cdf6379ab8686890d27fabb6bf8fa3ace
- *a1

确认改动无误后,运行 sync 子命令,将修改后的配置同步到已连接的实例:

adc sync -f ./adc.yaml

发送请求,测试新建的路由:

curl "152.42.234.39:9080/headers"

你会收到类似以下的上游响应:

{
"headers": {
"Accept": "*/*",
"Host": "152.42.234.39",
"User-Agent": "curl/8.4.0",
"X-Amzn-Trace-Id": "Root=1-661f9edd-188a0adf5d3bf0a509f5b034",
"X-Forwarded-Host": "152.42.234.39"
}
}

后续步骤​

ADC 仍在开发中,会持续改进。完整的子命令列表请参阅 ADC 参考文档。