manage setup-instance

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

Required role
Instance administrator You must be an administrator of the projects that are associated with an instance to run this command.

Before you begin

A cluster administrator must run the authorize-instance-topology command before you run the setup-instance command.

Extended description

Run this command for each instance of IBM® Software Hub that you plan to install or upgrade.

Important: You must re-run this command if you want to add a tethered project to an existing instance of IBM Software Hub.

The setup-instance command installs or upgrades the required operators and custom resources for an instance of IBM Software Hub.

Syntax

cpd-cli manage setup-instance \
--release=<version> \
--license_acceptance=true|false \
--cpd_operator_ns=<project-name> \
--cpd_instance_ns=<project-name> \
--block_storage_class=<RWO-storage-class> \
[--file_storage_class=<RWX-storage-class>] \
[--storage_vendor=portworx] \
[--tethered_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>] \
[--param-file=<file-name>] \
[--preview=true|false] \
[-vv][-vv][-vvv]

Arguments

The setup-instance command has no arguments.

Options

Table 1: Command options
Option Description
--block_storage_class Specify the name of an existing storage class that supports ReadWriteOnce (RWO) access.
Status
Required.
Syntax
--block_storage_class=<RWO-storage-class>
Default value
No default.
Valid values
The name of a storage class that supports 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 required operators.

You must create the catalog source objects for the required operators. 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 command to create the catalog source objects.

true
Create the catalog source objects for the required operators.
--cpd_instance_ns The project (namespace) where you want to install an instance of IBM Software Hub.
Status
Required.
Syntax
--cpd_instance_ns=<project-name>
Default value
No default. User-defined.
Valid values
The name of a project on the Red Hat® OpenShift® Container Platform cluster.
--cpd_operator_ns The project where you want to install the operators for this instance of IBM Software Hub.
Status
Required.
Syntax
--cpd_operator_ns=<project-name>
Default value
No default. User-defined.
Valid values
The name of a project on the Red Hat OpenShift Container Platform cluster.
--file_storage_class Specify the name of an existing storage class that supports ReadWriteMany (RWX) access.
Status
Required if you want to run storage tests to validate the performance and functionality of your storage (--run_storage_tests).
Syntax
--file_storage_class=<RWX-storage-class>
Default value
No default.
Valid values
The name of a storage class that supports RWX access.
--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
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, the specified components will not be installed.

true
This value indicates that you accept the license terms.

You must specify --license_acceptance=true to install the specified components.
--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.
--param-file The name of a YAML file that includes additional parameters.

The file must be in the work directory on the client workstation.

Status
Optional.

Refer to the installation documentation for the specified components for guidance.

Syntax
--param-file=tmp/work/<file-name>
Default value
No default. User-defined.
Valid values
The name of a YAML file that includes additional parameters.
--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 or upgrade to.
Status
Required.
Syntax
--release=<version>
Default value
No default. You must specify the release.
Valid values
  • 5.4.0
--run_storage_tests Specify whether to validate the performance and functionality of your storage.
Status
Optional.
Best practice: It is strongly recommended that you specify this option when you install or upgrade IBM Software Hub. If your storage does not meet the minimum requirements for performance and functionality, your environment is likely to encounter problems.
Syntax
--run_storage_tests=true|false
Default value
false
Valid values
false
Do not run the recommended storage tests.
true
Run the recommended storage tests.
--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.
--storage_vendor The type of storage that you are using. This setting uses the recommended storage class when provisioning storage during installation.
Status
Required if you use Portworx storage with the recommended storage class names.
Remember: Using custom storage class names is not recommended if you use Portworx storage.
Syntax
--storage_vendor=portworx
Default value
No default.
Valid values
portworx
Specify portworx if you use the recommended storage class names for Portworx.
--sub Specify whether to create the operator subscriptions for the required operators.

You must create the operator subscriptions for the required operators. 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 required operators.

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 required operators.
--tethered_ns A list of projects that you plan to tether to the operands project for this instance of IBM Software Hub.
Status
Optional. Specify this option only if you plan to create service instances in tethered projects.
Restriction: Review the service documentation to determine whether the services that you plan to install support creating service instances in tethered projects.
Syntax
--tethered_ns=<comma-separated-list-of-project-names>
Default value
No default. User-defined.
Valid values
A comma-separated list of projects on the Red Hat OpenShift Container Platform cluster that you plan to tether to the operands project for an instance of IBM Software Hub.
-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.


${CMD_PREFIX} setup-instance ] 
--cpd_instance_ns=cpd-instance-1 --tethered_ns=cpd-instance-1-tether-1,cpd-instance-1-tether-2 \
--block_storage_class=rwo-custom-class
# Preview the commands to install the required operators and custom resources 
# for an instance of IBM Software Hub.
${CMD_PREFIX} setup-instance --license_acceptance=true \
--release=5.1.0 --cpd_operator_ns=cpd-operator-1 \
--cpd_instance_ns=cpd-instance-1 \
--block_storage_class=rwo-custom-class \
--preview=true
Install the required operators and custom resources for an instance of IBM Software Hub
cpd-cli manage setup-instance \
--release=${VERSION} \
--license_acceptance=true \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK}
Run the recommended storage tests and then install the required operators and custom resources for an instance of IBM Software Hub
cpd-cli manage setup-instance \
--release=${VERSION} \
--license_acceptance=true \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--run_storage_tests=true
Preview the oc commands to install the required operators and custom resources for an instance of IBM Software Hub
cpd-cli manage setup-instance \
--release=${VERSION} \
--license_acceptance=true \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--preview=true