Update Apigee Edge 4.18.01 or 4.18.05 to 4.19.01

Edge for Private Cloud v4.19.01

This section describes how to perform the following upgrade:

From 4.18.01 to 4.19.01
From 4.18.05 to 4.19.01

All Upgrade Paths

The following table shows you the upgrade paths for version 4.19.01:


From 4.18.05	Directly upgrade from 4.18.05 → 4.19.01
From 4.18.01	Directly upgrade from 4.18.01 → 4.19.01
From 4.17.09	Directly upgrade from 4.17.09 → 4.19.01
From 4.17.05	Upgrade from 4.17.05 → 4.18.01, then upgrade from 4.18.01 → 4.19.01
From 4.17.01	Upgrade from 4.17.01 → 4.18.01, then upgrade from 4.18.01 → 4.19.01
From 4.16.09	Upgrade from 4.16.09 → 4.18.01, then upgrade from 4.18.01 → 4.19.01
From 4.16.05	Upgrade from 4.16.05 → 4.18.01, then upgrade from 4.18.01 → 4.19.01
From 4.16.01	Upgrade from 4.16.01 → 4.18.01, then upgrade from 4.18.01 → 4.19.01
From 4.15.0x	Upgrade from 4.15.0x → 4.16.01, then upgrade from Upgrade from 4.16.01 → 4.18.01, then upgrade from 4.18.01 → 4.19.01

Who can perform the update

The user running the update should be the same as the user who originally installed Edge, or a user running as root.

After you install the Edge RPMs, any user can configure them.

Which components must you update

You must update all Edge components. Edge does not support a setup that contains components from multiple versions.

Automatic propagation of property settings

If you have set any properties by editing .properties files in /opt/apigee/customer/application then these values are retained by the update.

Update prerequisites

Take care of following prerequisites before upgrading Apigee Edge:

Backup all nodes
Before you update, it is recommended to perform a complete backup of all nodes for safety reasons. Use the procedure for your current version of Edge to perform the backup.
This allows you to have a backup plan, in case the update to a new version doesn't function properly. For more information on backup, see Backup and restore.
Ensure Edge is running
Ensure that Edge is up and running during update process by using the command:
```
/opt/apigee/apigee-service/bin/apigee-all status
```

Updating the New Edge experience

If you installed the Beta version of New Edge experience in 4.18.0x, you must uninstall it and do a fresh install of the 4.19.01 version of the New Edge experience. For more information, see The New Edge experience for Private Cloud.

Note that there are installation configuration changes from Edge 4.18.01 (but not 4.18.05). The Edge 4.19.01 release of the New Edge experience contains changes to the configuration file from the Edge 4.18.01 release. The new properties are described in Installation configuration changes from Edge 4.18.01.

Handling a failed update

In the case of an update failure, you can try to correct the issue, and then run update.sh again. You can run the update multiple times and it continues the update from where it last left off.

If the failure requires that you roll back the update to your previous version, see Roll back 4.19.01 for more.

Logging update information

By default, the update.sh utility writes log information to:

/opt/apigee/var/log/apigee-setup/update.log

If the user running the update.sh utility does not have access to that directory, it writes the log to the /tmp directory as a file named update_username.log.

If the user does not have access to /tmp, the update.sh utility fails.

Zero-downtime update

A zero-downtime update, or rolling update, lets you update your Edge installation without bringing down Edge.

Zero-downtime update is only possible with a 5-node configuration and larger.

The key to zero-downtime upgrading is to remove each Router, one at a time, from the load balancer. You then update the Router and any other components on the same machine as the Router, and then add the Router back to the load balancer.

Update the machines in the correct order for your installation as described Order of machine update.
When it is time to update the Routers, select any one Router and make it unreachable, as described in Enabling/Disabling Server (Message Processor/Router) Reachability.
Update the selected Router and all other Edge components on the same machine as the Router. All Edge configurations show a Router and Message Processor on the same node.
Make the Router reachable again.
Repeat steps 2 through 4 for the remaining Routers.
Continue the update for any remaining machines in your installation.

Take care of the following before/after update:

On combined Router and Message Processor node:
- Before update – perform the following:
  1. Make the Router unreachable.
  2. Make the Message Processor unreachable.
- After update - perform the following:
  1. Make the Message Processor reachable.
  2. Make the Router reachable.
