Estimated Reading time: 9 minutes | Last modified: 2025-04-14, 1:35:40 pm

Upgrade OpenResty Edge

We recommend that before upgrading a production environment, you should use the data from the production environment to build a test environment that is identical to the production environment for upgrade testing. After confirming the test result, you can proceed to upgrade the production environment. For detailed steps, please refer to Cloning OpenResty Edge Environment.

If your current version is greater than 25.3.10-1, you can refer to this document: Upgrade and Downgrade.

1. Upgrade Log Server DB

  • If you would like to perform an online upgrade (recommended), you can directly download the installer by executing the following command:

    curl -O https://openresty.com/client/oredge/openresty-edge-installer.sh

  • If you prefer to upgrade using a bundle package

    1. Please download the following file from the Download Center, if not available please contact us:

      a. openresty-edge-bundle-VERSION.tar.gz: Contains OpenResty Edge business package, configuration package, and initial data. The old name was openresty-edge-bundle-VERSION.tar.gz.

    2. Extract openresty-edge-bundle-VERSION.tar.gz and enter the extracted directory:

      tar xf openresty-edge-bundle-VERSION.tar.gz
cd openresty-edge-bundle-VERSION

  • Run the installer:

    sudo /bin/bash openresty-edge-installer.sh

  • Enter the action you wish to perform: Upgrade

    > Checking network...
> Welcome to the OpenResty Edge Installer.
[1] Install
[2] Upgrade
[3] Downgrade
[4] Uninstall
[5] Self Check
[6] Get Default Info
What would you like to do? 2
> You chose: Upgrade.

  • Enter the version you want to upgrade to (you can get the latest version info from the Release Notes), if using the default version in the installer, simply press Enter:

    Which version would you like to upgrade to? (Default: 23.12.1, Press Enter to use the default version)
[WARN] Using default version number: 23.12.1

  • Enter the component you wish to upgrade: Log Server DB

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 1
> You chose: Edge Log Server Database.

  • If successful, you will see the following message:

    Great! update log-server database successfully.

2. Upgrade Log Server

  • The steps are the same; when upgrading, choose the Log Server component:

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 2
> You chose: Edge Log Server.

  • If successful, you will see the following message:

    Great! Upgrade openresty-edge-log-server successfully.

During the upgrade process, the installer will automatically generate a directory containing a record of historical operations. You will see a prompt similar to the following:

This execution process will be saved in the /home/USER/openresty-edge-VERSION/oredge-history/2024-07-01-02-03-04

Please note that this directory is crucial for potential future downgrade operations. Therefore, we strongly recommend that you keep this directory and do not delete it.

3. Upgrade Edge Node

3.1 Back Up Edge Node Database

If your current OpenResty Edge Admin version is less than 1.3.0, skip this step.

  • Log in to the OpenResty Edge Admin console.
  • Navigate to [Gateway Cluster]-[Backup and Restore]-[Start Backup].

3.2 Migrate Traffic (Optional)

To avoid impacting business, before upgrading the Edge Node, redirect the traffic from this node to other nodes that have not been upgraded yet. This step is optional, but we strongly recommend executing this step for the first few Edge Nodes being upgraded:

  • Redirect traffic away.
  • Upgrade.
  • Verify.

After ensuring there’s no problem, proceed with upgrading the remaining Edge Nodes. Additionally, pay attention to the error logs during the upgrade process.

If OpenResty Edge’s DNS is controlling the traffic, follow these steps to take the Edge Node that’s about to be upgraded offline:

  • Enter the OpenResty Edge console.
  • Go to the [Gateway Cluster] page.
  • Edit the cluster where the node is located.
  • Modify the node’s [status] to [Disable DNS, disable caching cluster].
  • Save.

Wait until the node has no traffic or only minimal traffic. This can be determined by looking at the access logs:

tail -f /usr/local/oredge-node/logs/access.log

3.3 Upgrade

  • The steps are the same; when upgrading, choose the Edge Node component:

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 3
> You chose: Edge Node.

  • If successful, you will see the following message:

    Great! Upgrade openresty-edge-node successfully.

During the upgrade process, the installer will automatically generate a directory containing a record of historical operations. You will see a prompt similar to the following:

This execution process will be saved in the /home/USER/openresty-edge-VERSION/oredge-history/2024-07-01-02-03-04

Please note that this directory is crucial for potential future downgrade operations. Therefore, we strongly recommend that you keep this directory and do not delete it.

