manage setup-instance-topology

Prepare the projects where you plan to run IBM Software Hub.

Deprecated This command is deprecated in 5.1.0. Use the setup-instance command instead.

Required role
Instance administrator To run this command, you must be either:
  • An administrator of the IBM® Software Hub 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 IBM Software Hub.
  • You want to add another tethered project to an existing instance of IBM Software Hub.
The setup-instance-topology prepares the projects where you plan to install or upgrade IBM Software Hub 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 IBM Software Hub 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] \
[--skip_components=<comma-separated-list-of-component-names>] \
[--preview=true|false] \
[--print_rbac=true|false] \
[-v][-vv][-vvv]

Arguments

The setup-instance-topology command has no arguments.

Options

Table 1: Command options
Option Description
--additional_ns A list of projects that you plan to tether to the IBM Software Hub 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 Software Hub operands project.
--block_storage_class The name of a block storage class on the cluster. The storage class must be associated with a supported storage option.
Status
Optional, but strongly recommended.
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 Software Hub 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 IBM Software Hub.
  • To add more tethered projects to an existing instance of IBM Software Hub, specify the project where the IBM Software Hub is installed.
--cpd_operator_ns The project for the operators for an instance of IBM Software Hub.
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 IBM Software Hub, specify the project where the IBM Software Hub operators are 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.
--print_rbac Print out the role-based access control (RBAC) requirements for the command.
Status
Optional.
Syntax
--print_rbac=true|false
Default value
false

If you omit this option, the default value is used.

Valid values
false
Do not print out the minimum role-based access control for the command.
true
Print out the minimum role-based access control for the command.
--release The release that you want to install.
Status
Required.
Syntax
--release=<version>
Default value
No default. You must specify the release.
Valid values
  • 5.4.0
--skip_components A comma-separated list of component IDs that are already have cluster-scoped operators.

If you have a cluster-scoped operator for a component, use this option to prevent the cpd-cli from creating a namespace-scoped instance of the operator. For example, if you have a cluster-scoped instance of the Cloud Native PostgreSQL operator, you can prevent the cpd-cli from creating a namespace-scoped operator if another component has a dependency on Cloud Native PostgreSQL.

Status
Optional.
Syntax
--skip_components=<comma-separated-list-of-component-names>
Default value
No default.
Valid values
For the list of components, see Component IDs.

You can specify individual components or a comma-separated list of components.
--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.

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 Setting up installation environment variables.

Prepare the projects where you plan to install IBM Software Hub
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 Software Hub
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