`manage setup-instance-topology`

Important: IBM Cloud Pak® for Data Version 4.8 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.8 reaches end of support. For more information, see Upgrading from IBM Cloud Pak for Data Version 4.8 to IBM Software Hub Version 5.1.

Prepare the projects where you plan to run IBM Cloud Pak for Data software.

Required role

Instance administrator To run this command, you must be either:

An administrator of the Cloud Pak for Data instance.
A cluster administrator.

Extended description

Important: A cluster administrator must run the authorize-instance-topology command before you can run this command.

Run this command in the following scenarios.

You are installing new instance of Cloud Pak for Data.
You want to add another tethered project to an existing instance of Cloud Pak for Data.

The setup-instance-topology prepares the projects where you plan to install or upgrade Cloud Pak for Data by completing the following tasks:

Installing or upgrade the required IBM Cloud Pak foundational services software in the specified operators project.
Creating or updating the ConfigMap for the NamespaceScope operator. (The ConfigMap) identifies the project or projects that the operators should watch.)

Run this command for each instance of Cloud Pak for Data that you plan to install or upgrade.

Syntax

cpd-cli manage setup-instance-topology \
--release=<version> \
--cpd_operator_ns=<project-name> \
--cpd_instance_ns=<project-name> \
--license_acceptance=true|false \
[--block_storage_class=<RWO-storage-class>] \
[--additional_ns=<comma-separated-list-of-project-names>] \
[--case_download=true|false] \
[--from_oci=true|false] \
[--oci_location=<registry-URL>] \
[--catsrc=true|false] \
[--sub=true|false] \ 
[--preview=true|false] \
[-v][-vv][-vvv]

Arguments

The setup-instance-topology command has no arguments.

Options

