IBM Support

How to use the IBM Db2 Click-to-Containerize utility for Db2 databases

How To


Summary

IBM Db2 Click-to-Containerize is a new application designed to help users move from a traditional Db2 deployment to a containerized Linux cluster. 

Objective

IBM Db2 Click-to-Containerize can be downloaded from the Db2 early access program.

Prerequisite
For information on how to install the IBM Red Hat OpenShift client, visit the OpenShift documentation here.
For information on how IBM Db2 integrates with OpenShift, visit the Db2 documentation here.

Environment

IMPORTANT: This tool is currently being offered as a technical preview and is not intended for production environments.

Environmental prerequisites:

In order to properly move your on-premises Db2 database you will need to gather some information and files:

  • IBM Db2 Click-to-Containerize executable for your platform of choice 

  • The source Db2 database needs to be at least on Version 10.5 fp7

  • On the SOURCE system, make sure that you have: 

    1. A connection to the database with the instance owner.

    2. A copy or access to the OpenShift CLI command (OC).

    3. The TAR file of the generated Shift command, or the makec2c command if you are generating the Shift file locally.

    4. Have granted SECADM and DBADM to user db2inst1 if this is not your instance user ID.
      Note: that the user ID does not have to exist in your Linux server
      . For example:

      CONNECT TO BLUDB USER db2v115 using db2v115 -- Assuming this is the instance owner or SECADM 
      GRANT SECADM ON DATABASE TO db2inst1 
      GRANT DBADM ON DATABASE to db2inst11

    • On the TARGET system, make sure that you have:
      1. A connection user ID and password, or token to the Cloud Pak for Data (CPD) or OpenShift cluster 

      2. A user ID and password, and port for the Db2 pod 

      3. If you are using CPD 3.5, make sure that you have the Data Management Console (DMC) enabled if you want to manage the databases. Otherwise you won't be able to check the status of the databases. 

Steps

The following sections and subsequent steps will go through the general flow of how to use Db2 Click-to-Containerize.
Users will first run the GUI part of application, generate required script and then run those scripts from source machine.
  1. Run the GUI application for Click-to-Containerize
  2. Generate the shift scripts and transfer them to Db2
  3. Run the shift.sh script
  4. Run the ldap_script.sh script
In the following sections, some of the steps will be explained to show more details about that step.
 
Running the GUI application
Run the application from the directory to which it was downloaded. The application takes several seconds to start as it creates temporary folders and uses temporary space to prepare the tool. Temporary folders include a C2C Db2 folder on your current machine.   
Note: the location of this folder will be different based on your system.  
- For Windows systems it will be C:/<user_dir>/c2cdb2  
- For Linux and MacOS systems, it will be <user_dir>/c2cdb2 
 
The graphical user interface opens with a license agreement message.
Click YES to accept the terms and use the application.
You will be presented with six different tiles.

TILES

OVERVIEW 

Provides a description of how Click to Containerize works. To return to the main tile view, click OK.  
 

DATABASE CONNECTION 
Provides a dialog box where you enter parameters for each source database and target container that you need. To complete this task, you will need to know the following: 
- Profile Name: A unique name or description for the database connection 
- Database: The name of the database 
- Host: The host name or IP address of the location where the database resides 
- Port: The port that is used to communicate with the database 
- SSL: The secure connection setting. True if you are using a secure port and False if you are using standard communication 
- Userid: A
user ID for connecting to the database and running SQL to retrieve settings 
- Password: Password for the
user ID above - Note that the password is not stored locally 
- SECADM: A
user ID that has SECADM privileges on the system (no password is required)

