Upgrading the Developer Portal subsystem from 2018 to v10

You can upgrade the Developer Portal subsystem from 2018.4.1.20 or later to the latest release of v10.

Before you begin

Review the following requirements:

The 2018 Developer Portal subsystem must be configured with either SFTP or S3 backups.
All portal-www and portal-db pods must be up and ready. If they are not, the upgrade will not proceed.
The environment must have enough storage space to accommodate the v10 PVCs.

If applicable, take the following optional steps:

Optional:
The portal subsystem upgrade is based around the backup and restore of the portal. All INSTALLED sites at the time of triggering the upgrade will be backed up. You can confirm the list of sites that will be backed up and subsequently upgraded by running the following command against one of the 2018 Portal www pods:
```
kubectl exec -it <portal_www_pod_name> -c admin  -n <namespace> -- /opt/ibm/bin/list_sites -p
```
Optional: Make a note of the site name of any essential sites that you want to ensure are upgraded first. To view the site names:
```
kubectl exec -it <portal_www_pod_name> -c admin  -n <namespace> -- /opt/ibm/bin/list_sites -p
```
You can provide these site names when creating the portal upgrade CR (see step 2 of the upgrade procedure), to ensure they are queued for upgrade in the order provided, before any remaining sites found in the specified backup location.

Important:

The length of time it takes for the Portal subsystem upgrade to complete is directly related to the number of sites that are present in the portal. The more sites, the longer it takes. It is recommended that any non essential sites (especially those without any customizations) be removed prior to starting the upgrade and recreated once the upgrade has completed.
Ensure that the specified backup location does not contain any old backups of portal sites that have subsequently been deleted. The upgrade procedure will restore (and upgrade) the backup for all sites found in the backup location. The backup location should only contain backups of the sites present and configured in API Manager at the time the upgrade is to take place.

About this task

The Portal upgrade procedure is primarily based around backing up a 2018 Portal subsystem and restoring it onto a newly deployed version 10 Portal cluster.

The steps which the operator goes through to upgrade the portal subsystem are as follows:

Upgrade initialization
Take a backup of the 2018 portal subsystem
Freeze the 2018 portal-www and portal-db pods
Create the 10 portal cluster CR.
Create a v10 portal restore CR to restore the 2018 portal backup onto the 10 portal subsystem and upgrade each portal site
Remove the 2018 portal subsystem resources
Set the Complete status condition of the portal upgrade CR to true.

To upgrade the Portal from 2018 to 10, complete the following steps:

Procedure

Verify that all prerequisites have been met:
- The Portal upgrade CR template file portal.apiconnect.ibm.com_v1beta1_upgradefromv2018_cr.yaml has been obtained from the API Connect upgrade helper_files.zip in IBM® API Connect <version> Operator Upgrade Release Files for Containers. See Installing the files for upgrade from 2018 .
- The apiconnect operator and apiconnect upgrade operator are installed and running: Upgrading from 2018 to 10.0.5.4 on Kubernetes
- The Management subsystem upgrade is complete: Upgrading the Management subsystem from 2018 to v10
- All of the Portal prerequisites have been met: Before you begin

