Setting up environment variables for a remote physical location

The commands for setting up a remote physical location for IBM Cloud Pak for Data use variables with the format ${VARIABLE_NAME}. You can create a script to automatically export the appropriate values as environment variables before you run the required commands. After you source the script, you will be able to copy most of the required commands from the documentation and run them without making any changes.

Who needs to complete this task?

Cloud Pak for Data operations team The IBM Cloud Pak for Data operations team should work with the remote cluster administrator to compile information about the remote cluster where the agents will be installed.

This information should be shared with any users who will run setup commands that require information about the remote cluster.

When do you need to complete this task?

Repeat as needed Create an environment variable script for each remote physical location that you plan to set up.

Creating an environment variables file

  1. Copy the following example to a text editor on your local file system:
    #===============================================================================
    # Remote physical location variables
    #===============================================================================
    
    # ------------------------------------------------------------------------------
    # Primary cluster (hub)
    # ------------------------------------------------------------------------------
    
    export CPD_HUB_URL=<your Cloud Pak for Data route>
    export CPD_HUB_API_KEY=<your base-64 encoded API key>
    
    
    # ------------------------------------------------------------------------------
    # Remote cluster
    # ------------------------------------------------------------------------------
    
    export REMOTE_OCP_URL=<enter your Red Hat
    OpenShift Container Platform URL>
    export REMOTE_IMAGE_ARCH=<enter your cluster architecture>
    # export REMOTE_OCP_USERNAME=<enter your username>
    # export REMOTE_OCP_PASSWORD=<enter your password>
    # export REMOTE_OCP_TOKEN=<enter your token>
    export REMOTE_SERVER_ARGUMENTS="--server=${REMOTE_OCP_URL}"
    # export REMOTE_LOGIN_ARGUMENTS="--username=${REMOTE_OCP_USERNAME} --password=${REMOTE_OCP_PASSWORD}"
    # export REMOTE_LOGIN_ARGUMENTS="--token=${REMOTE_OCP_TOKEN}"
    export REMOTE_CPDM_OC_LOGIN="cpd-cli manage login-to-ocp ${REMOTE_SERVER_ARGUMENTS} ${REMOTE_LOGIN_ARGUMENTS}"
    export REMOTE_OC_LOGIN="oc login ${REMOTE_OCP_URL} ${REMOTE_LOGIN_ARGUMENTS}"
    
    
    # ------------------------------------------------------------------------------
    # Remote projects
    # ------------------------------------------------------------------------------
    
    export REMOTE_PROJECT_CERT_MANAGER=<enter your certificate manager project>
    export REMOTE_PROJECT_LICENSE_SERVICE=<enter your License Service project>
    export REMOTE_PROJECT_SCHEDULING_SERVICE=<enter your scheduling service project>
    export REMOTE_PROJECT_MANAGEMENT=<enter your management project>
    export REMOTE_PROJECT_WORKLOAD=<enter your workload project>
    
    
    # ------------------------------------------------------------------------------
    # Remote storage
    # ------------------------------------------------------------------------------
    
    export REMOTE_STG_CLASS_BLOCK=<RWO-storage-class-name>
    export REMOTE_STG_CLASS_FILE=<RWX-storage-class-name>
    
    
    # ------------------------------------------------------------------------------
    # Image pull secret
    # ------------------------------------------------------------------------------
    
    export REMOTE_PULL_SECRET=<your secret name>
    
    # ------------------------------------------------------------------------------
    # Remote physical location
    # ------------------------------------------------------------------------------
    export REMOTE_PHYSICAL_LOCATION_ID=<unique ID>
    export REMOTE_PHYSICAL_LOCATION_DISPLAY_NAME="<display-name>"
    # export REMOTE_PHYSICAL_LOCATION_DESCRIPTION="<description>"
    # export REMOTE_PHYSICAL_LOCATION_REGION=<geographic location>
    # export REMOTE_PHYSICAL_LOCATION_MAX_CPU=<maxium vCPU to use>
    # export REMOTE_PHYSICAL_LOCATION_MAX_MEMORY=<maximum memory to use>
  2. Update each section in the script for your environment. See the following sections to learn about the variables and valid values in each section of the script:
  3. Save the file as a shell script. For example, save the file as remote_location_vars.sh.
  4. Confirm that the script does not contain any errors. For example, if you named the script remote_location_vars.sh, run:
    bash ./remote_location_vars.sh
  5. If you stored passwords in the file, prevent others from reading the file. For example, if you named the script remote_location_vars.sh, run:
    chmod 700 remote_location_vars.sh
