Pre-upgrade preparation and checks VMware

Prepare your VMware deployment for upgrading to the newest version of API Connect.

Before you begin

Review the Planning your API Connect upgrade on VMware to ensure that you are following a supported upgrade path and that you understand important changes that might affect your deployment.

Procedure

VM health checks:

From your project directory, run the apicup health-check command for each of your subsystems.

apicup subsys health-check <subsystem name>

If the health check is successful, then the command returns silently.

If you see an IO timeout error, then it's likely that a firewall is blocking access to port 9178. For example:

apicup subsys health-check <subsystem name>
...
Error: failed to install the subsystem: unable to open file send stream:  
 rpc error: code = Unavailable desc = all SubConns are in TransientFailure, 
 latest connection error: connection error: 
 desc = "transport: Error while dialing dial tcp 1.2.3.4:9178: i/o timeout"

If you see this error, make sure that your firewall has port 9178 open.

Login to each of your API Connect VMs and switch to the root user:
```
ssh apicadm@<hostname>
```
```
sudo -i
```
Delete any stale upgrade files that might be left on the VM from previous upgrades:
```
apic clean-upgrade-files
```
Remove obsolete sources files to ensure a clean upgrade.
Delete any files in the directory /etc/apt/sources.list.d whose names match the format: repo-<subsystem>-<version>-<appliance version>.list:
```
rm /etc/apt/sources.list.d/repo-*.list
```
Verify that each VM has sufficient disk space:
1. Check the available space on the data disk:
```
df -h /data/secure
```
  If disk usage is higher than 70%, then add disk capacity. See Adding disk space to a VMware appliance.
2. Check available space in /:
```
df -h /
```
  If disk usage is higher than 70%, delete or copy off older /var/log/syslog*.gz files. The syslog files contain your API Connect and system logs. Do not delete any syslog files that might contain log data that is needed for any active support cases. If in doubt, backup the syslog files to another system before your delete them.
Run the apicops pre-upgrade health checks:
1. Download the latest apicops release and copy it to your VM.
2. Run the apicops pre-upgrade check on your API Connect VMs:
  Note: If you have a three replica deployment, then run this check on just one VM from each subsystem.
  1. Management VM:
```
apicops system:pre-upgrade-check management
```
    Note: If you have a 2DCDR deployment, run this check only on the active management subsystem.
  2. Portal VM:
```
apicops system:pre-upgrade-check portal
```
  3. Analytics VM:
```
apicops system:pre-upgrade-check analytics
```
  If the pre-upgrade check returns any errors, then collect the output and open a support case.

Pre-upgrade backups and preparation:

Optional: Set up remote logging: Configuring remote logging for a VMware deployment.

If the upgrade process fails, it is possible that important log messages for problem diagnosis are not retained on the VMs. Configure remote logging to ensure that all API Connect logging during the upgrade is retained.
Backup all your subsystems. Ensure that you have:
- Database backups of all your subsystems.
- Project directory backup.
- Optional: VM snapshots of all subsystems.
Upgrading from V10.0.7.0 : see Backing up and restoring on VMware.

Upgrading from V10.0.5.x: see Backing up and restoring on VMware.

Download and verify the API Connect upgrade files:

Obtain the API Connect upgrade files:

You can access the latest files from IBM Fix Central by searching for the API Connect product and your installed version.

The following files are used during upgrade on VMware:

IBM API Connect <version> Management Upgrade File for VMware

Management subsystem files for upgrade. Filename is: upgrade_management_<version>.

IBM API Connect <version> Developer Portal Upgrade File for VMware

Developer Portal subsystem files for upgrade. Filename is: upgrade_portal_<version>

IBM API Connect <version> Analytics Upgrade File for VMware

Analytics subsystem files for upgrade. Filename is upgrade_analytics_<version>

IBM API Connect <version> Install Assist for <operating_system_type>

The apicup installation utility. Required for all installations on VMware. Filename is apicup-<platform>_<version>.

ubuntu-jammy-upgrade.tgz

The ubuntu-jammy-upgrade.tgz is required for upgrade to V10.0.8.1. The file contains the Ubuntu Linux upgrade packages which must be applied before the API Connect upgrade.

IBM® API Connect <version> Security Signature Bundle File

Signature files for verifying the integrity of your downloads.
Filename is signatures_<version>.
The following files are not used during the upgrade process, but should be downloaded to replace your existing versions of them:
IBM API Connect <version> Toolkit for <operating_system>
Toolkit command-line utility. Packaged as a stand-alone file, or with API Designer:

IBM® API Connect <version> Toolkit for <operating_system>

IBM® API Connect <version> Toolkit Designer for <operating_system>

Filename is toolkit-...<operating system>_<version>.
Not required during initial installation. After installation, you can download directly from the Cloud Manager UI and API Manager UI as explained in Installing the toolkit.
IBM API Connect <version> Local Test Environment

Optional test environment for testing locally as explained in Testing an API with the Local Test Environment.
Filename is apic-lte-<operating system>_<version>.

If control plane files are required for your upgrade path, download them from the same IBM Fix Central page.

Control plane files are required to support specific Kubernetes versions. The IBM API Connect <version> Management Upgrade File for VMware file contains the latest control plane file.

Table 1 lists the control plane files that are needed for upgrading to the current release.

Tip: On the Fix Central page, type "control-plane" in the Filter fix details field to list only the control plane files in the results table. Then, click the Description header to sort the results so you can easily locate the control plane files that you need.

Table 1. Control Plane files needed for upgrading to 10.0.8.0
Upgrading from API Connect version	Control Plane files needed
10.0.7.0 10.0.5.7 10.0.5.6 10.0.5.5	No Control Plane needed.
10.0.5.4	Download: `appliance-control-plane-1.27.x.tgz`

For information about the control plane files that are required for upgrading to older releases as interim steps, see Control Plane files for earlier releases.

Complete the steps in Verifying the integrity of IBM product files to verify that the downloaded product files are not corrupted.

Set up the new apicup command in your project directory.

The apicup executable file is updated with each API Connect release. To upgrade API Connect, you must replace the apicup file from your current release with the new apicup file.

Note: If you decide to stop or delay your API Connect upgrade, then revert these steps.

In your project directory, take a backup of your current apicup file, appending the current API Connect version to the name of the backup file.
For example:
```
cp apicup apicup_v10.0.7.0
```
Replace the apicup file in your project directory with the new apicup file that you downloaded in step 9.
macOS and Linux® only: Make the apicup file executable:
```
chmod +x apicup
```

Set your operating system's PATH variable to include your project directory:

Table 2. Commands for setting the path to the apicup file
Operating system	Command to set the path
macOS and Linux	`export PATH=$PATH:<project directory path>`
Windows	`set PATH=<project directory path>;%PATH%`

Verify that the new apicup command is in your PATH, run:
```
apicup version
```
The output should show the version that you are upgrading to.
Run the apicup command to accept the API Connect license:
```
apicup licenses accept <License ID>
```
<License ID> is specific to the API Connect Program Name that you purchased. To view the supported license IDs, see API Connect licenses.