Migrating your LDAP configuration to the IAM Service

If you have an existing Cloud Pak for Data LDAP configuration but you want to use the Identity and Access Management Service (IAM Service), you can use the Cloud Pak for Data LDAP migration utility (cpd-cli migrate-ldap) to migrate your Cloud Pak for Data LDAP configuration and user information to the IAM Service.

4.5.2 or later This feature is available only if you are running IBM® Cloud Pak for Data 4.5.2 or later.

Important: The IAM Service might not be right for your environment. Before you start to use the IAM Service, review the benefits and drawbacks in Integrating with the IAM Service.

Permissions you need for this task: To complete this task, you must be an administrator of the project (namespace) where Cloud Pak for Data is installed.
When you need to complete this task: If you have an existing Cloud Pak for Data LDAP configuration but you want to use the IAM Service to manage users, you must migrate your existing LDAP configuration to the IAM Service.

Before you begin

Best practice: You can run many of the commands in this task exactly as written if you set up environment variables for your installation. For instructions, see Setting up installation environment variables.

Ensure that you source the environment variables before you run the commands in this task.

The workstation from which you run the commands must be set up as a client workstation with the following command-line interfaces:
1. Cloud Pak for Data CLI: cpd-cli
2. OpenShift® CLI: oc
For more information, see Setting up a client workstation.
Enable IAM integration (iamIntegration:true) by completing the steps in Integrating with the IAM Service.

About this task

At a minimum, you must run the migration job for each LDAP server that you want to migrate to the IAM Service. However, there might be some situations where you need to run the migration job multiple times even if multiple instances of Cloud Pak for Data are connected to the same LDAP server. Use the following examples to help you determine when you need to run the LDAP migration:

You have 2 instances of Cloud Pak for Data, and each instance of Cloud Pak for Data is connected to a different LDAP server, run the migration job twice. (One time against each instance).
You have 2 instance of Cloud Pak for Data, and both instances of Cloud Pak for Data are connected to the same LDAP server:
- If both of the instances have the same users, groups, and roles, run the migration job once.
  It doesn't matter which instance you run the migration job against.
- If you want to migrate the users, groups, and roles that are associated with only one of the instances of Cloud Pak for Data, run the migration job once.
  Ensure that you specify the correct instance with the ${PROJECT_CPD_INSTANCE} environment variable.
- If each instance has different users, groups, or roles, run the migration job twice. (One time against each instance).

Procedure

If your cluster pulls images from a private container registry, complete the appropriate task to mirror the LDAP migration image to your private container registry.
The workstation can connect to the internet and to the private container registry
1. Set the DOCKER_EXE environment variable based on the client runtime on the workstation.
  - For Docker:
    export DOCKER_EXE=docker
  - For Podman:
    export DOCKER_EXE=podman
2. Set the ARCH environment variable based on the architecture of your cluster.
  - For x86_64 clusters:
    export ARCH=amd64
  - For s390x clusters:
    export ARCH=s390x
  - For ppc64le clusters:
    export ARCH=ppc64le
3. Source your installation environment variable script. For example,
```
source ./cpd_vars.sh
```
4. Set the following environment variables.
```
export SOURCE_REGISTRY=icr.io/cpopen/cpd
export MIGRATION_IMAGE=${SOURCE_REGISTRY}/zen-ldapmigrate:latest-${ARCH}
export MIRRORED_IMAGE=${PRIVATE_REGISTRY_LOCATION}/zen-ldapmigrate:latest-${ARCH}
```
5. Pull the image for the LDAP migration job from the IBM Entitled Registry:
```
${DOCKER_EXE} pull ${MIGRATION_IMAGE}
```
6. Push the image to the private container registry:
```
${DOCKER_EXE} login -u ${PRIVATE_REGISTRY_PUSH_USER} -p ${PRIVATE_REGISTRY_PUSH_PASSWORD} ${PRIVATE_REGISTRY_LOCATION} 
${DOCKER_EXE} tag ${MIGRATION_IMAGE} ${MIRRORED_IMAGE}
${DOCKER_EXE} push ${MIRRORED_IMAGE}
```
The workstation cannot connect to the internet and the private container registry at the same time
1. Complete the following steps on the client workstation that is connected to the internet:
  1. Set the DOCKER_EXE environment variable based on the client runtime on the workstation.
    
    For Docker:
    export DOCKER_EXE=docker
    
    For Podman:
    export DOCKER_EXE=podman
  2. Set the ARCH environment variable based on the architecture of your cluster.
    
    For x86_64 clusters:
    export ARCH=amd64
    
    For s390x clusters:
    export ARCH=s390x
    
    For ppc64le clusters:
    export ARCH=ppc64le
  3. Source your installation environment variable script. For example,
    source ./cpd_vars.sh
  4. Set the following environment variables.
    export SOURCE_REGISTRY=icr.io/cpopen/cpd export MIGRATION_IMAGE=${SOURCE_REGISTRY}/zen-ldapmigrate:latest-${ARCH} export MIRRORED_IMAGE=${PRIVATE_REGISTRY_LOCATION}/zen-ldapmigrate:latest-${ARCH}
  5. Pull the image for the LDAP migration job from the IBM Entitled Registry:
    ${DOCKER_EXE} pull ${MIGRATION_IMAGE}
  6. Save the image to a compressed file:
    ${DOCKER_EXE} save ${MIGRATION_IMAGE} | gzip > cpd-cli-workspace/olm-utils-workspace/work/offline/migration_image.tar.gz