On single Router node:
- Before update, make the Router unreachable.
- After update, make the Router reachable.
On single Message Processor node:
- Before update, make the Message Processor unreachable.
- After update, make the Message Processor reachable.

Using a silent configuration file

You must pass a silent configuration file to the update command. The silent configuration file should be the same one you used to install Edge 4.18.0x.

Update to 4.19.01 on a node with an external internet connection

Use the following procedure to update the Edge components on a node:

If present, disable any CRON jobs configured to perform a repair operation on Cassandra until after the update completes.
Log in to your node as root to install the Edge RPMs.
NOTE: While RPM installation requires root access, you can perform Edge configuration without root access.

Install yum-utils and yum-plugin-priorities:

sudo yum install yum-utils
sudo yum install yum-plugin-priorities

Disable SELinux as described in Install the Edge apigee-setup utility.
If you are installing on Oracle 7.x, run the following command:
```
sudo yum-config-manager --enable ol7_optional_latest
```

If you are installing on AWS, run the following yum-configure-manager commands:

yum update rh-amazon-rhui-client.noarch
sudo yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional

Download the Edge 4.19.01 bootstrap_4.19.01.sh file to /tmp/bootstrap_4.19.01.sh:

curl https://software.apigee.com/bootstrap_4.19.01.sh -o /tmp/bootstrap_4.19.01.sh

Install the Edge 4.19.01 apigee-service utility and dependencies:
```
sudo bash /tmp/bootstrap_4.19.01.sh apigeeuser=uName apigeepassword=pWord
```
Where uName:pWord are the username and password you received from Apigee. If you omit pWord, you will be prompted to enter it.

By default, the installer checks to see that you have Java 1.8 installed. If you do not, it installs it for you. Use the JAVA_FIX option to specify how to handle Java installation. JAVA_FIX takes the following values:
- I: Install OpenJDK 1.8 (default).
- C: Continue without installing Java.
- Q: Quit. For this option, you must install Java yourself.

Use apigee-service to update the apigee-setup utility:

/opt/apigee/apigee-service/bin/apigee-service apigee-setup update

Update the apigee-validate utility on the Management Server, as the following example shows:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-validate update
```
Update the apigee-provision utility on the Management Server, as the following example shows:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-provision update
```
Run the update utility on your nodes in the order described in Order of machine update:
```
/opt/apigee/apigee-setup/bin/update.sh -c component -f configFile
```
Where component is the Edge component to update. Possible values include:
- "cs": Cassandra
- "edge": All Edge components except Edge UI: Management Server, Message Processor, Router, QPID Server, Postgres Server
- "ldap": OpenLDAP
- "ps": postgresql
- "qpid": qpidd
- "sso": Edge SSO (if you installed SSO)
- "ui": Edge UI
- "zk": Zookeeper
And configFile is the same configuration file that you used to define your Edge components during the 4.18.0x installation.
NOTE: The configuration file must be readable by the "apigee" user. To change the owner, use the following command:
```
chown apigee:apigee configFile
```
You can run update.sh against all components by setting component to "all", but only if you have an Edge all-in-one (aio) installation profile. For example:
```
/opt/apigee/apigee-setup/bin/update.sh -c all -f ./sa_silent_config
```
Restart the Edge UI component on all nodes running it, if you haven't done so already:
```
/opt/apigee/apigee-service/bin/apigee-service edge-ui restart
```
Test the update by running the apigee-validate utility on the Management Server, as described in Test the install.

If you later decide to roll back the update, use the procedure described in Roll back 4.19.01.

Update to 4.19.01 from a local repo

If your Edge nodes are behind a firewall, or in some other way are prohibited from accessing the Apigee repository over the Internet, then you can perform the update from a local repository, or mirror, of the Apigee repo.

After you create a local Edge repository, you have two options for updating Edge from the local repo:

Create a .tar file of the repo, copy the .tar file to a node, and then update Edge from the .tar file.
Install a webserver on the node with the local repo so that other nodes can access it. Apigee provides the Nginx webserver for you to use, or you can use your own webserver.

To update from a local 4.19.01 repo:

