IBM Cloud Pak® CLI (cloudctl) CASE commands

Learn about the CASE commands that you can use with the Cloudctl command-line tool to manage your Container Application Software for Enterprises (CASE).

Important: In foundational services version 3.22, the cloudctl case command is deprecated and replaced with ibm-pak plug-in. Support for the cloudctl case command will be removed in a future release.

Commands

Cloudctl case save

Use the cloudctl case save command to save and parse a CASE package in preparation for installation. The package includes the CASE itself and any dependent CASEs and Helm charts. The container images that are referenced by the CASE is compiled into a comma-separated values (CSV) file, which you can use to mirror your images into a local image repository.

When you run this command, the command downloads all CASEs to the specified output directory. For each CASE, the command completes the following tasks:

Case save command:

cloudctl case save --case <CASE_PATH_OR_URL> --outputdir <OUTPUT_DIR>

OPTIONS:
   --case value,      -c value  Sets the local filepath or URL that includes the CASE file to be parsed. The expected file format for a CASE file is .tgz
   --outputdir value, -o value  Sets the output directory where the CASE file is saved. The output directory is created when the directory does not exist.
   --tolerance value, -t value  Indicates the tolerance level for validating the CASE. Accepted values:
                                  0 - Maximum validation level (default)
                                  1 - Reduced validation level

The command can return one of two possible return codes:

Case save examples

Sample output structure

Sample CASE hierarchy:

├── case1
│   ├── chart1
│   ├── case2
│   │   ├──chart2

When you run the cloudctl case save to save this case, the output includes two Helm charts (.tgz) in the charts directory, two CASE files (.tgzs) for the two CASEs in the root directory, and CSV files. These CSV files contain information about the Helm charts and container images that are associated with each of the CASEs.

├── charts
│   ├── chart1-1.0.0.tgz
│   ├── chart2-2.0.0.tgz
├── case1-1.0.0-charts.csv
├── case1-1.0.0-images.csv
├── case1-1.0.0.tgz
├── case2-2.0.0-charts.csv
├── case2-2.0.0-images.csv
└── case2-2.0.0.tgz

No container images are downloaded by running the cloudctl case save command. Only the metadata for container images are downloaded. If you are using the CASE to install a product on a system that has an active internet connect, you do not need to download the images before you use the cloudctl case launch command. If you need to install the product offline, use the contents of the image CSV files.

Image CSV files

The image CSV files include a list of all images that are referenced by a CASE. Each CASE references either a specific image manifest, or a manifest list, when the CASE supports multiple architectures. If a manifest list is specified, the list must always represent the entire set of manifests. The list cannot include a subset of manifests. Most repositories require the images to be present before you create the manifest list. If images are removed from the manifest list, the digest is changed.

Each image CSV file uses the following naming convention:

<case>-<version>-images.csv

The file includes the following fields:

You can parse, filter, and use the image CSV to mirror or download only the images that you need. For example, you can use the image CSV to complete the following tasks:

cloudctl case launch

Use the cloudctl case launch command to start a CASE into a targeted cluster. This command runs the CASE launcher script to complete an action that is defined in a CASE. This process validates any prerequisites for the action and validates the CASE before running the script. A CASE can include zero or multiple launch scripts.

Case launch command

cloudctl case launch --case <CASE-PATH> [additional parameters]

OPTIONS:
   --action value, -a value     The name of the action to be launched.
   --args value, -r value       Any additional arguments.
   --case value, -c value       The root directory where the extracted CASE file is located.
   --instance value, -i value   The name of the instance for the target application (release).
   --inventory value, -e value  The name of the inventory item launched.
   --namespace value, -n value  The name of the target namespace.
   --tolerance value, -t value  Indicates the tolerance level for validating the CASE. Accepted values:
                                  0 - Maximum validation level (default)
                                  1 - Reduced validation level

The command can return one of two possible return codes:

Case launch examples

cloudctl case launch --case /tmp/cache --inventory clusterSetup --action setup --args "--serviceAccount sample-sa1"
cloudctl case launch --case /tmp/cache --args "--localCache /tmp/cache"

Debugging a launcher script

A launcher script can fail due to the following possible causes:

cloudctl case create-images-delta

