Cloning a ML for IBM z/OS instance

If you install the ML for IBM z/OS® instance on the source system, then you can use the MLz clone utility to configure an instance on the target system and make a copy of the existing instance. You can deploy the clone as a standalone MLz instance or as a member of a MLz cluster.

Before you begin

Consider cloning a MLz instance in the following use cases:

You have set up a MLz instance in your preproduction environment and want to copy it to your production environment.
You have set up a MLz instance and want to duplicate it and run it as another standalone instance.
You have set up a MLz instance and want to reproduce it and add it as a member of your MLz cluster.

To clone an existing MLz instance from your source system to your target system, you must meet the following requirements:

The existing MLz instance must be installed and configured on the source system.
The cloned MLz instance on the target system can be assigned a different hostname or IP address, connected to a different Db2® system for its repository service, and configured a different keystore for user authentication and network connection. But it must use the same network ports that are already configured for the existing instance on your source system.
The user ID that you use for the cloning process must have the same privileges required for <mlz_setup_userid> as described in Configuring user ID for setting up Machine Learning for IBM z/OS Enterprise Edition.
MLz stores the configuration files and user data in the $IML_HOME directory. If the cloned instance is on a different LPAR, the user ID that you use on your target system must have READ access to the $IML_HOME directory of the existing instance on your source system. If the existing and cloned instances are on LPARs across different sysplexes, the existing $IML_HOME directory on your source system must be accessible to the LPAR of your target system where the clone instance is on.
The aln-clone.sh script is provided for you to clone your MLz. Make sure that you run the script on the target system where the cloned instance will run.
We can perform clone only in the same version, i.e. we are unable to clone a v2.4.0 MLz instance to a target instance with v3.2.0 MLz installed or vice versa.
We can perform clone only in the same MLz edition, for example, if your source instance is configured with MLz Enterprise edition, your cloned instance will also come with Enterprise edition configuration and features.

Procedure

Starting from v3.1.0, MLz supports two types of metadata objects repository: Db2 for z/OS and Embedded database.
- If the metadata objects repository is Db2 for z/OS for your source instance, you can choose whether to use Db2 or embedded database as the metadata objects repository for your cloned target instance.
- If the metadata objects repository is embedded database for your source instance, you can only select embedded database as the metadata objects repository for your cloned target instance.
If you would like to use Db2 as the metadata objects repository for your cloned target instance, you need to first create the metadata objects in Db2 for z/OS required by the cloned MLz instance.
1. Select a Db2 system that the MLz repository service uses to store metadata objects. See Installing prerequisite hardware and software for ML for IBM z/OS for details. If you want to reuse the metadata objects in Db2 for z/OS from the existing instance for your cloned instance, you will have the option to select the same Db2 system from the aln-clone.sh script.
2. Create the required metadata tables and associated objects in Db2 for the cloned MLz. See Creating metadata objects for the Machine Learning for IBM z/OS Enterprise Edition repository service for instructions.
  
  Skip this step if you plan to add the cloned instance as a new member of an existing MLz cluster. A MLz cluster uses one set of metadata objects for all member instances. You can also skip this step if you want to reuse the metadata objects in Db2 for z/OS from the existing instance for your cloned instance.
Create a clone of your MLz on your target system.
1. Change to the $IML_INSTALL_DIR/alnsamp directory on your target system and locate the aln-clone.sh script.
2. Issue the following command to start the clone process:
```
./aln-clone.sh
```
  The aln-clone.sh script duplicates the existing MLz instance from your source system to your target system, exports the configuration files, and copies your user data, such as any JAR file.
3. When prompted, respond by entering requested information, such as the hostname or IP address of the cloned instance, or accepting the default.
  - The location of the source $IML_HOME directory must be accessible from the target system.
  - When promoted to enter if you want to reuse the existing certificate, make sure you can access the existing certificate on your source system from your target system, or you can choose to enter a new valid certificate which is accessible from your target system. The cloned instance on your target system must use same type of certificate as your existing instance on your source system.
  - If you choose to reuse the source certificate on your target system, you will have the opportunity to confirm if you want to try to reuse the same admin password from the existing instance or enter one for your cloned instance. You can choose the same password for the existing instance and cloned instance. This option becomes handy in case there is any problem decrypting the existing admin password from the target system.
  - Similar to admin password, you will have the opportunity to confirm if you want to try to reuse the existing Db2 for z/OS user name and password from the existing instance or enter them for your cloned instance, if you choose to reuse the source certificate on your target system.
  - If you choose to use new certificate on your target system, you will always have to enter your admin password and Db2 credentials for your cloned instance.
  - If you reuse the same Db2 metadata objects from the source instance, you will have access to the same data from the target instance.
  - If you choose to use embedded database as on your target instance, you do not need to enter any user name or password for it. If you are doing a embedded database-to-embedded database clone, the data in the source instance’s embedded database will not be copied to the embedded database on your target instance.
  - If you configure MLz on the source host with either the ONNX compiler service or the Trustworthy AI service, or both the services together, then you must enter the zCX instance and the related information that is required to configure the services on the target system. For more information, see Configuring the ONNX compiler service for your ML for IBM z/OS and Configuring Trustworthy AI.
    
    Note:
    The zCX instance that you use to configure the target system must be different from the instance that you use to configure the source.
4. The clone process completes successfully when you see a message similar to the following example:
```
The source MLz instance is successfully cloned in ... seconds.
```
When prompted, you can choose to start all the MLz services automatically after the cloning completes.
You must start all the MLz services of the cloned instance manually if you opted not to do so automatically. For more information, see Stopping and starting services running on ML for IBM z/OS.
Optional: If you select to start all the MLz services automatically, then you can add a MLz proprietary model API user for the target instance.
This user can manage the models and deployments that you create and will have access to all the APIs that are externalized by MLz. You must manually create the proprietary model API user if you opted not to do so automatically. For more information, see Managing MLz users and privileges.
Configure a runtime environment for the MLz instance that you clone.
1. Source the following file:
  ${IML_HOME}/spark/conf/spark.profile
2. Run the $IML_INSTALL_DIR/alnsamp/aln-api-updates.sh script command with the addRuntimeEnv option and follow the system prompts.
Optional: Configure a scoring service for the cloned MLz instance.
For more information, see Configuring a ML for IBM z/OS scoring service by using the administration dashboard for instructions.