Estimated Reading time: 5 minutes | Last modified: 2024-06-06, 3:02:43 pm

OpenResty Edge Configuration Mirror Backed by YAML Files

We provide a command-line tool to support updating configurations in OpenResty Edge based on local YAML file configurations. The configurations are divided by partition, with each group of configurations corresponding to a partition in OpenResty Edge. You can use version control tools like Git to manage the local configurations.

The following documentation will explain how to install and use this tool.

Installation

  • Install the dependencies required by the command-line tool

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

    Please ensure that the version of openresty-edge-sdk is greater than or equal to 1.2.54.

  • Run the command-line tool

    If you want to view the usage of the command-line tool, you can run the following command:

    edge-config -h

    The output of this command will be similar to:

    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

    You can update the configuration to the specified partition by specifying the -p PARTITION_ID or -n PARTITION_NAME option.

    Example:

    edge-config -t 3ed00172-280e-4e43-a4ef-3c2fae5669ca -u https://192.168.1.1 -s -i /path/of/configs -n default -d test.com

    This command will update the configuration to the default partition (with the name default and id 1). If the test.com application does not exist, it will be created.

If you encounter the No module named 'MODULE_NAME' error, please use the following command to install the corresponding dependencies:

pip3 install MODULE_NAME

Please replace MODULE_NAME in the command with the actual module name.

Create API Token

  1. First, log in to the OpenResty Edge Admin Console.
  2. Click on the username in the upper right corner: USERNAME > API Tokens > Create API Token > Copy API Token.

Update or Add Configuration to OpenResty Edge

The command-line tool can recognize configurations with the following structure:

```
|-- 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
```

The configs/ directory contains all configurations for a partition. The global_lua_modules/ directory stores global Lua modules, with each Lua file representing a Lua module. The upstreams/ directory contains upstream server configurations. To manage them more efficiently, you can split them into multiple files. The page_rules directory contains page rules that will be added to the HTTP application associated with the partition. The order of the rules is determined by the alphabetical order of the file names and the order of the rules within the files. The basic_auth_groups directory contains Basic authentication user groups and user configurations, which are used when Basic authentication-related actions are involved. The global_configs.yaml file includes global configurations, such as global user variables. The users/ directory contains users you want to add to Edge Admin. After successful user creation, email notifications can also be sent. The sender’s email-related information is specified through the email.yaml file. The app.yaml file contains application-related configurations, such as domain names and access log formats.

More examples:

# Delete: Lua modules, global user variables, applications
# Reset: access log format
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

# Remove all page rules from the "test.com" application
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

# Remove all Lua modules from partition 1 (default)
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

# Update/insert all configurations into partition 1 (default)
edge-config -t 6cc1cf09-1a39-4c17-8ed6-c11838edac12 \
 -u https://192.168.1.1 -s -i /path/of/configs -n default -d test.com

# Update/insert page rules into the "test.com" application
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

Configuration Examples

Please refer to OpenResty Edge Configuration Examples Based on YAML Files for more examples.

- 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: ''

Page rules are ordered, and the order in the configuration file will be maintained when updating to Edge Admin. This example includes two-page rules. The first rule checks if the URI is /favicon.ico or /robots.txt. If so, it turns off access logging and outputs the specified content. The second rule unconditionally executes a piece of Edgelang code that sets the global user variable $or_global_user_variable_uuid.

All page rules form an array, each being an array element.

Error Message Examples

For configuration file errors, the command-line tool will attempt to provide hints indicating the specific line number where the error occurred.

[!] Error: invalid port in upstream upstream_name_foo: 70000, file: foo.yaml, line: 6.

Additionally, there are some other errors. For example, the following error indicates that the entered configuration path is incorrect, and the command-line tool cannot find that path.

[!] Error: bad configs path: /bad/path.