Populate the template upgrade CR for Portal portal.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: `ptl`
`$PORTAL_SUBSYSTEM_NAME`	Must match the v2018's portal 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` Note: The value of the `subsystemName` property must match the name of your v2018 portal subsystem. You can also specify the optional `siteName` property in the `portalSpec` section to define the site name given to the v10 cluster.
`$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 portal subsystem rollback.
`$SITEURL1 - $SITEURL2 - $SITEURL3`	`PriorityList:` entries prioritize the restore of any sites listed in the order in which they are provided. They will be queued for restore first, followed by any remaining sites present in the backup location. This is an optional property that can be omitted if the order of site restore or upgrades is not important. To obtain the site names, see Before you begin
`$IMAGE_REGISTRY`	Provide valid image registry to access the upgrade and version 10 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 the deployment profile, see Planning your deployment topology.
`$STORAGE_CLASS_NAME`	Storage class name must be provided for all Volume templates. The `default-class-name` will be used only if cluster's default-class-name has been set.
`$VOLUME_SIZE`	`databaseVolumeClaimTemplate:` - Minimum size of 15Gi for Dev Profile and 30Gi for Prod. Adjust the size of the PVC according to the number of portal sites required `databaseLogsVolumeClaimTemplate:` - Minimum size of 6Gi for Dev Profile and 12Gi for Prod. `webVolumeClaimTemplate:` - Minimum size of 8Gi for Dev Profile and 12Gi for Prod. Adjust the size of the PVC according to the number of portal sites required. `backupVolumeClaimTemplate:` - Minimum size of 15Gi for Dev Profile and 30Gi for Prod. Adjust the size of the PVC according to the number of portal sites required. `adminVolumeClaimTemplate:` - Minimum size of 6Gi for Dev Profile and 12Gi for Prod. `certVolumeClaimTemplate:` - 4Gi is the recommended size for this template. Increasing this size does not provide any benefit.

Note: Note: The PVC sizes of your existing 2018 deployment should be specified in the first instance.

The PVC sizes allocated may need to be adjusted further (beyond the minimum and existing 2018 values) depending on the number and content of the sites required.

The minimum PVC sizes are large enough to cater for a small number of portal sites. As a rough estimate, for every 10 additional small portal sites (with a limited number of apps, apis, consumer orgs, members and portal content) the amount of space allocated should be increased in line with the following estimates:

databaseVolumeClaimTemplate: +10 Gi
webVolumeClaimTemplate: +1 Gi
backupVolumeClaimTemplate: +2 Gi

If you have sites that have a lot of provider org content and lots of documentation, images, and additional content stored in the portal, then you may require a lot more space to be allocated to your PVCs. The following 2 PVCs do not need to be scaled based on the number of sites:

databaseLogsVolumeClaimTemplate
adminVolumeClaimTemplate

Edit the license: setting:

Set accept: to true to accept the license. Note that the default value is false. If you do not accept the license, the Operator will not install the subsystem.
Set use: to either production or nonproduction, to match the license you purchased.
Set license: to the License ID for the version of API Connect that you purchased. See API Connect licenses.

Example entry to accept the license for a production system:

  license:
    accept: true
    use: production
    license: L-RJON-CEBLEH

Example CR:

 	apiVersion: portal.apiconnect.ibm.com/v1beta1
 	kind: PortalUpgradeFromV2018
 	metadata:
 	  name: ptl 
 	spec:
 	  subsystemName: ptl 
 	  triggerRollback: false

 	  imageRegistry: apic-dev-docker-local.artifactory.swg-devops.com
 	  imagePullSecrets:
 	    - apic-registry-secret
 	  profile: n3xc4.m8
 	  license: 
 	    accept: true
 	    use: production
 	    license: 'L-RJON-CEBLEH' # Refer license document https://ibm.biz/apiclicenses
 	  certManagerIssuer:
 	    name: selfsigning-issuer
 	    kind: Issuer

 	  portalSpec:
 	    databaseVolumeClaimTemplate:
 	      storageClassName: local-storage
 	      volumeSize: 30Gi
 	    databaseLogsVolumeClaimTemplate:
 	      storageClassName: local-storage
 	      volumeSize: 12Gi
 	    webVolumeClaimTemplate:
 	      storageClassName: local-storage
 	      volumeSize: 12Gi
 	    backupVolumeClaimTemplate:
 	      storageClassName: local-storage
 	      volumeSize: 30Gi
 	    adminVolumeClaimTemplate:
 	      storageClassName: local-storage
 	      volumeSize: 12Gi
 	    certVolumeClaimTemplate:
 	      storageClassName: local-storage
 	      volumeSize: 4Gi

Apply the portal upgrade from the 2018 CR:

kubectl apply -f portal.apiconnect.ibm.com_v1beta1_upgradefromv2018_cr.yaml -n <namespace>

Monitor the progression of the upgrade CR:
- Check the current state of the upgrade CR itself:
```
kubectl get up2018p -n <namespace>
```
- Monitor the activity of the upgrade by tailing the apiconnect-upgrade-operator pod logs:
```
kubectl logs -f <apiconnect-upgrade-operator-pod-name>
```
Upon completion the upgrade CR will display the status condition Complete.
Verify the state of your portal sites once the portal upgradefromv2018 has completed:
Run the list_sites command against one of the version 10 www pod admin containers
```
kubectll exec -it <v10_portal_www_pod_name> -c admin -n <namespace> -- /opt/ibm/bin/list_sites -p
```
You should see all sites installed. If you have a large number of sites then some may show as out of sync. Note that it can take a short while for API Manager to serve the snapshot requests for all sites, and for the portal to process them all.
Note: With the upgrade to version 10, the developer portal has had a major update to its look and appearance. This might require you to make some additional updates to pre-existing themes. Changes include:
- Forms such as Sign up and login are updated.
- The subscription wizard is refreshed.
- New styling for hovering on navigation bars.
- New concepts such as ghost and tertiary buttons.
If any sites have not successfully been installed then check the portal-www logs for more information. See:
- Rolling back Developer Portal to v2018
- Troubleshooting Portal subsystem upgrade from v2018 to v10
Retain the Portal subsystem encryption secret in a safe location, in case you need to restore the Portal subsystem during a disaster recovery scenario.

The encryption secret is created when the Portal subsystem is initially deployed. You can obtain the name of the encryption secret from the Portal subsystem custom resource once the installation is complete. For example:
1. Obtain the name of the encryptionSecret:
```
kubectl get ptl portal -o yaml | grep encryptionSecret
encryptionSecret: portal-enc-key
```
  The name of encryption secret is portal-enc-key.
2. Save the secret yaml in a safe location:
```
kubectl get secret portal-enc-key -o yaml > portal-enc-key.yaml
```
Next upgrade the Analytics subsystem. Continue with Upgrading the Analytics subsystem from v2018 to v10.

If your deployment does not use Analytics, continue with Upgrading the gateway subsystem from 2018 to v10.