Migrating users and groups (IBM Knowledge Catalog)

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

IBM® Software Hub must be configured to use the embedded LDAP integration. For more information, see Configuring IBM Software Hub 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 in IBM Software Hub. 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 IBM Software Hub
  4. Importing users and groups to IBM Software Hub

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 instance name can contain only lowercase alphanumeric characters and hyphens (-) and must start and end with an alphanumeric character. Otherwise, the export will fail.

  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.
    Use one of the following commands:
    • 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 IBM Software Hub

Copy the exported users and groups information to the IBM Software Hub 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 IBM Software Hub:
    scp ${EXPORTED_DATA_TAR_GZ_FILE_PATH} ${OCP_USERNAME}@${OCP_HOST}:/tmp

Importing users and groups to IBM Software Hub

To import the InfoSphere Information Server users and groups information, complete these steps:
  1. Log in to IBM Software Hub 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}