Best practice: After you create the environment variables script for the remote physical location, add a comment to the end of your installation environment variables script that contains the name and location of the remote physical location environment variables script:
# ------------------------------------------------------------------------------
# Remote physical location scripts
# ------------------------------------------------------------------------------
# Information about remote physical location <name> is stored in the following
# environment variable script:
# /path-to-file/filename.txt

Adding this information to your installation environment variables script helps you keep track of the remote physical locations that are connected to your primary Cloud Pak for Data deployment, also called the hub.

Sourcing the environment variables

Save a copy of the script to your workstation and run it from a bash prompt before you the run remote physical location setup commands. The script exports the environment variables to your command-line session.

Important: You must re-run the script each time you open a new bash prompt.
  1. Change to the directory where you saved the script.
  2. Source the environment variables:
    1. Source your installation environment variables. For example, if you named the script cpd_vars.sh, run:
      source ./cpd_vars.sh
    2. Source your remote physical location environment variables. For example, if you named the script remote_location_vars.sh, run:
      source ./remote_location_vars.sh

Primary cluster (hub)

The variables in the Primary cluster (hub) section of the script specify information about the instance of IBM Cloud Pak for Data that you want to connect to from the remote physical location.

Variable Description
CPD_HUB_URL The route of the primary instance of Cloud Pak for Data that you want to connect to.
Default value
There is no default value.
Valid values
The route of the primary instance of Cloud Pak for Data that you want to connect to.

The route has the format https://cpd-namespace.apps.OCP-default-domain

CPD_HUB_API_KEY Your base-64 encoded API key for the primary instance of Cloud Pak for Data that you want to connect to.

You must specify the platform API key of a IBM Cloud Pak for Data user with the Manage physical location (manage_locations) permission.

For more information, see Generating API keys for authentication.

Default value
There is no default value.
Valid values
Your base-64 encoded API key for the primary instance of Cloud Pak for Data that you want to connect to.
Tip: To encode your API key, run:
'echo "<username>:<api_key>" | base64'

Remote cluster

The variables in the Remote cluster section of the script specify information about the remote Red Hat® OpenShift® Container Platform cluster where you want to create a remote physical location.

Tip: It is recommended that you prevent other users from reading the contents of the environment variable script by running chmod 700. However, if you still have concerns about storing your OpenShift credentials in this file, you can:
  • Enter the credentials directly instead of using the environment variable in the commands.
  • Manually export the credentials before you run the commands.
Variable Description
REMOTE_OCP_URL The URL of the remote Red Hat OpenShift Container Platform cluster where you want to create a remote physical location. For example, https://openshift1.example.com:8443.
Default value
There is no default value.
Valid values
Specify the URL of the remote Red Hat OpenShift Container Platform server.
REMOTE_IMAGE_ARCH The architecture of the remote cluster hardware.
Default value
There is no default value.
Valid values
amd64
Specify amd64 if your remote Red Hat OpenShift Container Platform cluster runs on x86-64 hardware.
ppc64le
Specify ppc64le if your remote Red Hat OpenShift Container Platform cluster runs on Power hardware.
s390x
Specify s390x if your remote Red Hat OpenShift Container Platform cluster runs on Z hardware.
REMOTE_OCP_USERNAME The username that you use to authenticate to the remote cluster where you want to create a remote physical location. You must have sufficient privileges to complete the task.

To use the REMOTE_OCP_USERNAME variable, you must uncomment the export command in the environment variables file.

REMOTE_OCP_PASSWORD The password that you use to authenticate to the remote cluster where you want to create a remote physical location.

To use the REMOTE_OCP_PASSWORD variable, you must uncomment the export command in the environment variables file.

REMOTE_OCP_TOKEN The token that you use to authenticate to the remote cluster where you want to create a remote physical location.

You can use a token instead of your user name and password to log in to your Red Hat OpenShift Container Platform cluster.

You can get your token from the Red Hat OpenShift Container Platform web console. From the username drop-down menu, select Copy login command. When prompted, click Display Token.

To use the REMOTE_OCP_TOKEN variable, you must uncomment the export command in the environment variables file.

REMOTE_SERVER_ARGUMENTS The server argument to pass to log in to the remote cluster.

Do not modify this export command.

The REMOTE_SERVER_ARGUMENTS environment variable depends on the REMOTE_OCP_URL environment variable.