Use the cloudctl case create-images-delta command to create a subset of images to be mirrored. This command helps mirror the container images that don’t exist in your internal registry. This is done by first identifying the delta list of images that need to be mirrored, then mirroring only those images. The list of images is stored in a CSV file in the image registry folder of the offline cache and is referred to as the delta CSV. If a delta CSV is discovered in the offline cache, it is used by the mirrorImages action by default. Otherwise, it follows the existing process. This can be overridden with the --args useDelta=false command line argument. If more than one delta CSV is discovered, the one with the latest timestamp is used.

Case create-images-delta command:

cloudctl case create-images-delta --case <CASE_PATH> --registry <REGISTRY_LOCATION>

OPTIONS:
   --case value, -c value      The local path containing the CASE
   --registry value, -r value  The name of registry where images are mirrored

Example mirror processes

Delta mirror process with bastion server

Note: This sequence assumes that it's not the initial mirroring process and skips the steps to configure credentials.

  1. Use cloudctl case save to download the new version of the subcase.
  2. Use cloudctl case create-image-delta to create the delta image CSV from the existing offline cache and previously mirrored images list.
  3. Call cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages to mirror images.
    1. Read the delta image CSV.
    2. Make the mirror image request through the bastion server and into the internal container registry.
    3. Complete the mirror process.
    4. Update the local cache’s list of previously mirrored images.

Delta mirror process with a portable compute device

Note: This sequence assumes that it's not the initial mirroring process and skips the steps to configure credentials

  1. Use cloudctl case save to download the new version of the subcase.
  2. Use cloudctl case create-image-delta to create the delta image CSV from the existing offline cache and previously mirrored images list.
  3. Call cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages to mirror images to a local registry on your portable compute device.
  4. Connect the portable compute device to the private network.
  5. Use cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages to mirror the images to an internal registry and update the local cache’s list of previously mirrored images.
  6. Copy the updated local cache from the portable compute device to the original local cache.

Delta mirror process with a portable storage device

Note: This sequence assumes that it's not the initial mirroring process and skips the steps to configure credentials.

  1. Use cloudctl case save to download the new version of the subcase.
  2. Use cloudctl case create-image-delta to create the delta image CSV from the existing offline cache and previously mirrored images list.
  3. Call cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages to mirror images to a local registry on your portable compute device.
  4. Save the local registry as a container image on a portable storage device and copy the local cache to the same portable storage device.
  5. Move the portable storage device inside of the private network and extract.
  6. Use cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages to mirror the images to an internal registry and update the local cache’s list of previously mirrored images.
  7. Move the portable storage device to the external network.
  8. Copy the updated local cache from the portable storage device to the original local cache.

verify-catalog cloudctl case command

In some situations where multiple air-gapped installations are run, the operator catalogs might be downgraded, which might cause an older version of a product catalog to be installed. The verify-catalog command ensures that no catalog sources on the cluster are potentially downgraded during installation. Downgrading the version of a catalog source on a cluster could have negative effects to running software on the cluster environment.

You can use the following commands to verify whether any downgraded images exist in your Red Hat OpenShift Container Platform cluster:

./cloudctl case --help
NAME:
   ./cloudctl case

USAGE:
   ./cloudctl case command [arguments...] [command options]

COMMANDS:
   create-images-delta       Creates a subset of images to be mirrored.
   launch                    Launches a CASE into the targeted cluster.
   refresh-catalog-mapping   Pulls new catalog image metadata to an existing offline cache.
   save                      Saves and parses a CASE file in preparation for installation.
   verify-catalog            Verifies if catalog sources can be down leveled by a given CASE.
   help

Enter './cloudctl case help [command]' for more information about a command.

For example:

cloudctl case verify-catalog --case <CASE_PATH_OR_URL> --version<VERSION_NUMBER> --inputdir <PATH> --catalog-sources <PATH>

For example:

cloudctl case refresh-catalog-mapping  --inputdir <PATH> --repo <PATH>

verify-catalog command examples:

The following section illustrates examples of when you might want to use the verify-catalog cloudctl case command.

Notes:

