3 分鐘閱讀 | 最後修改: 0001-01-01, 0:00:00 am

基於 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.