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
- Cloudctl case launch
- Cloudctl case create-images-delta
verify-catalog
cloudctl case command
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:
- Identify all charts from all
resources.yaml
files and store the charts within the charts directory. - Create a list of all charts used by the CASE.
-
Identify the images from the
resources.yaml
files and create a file with a list of the images.Result:
offline/ ibm-cp-datacore-1.0.1.tgz (a CASE) ibm-cp-datacore-1.0.1-images.csv (list of images) ibm-cp-datacore-1.0.1-helm2charts.csv (list of charts) helm2charts/ (Helm 2 chart archives) chart1-1.0.0.tgz (a chart archive)
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:
0
- Success1
- Failure
Case save examples
-
Example 1: This example command shows how to download the specified CASE from GitHub, extract, and parse it, and retrieve the components that make up the CASE.
cloudctl case save --case https://github.com/IBM/cloud-pak/raw/master/repo/case/sample-case-1.0.0.tgz --outputdir /tmp/cache
-
Example 2: This example command shows the same as example one, except the CASE is available locally
cloudctl case save --case /tmp/repo/case/sample-case-1.0.0.tgz --outputdir /tmp/cache
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:
hostport
- Required. The host and optional port for the remote registry where the image resides. The value is the formhost[:port]
.name
- Required. The fully qualified name of the image that is in the registry.tag
- Optional. The tag for the manifest. A tag is used for documentation purposes, since the digest is the authoritative identifier for the manifest.digest
- Required. The OCI formatted digest for the manifest.mtype
- Required. The valueLIST
is set for a manifest list. The valueIMAGE
is set for an image manifest.os
- Required whenMLIST=0
. The operating system for the image, such aslinux
.arch
- Required whenMLIST=0
. The architecture for the image, such asamd64
.variant
- Optional. The variant for the image, such asv7
.insecure
- Optional. The value1
indicates that the image is fetched by usinghttp
. The value0
or no value indicates that the image is fetched by usinghttps
.digestsource
- Required. The valueREGISTRY
indicates that the digest is the current version in the source registry. The valueCASE
indicates that the digest is the version from the CASE.
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:
- Compile a list of all images and run the
oc image mirror
command to pull the images locally. - Build a list of only
amd64
images and run theskopeo copy
command to mirror the images locally. - Build the image path for each image and then update the
hostport
property to point to an internal repository.
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:
0
- Success1
- Failure
Case launch examples
- The following example command runs a CASE launch script for setting up a cluster for the CASE that is found in a
tmp/cache
directory. This script is in theclusterSetup
inventory item and is associated with the setup action.
cloudctl case launch --case /tmp/cache --inventory clusterSetup --action setup --args "--serviceAccount sample-sa1"
- The following example runs the default CASE launcher script for the CASE that is in the
/tmp/cache
directory. An additional argument is included to point to the folder where the CASE was saved to through thecloudctl case save
command.
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:
-
The CASE is modified and the signature validation failed. Each CASE includes a signature to verify the integrity of the contents of the CASE, similar to an md5 hash. If this check fails, the CASE contents are changed from the original state, which can indicate that the CASE might not be the same product that you are installing. However, if you modified the CASE and can verify the contents, you can skip the signature verification by setting the tolerance
--tolerance
flag to1
. -
The prerequisite check failed. A launcher script is associated with an inventory item and an action within the CASE. The action defines cluster prerequisites for the script to run. If the cluster does not meet these prerequisites, the check fails. For more information on how prerequisites are specified in a CASE can be found in the CASE specification for actions.yaml and prereqs.yaml.
-
The script failed. When the launcher script fails, review the script output to determine the root cause. Review the documentation for the product that you are installing to learn how to resolve the issue.
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.
- Use
cloudctl case save
to download the new version of the subcase. - Use
cloudctl case create-image-delta
to create the delta image CSV from the existing offline cache and previously mirrored images list. - Call
cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages
to mirror images.- Read the delta image CSV.
- Make the mirror image request through the bastion server and into the internal container registry.
- Complete the mirror process.
- 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
- Use
cloudctl case save
to download the new version of the subcase. - Use
cloudctl case create-image-delta
to create the delta image CSV from the existing offline cache and previously mirrored images list. - Call
cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages
to mirror images to a local registry on your portable compute device. - Connect the portable compute device to the private network.
- 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. - 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.
- Use
cloudctl case save
to download the new version of the subcase. - Use
cloudctl case create-image-delta
to create the delta image CSV from the existing offline cache and previously mirrored images list. - Call
cloudctl case launch --case ${cache}/${case} --inventory operatorSetup --action mirrorImages
to mirror images to a local registry on your portable compute device. - Save the local registry as a container image on a portable storage device and copy the local cache to the same portable storage device.
- Move the portable storage device inside of the private network and extract.
- 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. - Move the portable storage device to the external network.
- 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.
cloudctl case verify-catalog
shows the images that will be down leveled from what you already have.
For example:
cloudctl case verify-catalog --case <CASE_PATH_OR_URL> --version<VERSION_NUMBER> --inputdir <PATH> --catalog-sources <PATH>
cloudctl case refresh-catalog-mapping
takes the location of the CASE cache and the CASE repository to download (that is, refresh) allresourcesIndex.yaml
files for the CASEs in the offline cache.
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:
- The file passed into
--catalogSources
can be in the following format: - list of catalogimages (one per line)
-
The following is the minimum RBAC needed to run the commands to query cluster for catalog index images. The permissions in the Kubernetes Role must be bound to every namespace queried for catalog index images:
apiVersion: rbac.authorization.k8s.io/v1 kind: Role rules: - apiGroups: - "" resources: - pods verbs: - get - list - apiGroups: - operators.coreos.com resources: - catalogsources verbs: - get - list
Using the following commands, it is possible to get the list of catalog images from a running cluster:
-
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
-
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