Migrating Watson OpenScale subscriptions

Use cpd-cli commands to export and import Watson OpenScale subscriptions within a Cloud Pak for Data cluster or between different clusters.

Who needs to complete this task?
To complete this task, you must have one of the following roles on Red Hat® OpenShift® Container Platform:
  • Cluster administrator
  • Instance administrator
In addition, you must have one of the following permissions in Cloud Pak for Data:
  • A user with the Platform administration permission
  • A user who is the owner or an administrator of the Watson OpenScale service instances that you want to export data from and import data to

Prerequisites

Before you can export and import Watson OpenScale subscriptions, you must complete the following tasks:

  1. Creating a profile to use the cpd-cli management commands
  2. Preparing to use the Cloud Pak for Data export and import utility
  3. Initializing the export and import utility

In addition, you must have access to Watson OpenScale service instances. When you run the commands you must specify the names of the service instances that you want to export subscriptions from and import subscriptions to.

To view of list of the Watson OpenScale service instances that you have access to on an instance of Cloud Pak for Data, run the following command: 
cpd-cli service-instance list \
--profile=${CPD_PROFILE_NAME} \
--service-type=aios
Best practice: You can run many of the commands in this task exactly as written if you set up environment variables for your installation. For instructions, see Setting up installation environment variables.

Ensure that you source the environment variables before you run the commands in this task.

1. Preparing to export subscriptions

To migrate a subscription, you must export it from one service instance and import it to another service instance. The target service instance can be within the same Cloud Pak for Data deployment, within another instance of Cloud Pak for Data on the same cluster, or on a different cluster.

You can export subscriptions from one Watson OpenScale service instance at a time.

To export the subscriptions from a service instance, you must create an export specification file that includes a JSON string that specifies the following information:

Service providers

The service providers that you want to export subscriptions from. The service providers must exist in both the source service instance and the target service instance.

Restriction: You cannot export subscriptions associated with Watson Machine Learning unless the service provider is a remote instance of Watson Machine Learning.
Subscriptions

For each service provider, you must specify the subscriptions that you want to export. You can export all of the subscriptions associated with a service provider, or you can export a subset of the subscriptions.

  • To export all of the subscriptions associated with a service provider, specify an empty array for the subscription_ids parameter:
    "subscription_ids": []
  • To export a subset of the subscriptions associated with a service provider, specify a list of subscription IDs:
    "subscription_ids": ["SUBSCRIPTION_ID1", "SUBSCRIPTION_ID2"]
Encryption key

Specify an encryption key to encrypt the file that is generated when you export the subscriptions. The encryption key must be base64 encoded strings with a 256 bit length.

You must specify the same encryption key when you import the subscriptions.

Use the following examples to construct the JSON string for your source environment.

Important: For clarity, the following examples show the JSON string as indented JSON.