4. Upgrade Edge Admin Database

  • The steps are the same; when upgrading, choose the Edge Admin DB component:

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 4
> You chose: Edge Admin DB.

  • Back up the Edge Admin database.

    Do you want to backup db? [Y/N]:  y

  • If successful, you will see the following message:

    Great! update admin database successfully.

5. Upgrade Edge Admin-web

  • The procedure is the same, with the component Edge Admin selected for the upgrade

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 5
> You chose: Edge Admin.

  • If successful, the following prompt will be displayed at the end

    Great! Upgrade openresty-edge-admin successfully.

During the upgrade process, the installer will automatically generate a directory containing a record of historical operations. You will see a prompt similar to the following:

This execution process will be saved in the /home/USER/openresty-edge-VERSION/oredge-history/2024-07-01-02-03-04

Please note that this directory is crucial for potential future downgrade operations. Therefore, we strongly recommend that you keep this directory and do not delete it.

6. (Optional) Upgrade WAF Rule Set

  • First, back up the WAF rule set:
    • Log in to the Edge Admin management interface
    • Go to Global Config > Global WAF > Export WAF Rules

Then, upgrade the WAF rule set. There are two methods, choose one of them:

  • Method 1: Download the WAF rule set through the Download Center, then go to Global Config > Global WAF > Import WAF Rules to upgrade.

  • Method 2: The operation steps are the same as before. When upgrading, select the component Edge Built-in WAF Rules

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 6
> You chose: Edge Built-in WAF Rules.

7. Recompile

  • The procedure is the same, with the component Rebuild selected for the upgrade

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 7
> You chose: Rebuild.

  • Recompile a few applications that do not contain wildcard domains with less traffic first. Recompile several high-traffic applications that do not contain wildcard domains later.

    Do you want to rebuild one application for test? [Y/N]:  y
Please input the application id: 1
rebuild application 1

  • Continue to follow the prompts to compile

    Do you want to rebuild upgrade config? [Y/N]:  y
rebuild upgrade config
recompile upgrade configurations successfully

Do you want to rebuild all wildcard apps? [Y/N]:  y
rebuild all wildcard apps

Do you want to rebuild all apps? [Y/N]:  y
Do you want to compile concurrently? [Y/N]:  n
rebuild all apps

Do you want to rebuild all http_proxy apps? [Y/N]:  y
rebuild all http_proxy apps

Do you want to rebuild all socks5_apps? [Y/N]:  y
rebuild all sock5_proxy apps

Do you want to rebuild global? [Y/N]:  y
rebuild global
recompile global successfully

Do you want to rebuild waf? [Y/N]:  y
rebuild waf
recompiled all of the WAF rule sets successfully.

Do you want to rebuild dns? [Y/N]:  y
rebuild dns
recompile dns successfully.

Do you want to rebuild global-action? [Y/N]:  y
rebuild global-action
recompile global action successfully

Do you want to rebuild gateway? [Y/N]:  y
rebuild gateway
recompiled gateway successfully

rebuild done!

If the whole system behaves normally, the upgrade is complete!

This step may take longer to compile when there are many HTTP/HTTPS applications.

Do you want to rebuild all apps? [Y/N]:  y

We can choose concurrent compilation, which will start 4 processes to compile.

Do you want to compile concurrently? [Y/N]:  y

If that is not fast enough, you can modify the installer to specify a larger concurrency, but not larger than 8, e.g.

sudo /bin/bash utils/parallel-recompile.sh 8

(Optional) 8. After Upgrade

After the previous steps have been performed and validated, this step can be performed to clean up database fields that are no longer needed or to add constraints to database fields.

  • The procedure is the same, with the component Clean db after upgrade selected for the upgrade

    [WARN] If you haven't performed an upgrade test yet, we strongly recommend that you conduct one before proceeding. For details, please visit: https://doc.openresty.com/en/edge/edge-installation-upgrade/edge-env-clone/.
[1] Edge Log Server Database
[2] Edge Log Server
[3] Edge Node
[4] Edge Admin Database
[5] Edge Admin
[6] Edge Built-in WAF Rules
[7] Rebuild
[8] Clean database after upgrade
[9] Exit
What would you like to do? 8
> You chose: Clean db after upgrade.

  • If successful, the following prompt will be displayed at the end

Great! upgrade admin database successfully.

If you have any questions, please get in touch with us.