Create a local 4.19.01 repo as described in "Create a local Apigee repository" at Install the Edge apigee-setup utility.
NOTE: If you already have an existing repo, you can add the 4.19.01 repo to it as described in "Update a local Apigee repository" at Install the Edge apigee-setup utility.
To install apigee-service from a .tar file:
1. On the node with the local repo, use the following command to package the local repo into a single .tar file named /opt/apigee/data/apigee-mirror/apigee-4.19.01.tar.gz:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-mirror package
```
2. Copy the .tar file to the node where you want to update Edge. For example, copy it to the /tmp directory on the new node.
3. On the new node, untar the file to the /tmp directory:
```
tar -xzf apigee-4.19.01.tar.gz
```
  This command creates a new directory, named repos, in the directory containing the .tar file. For example /tmp/repos.
4. Install the Edge apigee-service utility and dependencies from /tmp/repos:
```
sudo bash /tmp/repos/bootstrap_4.19.01.sh apigeeprotocol="file://" apigeerepobasepath=/tmp/repos
```
  Notice that you include the path to the repos directory in this command.
To install apigee-service using the Nginx webserver:
1. Configure the Nginx web server as described in "Install from the repo using the Nginx webserver" at Install the Edge apigee-setup utility.
2. On the remote node, download the Edge bootstrap_4.19.01.sh file to /tmp/bootstrap_4.19.01.sh:
```
/usr/bin/curl http://uName:pWord@remoteRepo:3939/bootstrap_4.19.01.sh -o /tmp/bootstrap_4.19.01.sh
```
  Where uName:pWord are the username and password you set previously for the repo, and remoteRepo is the IP address or DNS name of the repo node.
3. On the remote node, install the Edge apigee-setup utility and dependencies:
```
sudo bash /tmp/bootstrap_4.19.01.sh apigeerepohost=remoteRepo:3939 apigeeuser=uName apigeepassword=pWord apigeeprotocol=http://
```
  Where uName:pWord are the repo username and password.
Use apigee-service to update the apigee-setup utility, as the following example shows:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-setup update 
```
Update the apigee-validate utility on the Management Server, as the following example shows:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-validate update
```
Update the apigee-provision utility on the Management Server, as the following example shows:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-provision update
```
Run the update utility on your nodes in the order described in Order of machine update:
```
/opt/apigee/apigee-setup/bin/update.sh -c component -f configFile
```
Where:
- component is the Edge component to update. You typically update the following components:
  - "cs": Cassandra
  - "edge": All Edge components except Edge UI. The "edge" component includes the Management Server, Message Processor, Router, QPID Server, and Edge Postgres Server.
  - "ldap": OpenLDAP
  - "ps": postgresql
  - "qpid": qpidd
  - "sso": Edge SSO (if you installed SSO)
  - "ui": Edge UI
  - "zk": Zookeeper
- configFile is the same configuration file that you used to define your Edge components during the 4.18.0x installation.
  NOTE: The configuration file must be readable by the "apigee" user. To change the owner, use the following command:
```
chown apigee:apigee configFile
```
You can run update.sh against all components by setting component to "all", but only if you have an Edge all-in-one (AIO) installation profile. For example:
```
/opt/apigee/apigee-setup/bin/update.sh -c all -f /tmp/sa_silent_config
```
Restart the Edge UI component on all nodes running it, if you haven't done so already:
```
/opt/apigee/apigee-service/bin/apigee-service edge-ui restart
```
Test the update by running the apigee-validate utility on the Management Server, as described in Test the install.

If you later decide to roll back the update, use the procedure described in Roll back 4.19.01.

Order of machine update

The order that you update the machines in an Edge installation is important:

You must update all Cassandra and ZooKeeper nodes before you update any other nodes.
For any machine with multiple Edge components (Management Server, Message Processor, Router, QPID Server but not Postgres Server), use the -c edge option to update them all at the same time.
If a step specifies that it should be performed on multiple machines, perform it in the specified machine order.
There is no separate step to update Monetization. It is updated when you specify the -c edge option.

1-node standalone upgrade

To upgrade a 1-node standalone configuration to 4.19.01:

Update all components:

/opt/apigee/apigee-setup/bin/update.sh -c all -f configFile

(If you installed apigee-adminapi) Updated the apigee-adminapi utility:

/opt/apigee/apigee-service/bin/apigee-service apigee-adminapi update

2-node standalone upgrade

Update the following components for a 2-node standalone installation:

See Installation topologies for the list of Edge topologies and node numbers.

Update Cassandra and ZooKeeper on machine 1:

/opt/apigee/apigee-setup/bin/update.sh -c cs,zk -f configFile

Update Qpid and Postgres on machine 2:

