migrate-ldap

Migrate LDAP configuration and user information from the Cloud Pak for Data LDAP identity provider to the IAM Service.

Extended description

The migration utility uses the specified LDAP directory type to migrate the Cloud Pak for Data LDAP database and configuration and construct the appropriate LDAP configuration mappings over to the IAM Service. You can select a custom LDAP directory type to use for LDAP mapping. The default "Custom" settings might not work for all migrations. You can specify a custom filters *.json file (--filters=<json-file-path>) that defines LDAP search filters to use during migration.

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

Prerequisites

  1. Before you run any cpd-cli commands, ensure that you downloaded the cpd-cli 12.0.6 command line utility for your operating system and Cloud Pak for Data edition from: https://github.com/IBM/cpd-cli/releases.

  2. Pre-migration: A Cloud Pak for Data 3.5 or 4.x installation without IAM integration (iamIntegration:false) and LDAP enabled (with existing LDAP users).
  3. Upgrade to a Cloud Pak for Data 4.x deployment, install IBM Cloud Pak® foundational services, and enable IAM integration (iamIntegration:true).

For more information, see Migrating LDAP information from Cloud Pak for Data to IAM.

Important: If you have multiple Cloud Pak for Data namespaces, all namespaces must migrate to the IAM Service. Run the migration only one time when all Cloud Pak for Data namespaces share identical LDAP server configuration and users.

Required permissions

The migrate-ldap command requires cluster administrator or similar roles.

Commands

Option Description
version Display the migrate-ldap command version information.

Syntax

cpd-cli migrate-ldap \
--namespace=<namespace-name> \
[--arch=<system-cpu-architecture>] \
[--filters=<json-file-path>] \
[--image-prefix=${PRIVATE_REGISTRY_LOCATION}] \
[--ldaptype=1|2|3|4|5|6|7|8] \
[--verbose]

Arguments

The migrate-ldap command has no arguments.

Options

Option Description
--arch Provide the system architecture.
Status
Optional.
Syntax
--arch=<system-cpu-architecture>
Default value
x86_64
Valid values
x86_64
The 64-bit version of the x86 instruction set architecture.
ppc64le
The little-endian variant of the PowerPC 64-bit architecture.

--filters

-f

 Specify a custom filters *.json file path. The default filters work for most cases.
Status
Optional.
Syntax
--filters=<json-file-path>
Default value
No default.
Valid values
A valid *.json file path. The following example provides typical filter formatting.
{
   "Custom": {
      "LDAP_USERFILTER": "(&(%s=%%v)(objectclass=ePerson))",
      "LDAP_GROUPFILTER": "(&(%s=%%v)(objectclass=groupOfUniqueNames))",
      "LDAP_USERIDMAP": "*:%s",
      "LDAP_GROUPIDMAP": "*:%s",
      "LDAP_GROUPMEMBERIDMAP": "groupOfUniqueNames:%s"
   }
}
The objectclass sections are customizable; the other strings are part of the template and must be left as is. In most cases, the defaults settings work. Editing the objectclass sections is only needed when special extended schema is used.

--help

-h

 Display command help.
Status
Optional.
Syntax
--help
Default value
No default.
Valid values
Not applicable.

--image-prefix

-i

 The private registry image prefix for migrating the job image.
Status
Optional.
Syntax
--image-prefix=${PRIVATE_REGISTRY_LOCATION}
Default value
No default.
Valid values
Any valid private registry image prefix.

--ldaptype

-t

 Specify an LDAP directory type.
Status
Optional.
Syntax
--ldaptype=1|2|3|4|5|6|7|8
Default value
8. Custom
Valid values

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

--namespace

-n

 The namespace name in which the utility should operate.
Status
Optional.
Syntax
--namespace=<namespace-name>
Default value
${PROJECT_CPD_INSTANCE}
Valid values
A valid project (namespace) name.
--verbose Logs include more detailed messages.
Status
Optional.
Syntax
--verbose
Default value
No default.
Valid values
Not applicable.

Examples

Note: The following examples use the recommended installation environment variables.

Use a script to create environment variables with the correct values for your environment. For more information, see Best practice: Setting up install variables.

Use the Microsoft Active Directory LDAP directory type (--ldaptype=7) for configuration mapping when you migrate from ${PROJECT_CPD_INSTANCE} Cloud Pak for Data LDAP to the IAM Service.
cpd-cli migrate-ldap \
--namespace=${PROJECT_CPD_INSTANCE} \
--ldaptype=7