REMOTE_LOGIN_ARGUMENTS The credential arguments to pass to log in to the remote cluster.
The REMOTE_LOGIN_ARGUMENTS environment variable depends on the credentials that you use to log in.
A username and password
If you specify a username and password, the REMOTE_LOGIN_ARGUMENTS environment variable depends on the following environment variables:
  • REMOTE_OCP_USERNAME
  • REMOTE_OCP_PASSWORD

If you are working from the sample environment variables script, uncomment the export REMOTE_LOGIN_ARGUMENTS entry that includes the username and password entries.

Do not modify this export command.

A token
If you specify a token, the REMOTE_LOGIN_ARGUMENTS environment variable depends on the REMOTE_OCP_TOKEN environment variable.

If you are working from the sample environment variables script, uncomment the export REMOTE_LOGIN_ARGUMENTS entry that includes the token entry.

Do not modify this export command.

REMOTE_CPDM_OC_LOGIN Shortcut for the cpd-cli manage login-to-ocp command for the remote cluster.

Do not modify this export command.

The REMOTE_CPDM_OC_LOGIN environment variable depends on the following environment variables:
  • REMOTE_SERVER_ARGUMENTS
  • REMOTE_LOGIN_ARGUMENTS
REMOTE_OC_LOGIN Shortcut for the oc login command for the remote cluster.

Do not modify this export command.

The OC_LOGIN environment variable depends on the following environment variables:
  • OCP_URL
  • LOGIN_ARGUMENTS

Remote projects

The variables in the Remote projects section of the script specify where the components that are required to create a remote physical location are installed.

Need more information? See:
Variable Description
REMOTE_PROJECT_CERT_MANAGER The project for the Certificate Manager operator on the remote cluster.
Default value
ibm-cert-manager
Valid values
You can use any Red Hat OpenShift project, but do not co-locate IBM Certificate manager with other software.
REMOTE_PROJECT_LICENSE_SERVICE The project for the Licensing Service operator on the remote cluster.
Default value
ibm-licensing
Valid values
You can use any Red Hat OpenShift project, but do not co-locate IBM Certificate manager with other software.
REMOTE_PROJECT_SCHEDULING_SERVICE The project for the scheduling service on the remote cluster.
Default value
There is no default value.
Valid values
You can use any Red Hat OpenShift project; however, it is strongly recommended that you use ibm-cpd-scheduler. Do not co-locate the scheduling service with other software.
REMOTE_PROJECT_MANAGEMENT The project for the agents, operators, and custom resources for a remote physical location.
Default value
There is no default value.
Valid values
You can use any Red Hat OpenShift project; but do not install other software in this project.
Important: The management project and the physical location ID are combined to create the route to the physical location. The combined names can contain a maximum of 58 characters. If you exceed 58 characters, the create-physical-location command fails.
REMOTE_PROJECT_WORKLOAD The project for workloads for a remote physical location.
Default value
There is no default value.
Valid values
You can use any Red Hat OpenShift project; but do not install other software in this project.

Remote storage

The variables in the Remote storage section of the script specify the storage classes that are available on the remote cluster.

Variable Description
REMOTE_STG_CLASS_BLOCK The name of a block storage class on the remote cluster where you want to create a remote physical location. The storage class must be associated with a supported storage option.
Default value
There is no default value.
Valid values
Specify the name of a storage class that points to block storage (storage that supports ReadWriteOnce, also called RWO, access).
The following list provides the recommended storage classes for the supported storage options. If you use different storage classes, identify an equivalent storage class on the cluster.
  • OpenShift Data Foundation: ocs-storagecluster-ceph-rbd
  • IBM Storage Fusion Data Foundation: ocs-storagecluster-ceph-rbd
  • IBM Storage Fusion Global Data Platform: Either of the following storage classes, depending on your environment:
    • ibm-spectrum-scale-sc
    • ibm-storage-fusion-cp-sc
  • IBM Storage Scale Container Native: ibm-spectrum-scale-sc
  • Portworx: portworx-metastoredb-sc
  • NFS: managed-nfs-storage
  • Amazon Elastic Block Store: Either of the following storage classes, depending on your environment:
    • gp2-csi
    • gp3-csi