Using the following commands, it is possible to get the list of catalog images from a running cluster:

  1. Get the Pod Spec JSON from the cluster for pods that are running Catalog Index Images.

    The following command will search through all catalog sources and use the OLM labels to return a list of pods that are running the Catalog Index Image in the Catalog Source (it is possible to update the command to only look at certain namespaces when searching for catalog images):

    oc get catalogsources --all-namespaces -o json | jq -r '.items | map(.metadata.name) | join(",")' | xargs -I "<label>" oc get pods --all-namespaces -l "olm.catalogSource in (<label>)" -o json
    
  2. Using the preceding Pod JSON, query the results to return a list of image references by digest by running the following command:

    jq -r '.items[] | .status.containerStatuses[] | select(.name=="registry-server").imageID'
    

    The commands can be piped together as follows:

    oc get catalogsources --all-namespaces -o json | jq -r '.items | map(.metadata.name) | join(",")' | xargs -I "<label>" oc get pods --all-namespaces -l "olm.catalogSource in (<label>)" -o json |  jq -r '.items[] | .status.containerStatuses[] | select(.name=="registry-server").imageID'
    

    Example output:

    registry.redhat.io/redhat/certified-operator-index@sha256:4b223abd7c0edf252977dabcbd570a432ebf365c11b0badfe7e481cfcc3ea1c2
    registry.redhat.io/redhat/community-operator-index@sha256:26677d9bb76f6c37d98397373739db2aaf777eeb1135a7594efab6cce0b9c49c
    icr.io/cpopen/ibm-operator-catalog@sha256:45c4bb2b36d0fead32bb4246a2933ac864d8b8de2e6e32b3edb2cc1f10b1420a
    registry.redhat.io/redhat/redhat-marketplace-index@sha256:cbcc8761c392ba25db36aff3b943d7be6ecd54c48c94fffe6f831f43978efd13
    registry.redhat.io/redhat/redhat-operator-index@sha256:044555748f215e812f07b2a6d2f8d523012e44047c1d0fc3a572c387a3893e14
    

CASE being downloaded has a version lower than what is installed to the cluster

Note: The version is optional in the following section.

$ cloudctl case verify-catalog -c ibm-cp-common-services -v 1.8.1 -i folderName/verifyDowngradeCatalogCaseCache -s folderName/catalogSourceTextFiles/catalogfile.txt

The catalog images specified on the cluster will be affected by the following:
- Catalog image:           icr.io/cpopen/ibm-common-service-catalog@sha256:a926289001b2681a09b87e6a0161668408e6f99aef2a3d320576566ebf657500
  Provided by CASE:        ibm-cp-common-services
  Resolved CASE version:   1.9.0
  Requested CASE version:  1.8.1
  Catalog image change:    downgraded
  Summary:                 Catalog image icr.io/cpopen/ibm-common-service-catalog@sha256:a926289001b2681a09b87e6a0161668408e6f99aef2a3d320576566ebf657500 provided by CASE version 1.9.0 will be downgraded by the catalog image in CASE ibm-cp-common-services:1.8.1

Summary of potential issues found:
- Catalog image:           icr.io/cpopen/ibm-common-service-catalog@sha256:a926289001b2681a09b87e6a0161668408e6f99aef2a3d320576566ebf657500
  Provided by CASE:        ibm-cp-common-services
  Resolved CASE version:   1.9.0
  Requested CASE version:  1.8.1
  Catalog image change:    downgraded
  Summary:                 Catalog image icr.io/cpopen/ibm-common-service-catalog@sha256:a926289001b2681a09b87e6a0161668408e6f99aef2a3d320576566ebf657500 provided by CASE version 1.9.0 will be downgraded by the catalog image in CASE ibm-cp-common-services:1.8.1

OK

CASE being downloaded has a version the same as what is installed to the cluster

Note: The version is optional in the following section.

$ cloudctl case verify-catalog -c ibm-cp-common-services -v 1.8.1 -i folderName/verifyDowngradeCatalogCaseCache -s folderName/catalogSourceTextFiles/catalogfile.txt

The catalog images specified on the cluster will be affected by the following:
- Catalog image:           icr.io/cpopen/ibm-common-service-catalog@sha256:62d4e76017c4415deb4a80843e820864b774b1c56ebaebe12cac07cc6e47e0b4
  Provided by CASE:        ibm-cp-common-services
  Resolved CASE version:   1.8.1
  Requested CASE version:  1.8.1
  Catalog image change:    unaffected
  Summary:                 Catalog image icr.io/cpopen/ibm-common-service-catalog@sha256:62d4e76017c4415deb4a80843e820864b774b1c56ebaebe12cac07cc6e47e0b4 provided by CASE version 1.8.1 will be unaffected by the catalog image in CASE ibm-cp-common-services:1.8.1

