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).

Commands

Cloudctl case save
Cloudctl case launch

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 - Success
1 - 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 form host[: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 value LIST is set for a manifest list. The value IMAGE is set for an image manifest.
os - Required when MLIST=0. The operating system for the image, such as linux.
arch - Required when MLIST=0. The architecture for the image, such as amd64.
variant - Optional. The variant for the image, such as v7.
insecure - Optional. The value 1 indicates that the image is fetched using http. The value 0 or no value indicates that the image is fetched using https.
digestsource - Required. The value REGISTRY indicates that the digest is the current version in the source registry. The value CASE 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 the skopeo 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 launch 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 - Success
1 - 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 the clusterSetup 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 the cloudctl 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 to 1.
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.