Migrating users and groups (IBM Knowledge Catalog)

Important: IBM Cloud Pak® for Data Version 4.8 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.8 reaches end of support. For more information, see Upgrading from IBM Cloud Pak for Data Version 4.8 to IBM Software Hub Version 5.1.

Before you migrate any connections, information and glossary assets, automated discovery information, and data quality project content, make sure that user information can be properly mapped.

Prerequisites

If the InfoSphere® Information Server system is configured to use an LDAP user registry, the system must be connected to the same LDAP server as the Cloud Pak for Data system.

Cloud Pak for Data must be configured to use the embedded LDAP integration. For more information, see Configuring Cloud Pak for Data to use the embedded LDAP integration.

If the InfoSphere Information Server system is set up with an internal user registry or a local operating-system user registry in the metadata repository, no additional configuration is required.

Procedure

To ensure that users have access to the migrated data in Cloud Pak for Data, create the appropriate Cloud Pak for Data user profiles. Map InfoSphere Information Server user information to the equivalent Cloud Pak for Data roles and permissions. For more information about role and permission mappings, see User role mapping.

To migrate users and groups, complete these steps as required for your setup:
  1. Evaluating whether users and groups can be exported from InfoSphere Information Server
  2. Exporting users and groups from InfoSphere Information Server
  3. Transferring the exported users and groups information to Cloud Pak for Data
  4. Importing users and groups to Cloud Pak for Data

If InfoSphere Information Server is set up with an internal or local operating-system user registry, a temporary password is created for each user in the legacy-migration-aux-exim-cm ConfigMap with the key migration-password. Provide your users with their Cloud Pak for Data username and the temporary password and have them verify that they can log in to Cloud Pak for Data.

Evaluating whether users and groups can be exported from InfoSphere Information Server

To evaluate whether the InfoSphere Information Server user and group configuration can be properly exported, run the export in inspect mode.

Follow the instructions for running the export in Exporting users and groups from InfoSphere Information Server. However, make sure to run the export command with the -inspect true option.

You can get to the resulting report as follows:
cat ${EXPORT_DATA_DIR}/${EXPORT_INSTANCE_NAME}/2*/legacy-migration/export-inspect-report.txt

Exporting users and groups from InfoSphere Information Server

Export the InfoSphere Information Server user and group configuration.

  1. In a new terminal, log in to InfoSphere Information Server as root.
    Note: If InfoSphere Information Server is on Windows, login to the standalone Red Hat® Enterprise Linux® machine as root.
  2. Change to the wkc user and open a bash shell:
    su wkc
bash
  3. Set environment variables for the following required parameters and change to the ${TOOLKIT_PATH} directory:
    TOOLKIT_PATH=<path to the directory where the toolkit was extracted (see Preparing for migration in InfoSphere Information Server)>
IIS_HOST=<IIS host>
IIS_PORT=<IIS port>
IIS_USERNAME=<IIS username>
IIS_PASSWORD=<IIS password>
EXPORT_INSTANCE_NAME=<name of the export instance>
NAMESPACE=<namespace in the target CP4D>
cd ${TOOLKIT_PATH}

    The export will fail if the export instance name doesn't follow the conventions.

  4. Set a valid existing directory as the target directory for the exported data. The wkc user must have write permission to this directory.
    EXPORT_DATA_DIR=<path to export data directory>
  5. Set the path to the toolkit directory.
    export PATH=${TOOLKIT_PATH}/jdk-17.0.9+9/bin:${TOOLKIT_PATH}:$PATH
  6. Run the export script.
    • To export the users and groups information from an LDAP user registry:
      ${TOOLKIT_PATH}/migration/iis_scripts/trigger_export_users_iis.sh -host ${IIS_HOST} -port ${IIS_PORT} -user ${IIS_USERNAME} -password ${IIS_PASSWORD} -export_instance_name ${EXPORT_INSTANCE_NAME} -namespace ${NAMESPACE} -dir ${EXPORT_DATA_DIR} -inspect false
    • To export the users and groups information from an internal user registry:
      ${TOOLKIT_PATH}/migration/iis_scripts/trigger_export_users_iis.sh -host ${IIS_HOST} -port ${IIS_PORT} -user ${IIS_USERNAME} -password ${IIS_PASSWORD} -export_instance_name ${EXPORT_INSTANCE_NAME} -namespace ${NAMESPACE} -dir ${EXPORT_DATA_DIR} -inspect false -ldapType no
  7. You can periodically check the progress of the export by looking at the status file in the ${EXPORTED_DATA_DIR} target directory in the following path:
    cat ${EXPORT_DATA_DIR}/${EXPORT_INSTANCE_NAME}/2*/legacy-migration/export-status.json
    After the export is complete, the export-status.json file contains a status: succeeded message. An example of the status message:
    {"status":"succeeded","startTime":1700040848,"completionTime":1700041206,"message":"export is successfully completed.","percentageCompleted":100}

After the export command completes, a .tar.gz file with the export instance name is created in the folder that you specified with the EXPORT_DATA_DIR parameter. The file name has the format cpd-exports-${EXPORT_INSTANCE_NAME}-*-data.tar.gz.