2. Transfer the image to a workstation that can connect to the private container registry.
3. Complete the following steps on the client workstation that is connected to the private container registry:
  1. Set the DOCKER_EXE environment variable based on the client runtime on the workstation.
    
    For Docker:
    export DOCKER_EXE=docker
    
    For Podman:
    export DOCKER_EXE=podman
  2. Set the ARCH environment variable based on the architecture of your cluster.
    
    For x86_64 clusters:
    export ARCH=amd64
    
    For s390x clusters:
    export ARCH=s390x
    
    For ppc64le clusters:
    export ARCH=ppc64le
  3. Source your installation environment variable script. For example,
    source ./cpd_vars.sh
  4. Set the following environment variables.
    export SOURCE_REGISTRY=icr.io/cpopen/cpd export MIGRATION_IMAGE=${SOURCE_REGISTRY}/zen-ldapmigrate:latest-${ARCH} export MIRRORED_IMAGE=${PRIVATE_REGISTRY_LOCATION}/zen-ldapmigrate:latest-${ARCH}
  5. Load the image to the container runtime on the workstation:
    ${DOCKER_EXE} load -i cpd-cli-workspace/olm-utils-workspace/work/offline/migration_image.tar.gz
  6. Confirm that the image is available in the container runtime:
    ${DOCKER_EXE} images icr.io/cpopen/cpd/zen-ldapmigrate:latest-${ARCH}
    If the image is available, the command returns output with the following format:
    REPOSITORY TAG IMAGE ID CREATED SIZE icr.io/cpopen/cpd/zen-ldapmigrate latest-arch XXXXXXXXXXXX XXXXXX XXXMB
  7. Push the image to the private container registry:
    ${DOCKER_EXE} login -u ${PRIVATE_REGISTRY_PUSH_USER} -p ${PRIVATE_REGISTRY_PUSH_PASSWORD} ${PRIVATE_REGISTRY_LOCATION} ${DOCKER_EXE} tag ${MIGRATION_IMAGE} ${MIRRORED_IMAGE} ${DOCKER_EXE} push ${MIRRORED_IMAGE}

Set the LDAP_TYPE environment variable to the appropriate value for your environment.

export LDAP_TYPE=<ldap-type-number>

The following LDAP types are supported.

LDAP type number	Description
1	IBM Tivoli Directory Server
2	IBM Lotus Domino
3	IBM SecureWay Directory Server
4	Novell eDirectory
5	Sun Java™ System Directory Server
6	Netscape Directory Server
7	Microsoft Active Directory
8	Custom

For example, if you use Microsoft Active Directory, run:

export LDAP_TYPE=7

Run the cpd-cli manage login-to-ocp command to log in to the cluster as a user with sufficient permissions to complete this task. For example:
```
cpd-cli manage login-to-ocp \
--username=${OCP_USERNAME} \
--password=${OCP_PASSWORD} \
--server=${OCP_URL}
```
Tip: The login-to-ocp command takes the same input as the oc login command. Run oc login --help for details.

Run the

cpd-cli
migrate-ldap

command.

Clusters that pull images from a private container registry

cpd-cli migrate-ldap \
--namespace=${PROJECT_CPD_INSTANCE} \
--ldaptype=${LDAP_TYPE} \
--image-prefix=${PRIVATE_REGISTRY_LOCATION}

Clusters that pull images directly from the IBM Entitled Registry

cpd-cli migrate-ldap \
--namespace=${PROJECT_CPD_INSTANCE} \
--ldaptype=${LDAP_TYPE}

What to do next

After migration, Cloud Pak for Data users are managed by the IAM Service.