Option	Description
`--additional_ns`	A list of projects that you plan to tether to the Cloud Pak for Data control plane project. If Restriction: Only some services can deploy workloads or service instances to tethered projects. To determine whether the services that you plan to install can use tethered projects, see Multitenancy support. Status Optional. Syntax `--additional_ns=<comma-separated-list-of-project-names>` Default value No default. User defined. Valid values A comma-separated list of project names to tether to the IBM Cloud Pak for Data control plane project.
`--block_storage_class`	The name of a block storage class on a supported storage option. Status The status depends on the version of the `olm-utils-v2` image that you are using: In Version 4.8.0, 4.8.1, 4.8.2, 4.8.3, or 4.8.4, this setting is optional but strongly recommended. In Version 4.8.5 and later, this setting is required to install the IBM Cloud Pak foundational services. Syntax `--block_storage_class=<RWO-storage-class>` Default value No default. Valid values The name of an existing storage class on the cluster that supports ReadWriteOnce (RWO) access.
`--case_download`	Specify whether to download the CASE packages for the specified components if they are not detected in the work directory. Important: The command will fail if the CASE packages are not in the `work` directory. Default location If you made the `cpd-cli` executable from any directory, the path to the directory is: `<current-directory>/cpd-cli-workspace/olm-utils-workspace/work` If you did not make the `cpd-cli` executable from any directory, the path to the directory is: `<cli-install-directory>/cpd-cli-workspace/olm-utils-workspace/work` Custom location If you set the `CPD_CLI_MANAGE_WORKSPACE` environment variable, path to the directory is: `${CPD_CLI_MANAGE_WORKSPACE}/work` Status Optional. Syntax `--case_download=true\|false` Default value `true` If you omit this option, the default value is used. Valid values `false` Specify `false` if you are running the commands in a restricted network where the download will fail. If you specify `false` and the CASE packages are not in the `work` directory, the command will fail. `true` Specify `true` to download the CASE packages. If you are not allowed to download the CASE packages from GitHub, ensure that you set `--from_oci=true`.
`--catsrc`	Specify whether to create the catalog source objects for the specified components. You must create the catalog source objects for the IBM Cloud Pak foundational services. However, you can create the catalog source objects separately from the subscriptions. Status Optional. Syntax `--catsrc=true\|false` Default value true If you omit this option, the default value is used. Valid values false Do not create the catalog source objects for the IBM Cloud Pak foundational services. For example, specify `false` if you already ran the `setup-instance-topology` command to create the catalog source objects. true Create the catalog source objects for the IBM Cloud Pak foundational services.
`--cpd_instance_ns`	The project for the IBM Cloud Pak for Data control plane and services. Status Required. Syntax `--cpd_instance_ns=<project-name>` Default value No default. User-defined. Valid values For install, the project where you want to install the IBM Cloud Pak for Data control plane. To add more tethered projects to an existing instance of Cloud Pak for Data, specify the project where the IBM Cloud Pak for Data control plane is installed.
`--cpd_operator_ns`	The project for the operators for an instance of Cloud Pak for Data. Status Required. Syntax `--cpd_operator_ns=<project-name>` Default value No default. User-defined. Valid values For install, the project where you want to install the operators. To add more tethered projects to an existing instance of Cloud Pak for Data, specify the project where the IBM Cloud Pak for Data control plane is installed.
`--from_oci`	Download CASE packages from the IBM Cloud Pak Open Container Initiative (OCI) registry rather than from GitHub. This option is recommended for environments that are not allowed to access GitHub (github.com). Restriction: This setting applies only if you set `--case_download=true`. Status Optional. Syntax `--from_oci=true\|false` Default value `false` If you omit this option, the default value is used. Valid values `false` Download the CASE packages from GitHub. `true` Download the CASE packages from the IBM Cloud Pak Open Container Initiative.
`--license_acceptance`	Specify whether you accept the license terms. You must set this option to true to install the software. Status Required. Syntax `--license_acceptance=true\|false` Default value `false` If you omit this option, the default value is used. Valid values `false` This value indicates that you do not accept the license terms. If you specify `--license_acceptance=false`, IBM Cloud Pak foundational services will not be installed. `true` This value indicates that you accept the license terms. You must specify `--license_acceptance=true` to install IBM Cloud Pak foundational services.
`--oci_location`	The URL of the Open Container Initiative (OCI) registry from which you want to download CASE packages. For example, specify this option if you want to download the CASE packages from a private OCI registry. Restriction: This setting applies only if you set `--from_oci=true`. Status Optional. Syntax `--oci_location=<registry-URL>` Default value `cp.icr.io/cpopen` If you omit this option, the default value is used. Valid values The URL of the Open Container Initiative (OCI) registry from which you want to download CASE packages.
`--preview`	Preview the commands that run when you issue this CLI command. The command issues a series of `oc` commands. You can see the list of `oc` commands that are associated with the command. The `oc` commands are saved to the `preview.sh` file in the `work` directory. Status Optional. Syntax `--preview=true\|false` Default value false If you omit this option, the default value is used. Valid values false Run the commands to apply the changes to your cluster. true Preview the commands without running them. You can copy the `oc` commands from the output and run them yourself. However, this method is not recommended. When you run the commands manually, you do not have access to the additional helper scripts that are included in the underlying Ansible® playbook.
`--release`	The release that you want to install. Status Required. Syntax `--release=<version>` Default value No default. You must specify the release. Valid values 4.8.0 4.8.1 4.8.2 4.8.3 4.8.4 4.8.5 4.8.6 4.8.7 4.8.8 4.8.9
`--sub`	Specify whether to create the operator subscriptions for the specified components. You must create the operator subscriptions for the IBM Cloud Pak foundational services. However, you can create the subscriptions separately from the catalog source objects. Status Optional. Syntax `--sub=true\|false` Default value true If you omit this option, the default value is used. Valid values false Do not create the operator subscriptions for the IBM Cloud Pak foundational services. For example, specify `false` if you want to create and validate the catalog source objects before you create the operator subscriptions. true Create the operator subscriptions for the IBM Cloud Pak foundational services.
`-v` `-vv` `-vvv`	Display verbose output. Options are listed from least verbose to the most verbose. Status Optional. Syntax Verbose output `-v` Very verbose output `-vv` Most verbose output `-vvv` Default value Not applicable. Valid values Not applicable.

Table 1: Command options

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 environment. For details, see Best practice: Setting up installation environment variables.

Prepare the projects where you plan to install IBM Cloud Pak for Data

cpd-cli manage setup-instance-topology \
--release=${VERSION} \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--additional_ns=${PROJECT_CPD_INSTANCE_TETHERED_LIST} \
--license_acceptance=true

Preview the oc commands to prepare the projects where you plan to install IBM Cloud Pak for Data

cpd-cli manage setup-instance-topology \
--release=${VERSION} \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--additional_ns=${PROJECT_CPD_INSTANCE_TETHERED_LIST} \
--license_acceptance=true \
--preview=true