You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info

This document outlines an alternative method for upgrading the Operating System (OS) of the servers in your Apigee Edge for Private Cloud cluster. Instead of setting up an entirely new parallel data center, this node-by-node approach allows you to upgrade your OS in-place, one machine/node at a time.

> [!CAUTION]
> **CAUTION:** We strongly recommend that you test these replacement processes on a lower environment before proceeding on a live production environment. Do not upgrade the Apigee version and perform a major version upgrade of the operating system at the same time.
>
> If you need to upgrade both the Apigee version and the operating system, perform the processes sequentially. Either fully upgrade Apigee first and then upgrade the operating system, or vice versa.

## Compatibility

Before initiating the node by node OS upgrade, verify that your current version of Apigee Edge for Private Cloud supports the target OS version. To verify, please refer to the [OS compatibility matrix](https://docs.apigee.com/release/supported-software#apigeeedgeforprivatecloudsupportedversions).

> [!NOTE]
> **NOTE:** The document only supports upgrading to similar distributions of the operating system. For example: RHEL-8 to RHEL-9.

## Prerequisites

Before you begin the node by node upgrade, confirm that you've completed the following tasks:

### Back up all nodes

Before following the procedure, we recommend that you perform a complete backup of all nodes, such as at the VM-level backup, component-level backup, (or both), for safety reasons.
This allows you to have a backup plan, in case any of the following steps does not function properly. For more information on component-level backup, see [Back up and Restore](https://docs.apigee.com/private-cloud/v4.53.01/backup-and-restore).

### Ensure Edge is running

Ensure that Edge is up and running during the update process by using the command:

```javascript
/opt/apigee/apigee-service/bin/apigee-all status
```

## Order of node replacement

We recommend upgrading nodes in the order listed below, based on component type:

- [Cassandra](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#cassandra)
- [Zookeeper](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#zookeeper)
- [Postgres](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#postgres)
- [LDAP](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#ldap)
- [Qpid](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#qpid)
- [Message-Processor](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#message-processor)
- [Router](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#router)
- [Management-server](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#management-server)
- [UI/UE](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#ui-ue)
- [SSO](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#sso)

## Additional scenarios

When performing a node-by-node OS upgrade, if any of the following configurations are present in the existing setup, please consider these additional steps:

- **apigee-mtls** - If apigee-mtls is enabled, node by node OS upgrade (rolling) is not supported for this setup. For upgrading the same, please follow the [Upgrading apigee-mtls guide](https://docs.apigee.com/private-cloud/v4.53.01/mtls-upgrade).

### Cassandra

When replacing Cassandra, consider replacing the non-seed nodes first, followed by the seed nodes.

Special cases to be considered for Cassandra are as follows:

- **Cassandra Native-mTLS** - If native-mTLS is enabled and enforced, remove the enforcement on mTLS-enabled nodes by setting `conf_cassandra_client_encryption_optional=true`. For more information, see the [native-mTLS documentation](https://docs.apigee.com/private-cloud/v4.53.01/configure-cassandra-mtls#operations-and-configurations).
- **Cassandra internode encryption enabled** - Refer to the [Enable Cassandra Internode Encryption](https://docs.apigee.com/private-cloud/v4.53.01/enable-cassandra-internode-encryption) to ensure that the certificates of existing Cassandra nodes are included in the newly replaced node's truststore and vice versa.

Steps to replace Cassandra node:

1. Back up the node by taking virtual machine snapshots (if possible) and take Apigee backup for Cassandra on all the nodes using the following command:

   ```javascript
   apigee-service apigee-cassandra backup
   ```
2. Acquire new node with the upgraded OS.
3. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
4. Download and run the Edge file to install the **apigee-service** utility. The bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup** .

   > [!NOTE]
   > **NOTE:** Ensure that the new node does not contain any data directory on the path of **apigee-cassandra** data directory.

5. List out the seed nodes:

   ```javascript
   apigee-service apigee-cassandra configure -search conf_cassandra_seeds
   ```
6. Update the configuration file by changing the existing Cassandra node's IP and replacing it with new node IP address.

   > [!NOTE]
   > **NOTE:** Ensure that the order of IP addresses being replaced is preserved. For example, if replacing IP2 with IP4.

   Existing **CASS_HOSTS**

   ```javascript
   CASS_HOSTS="$IP1 $IP2 $IP3"
   ```

   Newly Updated **CASS_HOSTS**

   ```javascript
   CASS_HOSTS="$IP1 $IP4 $IP3"
   ```
7. Reconfigure the existing nodes on the cluster with the updated new Cassandra node IP (except for the node to be replaced). Please use the [configuration file reference.](https://docs.apigee.com/private-cloud/v4.53.01/edge-configuration-file-reference)

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p c -f updatedConfigFile
   ```
8. Stop and deregister Cassandra on the old node:
   1. Stop Cassandra on the node to be replaced:

      ```javascript
      apigee-service apigee-cassandra stop
      ```
   2. List the UUID of Cassandra node to be decommissioned (if multiple data centers consider accordingly):

      ```javascript
      apigee-adminapi.sh servers list -r dc-1 -p central -t application-datastore --admin AdminEmailID --pwd 'AdminPassword' --host localhost
      ```
   3. Deregister the datastore types associated with the existing Cassandra UUID:

      ```javascript
      curl -u AdminEmailID:'AdminPassword' -X POST http://MS_IP:8080/v1/servers -d "type=cache-datastore&type=user-settings-datastore&type=scheduler-datastore&type=audit-datastore&type=apimodel-datastore&type=application-datastore&type=edgenotification-datastore&type=identityzone-datastore&type=auth-datastore&region=dc-1&pod=central&uuid=old_cassandra_uuid&action=remove"
      ```
   4. Delete the server.

      > [!NOTE]
      > **NOTE:** Do not run this step if Cassandra and other Edge components, such as management-server, are on the same node. This may be the case if your configuration uses a standard Apigee 5-node setup.

      ```javascript
      curl -u AdminEmailID:AdminPassword -X DELETE http://MS_IP:8080/v1/servers/old_cassandra_uuid
      ```
9. Prepare a new node for **apigee-cassandra** host. Add the following line to the **cassandra.properties** file under `/opt/apigee/customer/application/cassandra.properties` (create if not already present) on the new Cassandra node:

   ```javascript
   conf_jvm_options_custom_settings=-Dcassandra.replace_address=IPOfOldCassandraNode -Dcassandra.allow_unsafe_replace=true
   ```
10. Confirm that the owner and group is set to `apigee:apigee` in the **cassandra.properties** file. If required, use the following command to update the owner and group:

    ```javascript
    chown apigee:apigee /opt/apigee/customer/application/cassandra.properties
    ```
11. Install Cassandra and run the setup on the newly added node:

    ```javascript
    apigee-service apigee-cassandra install
    ```

    ```javascript
    apigee-service apigee-cassandra setup -f updatedConfigFile
    ```
12. After setting up the new node, remove the additional config added to `/opt/apigee/customer/application/cassandra.properties` and restart **apigee-cassandra** :

    ```javascript
    conf_jvm_options_custom_settings=-Dcassandra.replace_address=IPOfOldCassandraNode -Dcassandra.allow_unsafe_replace=true
    ```

    ```javascript
    apigee-service apigee-cassandra restart
    ```
13. Check for the status of the new replaced node:

    ```javascript
    apigee-service apigee-cassandra status
    ```

    ```javascript
    /opt/apigee/apigee-cassandra/bin/nodetool status
    ```
14. Rebuild the new node added to the cluster:

    ```javascript
    /opt/apigee/apigee-cassandra/bin/nodetool rebuild -dc dc-1
    ```
15. Resetup the existing nodes of Router, Message-Processor, Qpid, Postgres, and Management servers respectively by updating the New Cassandra Node IP in the configuration file:

    ```javascript
    /opt/apigee/apigee-setup/bin/setup.sh -p r|mp|qs|ps|ms|mo -f updatedConfigFile
    ```

    > [!NOTE]
    > **NOTE:** If the Router and Message Processor are on the same node use `-p rmp`.

16. Remove/uninstall Cassandra from older node:

    ```javascript
    apigee-service apigee-cassandra uninstall
    ```
17. Repeat for other Cassandra nodes in cluster.

### Zookeeper

Refer to the steps below to replace Zookeeper nodes. Consider replacing the follower nodes first and the leader nodes second, to ensure that the ensemble maintains quorum.

1. Back up the node by taking virtual machine snapshots (if possible) and take Apigee backup for Zookeeper on all nodes.
2. Stop and uninstall Zookeeper on existing node:

   ```javascript
   apigee-service apigee-zookeeper stop
   ```

   ```javascript
   apigee-service apigee-zookeeper uninstall
   ```
3. Acquire new node with the upgraded OS.
4. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
5. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
6. Update the configuration file by removing the stale/deleted node IP addresses and replacing it with new node IP for Zookeeper. For more details, see the [configuration file reference](https://docs.apigee.com/private-cloud/v4.53.01/edge-configuration-file-reference):

   > [!NOTE]
   > **NOTE:** Ensure that the order of IP being replaced is preserved. For example, if replacing IP2 with IP4.

   Existing ZK configuration

   ```javascript
   ZK_HOSTS="$IP1 $IP2 $IP3"
   ZK_CLIENT_HOSTS="$IP1 $IP2 $IP3"
       
   ```

   Updated ZK configuration

   ```javascript
   ZK_HOSTS="$IP1 $IP4 $IP3"
   ZK_CLIENT_HOSTS="$IP1 $IP4 $IP3"
       
   ```
7. Install, setup and start Zookeeper on new node using updated config file:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p zk -f updatedConfigFile
   ```
8. Make changes to the existing Zookeeper node with **updatedConfigFile** :

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p zk -f updatedConfigFile
   ```
9. Resetup the existing nodes of Router, Message-Processor, Qpid, Postgres and Management servers respectively by updating the New Zookeeper node IP in the configuration file:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p r|mp|qs|ps|ms|mo -f updatedConfigFile
   ```

   > [!NOTE]
   > **NOTE:** If the Router and Message Processor are on the same node use `-p rmp`.

10. Repeat for all Zookeeper nodes.

### Postgres

This section outlines a zero downtime approach to upgrading the Postgres nodes, where you will complete the outlined steps. Detailed instructions for completing each step are provided in the subsections to follow.

- Replace any of the existing standby node with the targeted OS.
- Promote the new standby node to master.
- Decommission the old master.
- Continue to replace additional standby nodes.

> [!NOTE]
> **NOTE:** If you are using a standalone Postgres node setup in your cluster, we recommend [adding new standby node](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#adding_new_standby) first, followed by promoting the new standby to [master](https://docs.apigee.com/how-to-guides/node-by-node-os-upgrade#master).

Before starting the replace, it's recommended to stop the **edge-qpid-server** to minimize any potential loss of analytics messages.

```javascript
apigee-service edge-qpid-server stop
```

#### Standby

1. Get UUID of the **edge-postgres-server** nodes:

   ```javascript
   curl http://pg_standby_ip:8084/v1/servers/self
   ```
2. Stop Postgres:

   ```javascript
   apigee-service edge-postgres-server stop
   ```

   ```javascript
   apigee-service apigee-postgresql stop
   ```
3. Remove the existing Postgres standby from analytics group [by following these steps](https://docs.apigee.com/api-platform/troubleshoot/analytics/add-remove-postgres-nodes#scenario-1:-one-postgres-server,-no-postgres-replication).
4. Uninstall **apigee-postgres** and **postgres-server** :

   ```javascript
   apigee-service edge-postgres-server uninstall
   ```

   ```javascript
   apigee-service apigee-postgresql uninstall
   ```
5. Acquire new node with the upgraded OS.
6. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
7. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
8. Setup master-standby replication on the existing master by updating the configuration file with the **EXISTING_PG_MASTER_IP** and **NEW_PG_STANDBY_IP** . For more details, see the [configuration file reference](https://docs.apigee.com/private-cloud/v4.53.01/edge-configuration-file-reference):

   ```javascript
   PG_MASTER=EXISTING_PG_MASTER_IP
   ```

   ```javascript
   PG_STANDBY=NEW_PG_STANDBY_IP
   ```

   ```javascript
   apigee-service apigee-postgresql setup-replication-on-master -f updatedConfigFile
   ```
9. Install, setup and start Postgres with master-standby configs on the new standby node:

   ```javascript
   PG_MASTER=EXISTING_PG_MASTER_IP
   ```

   ```javascript
   PG_STANDBY=NEW_PG_STANDBY_IP
   ```

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ps -f updatedConfigFile
   ```
10. Verify the standby setup:

    ```javascript
    apigee-service apigee-postgresql postgres-check-standby
    ```

#### Master

1. Get UUID of the existing Postgres master node:

   ```javascript
   curl http://pg_ip:8084/v1/servers/self
   ```
2. Promote the new upgraded OS standby node to master.
3. Stop Postgres on the existing master:

   ```javascript
   apigee-service apigee-postgresql stop
   ```

   ```javascript
   apigee-service edge-postgres-server stop
   ```
4. Promote the new standby node to master:

   ```javascript
   apigee-service apigee-postgresql promote-standby-to-master EXISTING_PG_MASTER_IP
   ```
5. Remove the [old master node](https://docs.apigee.com/api-platform/troubleshoot/analytics/add-remove-postgres-nodes#scenario-1:-one-postgres-server,-no-replication) from the analytics and consumer groups.
6. Add the [new master node](https://docs.apigee.com/api-platform/troubleshoot/analytics/add-remove-postgres-nodes#scenario-1:-one-postgres-server,-no-postgres-replication) to the analytics and consumer groups.
7. If using monetization, update the new Postgres master node and [perform the following steps](https://docs.apigee.com/private-cloud/v4.53.01/change-pg-settings-monetization).
8. Once the master node is replaced, the **edge-qpid-server** can be started with an updated master node configuration:

   ```javascript
   apigee-service edge-qpid-server start
   ```
9. If you are using monetization, restart the Management Server and Message Processor as well:

   ```javascript
   apigee-service edge-management-server restart
   ```
10. Stop and uninstall **apigee-postgres** and **postgres-server** on old master:

    ```javascript
    apigee-service edge-postgres-server uninstall
    ```

    ```javascript
    apigee-service apigee-postgresql uninstall
    ```

#### Adding new standby

1. Acquire new node with the upgraded OS.
2. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
3. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
4. Setup master-standby replication using new master IP and new standby node IP in the new master \& new standby node configuration file. For more details, see the [configuration file reference](https://docs.apigee.com/private-cloud/v4.53.01/edge-configuration-file-reference):

   ```javascript
   apigee-service apigee-postgresql setup-replication-on-master -f updatedConfigFile
   ```
5. Install and setup on the new standby node:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ps -f updatedConfigFile
   ```
6. Add the new standby to the analytics groups by following the [steps for master-standby setup](https://docs.apigee.com/api-platform/troubleshoot/analytics/add-remove-postgres-nodes#scenario-2:-two-postgres-servers-with-master-standby-replication).

   > [!NOTE]
   > **Note:** Make sure while adding new Standby nodes to analytics groups, the existing Postgres needs to be [removed first](https://docs.apigee.com/api-platform/troubleshoot/analytics/add-remove-postgres-nodes#remove-a-postgres-server-from-an-analytics-group) and then simultaneously added back with the standby.

### LDAP

Replacing the LDAP node would require the Management Server to stop and any of the Management APIs would be considered unavailable for the duration of this node replacement.

1. Stop Management Server on all nodes:

   ```javascript
   apigee-service edge-management-server stop
   ```
2. Decommissioning the existing LDAP node:

   > [!NOTE]
   > **NOTE:** If using version 4.53.01 or higher, make sure to use `mdb` in any LDAP configurations. If youa are using version 4.53.00 or less, ensure to use `bdb` in LDAP configuration.

   1. Take VM level backup/snapshot of the LDAP node.
   2. Before stopping LDAP, make sure to capture the count of LDAP data, which can be verified later, for example:

      ```javascript
      ldapsearch -o ldif-wrap=no -b "dc=apigee,dc=com" -D "cn=manager,dc=apigee,dc=com" -H ldap://:10389 -LLL -x -w Secret123 | wc -l
      ```
   3. For active-passive setup:
      1. Make the current passive to active by adding a file `mark_writable.ldif` on the passive node with the following content:

         ```javascript
         dn: olcDatabase={2}bdb,cn=config
         changetype: modify
         replace: olcReadOnly
         olcReadOnly: FALSE
         ```
      2. Execute the following command on the passive node to make it active:

         ```javascript
         ldapmodify -a -x -w "$APIGEE_LDAPPW" -D "$CONFIG_BIND_DN" -H "ldap://:10389" -f mark_writable.ldif
         ```
      3. Continue with Step d) for active-active to decommission nodes.
   4. In an Active-Active LDAP setup, break replication between the two LDAP nodes and update configs. Following the steps as listed in [LDAP decommissioning document](https://docs.apigee.com/private-cloud/v4.53.01/decommission-data-center#symas-ldap).
   5. Stop and take backup of LDAP data and uninstall the existing LDAP node (skip for active-active setup if already done):

      ```javascript
      apigee-service apigee-openldap stop
      ```

      ```javascript
      apigee-service apigee-openldap backup
      ```

      ```javascript
      apigee-service apigee-openldap uninstall
      ```
3. Acquire new node with the upgraded OS.
4. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
5. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
6. Setup new LDAP node:
   1. Update the **configFile** for new node based on setup, you can refer [Edge configuration file reference](https://docs.apigee.com/private-cloud/v4.53.01/edge-configuration-file-reference) for, based on active only or active-active setup:
      - `LDAP_TYPE`
      - `LDAP_PEER`
      - `LDAP_SID`
      - `USE_LDAP_REMOTE_HOST=y/n`

        > [!NOTE]
        > **Note:** Set **USE_LDAP_REMOTE_HOST** to 'y' or 'n' based on whether LDAP is configured on the same node as the Management Server or not.

   2. Setup and start LDAP on new node with **updatedConfigFile** :

      ```javascript
      /opt/apigee/apigee-setup/bin/setup.sh -p ld -f updatedConfigFile
      ```
   3. Back up the LDAP data from older nodes (if active-active setup can be skipped):
      1. Take a sample backup on the new node, this is so that it generates a default backup folder/path:

         ```javascript
         apigee-service apigee-openldap backup
         ```
      2. Move your backed up data from old node, to the backup folder generated.
      3. Stop **apigee-openldap** before restoring the data:

         ```javascript
         apigee-service apigee-openldap stop
         ```
      4. Restore the backup taken from the older node:

         ```javascript
         apigee-service apigee-openldap restore backup_file
         ```

         For example:

         ```javascript
         apigee-service apigee-openldap restore 2026.02.09,10.28.20
         ```
7. Repeat for other LDAP node (if active-active).
8. Resetup and start Management Server with updated LDAP host configs:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p mt -f updatedConfigFile
   ```
9. Reset up and start SSO (if applicable):

   ```javascript
   apigee-service apigee-sso setup -f updatedConfigFile
   ```

   ```javascript
   apigee-service apigee-sso restart
   ```
10. (Optional) Configure the second active directory to read-only by following the [documentation](https://docs.apigee.com/private-cloud/v4.53.00/after-the-install#configure-an-openldap-server-to-be-read-only) steps.

### Qpid

To replace an existing Qpid node with an upgraded OS node, we need to make sure of the following steps:

1. Stop receiving any messages to the existing node queue from message processors.
2. Drain the existing messages in the queue.
3. Stop and Decommission the existing node.

Decommissioning existing nodes. To make sure that no messages are lost additional measures are listed along:

> [!NOTE]
> **NOTE:** To monitor the Qpid queues and other stats, please use the web management console or REST API to get the same.

1. Stop Qpid broker:

   ```javascript
   apigee-service apigee-qpidd stop
   ```
2. Block incoming traffic on port 5672 from all the Message Processors:

   ```javascript
   iptables -A INPUT -p tcp --dport 5672 -s MP_IP -j DROP
   ```
3. Start Qpid broker again to drain existing messages:

   ```javascript
   apigee-service apigee-qpidd start
   ```
4. Make sure all the messages in the queue are drained to the consumer, before you start to decommission.
5. Get UUID of the **edge-qpid-server** node:

   ```javascript
   curl http://qpid_node_ip:8083/v1/servers/self
   ```
6. Complete the [decommission or remove steps for Qpid from analytics](https://docs.apigee.com/private-cloud/v4.53.01/add-or-remove-qpid-nodes#removeaqpidserver) for **apigee-qpidd** and **edge-qpid-server**.
7. Stop and Uninstall both **apigee-qpidd** and **edge-qpid-server** :

   ```javascript
   apigee-service apigee-qpidd stop
   ```

   ```javascript
   apigee-service edge-qpid-server stop
   ```

   ```javascript
   apigee-service apigee-qpidd uninstall
   ```

   ```javascript
   apigee-service edge-qpid-server uninstall
   ```

Add new node:

1. Acquire new node with the upgraded OS.
2. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
3. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
4. Setup and run the Qpid services on the new node and add these to the consumer groups, [following these steps](https://docs.apigee.com/private-cloud/v4.53.01/add-or-remove-qpid-nodes#addaqpidserver). Consider the same steps to add other groups like for monetization.
5. If monetization service is enabled, restart Management Server and Message Processor:

   ```javascript
   apigee-service edge-management-server restart
   ```

   ```javascript
   apigee-service edge-message-processor restart
   ```
6. Repeat on all Qpid nodes.

### Message-processor

1. Get UUID of the <var translate="no">edge-message-processor</var> node:

   ```javascript
   curl http://mp_ip:8082/v1/servers/self
   ```
2. [Decommission and uninstall Message Processor node.](https://docs.apigee.com/private-cloud/v4.53.01/removing-server-management-servermessage-processorrouter)
3. If monetization service enabled, uninstall the **edge-mint-message-processor**.
4. Uninstall Message Processor:

   ```javascript
   apigee-service edge-message-processor uninstall
   ```
5. Acquire new node with the upgraded OS.
6. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
7. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
8. Add, setup and start Message Processor to the cluster, [following the steps](https://docs.apigee.com/private-cloud/v4.53.01/adding-router-or-message-processor-node#addamessageprocessor).
9. If monetization is enabled, set up the monetization service along with the Message Processor. For more information, refer the [following documentation](https://docs.apigee.com/private-cloud/v4.53.01/installing-monetization-services).

### Router

1. Get UUID of the <var translate="no">edge-router</var> node:

   ```javascript
   curl http://router_ip:8081/v1/servers/self
   ```
2. Disable reachability and Verify if its reachable:

   ```javascript
   iptables -A INPUT -i eth0 -p tcp --dport 15999 -j REJECT
   ```

   ```javascript
   curl -vvv -X GET http://router_ip:15999/v1/servers/self/reachable
   ```
3. [Decommission and uninstall](https://docs.apigee.com/private-cloud/v4.53.01/removing-server-management-servermessage-processorrouter) Router node.
4. Uninstall Router:

   ```javascript
   apigee-service edge-router uninstall
   ```
5. Acquire new node with the upgraded OS.
6. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
7. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
8. [Add, setup and start router](https://docs.apigee.com/private-cloud/v4.53.01/adding-router-or-message-processor-node#addarouter) to the cluster.

> [!NOTE]
> **NOTE:** Router and Message Processor can follow the alternate approach of adding a new node first (Step 5-8) and then Decommission the existing node (Step 1-4) to minimize any traffic impact and the load balancing configured.

### Management server

> [!NOTE]
> **NOTE:** If using only a single Management Server, it is mandatory to install and setup a new Management Server and then follow the steps to decommission the older one.

#### Single management server only

1. Acquire new node with the upgraded OS.
2. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
3. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
4. Add Management Server using the updated IP and configuration file which can be [referred from here](https://docs.apigee.com/private-cloud/v4.53.01/edge-configuration-file-reference) and run the setup command:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p mt -f updatedConfigFile
   ```
5. Resetup and restart UI with new Management IP configuration.

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ui -f updatedConfigFile
   ```
6. Resetup SSO with new Management IP configuration (if applicable):

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile
   ```
7. Resetup New UI (UE) with new Management IP configuration (if applicable):

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ue -f updatedConfigFile
   ```
8. If monetization is enabled:
   1. Resetup monetization MS with new Management IP configuration (if applicable), referring [monetization configuration](https://docs.apigee.com/private-cloud/v4.53.01/installing-monetization-services) documentation.

      ```javascript
      /opt/apigee/apigee-setup/bin/setup.sh -p mo -f updatedConfigFile
      ```
   2. Restart Management Server:

      ```javascript
      apigee-service edge-management-server restart
      ```
9. Decommission the Management Server on the existing/old node, [following the steps](https://docs.apigee.com/private-cloud/v4.53.01/decommission-data-center#management-server).
10. If monetization is enabled, remove the Management Server UUID from the analytics groups. Example:

    ```javascript
    curl -v -u AdminEmail:AdminPassword -X DELETE "http://localhost:8080/v1/analytics/groups/ax/mint_axgroup/servers?uuid=MS_UUID&type=consumer-server"
    ```
11. Uninstall the monetization Management Server:

    ```javascript
    apigee-service edge-mint-management-server uninstall
    ```

#### Multiple management servers

1. Decommission one of the Management Servers using the other on existing node, [following the steps](https://docs.apigee.com/private-cloud/v4.53.01/decommission-data-center#management-server).
2. Stop and uninstall Management Server:

   ```javascript
   apigee-service edge-management-server stop
   ```

   ```javascript
   apigee-service edge-management-server uninstall
   ```
3. Acquire new node with the upgraded OS.
4. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
5. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
6. Add Management Server using the updated IP and configuration file which can be [referred from here](https://docs.apigee.com/private-cloud/v4.53.01/edge-configuration-file-reference) and run the setup command:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p mt -f updatedConfigFile
   ```
7. Resetup and restart UI with updated Management IP configuration:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ui -f updatedConfigFile
   ```
8. (Only if SSO enabled) Resetup and restart SSO with updated Management IP configuration:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile
   ```
9. (Only if New UI enabled) Resetup and restart New UI with updated Management IP configuration:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ue -f updatedConfigFile
   ```
10. Repeat for other Management Server.

### UI/UE

1. Take backup/VM snapshot of UI node.
2. Stop and uninstall UI:

   ```javascript
   apigee-service edge-ui stop
   ```

   ```javascript
   apigee-service edge-ui uninstall
   ```
3. (If using New UI only) Stop and uninstall New UI:

   ```javascript
   apigee-service edge-management-ui stop
   ```

   ```javascript
   apigee-service edge-management-ui uninstall
   ```
4. Acquire new node with the upgraded OS.
5. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
6. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
7. Setup and run <var translate="no">edge-ui</var> on the new node, with updated IP configurations:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ui -f updatedConfigFile
   ```
8. (Only if SSO enabled) Resetup and run SSO with UI new node IP [configurations](https://docs.apigee.com/private-cloud/v4.53.01/install-and-configure-edge-sso) as applicable:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile
   ```
9. (Only if New UI enabled) Setup and run New UI on the new node, with updated IP configurations:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p ue -f updatedConfigFile
   ```

   ```javascript
   apigee-service edge-management-ui configure-sso -f updatedConfigFile
   ```

   ```javascript
   apigee-service edge-ui configure-sso -f updatedConfigFile
   ```

### SSO

> [!NOTE]
> **NOTE:** While replacing the SSO component, the UI service would be unavailable for the time period.

1. Take backup/VM snapshot of UI node.
2. Stop and uninstall SSO:

   ```javascript
   apigee-service apigee-sso stop
   ```

   ```javascript
   apigee-service apigee-sso uninstall
   ```
3. Acquire new node with the upgraded OS.
4. Apply the [OS-specific prerequisites](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#prerequisites-for-rhel-8rocky-8oracle-8).
5. Download bootstrap of Apigee version in use, [run bootstrap](https://docs.apigee.com/private-cloud/v4.53.01/install-edge-apigee-setup-utility#internet-node) to get **apigee-service** and install **apigee-setup**.
6. Add configurations and keys for SSO following the [guide](https://docs.apigee.com/private-cloud/v4.53.01/install-and-configure-edge-sso), considering the new node IP.
7. Setup and start SSO:

   ```javascript
   /opt/apigee/apigee-setup/bin/setup.sh -p sso -f updatedConfigFile
   ```
8. Update config with the new SSO node IPs and reconfigure SSO for UI:

   ```javascript
   apigee-service edge-ui configure-sso -f updatedConfigFile
   ```
9. (If using New UI) Run the configure-sso on the New UI node, referring the [documentation](https://docs.apigee.com/private-cloud/v4.53.01/enable-external-idp-edge-ui):

   ```javascript
   apigee-service edge-management-ui configure-sso -f updatedConfigFile
   ```

   ```javascript
   apigee-service edge-ui configure-sso -f updatedConfigFile
   ```