However, when you specify the JSON string in the export specification file, you must provide the JSON as a single line (without line breaks or formatting whitespace characters) surrounded by single quotation marks (').

Export all of the subscriptions for a single service provider
The following JSON string exports all of the subscriptions associated with an Azure service provider. The service provider ID on the source system is 7e71e76f-7ce3-4ebc-8629-aacc44e5073d.
{
	"name":"azure-provider-export-all",
	"description":"Export all subscriptions for 1 provider",
	"targets":[
		{
			"service_provider_id":"7e71e76f-7ce3-4ebc-8629-aacc44e5073d",
			"subscription_ids":[
				
			]
		}
	],
	"encryption":{
		"key":"VEZIQnN1VHZPS05iY0tYM045R3pWRmN2ZGM4TUg5ZE8="
	}
}
Export a subset of the subscriptions for a single service provider
The following JSON string exports a subset of the subscriptions associated with an Azure service provider. The service provider ID on the source system is 7e71e76f-7ce3-4ebc-8629-aacc44e5073d.
{
	"name":"azure-provider-export-all",
	"description":"Export the specified subscriptions for 1 provider",
	"targets":[
		{
			"service_provider_id":"7e71e76f-7ce3-4ebc-8629-aacc44e5073d",
			"subscription_ids":[
				"SUBSCRIPTION_ID1",
                            "SUBSCRIPTION_ID2"
			]
		}
	],
	"encryption":{
		"key":"VEZIQnN1VHZPS05iY0tYM045R3pWRmN2ZGM4TUg5ZE8="
	}
}
Export a subset of the subscriptions for multiple service providers
The following JSON string exports specific subscriptions associated with the following service providers:
  • An Azure service provider. The service provider ID on the source system is 7e71e76f-7ce3-4ebc-8629-aacc44e5073d.
  • An AWS service provider. The service provider ID on the source system is e06a59dd-5c62-4509-b63f-18fb84d6a970.
{
    "name":"azure-aws-provider-export-subset",
    "description":"Export the specified subscriptions for 2 service providers",
    "targets":[
        {
            "service_provider_id":"7e71e76f-7ce3-4ebc-8629-aacc44e5073d",
            "subscription_ids":[
                "SUBSCRIPTION_ID1",
                "SUBSCRIPTION_ID2",
                "SUBSCRIPTION_ID3",
                "SUBSCRIPTION_ID4"
            ]
        },
        {
            "service_provider_id":"e06a59dd-5c62-4509-b63f-18fb84d6a970",
            "subscription_ids":[
                "SUBSCRIPTION_ID5",
                "SUBSCRIPTION_ID6",
                "SUBSCRIPTION_ID7",
                "SUBSCRIPTION_ID8"
            ]
        }
    ],
    "encryption":{
        "key":"VEZIQnN1VHZPS05iY0tYM045R3pWRmN2ZGM4TUg5ZE8="
    }
}

2. Exporting subscriptions

Complete 1. Preparing to export subscriptions before you export any subscriptions.

To export subscriptions from Watson OpenScale service instances, you must complete the following steps:
  1. Log in to Red Hat OpenShift Container Platform as a user with sufficient permissions to complete the task.
    ${OC_LOGIN}
    Remember: OC_LOGIN is an alias for the oc login command.
  2. Identify the service instance that you want to export data from.
  3. Create the YAML file that defines your export specification:
    openscale-aux:
   PARAMS: '<EXPORT_JSON_STRING>'

    Replace <EXPORT_JSON_STRING> with the JSON string that you created in 1. Preparing to export subscriptions.

    Important: You must specify the JSON string as a single line (without line breaks or formatting whitespace characters). The string must be enclosed in single quotation marks.
  4. Change to the directory where the cpd-cli command-line interface is installed.
  5. Set the following environment variables:
    1. Set the EXPORT_NAME environment variable to the name that you want to use to identify the export job:
      export EXPORT_NAME=<name>
    2. Set the OVERRIDE_YAML_FILE_LOCATION environment variable to the fully qualified path of the YAML file that contains the export specification:
      export OVERRIDE_YAML_FILE_LOCATION=<fully-qualified-path-to-YAML-file>
    3. Set the OPENSCALE_INSTANCE_NAME environment variable to the name of the Watson OpenScale service instance that you want to export data from:
      export OPENSCALE_INSTANCE_NAME=<instance-name>
  6. Run the following command to export the data from the service instance: 
    cpd-cli export-import export create ${EXPORT_NAME} \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--profile=${CPD_PROFILE_NAME} \
--arch=${CPU_ARCH} \
--service-type=aios \
--instance-name=${OPENSCALE_INSTANCE_NAME} \
--values=${OVERRIDE_YAML_FILE_LOCATION}
  7. Check the status of the export: 
    cpd-cli export-import export status ${EXPORT_NAME} \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--profile=${CPD_PROFILE_NAME} \
--arch=${CPU_ARCH}
  8. If you plan to import the data to a different cluster, download the result of the export: 
    cpd-cli export-import export download ${EXPORT_NAME} \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--profile=${CPD_PROFILE_NAME} \
--arch=${CPU_ARCH}

    The command generates the result of the exported package with following format: cpd-exports-<export_name>-<timestamp>-data.tar

3. Preparing to import subscriptions

You can import subscriptions to one Watson OpenScale service instance at a time.

To import subscriptions to a service instance, you must create an import specification file that includes a JSON string that specifies what you want to import from the file that was generated when you exported the subscriptions (subsequently referred to as the export archive). The JSON string must specify the following information:

Target service providers
The service providers that you want to import subscriptions to. You can import subscriptions to one or more service providers.
Remember: The service providers must exist in both the source service instance and the target service instance.
Source service instance
The ID of the service instance that the subscriptions were exported from.
Restriction: All of the subscriptions must be from the same service instance. You cannot import subscriptions from multiple service instances at the same time.
Source service provider

The service providers that you exported subscriptions from. You can import subscriptions from one or more service providers.

Subscriptions

For each source service provider, you must specify the subscriptions that you want to import. You can import all of the subscriptions that are included in the export archive, or you can import a subset of the subscriptions.

  • To import all of the subscriptions from the export archive, specify an empty array for the subscription_ids parameter:
    "subscription_ids": []
  • To import a subset of the subscriptions from the export archive, specify a list of subscription IDs:
    "subscription_ids": ["SUBSCRIPTION_ID1","SUBSCRIPTION_ID2"]
Encryption key

Specify the encryption key that was used to encrypt the export archive.

Use the following examples to construct the JSON string for your target environment.
Important: For clarity, the following examples show the JSON string as indented JSON.

However, when you specify the JSON string in the import specification file, you must provide the JSON as a single line (without line breaks or formatting whitespace characters) surrounded by single quotation marks (').

Import all of the subscriptions for a single service provider
The following JSON string imports all of the subscriptions from the export archive for an Azure service provider. The service provider ID on the source system is 7e71e76f-7ce3-4ebc-8629-aacc44e5073d. The service provider ID on the target system is 23515569-4809-49cd-85df-88cf33059a3e.
{
    "name":"azure-provider-import-all",
    "description":"Import all subscriptions from the export archive for 1 service provider",
    "targets":[
        {
            "target":{
                "service_provider_id":"23515569-4809-49cd-85df-88cf33059a3e"
            },
            "source":{
                "service_instance_id":"00000000-0000-0000-0000-000000000000",
                "service_provider_id":"7e71e76f-7ce3-4ebc-8629-aacc44e5073d",
                "subscription_ids":[
                    
                ]
            }
        }
    ],
    "encryption":{
        "key":"VEZIQnN1VHZPS05iY0tYM045R3pWRmN2ZGM4TUg5ZE8=",
        "archive":""
    }
}
Import a subset of the subscriptions for a single service provider
The following JSON string imports a subset of the subscriptions from the export archive for an Azure service provider. The service provider ID on the source system is 7e71e76f-7ce3-4ebc-8629-aacc44e5073d. The service provider ID on the target system is 23515569-4809-49cd-85df-88cf33059a3e.
{
    "name":"azure-provider-import-all",
    "description":"Import all subscriptions from the export archive for 1 service provider",
    "targets":[
        {
            "target":{
                "service_provider_id":"23515569-4809-49cd-85df-88cf33059a3e"
            },
            "source":{
                "service_instance_id":"00000000-0000-0000-0000-000000000000",
                "service_provider_id":"7e71e76f-7ce3-4ebc-8629-aacc44e5073d",
                "subscription_ids":[
                    "SUBSCRIPTION_ID2"
                ]
            }
        }
    ],
    "encryption":{
        "key":"VEZIQnN1VHZPS05iY0tYM045R3pWRmN2ZGM4TUg5ZE8=",
        "archive":""
    }
}
Import a subset of the subscriptions for multiple service providers
The following JSON string imports a subset of the subscriptions from the export archive file for the following service providers:
  • An Azure service provider. The service provider ID on the source system is 7e71e76f-7ce3-4ebc-8629-aacc44e5073d. The service provider ID on the target system is 23515569-4809-49cd-85df-88cf33059a3e.
  • An AWS service provider. The service provider ID on the source system is e06a59dd-5c62-4509-b63f-18fb84d6a970. The service provider ID on the target system is 47938502-1096-8afe-cd76-92fa00814t7a.
{
    "name":"Import job for for Azure Service subscriptions",
    "description":"testjob",
    "targets":[
        {
            "target":{
                "service_provider_id":"23515569-4809-49cd-85df-88cf33059a3e"
            },
            "source":{
                "service_instance_id":"00000000-0000-0000-0000-000000000000",
                "service_provider_id":"7e71e76f-7ce3-4ebc-8629-aacc44e5073d",
                "subscription_ids":[
                    "SUBSCRIPTION_ID1",
                    "SUBSCRIPTION_ID6",
                    "SUBSCRIPTION_ID7",
                    "SUBSCRIPTION_ID8"
                ]
            },
            "target":{
                "service_provider_id":"47938502-1096-8afe-cd76-92fa00814t7a"
            },
            "source":{
                "service_instance_id":"00000000-0000-0000-0000-000000000000",
                "service_provider_id":"e06a59dd-5c62-4509-b63f-18fb84d6a970",
                "subscription_ids":[
                    "SUBSCRIPTION_ID7",
                    "SUBSCRIPTION_ID8"
                ]
            }
        }
    ],
    "encryption":{
        "key":"VEZIQnN1VHZPS05iY0tYM045R3pWRmN2ZGM4TUg5ZE8=",
        "archive":""
    }
}

4. Importing subscriptions

To import subscriptions from Watson OpenScale service instances, you must complete the following steps:
  1. Change to the directory where the cpd-cli command-line interface is installed.
  2. Follow the appropriate guidance based on where you want to import the subscriptions:
    • If you are importing the subscriptions to another Watson OpenScale service instance on the same instance of Cloud Pak for Data, update the value of the OPENSCALE_INSTANCE_NAME environment variable.
    • If you are importing the subscriptions to a Watson OpenScale service instance on a different instance of Cloud Pak for Data:
      1. Ensure that you source the correct environment variables file.
      2. Update the value of the OPENSCALE_INSTANCE_NAME environment variable, if needed.
    • If you are importing the subscriptions to a Watson OpenScale service instance on a different cluster:
      1. Ensure that you source the correct environment variables file.
      2. Log in to Red Hat OpenShift Container Platform as a user with sufficient permissions to complete the task.
        ${OC_LOGIN}
        Remember: OC_LOGIN is an alias for the oc login command.
      3. Update the value of the OPENSCALE_INSTANCE_NAME environment variable, if needed.
      4. Ensure that the archive file that you created when you completed 2. Exporting subscriptions is on the workstation.
      5. Set the EXPORT_ARCHIVE_FILE environment variable to the fully qualified path of the archive file:
        export EXPORT_ARCHIVE_FILE=<fully-qualified-path-to-TAR-file>
      6. Upload the archive file:
        cpd-cli export-import export upload \
--file=${EXPORT_ARCHIVE_FILE} \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--profile=${CPD_PROFILE_NAME} \
--arch=${CPU_ARCH}
  3. Create the YAML file that defines your import specification:
    openscale-aux:
   PARAMS: '<IMPORT_JSON_STRING>'

    Replace <IMPORT_JSON_STRING> with the JSON string that you created in 3. Preparing to import subscriptions.

    Important: You must specify the JSON string as a single line (without line breaks or formatting whitespace characters). The string must be enclosed in single quotation marks.
  4. Set the following environment variables:
    1. Set the IMPORT_NAME environment variable to the name that you want to use to identify the import job:
      export IMPORT_NAME=<name>
    2. Set the OVERRIDE_YAML_FILE_LOCATION environment variable to the fully qualified path of the YAML file that contains the import specification:
      export IMPORT_YAML_FILE_LOCATION=<fully-qualified-path-to-YAML-file>
    3. Set the OPENSCALE_INSTANCE_NAME environment variable to the name of the Watson OpenScale service instance that you want to import data to:
      export OPENSCALE_INSTANCE_NAME=<instance-name>
  5. Import the data to Watson OpenScale: 
    cpd-cli export-import import create ${IMPORT_NAME} \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--profile=${CPD_PROFILE_NAME} \
--arch=${CPU_ARCH} \
--service-type=aios \
--instance-name=${OPENSCALE_INSTANCE_NAME} \
--from-export=${EXPORT_NAME}
--values=${IMPORT_YAML_FILE_LOCATION}
  6. Check the status of the import : 
    cpd-cli export-import import status ${IMPORT_NAME} \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--profile=${CPD_PROFILE_NAME} \
--arch=${CPU_ARCH}

What to do next

If you imported batch subscriptions that use Analytics Engine powered by Apache Spark:

  1. Edit the Integrated System details to specify an a new analytics engine on your target cluster to enable evaluations.
  2. If you configure Explain settings, you must edit the Explain details.