`manage create-physical-location`

Install the Cloud Pak for Data agents on a remote cluster so that users can run workloads on the remote cluster.

Required role

To run this command, you must have the following permissions:

Cluster administrator You must be a cluster administrator on the remote cluster.
You must have the Manage physical locations (manage_locations) permission in the primary instance of IBM Cloud Pak for Data (the hub).

Prerequisites

Before you run this command:

Set up a remote cluster.
On the remote cluster, create a management project and a workload project.
On the remote cluster, create an image pull secret in the management project and the workload project.
Get your platform API key from the primary instance of IBM Cloud Pak for Data.
Generate a base64 encoded version of your platform API key by running the following command:
```
'echo "<username>:<api_key>" | base64'
```

Extended description

In a typical installation, IBM Cloud Pak for Data runs in a set of projects (namespaces) on a single Red Hat® OpenShift® Container Platform cluster. You can use remote physical locations to expand your Cloud Pak for Data deployment to a remote cluster by installing Cloud Pak for Data agents on the remote cluster.

For more information, see:

Syntax

cpd-cli manage create-physical-location \
--physical_location_name=<unique-ID> \
--physical_location_host=<hostname> \
--management_ns=<project-name> \
--workload_ns=<project-name> \
--cpd_hub_url=<route> \
--cpd_hub_api_key=<base64-encoded-API-key> \
--block_storage_class=<RWO-storage-class> \
--release=<version> \
[--image_pull_secret=<pull-secret-name>] \
[--image-prefix=<image-registry-prefix>] \
[--upgrade=true|false] \
[--generate_digests=true|false]

Arguments

The create-physical-location command has no arguments.

Options

Table 1: Command options

Option	Description
`--block_storage_class`	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. Status Required. Syntax `--block_storage_class=<RWO-storage-class>` Default value No default. Valid values The name of the storage class that supports RWO access.
`--cpd_hub_api_key`	Your base64-encoded API key for the primary instance of Cloud Pak for Data that you want to connect to. Status Required. Syntax `--cpd_hub_api_key=<base64-encoded-API-key>` Default value No default. Valid values Your base64-encoded API key for the primary instance of Cloud Pak for Data that you want to connect to.
`--cpd_hub_url`	The route to the primary instance of Cloud Pak for Data that you want to connect to. Status Required. Syntax `--cpd_hub_url=<route>` Default value No default. Valid values The route to the primary instance of Cloud Pak for Data that you want to connect to. The route has the format `cpd-namespace.apps.OCP-default-domain`. Tip: To get the route, run the following command: `oc get route cpd -n=${PROJECT_CPD_INST_OPERANDS}`
`--generate_digests`	Specify whether to update the image digest in the physical_location_image_digests.yml file, if it exists. The image digest is based on the value in the `cpd_platform` CASE package. Status Optional. Syntax `--generate_digests=true\|false` Default value `false` If you omit this option, the default value is used. Valid values `false` Leave the image digest information unchanged. Important: This value is ignored if the YAML file does not exist. `true` Update the image digest. Important: To use this option, you must have the CASE package on your workstation.
`--image-prefix`	The registry to pull the required images from. Status Required to pull images from a private container registry. Syntax `--image-prefix=<image-registry-prefix>` Default value `icr.io/cpopen/cpfs` If you omit this option, the default value is used. Valid values `icr.io/cpopen/cpfs` `${PRIVATE_REGISTRY_LOCATION}/cpopen/cpfs`
`--image_pull_secret`	The name of the image pull secret that you created on the remote cluster. Status Required if the remote cluster does not have a global image pull secret. Syntax `--image_pull_secret=<pull-secret-name>` Default value No default. User defined. Valid values The name of the image pull secret that you created on the remote cluster. Important: The secret must be in the management project and the workload project.
`--management_ns`	The project on the remote cluster where you want to install the required agents, operators, and custom resources. Status Required. Syntax `--management_ns=<project-name>` Default value No default. Valid values The name of an existing project.
`--physical_location_host`	The fully qualified domain name of the remote cluster. Status Required. Syntax `--physical_location_host=<hostname>` Default value No default. Valid values The fully qualified domain name of the remote cluster.
`--physical_location_name`	The unique name to use to identify the physical location. Status Required. Syntax `--physical_location_name=<unique-ID>` Default value No default. 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
`--release`	The version of the Cloud Pak for Data agents to install on the physical location. Important: The version on the remote physical location must be the same as the version on the primary instance of Cloud Pak for Data (the hub). Status Required. Syntax `--release=<version>` Default value No default. You must specify the release. Valid values 5.0.0 5.0.1 5.0.2 5.0.3
`--upgrade`	Specify whether you are upgrading an existing installation. You must set this option to true to upgrade the software. Status Required to upgrade a remote physical location. Syntax `--upgrade=true\|false` Default value `false` If you omit this option, the default value is used. Valid values `false` Do not upgrade the remote physical location. `true` Upgrade the remote physical location. Important: This command automatically updates the image digest (`--generate_digests=true`). You must have the CASE package on your workstation.
`--workload_ns`	The project where you want to run workloads on the remote cluster. Status Required. Syntax `--workload_ns=<project-name>` Default value No default. Valid values The name of an existing project.

Examples

Note: The following example uses the recommended installation environment variables.

It is strongly recommended that you use a script to create environment variables with the correct values for your remote physical location. For details, see Setting up environment variables for a remote physical location.

Create a physical location that pulls images from the IBM Entitled Registry

The cluster uses namespace-scoped pull secrets

cpd-cli manage create-physical-location \
--physical_location_name=${REMOTE_PHYSICAL_LOCATION_ID} \
--physical_location_host=${REMOTE_OCP_URL} \
--block_storage_class=${REMOTE_STG_CLASS_BLOCK} \
--management_ns=${REMOTE_PROJECT_MANAGEMENT} \
--workload_ns=${REMOTE_PROJECT_WORKLOAD} \
--cpd_hub_url=${CPD_HUB_URL} \
--cpd_hub_api_key=${CPD_HUB_API_KEY} \
--release=${VERSION} \
--image_pull_secret=${REMOTE_PULL_SECRET}

Create a physical location that pulls images from a private container registry

The cluster uses namespace-scoped pull secrets

cpd-cli manage create-physical-location \
--physical_location_name=${REMOTE_PHYSICAL_LOCATION_ID} \
--physical_location_host=${REMOTE_OCP_URL} \
--block_storage_class=${REMOTE_STG_CLASS_BLOCK} \
--management_ns=${REMOTE_PROJECT_MANAGEMENT} \
--workload_ns=${REMOTE_PROJECT_WORKLOAD} \
--cpd_hub_url=${CPD_HUB_URL} \
--cpd_hub_api_key=${CPD_HUB_API_KEY} \
--release=${VERSION} \
--image-prefix=${PRIVATE_REGISTRY_LOCATION} \
--image_pull_secret=${REMOTE_PULL_SECRET}