IBM DataPower Gateway transformation guide

Complete the following tasks to migrate your IBM DataPower Gateway deployment to Cloud Pak for Integration:

• Backing up your existing IBM DataPower Gateway deployment - Extract the IBM DataPower Gateway configuration from an existing physical or virtual appliance in the form of a Backup archive.

• Generating ConfigMap YAMLs for application domains - Format the configuration for deployment in Kubernetes.

• Creating ConfigMaps in OpenShift cluster - Migrate your standard IBM DataPower Gateway configuration (*.cfg files) and files in the local:/// filesystem to ConfigMaps in Kubernetes.

• Creating Kubernetes Secrets in your OpenShift cluster - Create various crypto & TLS material needed by your IBM DataPower Gateway service configurations.

• Creating an admin user credential - Create Gateway user credentials (for example, the admin password) and migrate to Secrets in Kubernetes.

• Building the DataPowerService resource spec - Create a DataPowerService resource spec to deploy the configuration, such that the resulting IBM DataPower Gateway pods are functionally equivalent to the source IBM DataPower Gateway.

• Deploying the DataPowerService resource - Deploying the DataPowerService custom resource in your cluster, completing the migration.

1. Log in to your existing IBM DataPower Gateway WebGUI as the admin user.

2. From the default domain, select Export Configration in the Control Panel.

3. Select either Create a backup of one or more application domains or Create a backup of the entire system, depending on how many domains you intend to migrate.

4. Follow the system prompts.

5. Once complete, download the backup ZIP.

1. Download the migrate-backup.sh script.

   This script is designed to automatically generate the ConfigMaps for each application domain from an IBM DataPower Gateway backup:

   • ConfigMap YAML for each domain cfg file

   • ConfigMap YAML for each domain's local:/// file system

2. Run the script against your backup ZIP.

   ./migrate-backup.sh backup.zip

   If you only wish to migrate a single domain, specify the -d or --domain argument. For example:

   ./migrate-backup.sh --domain test backup.zip

3. Inspect the generated output for details on where output files are generated, for example,

   YAML will be generated in: backup-output

4. Review the generated YAML files.

   • Files ending in -cfg.yaml contain the domain's configuration in cfg format.

   • Files ending in -local.yaml contain the domain's local:/// file system, in .tar.gz format.

   You apply the YAML (both formats) in the next step.

In the appropriate OpenShift project (namespace), apply the generated YAML for each domain that you wish to migrate. These ConfigMaps will be used later in Building the DataPowerService resource spec.

1. Using your oc CLI, switch to the project (namespace) you wish to deploy the migrated IBM DataPower Gateway.

   oc project <namespace>

2. Apply the generated YAML files. Be sure to apply all YAML files for each domain you wish to migrate.

   Example of single domain with a cfg and local YAML each:

   cd backup-output
   oc apply -f domain-cfg.yaml
   oc apply -f domain-local.yaml

   Example using bash scripting to apply all YAMLs from the backup at once:

   for yaml in $(find backup-output -name '*.yaml'); do
       oc apply -f $yaml
   done

3. Once the YAML is applied, check the cluster to ensure that everything looks correct:

   oc get configmap

The TLS keys and certificates used by your IBM DataPower Gateway services must be stored in Kubernetes secrets. These secrets will be used later in Building the DataPowerService resource spec.

1. Gather the keys and certificates you wish to use.

   Note: You cannot export the private keys from an existing physical or virtual appliance.

2. For each key/cert pair or set of crypto, create a Secret with an appropriate name to reference later:

   oc create secret tls <my-tls-secret> --key=/path/to/my.crt --cert=/path/to/my.key

   or for generic (non-TLS) crypto:

   oc create secret generic <my-crypto-secret> --from-file=/path/to/cert --from-file=/path/to/key

   Refer to the Kubernetes documentation for details on the differences among Secrets.

Following security best-practices, the admin user credentials are stored in a Kubernetes secret.

Create the secret using oc, specifying the password via CLI, and noting the name of the Secret as you will need this later:

oc create secret generic admin-credentials --from-literal=password=admin

Example: In the preceding command, admin-credentials is the name of the Secret, and admin is the password.

Recommended: Open our DataPowerService API docs for reference as you build your custom resource spec.

1. Open your editor of choice, and start with the following template:

   apiVersion: datapower.ibm.com/v1beta3
   kind: DataPowerService
   metadata:
     name: migration-example
   spec:
     replicas: 1
     version: 10.5-lts
     license:
       accept: true
       use: production
       license: L-RJON-CCAT5F

2. Edit the spec.version and spec.license to choose your desired firmware version and edition.

   • Refer to our Licenses guide for appropriate values for spec.license.license and how they map to the spec.version and spec.license.use.

   • Refer to the spec.license and spec.version API docs for details on these fields.

3. Add a spec.users definition for your admin user, using the Secret name (admin-credentials) created in the Create an admin user credential step for the value of passwordSecret. See the spec.users API docs for details.

   For example:

   users:
   - name: admin
     accessLevel: privileged
     passwordSecret: admin-credentials

4. Add a spec.domains definition, with an entry for each application domain you wish to deploy.

   For reference, see the Domain configuration guide.

   As an example, let's assume a domain name of example. Let's also assume that we created example-cfg and example-local ConfigMaps for this domain, containing its configuration and local:/// file system respectively. The spec.domains definition would be:

   domains:
   - name: example
     dpApp:
       config:
       - example-cfg
       local:
       - example-local

   Next, update the domain object to include any certs definitions, referencing the Secrets you created in an earlier step containg TLS or other crypto material.

   As an example, let's assume we created a Secret named example-service which contains a TLS key/cert pair for a service defined in this example application domain. The amended domains spec would be:

   domains:
   - name: example
     certs:
     - certType: usrcerts
       secret: example-service
     dpApp:
       config:
       - example-cfg
       local:
       - example-local

   Repeat the full procedure in this step for each application domain you wish to deploy.

5. You should now have a complete DataPowerService definition. Putting the preceding examples together would give us:

   apiVersion: datapower.ibm.com/v1beta3
   kind: DataPowerService
   metadata:
     name: migration-example
   spec:
     replicas: 1
     version: 10.0-cd
     license:
       accept: true
       use: production
       license: L-RJON-BYDR3Q
     users:
     - name: admin
       accessLevel: privileged
       passwordSecret: admin-credentials
     domains:
     - name: example
       certs:
       - certType: usrcerts
         secret: example-service
       dpApp:
         config:
         - example-cfg
         local:
         - example-local

6. Save the YAML to a file of your choosing. For subsequent examples, we'll use migration-example.yaml.

1. Create the DataPowerService resource in the cluster.

   oc apply -f migration-example.yaml

2. Check the status of the deployment to ensure successful migration.

   # full view
   oc get all
   
   # just the DataPowerService instance(s)
   oc get dp

   Refer to our guide on operand status for more information.

3. If the DataPowerService is operational and Ready, continue on to modernizing your IBM DataPower Gateway workloads.