You can and should create and register new profiles for each source database and target database you need. Name them appropriately.  
Attention: Ensure that when you register new profiles, your source database name need to match target’s. which unless configured otherwise is BLUDB. In addition, ensure that the instance name for both your source and target databases are the same.
Each time you click Register, (whether it's a source or target database) the application runs an analysis of the parameters of that specific database.  
Note: Make sure that the source and target databases are the same Db2 version and level (for example Db2 Version 11.5.5) or that the target database is a higher level and version than the source. 

From the displayed analysis results, click the small tile for each analysis result to see if there are any parameter values that you need to override.  
Note: The values from the instance parameters tile are, by default, not moved during containerization. You can only set them with overrides. 

Click close to return to the Register Database Connection dialog box. 
Note: The parameters are being referenced against default values for each of the databases.


 

CONTAINERIZE Db2 

Provides a dialog box that allows you to enter the properties needed to generate the script that is used to move your database to your target Cloud Pak for Data or OpenShift cluster.

From the drop-down list boxes in the Source and Target panels, you can select profiles for your source database and target OpenShift cluster defined in Database connection tile.  
Note: You will need to enter the password for each database instance (source and target) every time you use the utility.

In the OpenShift settings panel, enter values that are based on your own system. The values you select depend on whether you are using Db2 on OpenShift or Cloud Pak for Data as your target cluster. For example, the values that you enter in both the Db2 OC Project and Db2 Release Name fields depend on your target cluster: 
For Db2 on OpenShift: 
- Db2 OC Project remains as the default of Db2 
- Db2 Release Name remains as the default Db2u 
For Cloud Pak for Data: 
- Db2 OC Project requires a different value. Check your Cloud Pak for Data instance to be sure. The default instance name is zen. 
- Db2 Release Name requires a different value for each Cloud Pak for Data instance. Check your system. 
If you would like to verify the database parameters, the ones shown during the analysis in the Database Connection step, you can do so here before moving on. 

Analyze button will present another summary of that analysis. You can override any of the parameters, if required. 

The Create Script button will detail the creation of the script. If there are any issues with the previous settings, such as your source and target database levels not matching, they are flagged here.  
If the scripts are created successfully, they are packaged into an archived file and will be in the default C2C Db2 folder the application created when you started the application for the first time. 
 

 

ANALYZER SETTINGS 

Default OpenShift and Dictionary settings can be modified in this tile. The Dictionary contains information about all of the Db2 parameters and it can be modified to adjust for values that may be outside of reference values.This tile also allows you to change the reference database that is used to compare against candidate databases. 

 

DATABASE UTILITIES

This tile may be used to show registered database connections. 

All database configuration information is kept locally. No connection or login credentials are kept. 

 

ADDITIONAL SUPPORT 

Provides a link to Db2 Early Access Program website, as well as link to OpenShift on hands lab.


 

Running generated scripts 

Prerequisites: 

  1. The database is suspended or shutdown *before* shifting, if doing the entire shift at once.

  2. Do not leave a long period of time between generating the Shift script and the execution of the script. If Db2 creates another file object, the relocate will fail.

  3. Safer way to use the shift program is to Logon to OpenShift first (with user ID/token) and use shift.sh -e -w to run the script.

Once you are done, close the application and find the generated archive on your machine. The scripts file needs to be moved to the location of the Candidate (on-premise) database and unpacked into a directory owned by the database instance owner. Typically this user ID will be db2inst1 but could have been set to something else. Unpack the archived file by using the command:
tar -xvf {fname}.
This will unpack a series of files into the local directory, including the following shell scripts:
 
- shift.sh: The command to move the contents of the candidate database to the OpenShift container 
- ldap_script.sh: Security script used to move the SECADM privileges to the OpenShift container 
 

  • shift.sh 

  Script generated using the Db2 Click-to-Containerize tool 

    It is used to containerize the source database into the target machine with Db2u already installed 

    To run properly, the shift.sh script needs OC and rsync installed.

    Usage: ./shift.sh [-r] [-i] [-e] [-s] [-w] 

           [-t <token>] [-u <userid>] [-p <password>] 

 

        -r    :  resume processing starting with data sync (omitting the target wipe) 

        -i    :  places Db2 into Standby Mode if source system was put in Write Suspend State (used for HADR) 

        -e    :  do not log into the OpenShift cluster and use existing login 

        -s    :  run application in Sync Mode only and stop before starting to activate Destination copy (can be used in combination with -r to resync ) 

        -w    :  allow target database wipe - for non-interactive run 

        -t    :  use token to login into server 

        -u    :  define user ID to use and override (will prompt for password, unless provided with -p) 

  -p    :  define password to use and override (will prompt for username, unless provided with -u) 

 

Before running the shift.sh script, you must either stop the database you are containerizing or place it into write/suspend mode. Run either of the following commands: 
 
db2stop (force) 
./shift.sh (-e -w) 
db2start 
 
or 
 
db2 connect to {database} 
set write suspend for database 
./shift.sh (-e -w) 
set write resume for database 
 
Note: You must ensure that the database is either stopped or suspended, otherwise the data may be inconsistent when it is moved over to the container. Once the movement is done and the target database is running,  you can restart or resume the source database. 

 
 

  • ldap_script.sh

A script generated using the Click-to-Containerize tool 

It is used to move user IDs and to give user authorities into the target machine with Db2u already installed 

    To run the ldap_script.sh properly, you will need OC.

Usage: 

        -t    :  use token to login into server 

        -u    :  define user ID to use and override (will prompt for password, unless provided with -p) 

        -p    :  define password to use and override (will prompt for username, unless provided with -u) 

        -e    :  do not log into the OpenShift cluster and use existing login 

After successfully running shift.sh, you should wait for a short period of time to give the pods time to restart and then run the ldap_script.sh 

./ldap_script.sh (-e) 

Additional Information

Troubleshooting 

If theshift.sh fails because of changed files, the preferred approach is: 

  1. Edit the makec2c.txt file that has been generated by the Db2 Click-to-Containerize program (if using the GUI) and add the flag --refresh to the end of the command and execute it in a terminal window 

  1. If using the makec2c program, repeat the command with --refresh 

  1. Rerun shift.sh on source system after the files are generated and moved to source system 

This technique will bypass reading the target system (which you won't be able to connect to) and just refresh the data based on the source system. 

Document Location

Worldwide

[{"Line of Business":{"code":"LOB10","label":"Data and AI"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSEPGG","label":"Db2 for Linux, UNIX and Windows"},"ARM Category":[{"code":"a8m500000008PkiAAE","label":"Administrative Tools"}],"ARM Case Number":"","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"11.5.0"}]

Document Information

Modified date:
06 May 2021

UID

ibm16416561