Upgrading Apigee OPDK 4.51 to 4.53 with OS Modernization

Google Cloud Apigee Knowledge Hub
,
1

Upgrading Apigee OPDK 4.51 to 4.53 with OS Modernization

1. Introduction and Core Strategy

This post outlines the official, supported methodology to upgrade your Apigee Edge for Private Cloud (OPDK) platform from version 4.51 to 4.53 while simultaneously performing a major version upgrade of the underlying Operating System (e.g., from RHEL 7.x to a supported version like RHEL 8.x/9.x).

It is critical to understand that these two operations—the OS upgrade and the Apigee software upgrade—are two separate, sequential projects.

Critical Guideline: Apigee does not support an in-place OS upgrade on servers with Apigee components installed. You must first migrate your Apigee platform to new servers running the target OS, and only then can you upgrade the Apigee software. This is the only supported path.

This sequence is mandatory because Apigee 4.53 drops support for older OS versions like RHEL 7.x. Therefore, the OS upgrade is a non-negotiable prerequisite for the final Apigee upgrade.

Project 1: Infrastructure Modernization (OS Upgrade via Build-Out)

Goal: Migrate your entire, functional Apigee 4.51 platform from its current servers to a new set of servers running a modern, supported OS, with zero change to the Apigee software version.

Procedure:

  1. Procure New Servers: Build a completely new set of servers (VMs or physical) that meet the installation requirements for your final target, OPDK 4.53. Install a supported OS such as RHEL 8.x, RHEL 9.x, Rocky Linux 8.x, or Rocky Linux 9.x.

  1. Install Current Apigee Version: On these new servers, install your current Apigee OPDK 4.51 software.

  2. Configure as a New Data Center: Following the official multi-data-center installation guide, configure this new set of servers as a new logical data center (e.g., “dc-2”) within your existing Apigee topology.

  1. Join and Sync Cluster: Join the new data store nodes (ZooKeeper, Cassandra, Postgres) to your existing “dc-1” cluster. Allow sufficient time for all data to fully sync and replicate to “dc-2”. Continuously monitor and verify data consistency across both data centers.

  2. Shift Traffic: Once you have verified that “dc-2” is fully synced, healthy, and passing all functional tests, work with your networking team to shift all API traffic from the old “dc-1” routers to the new “dc-2” routers.

  3. Decommission Old Data Center: After all traffic is successfully and stably served by “dc-2” for a validation period, formally decommission all Apigee components in “dc-1” (your old-OS servers).

Checkpoint: At the end of Project 1, your entire Apigee OPDK 4.51 installation is now running on a stable, supported new OS. You are now ready to begin the Apigee software upgrade.

Project 2: Apigee Application Upgrade

Goal: Upgrade the Apigee software, now running on your new servers, from version 4.51 to 4.53. This is performed in two distinct phases.

Required Component Upgrade Order (Follow for each phase below):

  1. Apigee Setup Utility (apigee-setup)

  2. ZooKeeper

  3. Cassandra (one node at a time)

  4. OpenLDAP

  5. PostgreSQL (Master first, then Standby)

  6. Management Server

  7. Routers

  8. Message Processors

  9. Qpid Server

  10. UI (User Interface)

Phase 2A: Upgrade from 4.51 to 4.52.x

  1. Preparation:

  1. Execution: Following the component upgrade order, run the update script on each node to upgrade from 4.51 to 4.52.x.

  2. Validation: After all components are upgraded, perform thorough health checks and functional testing.

Phase 2B: Upgrade from 4.52.x to 4.53

  1. Preparation:

  • Release Notes: Critically review the 4.53 release notes. This version includes significant third-party component updates and potential breaking changes.

  • Link: Apigee 4.53.00 Release Notes

  • Documentation: Review the official 4.52.x to 4.53 upgrade guide.

  • Official Guide: Update Apigee Edge 4.52.02 to 4.53.00

  • Backup: Perform another complete backup of your now stable 4.52.x environment.

  1. Execution: Following the same component upgrade order, run the update script on each node to upgrade from 4.52.x to 4.53.

  2. Final Validation: Perform a comprehensive set of health checks, API regression tests, and performance tests to confirm the upgrade is complete and successful.

3. Upgrading an Existing 2-Data Center Setup

