Skip to main content
API7.ai Logo
Version: 3.9.x

Upgrade API7 Gateway

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

The upgrade between API7 Gateway 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:

  1. In-Place Upgrade
    • 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.
  2. Dual-Cluster Upgrade
    • This strategy involves deploying a completely new, parallel cluster (Cluster Y) alongside your existing production cluster (Cluster X).

Upgrade Overview​

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

Preparation Phase​

  1. Review the release notes and compatibility between the current version and the target version.
  2. Confirm the upgrade strategies to be executed.
  3. Review upgrade considerations, including Ingress Controller resource updates for Kubernetes deployments.
  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 Gateway 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 Gateway 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 Gateway 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 backed up your database and declarative configuration files.

  1. Database Backup: API7 Gateway uses PostgreSQL database by default. You can use native export (pg_dump) and import (pg_restore) commands to back up or restore your database.
  2. Declarative Configuration File Backup: API7 Gateway provides the declarative management tool ADC, which supports managing API7 Gateway'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 restore 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 Gateway'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:

In-Place Upgrade​

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 Gateway 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.

Dual-Cluster Upgrade​

The dual-cluster upgrade is the safest and most robust method for upgrading API7 Gateway, designed for mission-critical environments where zero downtime and minimal risk are paramount. This strategy involves deploying a completely new, parallel cluster (Cluster Y) alongside your existing production cluster (Cluster X). Each cluster is entirely independent, with its own Control Plane, Data Plane, and Database.

Traffic is gradually shifted from the old cluster to the new one using an external load balancer. This allows for thorough testing of the new cluster with a small percentage of live traffic before committing to a full migration. Since the old cluster remains untouched, you can instantly roll back by redirecting all traffic back to it if any issues arise.

The diagram below illustrates the dual-cluster upgrade architecture:

Check Breaking Changes and Changelog​

Based on the current version and the target version for upgrade, review all release notes between versions. Use them as the source of truth for breaking changes, deprecations, and required configuration updates before you begin the upgrade.

Upgrade Considerations​

Regardless of how you deploy API7 Gateway, 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 release notes between the current version and the target version for upgrade. Check for any potential conflicts, such as feature removal, API changes, or required configuration updates.
  3. If you have custom plugins, please check if there are any core modifications in the release notes 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.

Ingress Controller Resource Updates​

caution

This warning applies only if you use API7 Ingress Controller to manage gateway resources.

The controller can update these resources even when no one changes configuration in the Dashboard or Admin API. Account for these automatic updates when preparing backups, migrating to another cluster, or rolling back an upgrade.

API7 Ingress Controller watches Kubernetes resources and synchronizes gateway configuration through the CP. Application rollouts, autoscaling, Pod restarts, and rescheduling can change backend endpoints and trigger upstream updates without anyone editing a route.

If the supported upgrade procedure keeps the CP available for configuration writes, Ingress Controller can continue synchronizing resources. Follow the write restrictions in the selected upgrade procedure: CP high availability does not remove restrictions required for database migration.

For PostgreSQL, pg_dump creates a consistent snapshot even while updates continue. Updates after that snapshot are not included in the backup. ADC exports taken separately can represent a different point in time. Restoring a successful backup therefore does not guarantee that routes and upstreams match the current Kubernetes state.

For deployments managed by Ingress Controller:

  1. Identify controller-managed resources and other configuration writers, including ADC jobs and GitOps workflows. Record when the database backup and ADC exports were taken, and preserve the Kubernetes resource definitions alongside the immutable source backup.
  2. For a dual-cluster upgrade, updates to the source cluster after the backup are not automatically included in the target cluster. Plan and test how to synchronize subsequent changes. Confirm the controller targets the intended CP and validate the target routes and upstreams against current Kubernetes resources before shifting traffic.
  3. For restoration or rollback, the backup can contain obsolete backend addresses. Rehearse how to synchronize controller-managed resources after the CP accepts writes again. Check controller logs, verify gateway upstreams against current Kubernetes endpoints, and test affected routes before declaring recovery complete. Reconcile changes from other configuration writers separately.

If the CP becomes unavailable or rejects configuration writes, endpoint updates cannot reach the gateway. Existing DP nodes continue using their last received configuration, which can cause requests to fail if the configured Pod IP addresses are no longer available. Account for backend endpoint changes during any planned CP write interruption.

Execute Upgrade​

  1. Control Plane In-Place Upgrade
  2. Data Plane Rolling Upgrade
  3. Dual-Cluster Upgrade