Upgrade to API7 Enterprise 3.x.x

This guide introduces the process of upgrading API7 Enterprise from an older version to the latest version. You can determine the upgrade path based on your API7 Enterprise deployment architecture. Additionally, this document explains important factors to consider during the upgrade process and how to backup and restore data.

The upgrade between API7 Enterprise v3.x.x versions mainly involves updates to the Control Plane (CP) and Data Plane (DP). Since all v3.x.x versions maintain architectural compatibility, this document will guide you through the following upgrade strategies:

• CP In-Place Upgrade: This strategy reuses the existing database while upgrading the CP in place.
• DP Rolling Upgrade: This strategy involves gradually adding new version DP nodes and shutting down old ones, ensuring zero downtime.

Upgrade Overview

Upgrading API7 Enterprise is generally divided into two phases: preparation and implementation.

Preparation Phase

1. Review the complete changelog and compatibility between the current version and the target version.
   • Breaking Changes
   • Complete Changelog
2. Confirm the upgrade strategies to be executed.
   • CP In-Place Upgrade
   • DP Rolling Upgrade
3. Review upgrade considerations.
4. Database backup.
5. Perform upgrade testing in test or pre-production environment.

Perform Upgrade

After completing the preparation phase and confirming everything is correct, you can begin upgrading the production environment following the process executed in the test environment.

Guaranteed Upgrade Path

API7 Enterprise version numbers follow a standard semantic structure, using a.b.c as an example, representing major version (a), minor version (b), and patch version (c). By default, API7 Enterprise v3 has performed upgrade testing between the following versions, to ensure a smooth upgrade process:

1. Upgrades between patch versions within the same major and minor version, e.g., (3.3.0 to 3.3.1).
2. Upgrades between adjacent minor versions within the same major version, e.g., (3.3.x to 3.4.x).

info

While API7 Enterprise has conducted upgrade testing, you should still follow the documented steps and conduct testing in your environment before applying the upgrade.

Data Backup Strategy

Before executing the upgrade, please ensure you have back up your database and declarative configuration files.

1. Database Backup: API7 Enterprise uses PostgreSQL database by default. You can use native export (pg_dump) and import (pg_restore) commands to backup or restore your database.
2. Declarative Configuration File Backup: API7 Enterprise provides the declarative management tool ADC, which supports managing API7 Enterprise's services, routes, consumers, plugins, and other configurations through declarative configuration files.

It is strongly recommended to use both methods to back up data whenever possible, as this provides flexibility in data recovery. If you encounter any issues during the test upgrade and need to roll back immediately, please refer to backup and rollback guide to restore your old data.

Upgrade Strategy

It is recommended to complete the upgrade according to the upgrade strategy described in this guide.

During the upgrade process, you should consider API7 Enterprise's downtime and make reasonable upgrade plans, as you cannot modify or update data through API or Dashboard during the upgrade process.

The diagram below explains how the entire upgrade process works:

CP In-Place Upgrade

The CP must be upgraded first before upgrading the DP. The CP interacts with the database, so please do not use API or other methods to change your current data during the upgrade process. The diagram below shows how the in-place upgrade strategy is implemented.

1. Current CP A is directly replaced with CP B, sharing the same database during the upgrade process.
2. After the upgrade is complete, the nodes in current DP A will automatically connect to the new CP B.

info

During the Control Plane (CP) upgrade process, the nodes in DP A maintain a connection with either CP A or CP B, as illustrated in the diagram. API7 Enterprise ensures compatibility between newer CP minor versions and older DP minor versions. Therefore, when running different CP and DP versions, check the status of each DP node on the Gateway Instances page in the CP, and follow the prompts to upgrade any DP nodes flagged as incompatible.

It is recommended to keep CP and DP versions consistent for each upgrade to ensure everything is correct.

DP Rolling Upgrade

After the CP upgrade is complete, you can proceed to upgrade the DP nodes. For DP upgrades, it is recommended to use the rolling upgrade method, as it can avoid downtime. The diagram below shows how the rolling upgrade strategy is implemented.

1. The new CP B reuses the current database, and the current DP A continues to handle API requests.
2. Using rolling upgrade, gradually replace the nodes in DP A with new nodes from DP B. After the nodes in new DP B are updated, they also handle API requests.

Check Breaking Changes and Changelog

Based on the current version and the target version for upgrade, confirm all breaking changes and changelog between versions. Prepare and adjust your configuration in advance according to the prompts in the changelog.

Upgrade Considerations

Regardless of how you deploy API7 Enterprise, there are some general factors that affect the upgrade process. Before starting the upgrade, please note:

1. During the upgrade process, any changes to the database are prohibited. Do not modify any data through API or Dashboard UI until the upgrade is complete.
2. Please carefully review all changelogs between the current version and the target version for upgrade, paying special attention to breaking changes. Check for any potential conflicts, such as feature removal, API changes, etc.
3. If you have custom plugins, please check if there are any core modifications in the changelog and test your custom plugins in the test environment with the new version to ensure they work properly.
4. Database backup is mandatory at all times. Please make sure to back up your data before each upgrade.

Execute Upgrade

1. Control Plane In-Place Upgrade
2. Data Plane Rolling Upgrade