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