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 to1.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
- First, log in to the OpenResty Edge Admin Console.
- 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.