Summary of potential issues found:
None

OK

CASE being downloaded has a version higher than what is installed to the cluster

Note: The version is optional in the following section.

$ cloudctl case verify-catalog -c ibm-apiconnect -v 3.0.3 -i folderName/verifyDowngradeCatalogCaseCache -s folderName/catalogSourceTextFiles/catalogfile.txt

The catalog images specified on the cluster will be affected by the following:
- Catalog image:           icr.io/cpopen/ibm-common-service-catalog@sha256:f493f4164783f32a3cf5e739c8963e0cfe188844ecebc3266dbdef5c4106c2d6
  Provided by CASE:        ibm-cp-common-services
  Resolved CASE version:   1.7.0
  Requested CASE version:  1.8.1
  Catalog image change:    upgraded
  Summary:                 Catalog image icr.io/cpopen/ibm-common-service-catalog@sha256:f493f4164783f32a3cf5e739c8963e0cfe188844ecebc3266dbdef5c4106c2d6 provided by CASE version 1.7.0 will be upgraded by the catalog image in CASE ibm-cp-common-services:1.8.1
- Catalog image:           icr.io/ibmcom/ibm-apiconnect-catalog@sha256:98a0cb600be842718b7377c5d270b7d0a27afaf52be448ef682e5e76d0c15278
  Provided by CASE:        ibm-apiconnect
  Resolved CASE version:   3.0.2
  Requested CASE version:  3.0.3
  Catalog image change:    upgraded
  Summary:                 Catalog image icr.io/ibmcom/ibm-apiconnect-catalog@sha256:98a0cb600be842718b7377c5d270b7d0a27afaf52be448ef682e5e76d0c15278 provided by CASE version 3.0.2 will be upgraded by the catalog image in CASE ibm-apiconnect:3.0.3

Summary of potential issues found:
None

OK

Multi CASE being downloaded has a dependency that will be down leveled

Note: The version is optional in the following section.

$ cloudctl case verify-catalog -c ibm-apiconnect -v 3.0.2 -i folderName/verifyDowngradeCatalogCaseCache -s folderName/catalogSourceTextFiles/catalogfile.txt

The catalog images specified on the cluster will be affected by the following:
- Catalog image:           icr.io/cpopen/ibm-common-service-catalog@sha256:62d4e76017c4415deb4a80843e820864b774b1c56ebaebe12cac07cc6e47e0b4
  Provided by CASE:        ibm-cp-common-services
  Resolved CASE version:   1.8.1
  Requested CASE version:  1.8.0
  Catalog image change:    downgraded
  Summary:                 Catalog image icr.io/cpopen/ibm-common-service-catalog@sha256:62d4e76017c4415deb4a80843e820864b774b1c56ebaebe12cac07cc6e47e0b4 provided by CASE version 1.8.1 will be downgraded by the catalog image in CASE ibm-cp-common-services:1.8.0
- Catalog image:           icr.io/ibmcom/ibm-apiconnect-catalog@sha256:98a0cb600be842718b7377c5d270b7d0a27afaf52be448ef682e5e76d0c15278
  Provided by CASE:        ibm-apiconnect
  Resolved CASE version:   3.0.2
  Requested CASE version:  3.0.2
  Catalog image change:    unaffected
  Summary:                 Catalog image icr.io/ibmcom/ibm-apiconnect-catalog@sha256:98a0cb600be842718b7377c5d270b7d0a27afaf52be448ef682e5e76d0c15278 provided by CASE version 3.0.2 will be unaffected by the catalog image in CASE ibm-apiconnect:3.0.2

Summary of potential issues found:
- Catalog image:           icr.io/cpopen/ibm-common-service-catalog@sha256:62d4e76017c4415deb4a80843e820864b774b1c56ebaebe12cac07cc6e47e0b4
  Provided by CASE:        ibm-cp-common-services
  Resolved CASE version:   1.8.1
  Requested CASE version:  1.8.0
  Catalog image change:    downgraded
  Summary:                 Catalog image icr.io/cpopen/ibm-common-service-catalog@sha256:62d4e76017c4415deb4a80843e820864b774b1c56ebaebe12cac07cc6e47e0b4 provided by CASE version 1.8.1 will be downgraded by the catalog image in CASE ibm-cp-common-services:1.8.0

