Estimated Reading time: 4 minutes | Last modified: 2025-11-11, 12:42:04 pm

Containerized OpenResty Edge Upgrade Guide

This guide provides detailed instructions on how to upgrade OpenResty Edge components deployed in a containerized environment. The upgrade process must follow a specific sequence to ensure system stability and data integrity.

Please note: For production environments, we do not recommend using container-based deployment, as upgrades in containerized environments will cause business interruptions.

Pre-Upgrade Preparation

1. Environment Variable Configuration

Set the following environment variables (adjust according to your actual situation):

export OREDGE_IMAGE_VERSION=25.9.17-1
export OREDGE_ADMIN_DB_HOST=172.17.0.2
export OREDGE_LOG_SERVER_DB_HOST=172.17.0.3
export OREDGE_LOG_SERVER_HOST=172.17.0.4
export OREDGE_ADMIN_HOST=172.17.0.5
export OREDGE_NODE_HOST=172.17.0.6
export OREDGE_DATA_ROOT=/data/oredge
export OREDGE_DATA_BACKUP_ROOT=/data/oredge-backup
export OREDGE_REGISTRY_USERNAME=oredge-registry-username

2. Pull New Version Images

Pull all images in advance to speed up the subsequent upgrade process and reduce service downtime:

# Login to the image registry
docker login --username $OREDGE_REGISTRY_USERNAME registry.openresty.com

# Pull all component images
docker pull registry.openresty.com/edge/rocky/8/openresty-edge-admin-db:$OREDGE_IMAGE_VERSION
docker pull registry.openresty.com/edge/rocky/8/openresty-edge-log-server-db:$OREDGE_IMAGE_VERSION
docker pull registry.openresty.com/edge/rocky/8/openresty-edge-log-server:$OREDGE_IMAGE_VERSION
docker pull registry.openresty.com/edge/rocky/8/openresty-edge-admin:$OREDGE_IMAGE_VERSION
docker pull registry.openresty.com/edge/rocky/8/openresty-edge-node:$OREDGE_IMAGE_VERSION

3. Backup Data

Important Note: Be sure to backup all data before upgrading in case a rollback is needed. Before backing up data, please check if you have sufficient disk space.

Backup Databases

# Backup Admin database
docker exec openresty-edge-admin-database \
    /usr/local/openresty-postgresql12/bin/pg_dump or_edge_admin -C -Upostgres \
    | gzip > or_edge_admin-$(date +%F).sql.gz

# Backup Log Server database (optional)
docker exec openresty-edge-log-server-database \
    /usr/local/openresty-postgresql12/bin/pg_dump or_edge_log_server -C -Upostgres \
    | gzip > or_edge_log_server-$(date +%F).sql.gz

Backup Configuration Files

# Backup configuration directories
cp -r $OREDGE_DATA_ROOT $OREDGE_DATA_BACKUP_ROOT

Upgrade Sequence

To ensure a smooth upgrade process, please strictly follow this sequence:

  1. Log Server DB → 2. Log Server → 3. Node → 4. Admin DB → 5. Admin

This sequence minimizes business impact and ensures compatibility between components.

Component Upgrade Steps

1. Upgrade Log Server Database

# Stop and remove old container
docker stop openresty-edge-log-server-database
docker rm openresty-edge-log-server-database

# Start new version container
docker run -d --name openresty-edge-log-server-database                 \
    --ip $OREDGE_LOG_SERVER_DB_HOST                                     \
    -e 'POSTGRES_DB=or_edge_log_server'                                 \
    -e 'POSTGRES_USER=or_edge_log_server'                               \
    -e 'PGUSER=or_edge_log_server'                                      \
    -e 'POSTGRES_HOST_AUTH_METHOD=trust'                                \
    -e 'POSTGRES_CONF_ENABLE_TIMESCALE=true'                            \
    -v $OREDGE_DATA_ROOT/log-server-db:/var/postgres12/                 \
    registry.openresty.com/edge/rocky/8/openresty-edge-log-server-db:$OREDGE_IMAGE_VERSION

