基于 YAML 文件的 OpenResty Edge 配置镜像
我们提供了一个命令行工具,用以支持基于本地 YAML 文件配置更新 OpenResty Edge 中的配置。配置按照分区划分,每组配置对应 OpenResty Edge 中的一个分区。可以使用 Git 等程序对本地配置进行版本控制。
以下文档内容解释了如何使用该工具。
创建 API 令牌
- 首先登录到 OpenResty Edge 管理控制台。
- 然后点击右上角的用户名:USERNAME > API 令牌 > 创建 API 令牌 > 复制 API 令牌。
更新或添加配置到 OpenResty Edge
我们将处理配置的命令行工具和初始配置分开到不同的包中,以防后续发布的新包中的初始配置将您更新过的配置覆盖了。
从 OpenResty 下载中心下载
openresty-edge-cmd-tools-VERSION.tar.gz
和openresty-edge-cmd-configs-VERSION.tar.gz
。openresty-edge-cmd-tools-VERSION.tar.gz
包含命令行工具。openresty-edge-cmd-configs-VERSION.tar.gz
包含配置。如果您正从其他平台迁移到 OpenResty Edge,我们可以对您的配置进行转换并为您提供示例。将
openresty-edge-cmd-tools-VERSION.tar.gz
和openresty-edge-cmd-configs-VERSION.tar.gz
包上传到已安装 Python3 并能够访问 OpenResty Edge 管理控制台的机器上。将
openresty-edge-cmd-configs-VERSION.tar.gz
解压得到以下目录:- openresty-edge-cmd-configs-VERSION/ |-- configs/ |-- global_lua_modules/ |-- util.lua |-- uuid.lua |-- ... |-- upstreams/ |-- upstream-a.yaml |-- upstream-b.yaml |-- ... |-- page_rules |-- 000-core-rules.yaml |-- other-rules.yaml |-- ... |-- basic_auth_groups |-- group1.yaml |-- global_configs.yaml
configs/
目录包含了某个分区的所有配置。global_lua_modules/
目录保存了全局 Lua 模块,每个 Lua 文件代表一个 Lua 模块。upstreams/
目录包含了上游服务器配置,您可以将上游分割成多个文件以便于管理。page_rules
目录中包含页面规则,这些规则将被添加到与分区相关的 HTTP 应用中,规则的顺序根据文件名称字母序和文件内的规则顺序决定。basic_auth_groups
目录中是 Basic 认证用户组及用户配置,当使用 Basic 认证相关动作时,需要用到。global_configs.yaml
文件包括全局配置,如全局用户变量。将
openresty-edge-cmd-tools-VERSION.tar.gz
解压得到以下目录:- openresty-edge-cmd-tools-VERSION/ |-- edge-config.py |-- gen-cert.sh
edge-config.py
是您可以执行以管理分区配置的命令行工具。 您可以通过命令行工具的-i
选项指定配置路径;当不指定选项-i
选项时,默认使用与edge-config.py
同目录的configs/
目录。您可以参考我们提供的配置文件和目录结构为其他环境生成配置。如果遇到任何问题,或者命令行工具需要支持额外的配置,请随时与我们联系,我们将非常乐意为您提供必要的支持。
安装命令行工具所需的依赖
pip3 install openresty-edge-sdk ruamel.yaml
openresty-edge-sdk
的版本应该大于或等于1.2.52
。执行命令行工具
如果您想看到这个命令行工具的使用方法,您可以执行以下命令:
python3 edge-config.py -h
这个命令的输出看起来像这样:
usage: edge-config.py [-h] -t API_TOKEN -u ADMIN_URL [-s] [-c] [-i CONFIGS_PATH] [-l LOCATION] [-d DOMAIN] (-p PARTITION_ID | -n PARTITION_NAME) Update or add OpenResty Edge configuration. optional arguments: -h, --help show this help message and exit -t API_TOKEN, --api-token API_TOKEN specify the API Token for sending the request -u ADMIN_URL, --admin-url ADMIN_URL specify the URL of the OpenResty Edge Admin. For example, https://admin.com:443 -s, --disable-ssl-verify turn off SSL verify for requests to access OpenResty Edge Admin -c, --cleanup based on the location. This option allows for the cleanup of page rules, application upstreams, global user variables, and resetting the access log format for partitions. It can also be used independently of the location -i CONFIGS_PATH, --configs-path CONFIGS_PATH specify the path to the configuration file; if not specified, the default is the 'configs' directory in the same directory as the current script -l LOCATION, --location LOCATION specify the configuration name that needs to be updated, supported: page_rules, upstreams, global_lua_modules, global_configs -d DOMAIN, --domain DOMAIN specify a domain name. When an HTTP application containing this domain exists, it will be updated; otherwise, a new application will be created -p PARTITION_ID, --partition-id PARTITION_ID specify the id of the partition where you want to add or update the configuration -n PARTITION_NAME, --partition-name PARTITION_NAME specify the name of the partition where you want to add or update the configuration
通过指定
-p PARTITION_ID
或-n PARTITION_NAME
选项,可以将配置更新到指定的分区。示例:
python3 edge-config.py -t 3ed00172-280e-4e43-a4ef-3c2fae5669ca -u https://192.168.1.1 -s -i /path/of/configs -n default -d test.com
此命令将更新配置到默认分区(名称为 default,id 为 1),如果 test.com 应用不存在,则会创建它。
如果您继续遇到 No module named 'MODULE_NAME'
错误,请使用以下命令安装依赖:
pip3 install MODULE_NAME
请将命令中的 MODULE_NAME
更改为实际的模块名称。
更多示例:
# 删除:lua 模块、全局用户变量、应用
# 重置:访问日志格式
python3 edge-config.py -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
-u https://192.168.1.1 -s -i /path/of/configs -n default -d test.com -c
# 从应用 "test.com" 中移除所有页面规则
python3 edge-config.py -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
-u https://192.168.1.1 -s -i /path/of/configs -n default -l page_rules -d test.com -c
# 从分区 1(默认)中移除所有 Lua 模块
python3 edge-config.py -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
-u https://192.168.1.1 -s -i /path/of/configs -n default -l global_lua_modules -c
# 将所有配置更新/插入到分区 1(默认)
python3 edge-config.py -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
-u https://192.168.1.1 -s -i /path/of/configs -n default -d test.com
# 将页面规则更新/插入到应用 "test.com"
python3 edge-config.py -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
-u https://192.168.1.1 -s -i /path/of/configs -n default -l page_rules -d test.com
配置示例
更多示例见基于 YAML 文件的 OpenResty Edge 配置示例。
- enable_rule: true
actions:
set-access-log-off: {}
print:
content_type: text/html
msg: favicon.ico 和 robots.txt
exit:
code: 200
conditions:
- op: eq
var: uri
vals:
- /favicon.ico
- /robots.txt
order: 1
comment: ''
- enable_rule: true
actions:
"user-code":
el: |-
{
my Str $transid;
true =>
foreign-call(module: "example", func: "go"),
$transid = ctx-var("lm_transid"),
$or_global_user_variable_uuid = $transid,
done;
}
comment: ''
页面规则是有序的,更新到 Edge Admin 时将保持配置文件中的顺序。此示例包括两条页面规则。第一条规则判断 URI 是否为 /favicon.ico
或 /robots.txt
,如果是,则禁用访问日志并输出指定内容。第二条规则无条件执行一段 Edgelang 代码,该代码设置全局用户变量 $or_global_user_variable_uuid
。
所有页面规则组成一个数组,每条页面规则都是数组的一个元素。
错误消息示例
对于配置文件错误,命令行工具将尝试提供提示,指出错误发生的具体行号。
[!] Error: invalid port in upstream upstream_name_foo: 70000, file: foo.yaml, line: 6.
还有其他一些错误,例如下面的错误表明输入的配置路径不正确,命令行工具找不到这个路径。
[!] Error: bad configs path: /bad/path.