OK

Refresh offline cache with resources index files

$ tree tmp/
tmp/
├── caseDependencyMapping.csv
├── charts
├── ibm-auditlogging-1.9.0-charts.csv
├── ibm-auditlogging-1.9.0-images.csv
├── ibm-auditlogging-1.9.0.tgz
├── ibm-cert-manager-1.8.1+20211021.235959-charts.csv
├── ibm-cert-manager-1.8.1+20211021.235959-images.csv
├── ibm-cert-manager-1.8.1+20211021.235959.tgz
├── ibm-cp-common-services-1.8.1-charts.csv
├── ibm-cp-common-services-1.8.1-images.csv
├── ibm-cp-common-services-1.8.1.tgz
├── ibm-cpp-1.0.0-charts.csv
├── ibm-cpp-1.0.0-images.csv
├── ibm-cpp-1.0.0.tgz
├── ibm-crossplane-bundle-1.1.0-charts.csv
├── ibm-crossplane-bundle-1.1.0-images.csv
├── ibm-crossplane-bundle-1.1.0.tgz
├── ibm-cs-commonui-1.10.1-charts.csv
├── ibm-cs-commonui-1.10.1-images.csv
├── ibm-cs-commonui-1.10.1.tgz
├── ibm-cs-healthcheck-1.8.0-charts.csv
├── ibm-cs-healthcheck-1.8.0-images.csv
├── ibm-cs-healthcheck-1.8.0.tgz
├── ibm-cs-iam-1.8.0-charts.csv
├── ibm-cs-iam-1.8.0-images.csv
├── ibm-cs-iam-1.8.0.tgz
├── ibm-cs-mongodb-1.7.0-charts.csv
├── ibm-cs-mongodb-1.7.0-images.csv
├── ibm-cs-mongodb-1.7.0.tgz
├── ibm-cs-monitoring-1.8.0-charts.csv
├── ibm-cs-monitoring-1.8.0-images.csv
├── ibm-cs-monitoring-1.8.0.tgz
├── ibm-events-operator-3.11.0-charts.csv
├── ibm-events-operator-3.11.0-images.csv
├── ibm-events-operator-3.11.0.tgz
├── ibm-licensing-1.9.0-charts.csv
├── ibm-licensing-1.9.0-images.csv
├── ibm-licensing-1.9.0.tgz
├── ibm-management-ingress-1.8.1-charts.csv
├── ibm-management-ingress-1.8.1-images.csv
├── ibm-management-ingress-1.8.1.tgz
├── ibm-platform-api-operator-1.8.0-charts.csv
├── ibm-platform-api-operator-1.8.0-images.csv
├── ibm-platform-api-operator-1.8.0.tgz
├── ibm-zen-2.3.0+20211011.134600-charts.csv
├── ibm-zen-2.3.0+20211011.134600-images.csv
├── ibm-zen-2.3.0+20211011.134600.tgz
└── resourceIndexes

2 directories, 46 files

$ ~/Downloads/cloudctl-314-dev case refresh-catalog-mapping -i tmp -r http://localhost:3000
OK

$ tree tmp/resourceIndexes/
tmp/resourceIndexes/
├── ibm-auditlogging-resourcesIndex.yaml
├── ibm-cert-manager-resourcesIndex.yaml
├── ibm-cp-common-services-resourcesIndex.yaml
├── ibm-cpp-resourcesIndex.yaml
├── ibm-crossplane-bundle-resourcesIndex.yaml
├── ibm-cs-commonui-resourcesIndex.yaml
├── ibm-cs-healthcheck-resourcesIndex.yaml
├── ibm-cs-iam-resourcesIndex.yaml
├── ibm-cs-mongodb-resourcesIndex.yaml
├── ibm-cs-monitoring-resourcesIndex.yaml
├── ibm-events-operator-resourcesIndex.yaml
├── ibm-licensing-resourcesIndex.yaml
├── ibm-management-ingress-resourcesIndex.yaml
├── ibm-platform-api-operator-resourcesIndex.yaml
└── ibm-zen-resourcesIndex.yaml

0 directories, 15 files