# Verify container status
docker logs openresty-edge-log-server-database

2. Upgrade Log Server

# Stop and remove old container
docker stop openresty-edge-log-server
docker rm openresty-edge-log-server

# Start new version container
docker run -d --name openresty-edge-log-server                                      \
    --ip $OREDGE_LOG_SERVER_HOST                                                    \
    -v $OREDGE_DATA_ROOT/log-server/custom/:/usr/local/oredge-log-server/custom/    \
    registry.openresty.com/edge/rocky/8/openresty-edge-log-server:$OREDGE_IMAGE_VERSION

# Verify container status
docker logs openresty-edge-log-server

3. Upgrade Edge Node

# Stop and remove old container
docker stop openresty-edge-node
docker rm openresty-edge-node

# Start new version container (Note: adjust port mappings if there are conflicts)
docker run -d -p 80:80 -p 443:443 --name openresty-edge-node        \
    --ip $OREDGE_NODE_HOST                                          \
    -v $OREDGE_DATA_ROOT/node/custom:/usr/local/oredge-node/custom  \
    -v $OREDGE_DATA_ROOT/node/data:/usr/local/oredge-node/data      \
    registry.openresty.com/edge/rocky/8/openresty-edge-node:$OREDGE_IMAGE_VERSION

# Verify container status
docker logs openresty-edge-node

4. Upgrade Admin Database

# Stop and remove old container
docker stop openresty-edge-admin-database
docker rm openresty-edge-admin-database

# Start new version container
docker run -d --name openresty-edge-admin-database                  \
    --ip $OREDGE_ADMIN_DB_HOST                                      \
    -e POSTGRES_DB=or_edge_admin                                    \
    -e POSTGRES_USER=or_edge_admin                                  \
    -e PGUSER=or_edge_admin                                         \
    -e POSTGRES_HOST_AUTH_METHOD=trust                              \
    -e POSTGRES_CONF_ENABLE_TIMESCALE=true                          \
    -v $OREDGE_DATA_ROOT/admin-db:/var/postgres12/                  \
    registry.openresty.com/edge/rocky/8/openresty-edge-admin-db:$OREDGE_IMAGE_VERSION

# Verify container status
docker logs openresty-edge-admin-database

5. Upgrade Admin Console

# Stop and remove old container
docker stop openresty-edge-admin
docker rm openresty-edge-admin

# Start new version container (Note: adjust port mappings if there are conflicts)
docker run -d -p 443:443 --name openresty-edge-admin                    \
    --ip $OREDGE_ADMIN_HOST                                             \
    -v $OREDGE_DATA_ROOT/admin/custom:/usr/local/oredge-admin/custom/   \
    registry.openresty.com/edge/rocky/8/openresty-edge-admin:$OREDGE_IMAGE_VERSION

# Verify container status
docker logs openresty-edge-admin

6. Recompile Configuration

You can refer to this document to create an upgrade task and skip the previous upgrade steps, performing only the recompilation-related steps: https://doc.openresty.com/en/edge/edge-admin/upgrade/

Post-Upgrade Verification

1. Check All Container Status

docker ps -a | grep openresty-edge

Ensure all containers are in the Up state.

2. Check Service Status

# Check Admin console
curl -k https://$OREDGE_ADMIN_HOST/

# Check Node
curl http://$OREDGE_NODE_HOST/

3. Login to Admin Console for Verification

  1. Access via browser: https://<OREDGE_ADMIN_HOST>
  2. Login and verify all functions are working properly
  3. Check the [Gateway Cluster] page to confirm gateway server status is normal
  4. Verify logs and monitoring data are being collected properly

4. Check Version Information

Confirm the version has been updated to the target version on the [About] page in the Admin console.

If you encounter any issues during the upgrade process, please feel free to contact us.