/opt/apigee/apigee-setup/bin/update.sh -c qpid,ps -f configFile

Update LDAP on machine 1:

/opt/apigee/apigee-setup/bin/update.sh -c ldap -f configFile

Update Edge components on machine 2 and 1:

/opt/apigee/apigee-setup/bin/update.sh -c edge -f configFile

Update UI on machine 1:

/opt/apigee/apigee-setup/bin/update.sh -c ui -f configFile

(If you installed apigee-adminapi) Updated the apigee-adminapi utility on machine 1:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-adminapi update
```
(If you installed Edge SSO) Update Edge SSO on machine 1:
```
/opt/apigee/apigee-setup/bin/update.sh -c sso -f sso_config_file
```
Where sso_config_file is the configuration file you created when you installed SSO.

Restart the Edge UI component on machine 1:

/opt/apigee/apigee-service/bin/apigee-service edge-ui restart

5-node upgrade

Update the following components for a 5-node installation:

See Installation topologies for the list of Edge topologies and node numbers.

Update Cassandra and ZooKeeper on machine 1, 2, and 3:

/opt/apigee/apigee-setup/bin/update.sh -c cs,zk -f configFile

Update Qpid and Postgres on machine 4:

/opt/apigee/apigee-setup/bin/update.sh -c qpid, ps -f configFile

Update Qpid and Postgres on machine 5:

/opt/apigee/apigee-setup/bin/update.sh -c qpid, ps -f configFile

Update LDAP on machine 1:

/opt/apigee/apigee-setup/bin/update.sh -c ldap -f configFile

Update Edge components on machine 4, 5, 1, 2, 3:

/opt/apigee/apigee-setup/bin/update.sh -c edge -f configFile

Update UI on machine 1:

/opt/apigee/apigee-setup/bin/update.sh -c ui -f configFile

(If you installed apigee-adminapi) Updated the apigee-adminapi utility on machine 1:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-adminapi update
```
(If you installed Edge SSO) Update Edge SSO on machine 1:
```
/opt/apigee/apigee-setup/bin/update.sh -c sso -f sso_config_file
```
Where sso_config_file is the configuration file you created when you installed SSO.

Restart the Edge UI component on machine 1:

/opt/apigee/apigee-service/bin/apigee-service edge-ui restart

9-node clustered upgrade

Update the following components for a 9-node clustered installation:

See Installation topologies for the list of Edge topologies and node numbers.

Update Cassandra and ZooKeeper on machine 1, 2, and 3:

/opt/apigee/apigee-setup/bin/update.sh -c cs,zk -f configFile

Update Qpid on machines 6 and 7:

/opt/apigee/apigee-setup/bin/update.sh -c qpid -f configFile

Update Postgres on machine 8:

/opt/apigee/apigee-setup/bin/update.sh -c ps -f configFile

Update Postgres on machine 9:

/opt/apigee/apigee-setup/bin/update.sh -c ps -f configFile

Update LDAP on machine 1:

/opt/apigee/apigee-setup/bin/update.sh -c ldap -f configFile

Update Edge components on machine 6, 7, 8, 9, 1, 4, and 5 in that order:
```
/opt/apigee/apigee-setup/bin/update.sh -c edge -f configFile
```

Update UI on machine 1:

/opt/apigee/apigee-setup/bin/update.sh -c ui -f configFile

(If you installed apigee-adminapi) Updated the apigee-adminapi utility on machine 1:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-adminapi update
```
(If you installed Edge SSO) Update Edge SSO on machine 1:
```
/opt/apigee/apigee-setup/bin/update.sh -c sso -f sso_config_file
```
Where sso_config_file is the configuration file you created when you installed SSO.

Restart the Edge UI component on machine 1:

/opt/apigee/apigee-service/bin/apigee-service edge-ui restart

13-node clustered upgrade

Update the following components for a 13-node clustered installation:

See Installation topologies for the list of Edge topologies and node numbers.

Update Cassandra and ZooKeeper on machines 1, 2, and 3:

/opt/apigee/apigee-setup/bin/update.sh -c cs,zk -f configFile

Update Qpid on machines 12 and 13:

/opt/apigee/apigee-setup/bin/update.sh -c qpid -f configFile

Update Postgres on machine 8:

/opt/apigee/apigee-setup/bin/update.sh -c ps -f configFile

Update Postgres on machine 9:

/opt/apigee/apigee-setup/bin/update.sh -c ps -f configFile

Update LDAP on machine 4 and 5:

/opt/apigee/apigee-setup/bin/update.sh -c ldap -f configFile

Update Edge components on machines 12, 13, 8, 9, 6, 7, 10, and 11 in that order:
```
/opt/apigee/apigee-setup/bin/update.sh -c edge -f configFile
```

Update UI on machines 6 and 7:

/opt/apigee/apigee-setup/bin/update.sh -c ui -f configFile

(If you installed apigee-adminapi) Updated the apigee-adminapi utility on machines 6 and 7:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-adminapi update
```
(If you installed Edge SSO) Update Edge SSO on machines 6 and 7:
```
/opt/apigee/apigee-setup/bin/update.sh -c sso -f sso_config_file
```
Where sso_config_file is the configuration file you created when you installed SSO.

