Skip to main contentIBM DataPower Operator Documentation

Migrating to containers

This guide provides steps to migrate an existing IBM DataPower Gateway (physical / virtual) to a container-based deployment utilizing the IBM DataPower Operator.

Prepare for your migration

This guide assumes that you have already installed IBM DataPower Operator; if you have not, see Getting Started.

Additionally, ensure that you have:

Migrate

Overview

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

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

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 Kuberetes / OpenShift cluster

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

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

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.

  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

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

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

  3. 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
  4. 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 apply -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.

Modernize

Now that you have successfully migrated an existing IBM DataPower Gateway workload to Kubernetes / OpenShift leveraging the IBM DataPower Operator, you can begin leveraging features that modernize your deployment.

  • Automatically scale your IBM DataPower Gateway pods horizontally or vertically using Pod Auto-Scaling.
  • Learn how the IBM DataPower Operator manages IBM DataPower Gateway upgrades in Operand Upgrades.
  • Fine-tune your topology and scheduling of IBM DataPower Gateway pods using affinity, tolerations, and nodeSelector properties in the DataPowerService custom resource.
  • Check out our release notes for the latest details on features and changes within the IBM DataPower Operator.