IBM API Catalog service upgrade and rollback

Complete the following steps to upgrade the IBM API Catalog service from a previous version.

If you need to revert to a previous version, see Roll back the service section.

Upgrade the service

Before you upgrade, back up the data so that you can restore it in case the upgrade fails.

Backing up the data

Complete these steps to back up the data:

Back up the Enc/Cred/Password secrets. You must export the management database encryption secret, credentials secrets, and user or password secrets to YAML files. The default encryption secret name is apicatalog-enc-key. If you used a custom name, replace the name in the following command. The custom name that you used is defined in the managementCR.spec.encryptionSecret file.

oc get secret apicatalog-enc-key -n ibm-common-services -o yaml > ~/apicatalog-enc-key.yaml
oc get secret apicatalog-cli-cred -n ibm-common-services -o yaml > ~/apicatalog-cli-cred.yaml
oc get secret apicatalog-juhu-cred -n ibm-common-services -o yaml > ~/apicatalog-juhu-cred.yaml
oc get secret apicatalog-admin -n ibm-common-services -o yaml > ~/apicatalog-admin.yaml
oc get secret apicatalog-global-org-user -n ibm-common-services -o yaml > ~/apicatalog-global-org-user.yaml
oc get secret apicatalog-ibm-platform-user -n ibm-common-services -o yaml > ~/apicatalog-ibm-platform-user.yaml

From the YAML files that you created, remove the following sections:

metadata.creationTimestamp
metadata.managedFields
metadata.ownerReferences
metadata.resourceVersion

metadata.uid
Following is an example of the output YAML file:

apiVersion: v1
data:
encryption_secret.bin: HJ0m7YRBMuA0jQ1OtCYsqKHqVtVBJgIl+SWxA7/3QvtkS5/HSUIWs1lTSXxAjSP9a6p9MauTDhhsRw0WtIQJhaq3V4Z4qbZHHSd1gk26gU8Ztv1n2QR7cFbpEf86t6qoCtmLNQPBIWl0yqAlLk+NEGgnWuYCaaa89AYIwXSm+Qk=
kind: Secret
metadata:
labels:
 app.kubernetes.io/instance: apicatalog
 app.kubernetes.io/managed-by: ibm-apiconnect
 app.kubernetes.io/name: apicatalog-enc-key
name: apicatalog-enc-key
namespace: ibm-common-services
type: Opaque

Back up the data in the PostgreSQL databases.

Access the PostgreSQL database pod.

oc exec -it apicatalog-db-1 bash -n ibm-common-services

Export the data to the backup files.

pg_dump -U postgres -c apim > /var/lib/postgresql/data/pgdump_apim.sql
pg_dump -U postgres -c lur > /var/lib/postgresql/data/pgdump_lur.sql

Copy the backed-up files to your local host.

oc cp apicatalog-db-1:/var/lib/postgresql/data/pgdump_apim.sql -n ibm-common-services ~/pgdump_apim.sql
oc cp apicatalog-db-1:/var/lib/postgresql/data/pgdump_lur.sql -n ibm-common-services ~/pgdump_lur.sql

Upgrading the service

When you upgrade IBM Cloud Pak foundational services, the IBM API Catalog service is automatically upgraded.

For more information about upgrading foundational services, see Upgrading foundational services from an operator release.

Roll back the service

In case an upgrade fails, you can revert to the previous version of the service.

Follow these steps to roll back the service and to restore your previous data.

Uninstall the upgraded IBM API Catalog service. For more information about how to uninstall the service, see Uninstalling the IBM API Catalog service or Uninstalling the IBM API Catalog service in an air-gapped environment.

Restore the management database encryption secret, credentials secrets, and user or password secrets. Use the names of the YAML files that you created during backup in the following commands:

oc apply -f ~/apicatalog-enc-key.yaml -n ibm-common-services
oc apply -f ~/apicatalog-cli-cred.yaml -n ibm-common-services
oc apply -f ~/apicatalog-juhu-cred.yaml -n ibm-common-services
oc apply -f ~/apicatalog-admin.yaml -n ibm-common-services
oc apply -f ~/apicatalog-global-org-user.yaml -n ibm-common-services
oc apply -f ~/apicatalog-ibm-platform-user.yaml -n ibm-common-services

The command re-creates the original secrets with the original names.

Install the IBM API Catalog service with the previous version. Wait until the service is up and running.
```
oc get apicat
```
Following is a sample output:
```
NAME         READY   STATUS    RECONCILED VERSION   AGE
apicatalog   12/12   Running   1.0.0-37             4m47s
```

Restore data to the PostgreSQL databases.

Scale down the apicatalog-operator and the application microservices.

oc scale --replicas=0 deployment apicatalog-juhu -n ibm-common-services
oc scale --replicas=0 deployment apicatalog-apim -n ibm-common-services
oc scale --replicas=0 deployment apicatalog-lur -n ibm-common-services
oc scale --replicas=0 deployment ibm-apicatalog-controller-manager -n ibm-common-services

Copy the backed-up files from your local host to the PostgreSQL database pod.

oc cp ~/pgdump_apim.sql apicatalog-db-1:/var/lib/postgresql/data/pgdump_apim.sql -n ibm-common-services
oc cp ~/pgdump_lur.sql apicatalog-db-1:/var/lib/postgresql/data/pgdump_lur.sql -n ibm-common-services

Access the PostgreSQL database pod.

oc exec -it apicatalog-db-1 bash -n ibm-common-services

Import the data into the databases.

psql -U postgres apim -f /var/lib/postgresql/data/pgdump_apim.sql
psql -U postgres lur -f /var/lib/postgresql/data/pgdump_lur.sql

Scale up the apicatalog-operator and application microservices.

oc scale --replicas=1 deployment ibm-apicatalog-controller-manager -n ibm-common-services
oc scale --replicas=1 deployment apicatalog-lur -n ibm-common-services
oc scale --replicas=1 deployment apicatalog-apim -n ibm-common-services
oc scale --replicas=1 deployment apicatalog-juhu -n ibm-common-services