Migrating from v2018 to v10

This migration document assumes that a user has all v10 resources ready to deploy. Specifically, it assumes the following prerequistes:

To perform a side-by-side migration from Helm managed v2018 to Operator managed v10, you must bridge the gap with “migration labels.” These labels will be used to connect the v2018 and v10 Pods to the same API traffic via the relevant Services while scaling operations are performed. To add the label, you can edit the Deployment or StatefulSet directly:

Where v2018-ibm-datapower-dev is the name of your v2018 Deployment.

The labels section of your Deployment yaml should look similar to:

You will now add a label, v2018.v10.datapower.migration: <release-name> where <release-name> is the name of this release. This new label will be the intermediary Selector for the Services handling your traffic. The purpose of <release-name> is to ensure uniqueness so that your Service doesn’t send traffic to another Deployment with an on-going migration. Using the above example labels, your new label set should look like:

Now save and exit your editor, which should prompt an update of the v2018 Deployment. This will cause a Rolling Update (default) and you should wait until all pods are back up before proceeding to the next step.

Now we need to install the v10 StatefulSet. A prerequisite for this guide is to have built a DataPowerService CustomResource yaml that configures the same APIs as your v2018 deployment. Before installing this custom resource, you need to add the “migration labels” to it. To do so, add the following to your custom resource yaml:

With the migration label in place, install the DataPowerService resource.

Wait for a minute for the Pods to come up. Once up, you can inspect the labels.

The labels on the v10 pod should resemble:

Note that now you have a common label on both v2018 and v10 Pods. This allows us to edit any Service objects to send traffic to both sets of Pods.

With the labels in place, it’s time to edit the relevant service(s) to Select using the “migration label” instead of previous Selectors.

In your editor, you can find the below selector section.

This selector will need to change to the migration label:

Save and exit the editor. The Service will now be pointing at both the v2018 and v10 Pods.

With the traffic handling Service pointing at both v10 and v2018 pods, you can now safely scale down v2018 while scaling up v10.

To scale down v2018, edit the Deployment/Statefulset and decrease the spec.replicas by 1.

To scale up v10, edit the DataPowerService resource and increase the spec.replicas by 1.

Continue to scale down v2018 and scale up v10 until there are no more v2018 Pods. Between each iteration, wait for the new v10 pod to become Ready.

If ability to Rollback isn’t required, you can delete the Helm installation at this stage.

With the v2018 deployment fully scaled down, you can change the Service selectors to be v10 specific.

Your updated selector labels should look something like:

If desired, clean up the v10 StatefulSet by removing the custom migration label from the Custom Resource.