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

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

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

以下文档内容将详细解释如何安装及使用该工具。

安装

  • 安装命令行工具所需的依赖项

    pip3 install openresty-edge-sdk ruamel.yaml pyOpenSSL jinja2

    请确保 openresty-edge-sdk 的版本大于或等于 1.2.54。

  • 执行命令行工具

    如果您想查看该命令行工具的使用方法，可以执行以下命令：

    edge-config -h

    该命令的输出将类似于：

    usage: edge-config [-h] -t API_TOKEN -u ADMIN_URL [-s] [-c] -i CONFIGS_PATH [-e EMAIL_CONFIG_FILE] [-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
  -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
  -l LOCATION, --location LOCATION
                        specify the configuration name that needs to be updated, supported: page_rules, upstreams, global_lua_modules,
                        global_configs, basic_auth_groups, users
  -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 选项，您可以将配置更新到指定的分区。

    示例：

    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 令牌

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

更新或添加配置到 OpenResty Edge

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

```
|-- 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
  |-- users/
    |-- user-list-1.ymal
    |-- user-list-2.ymal
    |-- ...
  |-- app.yaml
  |-- email.yaml
```

`configs/` 目录包含了某个分区的所有配置。
`global_lua_modules/` 目录保存了全局 Lua 模块，每个 Lua 文件代表一个 Lua 模块。
`upstreams/` 目录包含了上游服务器配置，您可以将上游分割成多个文件以便于管理。
`page_rules` 目录中包含页面规则，这些规则将被添加到与分区相关的 HTTP 应用中，规则的顺序根据文件名称字母序和文件内的规则顺序决定。
`basic_auth_groups` 目录中是 Basic 认证用户组及用户配置，当使用 Basic 认证相关动作时，需要用到。`global_configs.yaml` 文件包括全局配置，如全局用户变量。
`users/` 目录中是想要添加到 Edge Admin 中的用户，在用户创建成功后，还可以发送邮件通知。发送者邮箱相关信息通过 `email.yaml` 文件指定。
`app.yaml` 文件中是应用相关的配置，例如域名、访问日志格式。

更多示例：

# 删除：lua 模块、全局用户变量、应用
# 重置：访问日志格式
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

# 将所有配置更新/插入到分区 1（默认）
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

配置示例

更多示例请参见基于 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.