Upgrading the Developer Portal subsystem from 2018 to 10.0.1.x-eus

You can upgrade the Developer Portal subsystem from 2018 to the latest version of 10.0.1.x-eus.

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:

  1. Optional task:

    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
  2. 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.

  • 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:

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

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


  1. Verify that all prerequisites have been met:
  2. 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.
    - $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 mode of the v10 installation to upgrade to. Takes n1xc2.m8 for dev or n3xc4.m8 for production setup of version 10.
    $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 templates. The default-class-name will be used only if cluster's default-class-name has been set.
    • 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

    For example:

    apiVersion: portal.apiconnect.ibm.com/v1beta1
    kind: PortalUpgradeFromV2018
      name: ptl
      subsystemName: ptl
      triggerRollback: false
        - important-site.com
        - less-important-site.com
      imageRegistry: <your_registry_url>
      - <your_image_pull_secret>
      profile: n1xc2.m8
        accept: true
        use: production
        name: selfsigning-issuer
        kind: Issuer
          storageClassName: local-storage
          volumeSize: 15Gi
          storageClassName: local-storage
          volumeSize: 6Gi
          storageClassName: local-storage
          volumeSize: 10Gi
          storageClassName: local-storage
          volumeSize: 15Gi
          storageClassName: local-storage
          volumeSize: 10Gi
          storageClassName: local-storage
          volumeSize: 4Gi
  3. Apply the portal upgrade from the 2018 CR:
    kubectl apply -f portal.apiconnect.ibm.com_v1beta1_upgradefromv2018_cr.yaml -n <namespace>
  4. Monitor the progression of the upgrade CR:
    • Check the current state of the upgrade CR itself:
      kubectl describe portal.apiconnect.ibm.com_v1beta1_upgradefromv2018_cr.yaml <name> -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.

  5. 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:

  6. We highly recommend that you 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
  7. Next upgrade the Analytics subsystem. Continue with Upgrading the Analytics subsystem from v2018 to 10.0.1.x-eus.

    If your deployment does not use Analytics, continue with Upgrading the gateway subsystem from 2018 to 10.0.1.x-eus.