Migrating to containers

Overview

Follow the steps below to migrate your IBM DataPower Gateway to an IBM DataPower Operator managed deployment:

• Migrating to containers
  • Prepare for your migration
  • Migrate
    • Overview
    • Backing up your existing IBM DataPower Gateway deployment
    • Generating ConfigMap YAMLs for application domains
    • Creating ConfigMaps in your Kubernetes / OpenShift cluster
    • Creating Secrets in your Kubernetes / OpenShift cluster
    • Creating an admin user credential
    • Building the DataPowerService resource spec
    • Deploying the DataPowerService resource
  • Modernize

Backing up your existing IBM DataPower Gateway deployment

1. Log in to your existing IBM DataPower Gateway WebGUI as the admin user.
2. From the default domain, select Export Configuration 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.

Generating ConfigMap YAMLs for application domains

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

   For details on the script's invocation, see ./migrate-backup.sh --help.

2. Run the script against your backup ZIP.

   ./migrate-backup.sh backup.zip
   

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

Creating ConfigMaps in your Kubernetes / OpenShift cluster

In the appropriate Kubernetes namespace or OpenShift project, apply the generated YAML for each domain that you wish to migrate.

Note: The below examples use oc CLI as example (for OpenShift), Kubernetes users should substitute kubectl where appropriate, and make sure to use -n namespace to specify the target namespace for resource creation.

Note: These ConfigMaps will be used later in Building the DataPowerService resource spec.

1. (OpenShift only) 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 create -f domain-cfg.yaml
   oc create -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 create -f $yaml
   done
   

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

   oc get configmap
   

Creating Secrets in your Kubernetes / OpenShift cluster

The TLS keys and certificates used by your IBM DataPower Gateway services must be stored in Kubernetes Secrets.

Note: These Secrets will be used later in Building the DataPowerService resource spec.

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

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

Creating an admin user credential

Following security best-practices, the IBM DataPower Gateway admin user credentials are stored in a Kubernetes Secret.

Create the Secret using oc (or kubectl for Kubernetes), 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 above command, admin-credentials is the name of the Secret, and admin is the password.

Building the DataPowerService resource spec

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.0-cd
     license:
       accept: true
       use: production
       license: L-RJON-BYDR3Q
   

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 containing 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 above 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.

Deploying the DataPowerService resource

1. Create the DataPowerService resource in the cluster.

   oc create -f migration-example.yaml
   

   For Kubernetes users, where namespace is your desired namespace:

   kubectl -n namespace -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
   

   For Kubernetes users:

   # full view
   kubectl -n namespace get all
   
   # just the DataPowerService instance(s)
   kubectl -n namespace 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.