Restart the Edge UI component on machines 6 and 7:

/opt/apigee/apigee-service/bin/apigee-service edge-ui restart

12-node clustered upgrade

Update the following components for a 12-node clustered installation:

See Installation topologies for the list of Edge topologies and node numbers.

Update Cassandra and ZooKeeper:

On machines 1, 2 and 3 in Data Center 1:

/opt/apigee/apigee-setup/bin/update.sh -c cs,zk -f configFile

On machines 7, 8, and 9 in Data Center 2

/opt/apigee/apigee-setup/bin/update.sh -c cs,zk -f configFile

Update qpidd:

Machines 4, 5 in Data Center 1

Update qpidd on machine 4:

/opt/apigee/apigee-setup/bin/update.sh -c qpid -f configFile

Update qpidd on machine 5:

/opt/apigee/apigee-setup/bin/update.sh -c qpid -f configFile

Machines 10, 11 in Data Center 2

Update qpidd on machine 10:

/opt/apigee/apigee-setup/bin/update.sh -c qpid -f configFile

Update qpidd on machine 11:

/opt/apigee/apigee-setup/bin/update.sh -c qpid -f configFile

Update Postgres:

Machine 6 in Data Center 1

/opt/apigee/apigee-setup/bin/update.sh -c ps -f configFile

Machine 12 in Data Center 2

/opt/apigee/apigee-setup/bin/update.sh -c ps -f configFile

Update LDAP:

Machine 1 in Data Center 1

/opt/apigee/apigee-setup/bin/update.sh -c ldap -f configFile

Machine 7 in Data Center 2

/opt/apigee/apigee-setup/bin/update.sh -c ldap -f configFile

Update Edge components:

Machines 4, 5, 6, 1, 2, 3 in Data Center 1

/opt/apigee/apigee-setup/bin/update.sh -c edge -f configFile

Machines 10, 11, 12, 7, 8, 9 in Data Center 2

/opt/apigee/apigee-setup/bin/update.sh -c edge -f configFile

Update UI:

Machine 1 in Data Center 1:

/opt/apigee/apigee-setup/bin/update.sh -c ui -f configFile

Machine 7 in Data Center 2:

/opt/apigee/apigee-setup/bin/update.sh -c ui -f configFile

Restart the Edge UI component on machines 1 and 7:

/opt/apigee/apigee-service/bin/apigee-service edge-ui restart

(If you installed apigee-adminapi) Updated the apigee-adminapi utility:

Machine 1 in Data Center 1:

/opt/apigee/apigee-service/bin/apigee-service apigee-adminapi update

Machine 7 in Data Center 2:

/opt/apigee/apigee-service/bin/apigee-service apigee-adminapi update

(If you installed Edge SSO) Update Edge SSO:
1. Machine 1 in Data Center 1:
```
/opt/apigee/apigee-setup/bin/update.sh -c sso -f sso_config_file
```
2. Machine 7 in Data Center 2:
```
/opt/apigee/apigee-setup/bin/update.sh -c sso -f sso_config_file
```

For a non-standard configuration

If you have a non-standard configuration, then update Edge components in the following order:

ZooKeeper
Cassandra
qpidd, ps
LDAP
Edge, meaning the "-c edge" profile on all nodes in the order: nodes with Qpid server, Edge Postgres Server, Management Server, Message Processor, and Router.
NOTE: If a node has both Qpid server and Edge Postgres Server installed, run the "-c edge" profile step.
Edge UI
apigee-adminapi
Edge SSO

After you finish updating, be sure to restart the Edge UI component on all machines running it.