Upgrading an existing 2-DC setup (DC-1 and DC-2) requires an iterative process where each existing data center is replaced by a new one on the target OS. This results in a temporary 3-DC environment during each migration phase.

  1. Phase 1: Replace DC-1 with a new DC-3. Build DC-3 on the new OS with OPDK 4.51 by following the steps in Project 1. Once DC-3 is fully synced and stable, shift traffic and decommission DC-1.

  2. Phase 2: Replace DC-2 with a new DC-4. Build DC-4 on the new OS with OPDK 4.51. Join it to the active DC-3 cluster. After verification and traffic shift, decommission DC-2.

  3. Phase 3: Perform Project 2. Execute the Apigee Application Upgrade (Project 2) on the final cluster consisting of DC-3 and DC-4.

4. Critical Planning and Rollback Strategy

  • Non-Production First: This entire two-project plan must be performed and validated in a non-production environment before being scheduled for production.

  • Backup Strategy: Full, verified backups are mandatory before each major step: before the OS migration begins, before the upgrade to 4.52.x, and before the upgrade to 4.53.

  • Rollback Plan:

  • During Project 1 (OS Migration): Your primary rollback path is to simply shift traffic back to “dc-1” (your old servers), assuming you have not yet decommissioned it.

  • During Project 2 (Apigee Upgrade): Your rollback path is to restore your system from the verified backups taken before starting either the 4.52.x or 4.53 upgrade phase.

  • Reference: Roll back Apigee Edge 4.53.01 (Provides context on rollback procedures).

4. Pre-Decommissioning Verification Checklist

Before attempting to decommission the old data center (DC-1), it is mandatory to run through this checklist to ensure the entire hybrid-DC environment is stable. Do not proceed with decommissioning until every check passes cleanly.

A. Verify ZooKeeper Ensemble Health

Run these checks on every ZooKeeper node in both data centers.

  1. Basic Health Check: Confirm the service is running and responsive.
echo "ruok" | nc localhost 2181

# Expected output: imok
  1. Status Check: Verify roles and ensure there is only one leader in the entire cluster.
echo "stat" | nc localhost 2181

# Verify Mode is either 'leader' or 'follower'. There must be exactly ONE leader.
  1. Export Data Tree: Export the ZK tree to a file to verify DC-1 and DC-2 configurations are present before you begin.
    echo "ls -R /" | /opt/apigee/apigee-zookeeper/bin/zkCli.sh -server localhost:2181 > /tmp/zk_pre_decom_check.txt

B. Verify Cassandra Cluster Health

Run these checks from any Cassandra node. The commands will report on the entire cluster.

  1. Primary Cluster Status: This is the most critical check.
    /opt/apigee/apigee-cassandra/bin/nodetool status

  2. Verification: Ensure every single node in both dc-1 and dc-2 shows a status of UN (Up/Normal). Any other status indicates a problem that must be fixed.

  3. Network Stats: Check for data streaming activity. In a stable, fully synced cluster, this should be minimal.
    /opt/apigee/apigee-cassandra/bin/nodetool netstats

C. Verify Traffic and Service Health

  1. Confirm 100% Traffic Shift: Work with your networking team to confirm that dashboards and metrics show zero active API traffic flowing to the routers in DC-1. All traffic must be successfully served by DC-2.

  2. Check All Apigee Services: On every Apigee node in both data centers, run the master status check.
    /opt/apigee/apigee-service/bin/apigee-all status

  3. Verification: Every service must report as running or STARTED. Resolve any stopped services before proceeding.

D. Verify Postgres Replication

  1. Confirm with Apigee Support or your database administrator that the Postgres master in DC-2 is healthy and that replication to the DC-2 standby is active with minimal to no delay.

5. Conclusion

Successful modernization of your Apigee OPDK environment relies on treating the OS migration and the software upgrade as two distinct, sequential projects. By first migrating to a more current OS through a new data center build-out and then executing the phased Apigee application upgrade, you ensure a supported and stable path forward. Adhering strictly to this official methodology, maintaining a disciplined backup strategy, and performing rigorous validation at every checkpoint are essential requirements for a reliable and successful outcome.

:thought_balloon: Get in touch with a Google Cloud Sales Specialist

7 Likes