Configuration Migration

When you need to migrate a service deployed in Nginx/OpenResty to OpenResty Edge, you need to convert the original configuration to OpenResty Edge configuration.

OpenResty Edge provides both an online service and an offline CLI tool. The online service does not require any additional software installation, while the CLI conversion tool requires you to install the openresty-nginx2edge-cli package. You can choose the conversion method according to your needs.

# Use the online conversion service

Log in to your OpenResty-Edge-Admin site and select Nginx.conf Migration Tool under tools to perform the conversion.

Note: To use the online conversion service, you need to have an account registered with openresty.com and ngx2edge privileges.

After the conversion is complete, select Download to download the converted configuration locally.

# Use offline CLI tools

# Install openresty-nginx2edge-cli

openresty-nginx2edge-cli is stored in the OpenResty Edge repository, so you will need to have access to the machine on which the package is installed. For example, you can choose to install the package on OpenResty-Edge-Admin or OpenResty-Edge-Node. You can also choose to download and install it on another machine.

For CentOS, RHEL, Amazon Linux, Rocky Linux systems

# install on the current machine
sudo yum install -y openresty-nginx2edge-cli

# download package only
yum download openresty-nginx2edge-cli

# cp the rpm package to another machine
# execute the following command
sudo yum install -y openresty-nginx2edge-cli*.rpm

For Fedora

# install on the current machine
sudo dnf install -y openresty-nginx2edge-cli

# download package only
dnf download openresty-nginx2edge-cli

# cp the rpm package to another machine
# execute the following command
sudo dnf install -y . /openresty-nginx2edge-cli*.rpm

For Ubuntu, Debian systems

# install on the current machine
sudo apt-get -y install openresty-nginx2edge-cli

# download package only
apt-get download openresty-nginx2edge-cli

# cp the rpm package to another machine
# execute the following command
sudo apt-get install -y . /openresty-nginx2edge-cli*.rpm

# Perform a configuration conversion

The configuration conversion tool requires that the original configuration file be compressed into a tar.gz archive. If your configuration file uses the include directive and uses an absolute path, you need to convert the configuration to a relative path.

For example, /etc/nginx/nginx.conf has include /etc/nginx/conf.d/example.com.conf; in it. Then you need to convert that directive to include conf.d/example.com.conf;

After finishing the preparation of the configuration file, you can execute the following command to perform the configuration conversion.

/usr/local/orngx2edge-cli/ngx2edge . /nginx.tar.gz

For example, the last line of the following command shows the path of the final generated package as app-nginx-1013152554.tar.bz2.

$ /usr/local/orngx2edge-cli/ngx2edge /tmp/nginx.tar.gz
TODO: unsupported `root` directive in this location, not found settings of error page or favicon in server context at nginx.conf line 39.
TODO: unsupported `root` directive in this location, not found settings of error page or favicon in server context at nginx.conf line 61.
total App num: 2
done App num: 2

App dst: app-nginx-1013152554.tar.bz2

# Configuration import OpenResty-Edge-Admin

Here it is assumed that the configuration file you want to import is app-nginx-1013152554.tar.bz2.

# Install python sdk

You can install it directly using the pip command

pip3 install openresty-edge-sdk

If you can’t access the internet directly, you can choose to download it from https://pypi.org/project/openresty-edge-sdk/#files.

# Import configuration to admin

If you have openresty-nginx2edge-cli installed, then you can use the following to import it to admin.

export NGINX2EDGE_HOST='https://your.admin'
export NGINX2EDGE_USER='admin'
export NGINX2EDGE_PASSWORD='{your password}'

workdir=`date +%s`
rm -fr $workdir
mkdir -p $workdir
tar -xf -C $workdir . /app-nginx-1013152554.tar.bz2
tar -xf app-nginx-1013153306.tar.bz2 -C $workdir/

python3 /usr/local/orngx2edge-cli/utils/global_ini.py $workdir
python3 /usr/local/orngx2edge-cli/utils/create_apps.py $workdir/app
rm -fr $workdir

If you do not have openresty-nginx2edge-cli installed, then download ngx2edge-import-utils. After downloading, extract the tools to the current directory.

export NGINX2EDGE_HOST='https://your.admin'
export NGINX2EDGE_USER='admin'
export NGINX2EDGE_PASSWORD='{your password}'

if [ ! -d utils ]; then
   echo "Please download ngx2edge-import-utils-xxx.tar.gz from https://openresty.com/download/ first."
   exit 1
fi

workdir=`date +%s`
rm -fr $workdir
mkdir -p $workdir
tar -xf -C $workdir . /app-nginx-1013152554.tar.bz2
tar -xf app-nginx-1013153306.tar.bz2 -C $workdir/

python3 . /utils/global_ini.py $workdir
python3 . /utils/create_apps.py $workdir/app
rm -fr $workdir

# View configuration

After the import is complete, please go to your Openresty-Edge-Admin to view it and confirm that the import was successful and that the imported configuration is as expected. After the imported configuration is published, you need to test it to make sure the behavior of the access is as expected.