5 分钟阅读 | 最后修改: 2024-09-02, 3:26:06 pm

基于 YAML 文件的 OpenResty Edge 配置镜像

我们提供了一个命令行工具，用于支持基于本地 YAML 文件配置更新 OpenResty Edge 中的配置，以及从 OpenResty Edge 中导出配置到 yaml 文件中。本地配置中的应用配置按应用划分，全局配置按照分区划分。每份本地配置与 OpenResty Edge 中的一个分区和一个应用对应。您可以使用 Git 等版本控制工具对本地配置进行管理。

请注意：该命令行工具仅支持企业版的 OpenResty Edge。

本文档将详细介绍如何安装和使用该工具。

安装

安装命令行工具所需的依赖项
```
pip3 install --upgrade openresty-edge-sdk ruamel.yaml pyOpenSSL jinja2
```
请确保 openresty-edge-sdk 的版本大于或等于 1.2.60。

执行命令行工具

要查看该命令行工具的使用方法，请执行以下命令：

edge-config -h

命令输出如下（不同版本输出可能略有差异）：

usage: edge-config [-h] -t API_TOKEN -u ADMIN_URL [-s] [-i CONFIGS_PATH] [-e EMAIL_CONFIG_FILE] [-U USERS_CONFIG_PATH] [-F]
                  [-l LOCATION] [-d DOMAIN] [-P EXPORT_TO_PATH] [-p PARTITION_ID | -n PARTITION_NAME] [-c | -E]

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 verification for requests to access OpenResty Edge Admin
  -i CONFIGS_PATH, --configs-path CONFIGS_PATH
                        specify the path to the configuration file
  -e EMAIL_CONFIG_FILE, --email-config-file EMAIL_CONFIG_FILE
                        specify the file to the email configuration; if not specified, the email.yaml file in the configuration
                        path will be used
  -U USERS_CONFIG_PATH, --users-config-path USERS_CONFIG_PATH
                        specify the path to the users configuration; if not specified, the users/ path in the configuration
                        path will be used
  -F, --export-fake-privacy-info
                        use placeholders in place of privacy information when exporting
  -l LOCATION, --location LOCATION
                        specify the configuration name that needs to be updated, supported: page_rules, edgelang_rules,
                        upstreams, k8s_upstreams, user_variables, ip_lists, waf_whitelist, basic_auth_groups,
                        global_lua_modules, global_custom_actions, global_configs, global_page_templates, global_upstreams,
                        global_k8s_upstreams, global_ip_lists, global_basic_auth_groups, global_static_files, k8s, users, all
  -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 EXPORT_TO_PATH, --export-to-path EXPORT_TO_PATH
                        specify the storage path of the exported configuration. If not specified, a directory prefixed with
                        configs will be automatically created in the current path.
  -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
  -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
  -E, --export          export the configuration to the specified path, which can be specified through the --export-to-path
                        option

通过指定 -p PARTITION_ID 或 -n PARTITION_NAME 选项，您可以将配置更新到指定的分区。

示例：

edge-config -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 替换为实际的模块名称。

创建 API 令牌

登录 OpenResty Edge 管理控制台。
点击右上角的用户名：USERNAME > API 令牌 > 创建 API 令牌 > 复制 API 令牌。

目录结构介绍

该命令行工具可以识别以下结构的配置：

|-- configs/
  |-- global_lua_modules/
  |-- global_basic_auth_groups/
  |-- global_custom_actions/
  |-- global_ip_lists/
  |-- global_upstreams/
  |-- global_k8s_upstreams/
  |-- global_page_templates/
  |-- global_static_files/
  |-- k8s/
  |-- upstreams/
  |-- k8s_upstreams/
  |-- edgelang_rules/
  |-- page_rules/
  |-- basic_auth_groups/
  |-- ip_lists/
  |-- user_variables/
  |-- waf_whitelist/
  |-- users/
  |-- global_configs.yaml
  |-- app.yaml
  |-- email.yaml

configs/ 目录包含了某个分区的所有配置。

全局配置以 global_ 作为前缀：

global_lua_modules/：全局 Lua 模块，每个 Lua 文件代表一个模块。
global_basic_auth_groups/：全局 Basic 认证用户组及用户配置。
global_custom_actions/：全局自定义动作。
global_ip_lists/：全局 IP 列表。
global_upstreams/：全局上游。
global_k8s_upstreams/：全局 Kubernetes 上游。
global_page_templates/：全局页面模板。
global_static_files/：全局静态文件。
global_configs.yaml：包括全局配置，如全局用户变量、访问日志格式等。

应用配置没有前缀：

upstreams/：上游服务器信息，可分割成多个文件以便管理。
page_rules/：页面规则，将被添加到与分区相关的 HTTP 应用中。
basic_auth_groups/：Basic 认证用户组及用户配置。
k8s_upstreams/：Kubernetes 上游服务器信息。
edgelang_rules/：页面规则界面中最前面和最后面的 Edgelang 规则。
ip_lists/：IP 列表信息。
user_variables/：用户变量信息。
waf_whitelist/：WAF 白名单。
app.yaml：应用相关配置，如域名、访问日志格式。

其他没有 global 前缀的配置目录：

users/：要添加到 Edge Admin 中的用户，创建成功后可发送邮件通知。
k8s/：Kubernetes 集群信息。

所有这些配置目录都是可选的，命令行工具不要求配置目录必须存在。

导入配置到 OpenResty Edge 的示例

将所有配置导入到分区 1（default），当应用 test.com 不存在时，会创建应用：

edge-config -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
    -u https://192.168.1.1 -s -i /path/of/configs -n default -d test.com

仅将页面规则导入到应用 “test.com”：

edge-config -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

从 OpenResty Edge 中导出配置的示例

导出配置到随机生成的目录中（目录信息将在命令行工具的第一行中输出）：

edge-config -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
  -u https://192.168.1.1 -s -d test.com -E

导出配置到指定的目录中：

edge-config -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
  -u https://192.168.1.1 -s -d test.com -E --export-to-path /tmp/edge-configs

从 OpenResty Edge 中删除配置的示例

删除 default 分区中 test.com 域名对应的应用，如果全局配置没有启用“自动同步到其他分区”则还会清理分区配置：

edge-config -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” 中移除所有页面规则：

edge-config -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 模块（当启用"通过到所有分区"时，因为所有分区共享这些配置，因此将不会执行实际的删除操作）：

edge-config -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
    -u https://192.168.1.1 -s -i /path/of/configs -n default -l global_lua_modules -c

配置示例

更多示例请参见基于 YAML 文件的 OpenResty Edge 配置示例。

- enable_rule: true
  actions:
    set-access-log-off: {}
    print:
      content_type: text/html
      msg: favicon.ico and 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.

基于 YAML 文件的 OpenResty Edge 配置镜像

# 安装

# 创建 API 令牌

# 目录结构介绍

# 导入配置到 OpenResty Edge 的示例

# 从 OpenResty Edge 中导出配置的示例

# 从 OpenResty Edge 中删除配置的示例

# 配置示例

# 错误消息示例

# 更多说明

很乐意听到您的反馈，请与我们联系 👋

成功发送消息！

安装