Upgrading the Management subsystem from v2018 to v10

You can upgrade the management subsystem from v2018 to the latest version of v10.

Before you can upgrade the management subsystem, you must prepare the API Connect cluster namespaces. If you haven't done so already, see one of the following:

One of the major changes between v2018 and v10 is the change from Cassandra to Postgres for the management database. The upgrade process uses the following steps to upgrade the management subsystem database:
1. Take management database backup.
  Backup and restore must be configured for management subsystem on v2018.
2. Scale down the v2018 pods except Cassandra database
3. Extract data from Cassandra database.
  This task runs as an extract job. The extract job creates logs.
4. Bring up Postgres database.
5. Load the extracted data into Postgres database and do the necessary transformations.
  This task runs as the load job. The load job creates a log.
To upgrade the management subsystem, you configure an upgrade CR and apply it. When you apply the CR, the upgrade process runs automatically.

Trigger a manual backup for management subsystem if you have not backed up management subsystem as part of Preparing the v2018 deployment for upgrade.

Populate the template upgrade CR for management.apiconnect.ibm.com_v1beta1_upgradefromv2018_cr.yaml with values for your deployment:

Table 1. Variables to set in the Upgrade CR template
Variable	Description
`$NAME`	Name to uniquely identify this resource. Example: `mgmt`
`$MANAGEMENT_SUBSYSTEM_NAME`	Must match the v2018's management subsystem name. Use `apicup subsys list` to find the name. For example: `$ apicup subsys list Name Type Target mgmt ManagementSubsystem kubernetes gwv5 GatewaySubsystem kubernetes gwv6 GatewaySubsystem kubernetes portal PortalSubsystem kubernetes analytics AnalyticsSubsystem kubernetes`
`$TRIGGER_ROLLBACK`	Can be `true` or `false`. Must initially be set to `false` (default value) when creating the resource. After creation can be updated and set to `true` to trigger a management subsystem rollback.
`$IMAGE_REGISTRY`	Provide valid image registry to access the upgrade and v10 artifacts. Must be provided if `DEFAULT_IMAGE_REGISTRY` is not set.
`$IMAGE_PULL_SECRETS`	Valid image pull secrets to pull images from image registry specified in `$IMAGE_REGISTRY`. Must be provided if `DEFAULT_IMAGE_PULL_SECRET` is not set.
`$PROFILE`	Specifies mode of the v10 installation to upgrade to. Takes `n1xc4.m16` for dev or `n3xc4.m16` for production setup of v10.
`$PRODUCTION_OR_NONPRODUCTION`	License `use` type. Must be either `production` or `nonproduction` type of license Note that license `accept:` must be set to `true` to enable the upgrade to proceed.
`$STORAGE_CLASS_NAME`	Storage class name must be provided for all Volume Claim templates. The `default-class-name` will be used only if cluster's default-class-name has been set.
`$VOLUME_SIZE`	`upgradeVolumeClaimTemplate:` The size of the PVC created for the extract job. Minimum size 50Gi. `databaseVolumeClaimTemplate:` - Minimum size 120 Gi `dbBackupVolumeClaimTemplate:` - Minimum size 120 Gi `dbArchiveVolumeClaimTemplate:` - Minimum size 30 Gi. `messageQueueVolumeClaimTemplate:` - Minimum size of 10 Gi

Sample populated CR:

apiVersion: management.apiconnect.ibm.com/v1beta1
kind: UpgradeFromV2018
metadata:
  name: mgmt
spec:
  subsystemName: mgmt
  triggerRollback: false
  upgradeVolumeClaimTemplate:
    storageClassName: local-storage
    volumeSize: 50Gi
  imageRegistry: <your_image_registry>
  imagePullSecrets:
  - <your_imagePullSecret>
  profile: n1xc4.m16 # to bring up dev installation of v10 management subsystem
  license:
    accept: true
    use: production
  certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
  managementSpec:
    databaseVolumeClaimTemplate:
      storageClassName: local-storage
      volumeSize: 120Gi
    dbBackupVolumeClaimTemplate:
      storageClassName: local-storage
      volumeSize: 120Gi
    dbArchiveVolumeClaimTemplate:
      storageClassName: local-storage
      volumeSize: 30Gi
    messageQueueVolumeClaimTemplate:
      storageClassName: local-storage
      volumeSize: 10Gi

Create the v2018 upgrade CR for management:
```
kubectl apply -f management.apiconnect.ibm.com_v1beta1_upgradefromv2018_cr.yaml -n <namespace>
```
The upgrade CR triggers the upgrade process for management.
Monitor upgrade progress:
1. Open a new terminal and tail upgrade-operator pod:
```
kubectl logs <upgrade-operator-pod> -n <namespace>
```
2. Open a new terminal and watch upgrade-operator status:
```
watch kubectl get upgradefromv2018.management.apiconnect.ibm.com mgmt -n <namespace>
```
3. Open a new terminal and check the status of the upgrade-operator:
```
kubectl describe upgradefromv2018.management.apiconnect.ibm.com mgmt -n <namespace>
```
  Example output:
```
    Phase:                          Complete
      State:                          Upgrade completed
```
4. Once the upgrade process has completed the extract job, open a new terminal and monitor the progress of v10 installation:
```
kubectl get apic -n <namespace>
```
  When the upgrade succeeds, the upgrade state displays UpgradeComplete.
  
  If you encounter an error, see Rolling back a management upgrade to v2018.
Once the management subsystem has been upgraded, configure backup settings on the new v10 management subsystem.

Note: You must configure backups because Management subsystem backup configuration settings are not carried over from v2018 to v10 during the upgrade.

See Configuring backup settings for fresh install of the Management subsystem (v10.0.1.1 or later).

If configuring s3 backup settings, there is a brief downtime.
Save the upgrade logs after a successful upgrade. This is not mandatory but is recommended, to retain the ability to track the extract and load jobs.
1. Save the PVC logs after a successful upgrade.
  The upgrade logs are stored in the /upgrade folder in the PVC. See Logs for management upgrade
2. Optionally, you can view logs of orphaned data from database upgrades. In the downloaded PVC contents, the logs are located in logs/apim/orphans and logs/lur/orphans. The data represents records which were deleted or updated because of invalid or missing references to data in other tables. If necessary, you can contact IBM Support to better understand the orphaned data.
3. Save the extract and load jobs logs. See Logs for extract and load jobs
We highly recommend that you retain the encryption secret and database credential secrets in a safe location, in case you need to restore during a disaster recovery scenario. Complete the steps in Preparing the management subsystem for disaster recovery using S3 backups (v10.0.1.1 or later) or Preparing the management subsystem for disaster recovery using SFTP backups (v10.0.1.1 or later).

Note: If you do not complete the steps in Preparing the management subsystem for disaster recovery using S3 backups (v10.0.1.1 or later) or Preparing the management subsystem for disaster recovery using SFTP backups (v10.0.1.1 or later)., you will not be able to restore your management subsystem to a new cluster during a disaster recovery scenario.
Once the management subsystem has been upgraded, clear your browser cache and verify that you can log in to Cloud Manager UI and API manager UI and access the configuration menus.
Next, upgrade the Developer Portal subsystem. Continue with Upgrading the Developer Portal subsystem from v2018 to v10.

Note: If the management subsystem upgraded encountered problems, see the instructions in the links at the end of this page. See also Disaster recovery of a v2018 deployment