Transferring the exported users and groups information to Cloud Pak for Data

Copy the exported users and groups information to the Cloud Pak for Data system:
  1. Set the following environment variables:
    OCP_HOST=<ocp_host>
OCP_USERNAME=<username>
EXPORTED_DATA_TAR_GZ_FILE_PATH=${EXPORT_DATA_DIR}/cpd-exports-${EXPORT_INSTANCE_NAME}-*-data.tar.gz
  2. Copy the file with the exported users and groups information to Cloud Pak for Data:
    scp ${EXPORTED_DATA_TAR_GZ_FILE_PATH} ${OCP_USERNAME}@${OCP_HOST}:/tmp

Importing users and groups to Cloud Pak for Data

To import the InfoSphere Information Server users and groups information, complete these steps:
  1. Log in to Cloud Pak for Data as a user with the Red Hat OpenShift® Container Platform admin role.
  2. Set the following environment variables and change to the ${TOOLKIT_PATH} directory:
    TOOLKIT_PATH=<path to the folder where migration related files will be created>
CP4D_HOST=<cp4d host>
CP4D_USERNAME=<default platform administrator user: cpadmin or admin>
CP4D_PASSWORD=<cp4d password>
CP4D_APIKEY=<CP4D API key>
EXPORT_INSTANCE_NAME=<name of the export instance>
IMPORT_INSTANCE_NAME=<name of the import instance>
NAMESPACE=<namespace in the target CP4D>
PROFILE_NAME=<cpd-cli profile name in CP4D>
EXPORTED_DATA_TAR_FILE_PATH=/tmp/cpd-exports-${EXPORT_INSTANCE_NAME}-*-data.tar
cd ${TOOLKIT_PATH}
  3. Decompress the .tar.gz file in the /tmp directory that you copied from the InfoSphere Information Server system:
    gunzip ${EXPORTED_DATA_TAR_FILE_PATH}.gz
  4. Upload the resulting .tar file by using the following command:
    cpd-cli export-import export upload -f ${EXPORTED_DATA_TAR_FILE_PATH} --profile=${PROFILE_NAME}
  5. Generate a WKC_TOKEN value:
    WKC_TOKEN=`curl -i -s -k -X POST "https://${CP4D_HOST}/icp4d-api/v1/authorize" -H 'Accept: application/json' -H 'Content-Type: application/json' -d "{\"username\":\"${CP4D_USERNAME}\",\"api_key\":\"${CP4D_APIKEY}\"}" | grep '"token":' | grep -o '"token":\S*"' | awk -F , '{print$1}' | awk -F : '{print$2}' | tr -d '"'`
  6. Check whether the Identity Management Service is enabled in Cloud Pak for Data:
    oc get zenservice lite-cr -n ${NAMESPACE} -o jsonpath='{.spec.iamIntegration}'

    If the Identity Management Service is enabled, the command returns true. In this case, generate the following information:

    • A CP_CONSOLE_HOST value
      CP_CONSOLE_HOST=`oc get routes | grep "/v1/auth" | awk '{print $2}'`
    • A CP_USERNAME value
      CP_USERNAME=`oc get secret platform-auth-idp-credentials -n ${NAMESPACE} -o jsonpath='{.data.admin_username}' | base64 --decode`
    • A CP_PASSWORD value
      CP_PASSWORD=`oc get secret platform-auth-idp-credentials -n ${NAMESPACE} -o jsonpath='{.data.admin_password}' | base64 --decode`
    • An IDENTITY_TOKEN value
      IDENTITY_TOKEN=`curl -i -s -k -X POST "https://${CP_CONSOLE_HOST}/idprovider/v1/auth/identitytoken" -H 'Accept: application/json' -H 'Content-Type: application/json' -d "{\"username\":\"${CP_USERNAME}\",\"password\":\"${CP_PASSWORD}\",\"grant_type\": \"password\", \"scope\": \"openid\"}" | grep '"access_token":' | grep -o '"access_token":"[^"]*' | awk -F: '{print $2}' | tr -d '"'`
  7. To create an import_params.yaml file with the required information, copy the following code snippet to your command prompt and run it:
    cat <<EOF > ${TOOLKIT_PATH}/import_users_params.yaml
legacy-migration-aux:
 WKC_TOKEN: ${WKC_TOKEN}
 IDENTITY_TOKEN: ${IDENTITY_TOKEN}
 CP_CONSOLE_HOST: ${CP_CONSOLE_HOST}
EOF
  8. Start the import of the InfoSphere Information Server users and groups information by running the following command:
    cpd-cli export-import import create -n ${NAMESPACE} --from-export ${EXPORT_INSTANCE_NAME} --profile=${PROFILE_NAME} ${IMPORT_INSTANCE_NAME} -f ${TOOLKIT_PATH}/import_users_params.yaml --backoff-limit=0

    Optionally, you can capture additional debug messages for diagnosing failures by adding the --log-level=debug option to the command.

  9. You can periodically check the progress of the import by running the following command:
    cpd-cli export-import import status -n ${NAMESPACE} ${IMPORT_INSTANCE_NAME} --profile=${PROFILE_NAME}