REMOTE_STG_CLASS_FILE The name of a file storage class on the remote cluster where you want to create a remote physical location. The storage class must be associated with a supported storage option.
Default value
There is no default value.
Valid values
Specify the name of a storage class that points to file storage (storage that supports ReadWriteMany, also called RWX, access).
The following list provides the recommended storage classes for the supported storage options. If you use different storage classes, identify an equivalent storage class on the cluster.
  • OpenShift Data Foundation: ocs-storagecluster-cephfs
  • IBM Storage Fusion Data Foundation: ocs-storagecluster-cephfs
  • IBM Storage Fusion Global Data Platform: Either of the following storage classes, depending on your environment:
    • ibm-spectrum-scale-sc
    • ibm-storage-fusion-cp-sc
  • IBM Storage Scale Container Native: ibm-spectrum-scale-sc
  • Portworx: portworx-rwx-gp3-sc
  • NFS: managed-nfs-storage
  • Amazon Elastic File System: efs-nfs-client

Image pull secret

The variables in the Image pull secret section of the script specify information about pull secret that you want to use to ensure that you have access to the required images.

Variable Description
REMOTE_PULL_SECRET The name to use for the image pull secret for the remote physical location.
Default value
There is no default value.
Valid values
The name must be a valid Kubernetes DNS subdomain name.

Remote physical location

The variables in the Remote physical location section of the script specify information about the remote physical location on the remote cluster.

Variable Description
REMOTE_PHYSICAL_LOCATION_ID The unique ID for the remote physical location.
Default value
There is no default value.
Valid values
The ID must meet the following requirements:
  • Be between 1-50 characters
  • Contain only lowercase alphanumeric characters, dashes (-), and periods (.)
  • Start with an alphanumeric character
  • End with an alphanumeric character
Important: The management project and the physical location ID are combined to create the route to the physical location. The combined names can contain a maximum of 58 characters. If you exceed 58 characters, the create-physical-location command fails.
REMOTE_PHYSICAL_LOCATION_DISPLAY_NAME The user-friendly display name for the remote physical location.

This name will be displayed in the web client.

Default value
There is no default value.
Valid values

The display name can be up to 50 characters and can contain alphanumeric characters, dashes (-), and spaces.

If the display name includes spaces, the string must start and end with double quotation marks ("). For example:

--display_name="GPU cluster - North America"
REMOTE_PHYSICAL_LOCATION_DESCRIPTION The user-friendly description of the remote physical location.

For example, specify the geographic location, purpose, or hardware available on the remote physical location.

To use the REMOTE_PHYSICAL_LOCATION_DESCRIPTION variable, you must uncomment the export command in the environment variables file.

Default value
There is no default value.
Valid values

The string must start and end with double quotation marks ("). For example:

--description="A cluster with 4 GPUs for generative AI and deep learning experiments."
REMOTE_PHYSICAL_LOCATION_REGION The geographical region of the remote physical location.

To use the REMOTE_PHYSICAL_LOCATION_REGION variable, you must uncomment the export command in the environment variables file.

Default value
There is no default value.
Valid values
The region must meet the following criteria:
  • Be between 1-50 characters
  • Contain only alphanumeric characters, dashes (-), and spaces.
  • Start with an alphanumeric character
  • End with an alphanumeric character

If the region includes spaces, the string must start and end with double quotation marks ("). For example:

--region="South Africa"
REMOTE_PHYSICAL_LOCATION_MAX_CPU The maximum amount of vCPU that the scheduling service can use, if the workload exceeds the current available vCPU.
Restriction: This setting applies only if the remote cluster has a cluster autoscaler.

By default, the scheduling service uses the current available vCPU on the cluster to determine whether a workload can be scheduled on the physical location.

If the remote cluster has a cluster autoscaler, use this option to specify the maximum amount of vCPU that the scheduling service can use, if the workload exceeds the current available vCPU.

To use the REMOTE_PHYSICAL_LOCATION_MAX_CPU variable, you must uncomment the export command in the environment variables file.

Default value
There is no default value.
Valid values
Specify an integer.
REMOTE_PHYSICAL_LOCATION_MAX_MEMORY The maximum amount of memory that the scheduling service can use, if the workload exceeds the current available memory.
Restriction: This setting applies only if the remote cluster has a cluster autoscaler.

By default, the scheduling service uses the current available memory on the cluster to determine whether a workload can be scheduled on the physical location.

If the remote cluster has a cluster autoscaler, use this option to specify the maximum amount of memory that the scheduling service can use, if the workload exceeds the current available memory.

To use the REMOTE_PHYSICAL_LOCATION_MAX_MEMORY variable, you must uncomment the export command in the environment variables file.

Default value
There is no default value.
Valid values
Specify an integer.

What to do next

Now that you've created the environment variables script for the remote physical location, you're ready to complete Updating the global image pull secret for a remote physical location.