Installation via CASE

The Container Application Software for Enterprises (CASE) provides a common packaging definition for the many ways to install, manage, operate, upgrade, and uninstall complex software using multiple roles and personas.

Prerequisites
CASE inventory
datapowerOperator actions

Prerequisites

To install the CASE, you must have:

Downloaded the ibm-datapower-operator CASE bundle.
Installed the cloudctl tool v3.9.0+.
An OCP 4.6+ cluster.

CASE inventory

The IBM CASE structure has a concept of inventory items. These items are discrete sets of functionality; installing the DataPower Operator, for example. The DataPower Operator CASE has two primary inventory items: datapowerOperator and kibanaDashboard.

The datapowerOperator inventory item contains multiple scripted installation actions to install and uninstall the Operator either with OLM or using standard Kubernetes objects (Deployments). There are additional actions for configuring your cluster to support air-gapped installation of the Operator and DataPower Firmware. The kibanaDashboard item simply contains the dashboard json along with instructions for importing it in the README.

The DataPower Operator CASE also contains a set of DataPower Operand inventory items which allow for the selection of the correct DataPower Operand for your license type during installation.

datapowerOperator actions

Prior to running any actions for datapowerOperator, you must save the CASE bundle:

cloudctl case save \
   --repo $CASE_REPO_PATH \
   --case $CASE_NAME \
   --version $CASE_VERSION \
   --outputdir $OFFLINEDIR

Where:

$CASE_REPO_PATH is the URL of the CASE repository, i.e. https://github.com/IBM/cloud-pak/raw/master/repo/case.
$CASE_NAME is the name of the CASE, i.e. ibm-datapower-operator.
$CASE_VERSION is the target DataPower Operator version, i.e. 1.5.0.
$OFFLINEDIR is the absolute path to the intended output directory.

See Installing IBM Cloud Pak foundational services in an air-gapped environment for details.

The above command will distill the CASE into various artifacts contained in $OFFLINEDIR for processing by the actions.

Available datapowerOperator actions, in the order they would typically be run:

1. configure-creds-airgap
2. init-registry
3. start-registry
4. mirror-images
5. stop-registry
6. configure-cluster-airgap
7. install-catalog
8. install-operator
9. uninstall-operator
10. uninstall-catalog
11. install-operator-native
12. uninstall-operator-native

1. `configure-creds-airgap`

Configure credentials for airgap installation.

Run this action to save the credentials needed for the target and source container image registries. This command will be run twice, once for the source and once for the target.

Arguments

--registry               : source/target container image registry (required)
--user                   : login user name for the container image registry (required)
--pass                   : login password for the container image registry (required)

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action configure-creds-airgap \
  --args "--registry $SOURCE_REGISTRY --user $SOURCE_REGISTRY_USER --pass $SOURCE_REGISTRY_PASS"
cloudctl case launch \
  --case /path/to/case \

Where:

$SOURCE_REGISTRY is the URL of the source image registry, i.e. docker.io.
$TARGET_REGISTRY is the URL of the internal image registry which will host the mirrored images.
$SOURCE_REGISTRY_USER and $TARGET_REGISTRY_USER are the usernames for the respective registries.
$SOURCE_REGISTRY_PASS and $TARGET_REGISTRY_PASS are the passwords for the respective registries.

2. `init-registry`

Initialize a Docker registry locally.

This action will setup a Docker registry on your localhost. This is intended to be used as a staging area for image-mirroring before physically migrating the registry behind your firewall.

Arguments

--user                   : login user name for the container image registry
--pass                   : login password for the container image registry
--dir                    : local directory for the docker registry (default: /tmp/docker-registry)
--subject                : self-sign TLS certificate subject
--registry               : IP or FQDN for the docker registry ( default: $(hostname -f))
--clean                  : clean up all existing repositories data

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action init-registry \
  --args "[args]"

3. `start-registry`

Start a local Docker registry.

This action starts the Docker registry created by init-registry.

Arguments

--port                   : registry service port (default: 5000 )
--dir                    : local directory for the docker registry (default: /tmp/docker-registry)
--engine                 : container engine to run the container (docker or podman)
--image                  : docker registry image (default: docker.io/library/registry:2.6)

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action start-registry \
  --args "[args]"

4. `mirror-images`

Mirror images from a public source repository to an internal target repository.

Run this action to copy all images required by the CASE from their original source registries into your internal registry. All images copied in this way will maintain their namespace/registry path. For example, mirroring docker.io/ibmcom/datapower:10.0.0.0 to my-registry.io will result in the image my-registry.io/ibmcom/datapower:10.0.0.0. Must supply the Image Group appropriate for your license.

`license.use`	Image Group
`production`	`ibmdpProd`
`nonproduction`	`ibmdpNonprod`
`developers`	`ibmdpDeved`
`developers-limited`	`ibmdpLimited`

When deploying within IBM Cloud Pak for Integration, use image group ibmdpCp4i.

For more details regarding deployment within IBM Cloud Pak for Integration, see Cloud Pak for Integration: Instantiating gateway functionality with DataPower.

Arguments

--dryRun                 : print the actions that would be taken and exit without writing to the destinations
--inputDir               : path to saved CASE directory (required)
--fromRegistry           : override the source image registry in the CASE
--registry               : target container image registry (required)
--chunks                 : mirror the images in batches with a given size. Default is 100
--groups                 : comma-separated list of image groups to mirror

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action mirror-images \
  --args "--registry $TARGET_REGISTRY --inputDir /tmp/cases --groups $IMAGE_GROUP"

Where $TARGET_REGISTRY is the URL of the internal mirroring image registry and $IMAGE_GROUP is the correct Image Group for your license type.

5. `stop-registry`

Stop a local Docker registry.

This action stops the Docker registry started by start-registry. Run this action only after you’ve completed the mirroring process.

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action stop-registry

6. `configure-cluster-airgap`

Configure cluster to utilize mirrored image registry.

This command deploys an ImageContentSourcePolicy that redirects image pull requests of Pods from their original source to the internal target registry.

Arguments

--dryRun                 : print the actions that would be taken and exit without writing to the destinations
--inputDir               : path to saved CASE directory
--registry               : target container image registry (required)

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action configure-cluster-airgap \
  --args "--registry $TARGET_REGISTRY --inputDir /tmp/cases"

7. `install-catalog`

Install the CatalogSource object to your cluster.

This command deploys the OLM CatalogSource object into the cluster in the openshift-marketplace namespace. Once the CatalogSource is in the OCP cluster, the DataPower Operator will become a tile in the OCP Operator UI. The CatalogSource is required to create a Subscription to the DataPower Operator.

This action must be taken prior to install-operator.

Arguments

--dryRun                 : print the actions that would be taken and exit without writing to the destinations
--registry               : target container image registry
--recursive              : recursively install dependent catalogs
--inputDir               : path to saved CASE directory ( required if --recurse is set)

`--registry`

A target registry can be specified for pulling the CatalogSource image. If an ImageContentSourcePolicy is in place on the cluster, this argument shouldn’t be required.

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action install-catalog \
  --args "--registry $TARGET_REGISTRY"

8. `install-operator`

Install the Operator via OLM Subscription.

This command installs the DataPower Operator by way of OLM Subscription. A Subscription yaml is applied to the cluster in the namespace provided. If an OperatorGroup is not already present, one will be created.

Arguments

--dryRun                 : print the actions that would be taken and exit without writing to the destinations
--channelName            : name of channel for subscription (packagemanifest default used if not specified)
--secret                 : name of existing image pull secret for the container image registry
--registry               : container image registry (required if pass|user specified)
--user                   : login user name for the container image registry (required if registry|pass specified)
--pass                   : login password for the container image registry (required if registry|user specified)

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action install-operator

9. `uninstall-operator`

Uninstall the Operator OLM Subscription.

This command uninstalls the Operator by removing the OLM Subscription from the provided namespace.

All Operator Subscriptions should be uninstalled before uninstalling the CatalogSource.

Arguments

--dryRun                 : print the actions that would be taken and exit without writing to the destinations

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action uninstall-operator

10. `uninstall-catalog`

Uninstall the Operator CatalogSource.

This command removes the CatalogSource from the cluster.

Arguments

--dryRun                 : print the actions that would be taken and exit without writing to the destinations
--recursive              : recursively install dependent catalogs
--inputDir               : path to saved CASE directory ( required if --recurse is set)

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action uninstall-catalog

11. `install-operator-native`

Install the Operator using standard Kubernetes resources.

This command deploys the DataPower Operator using standard Kubernetes resources, namely Deployment. Installing this way will not benefit from any of OLM’s functionality.

Arguments

--secret                 : name of existing image pull secret for the container image registry
--registry               : container image registry (required if pass|user specified)
--user                   : login user name for the container image registry (required if pass specified)
--pass                   : login password for the container image registry (required if user specified)
--recursive              : recursively install dependent catalogs
--inputDir               : path to saved CASE directory ( required if --recurse is set)

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action install-operator-native

12. `uninstall-operator-native`

Uninstall DataPower Operator which was installed using native Kubernetes resources.

Arguments

--deleteCRDs             : deletes CRD's associated with this operator (if not set, crds won't get deleted)
--recursive              : recursively install dependent catalogs
--inputDir               : path to saved CASE directory ( required if --recurse is set)

Example

cloudctl case launch \
  --case /path/to/case \
  --namespace my-namespace \
  --inventory datapowerOperator \
  --action uninstall-operator-native

Edit this page on GitHub

Install: Installation via OLM

Uninstall: Uninstalling

Installation via CASE

Prerequisites

CASE inventory

datapowerOperator actions

1. configure-creds-airgap

Arguments

Example

2. init-registry

Arguments

Example

3. start-registry

Arguments

Example

4. mirror-images

Arguments

Example

5. stop-registry

Example

6. configure-cluster-airgap

Arguments

Example

7. install-catalog

Arguments

--registry

Example

8. install-operator

Arguments

Example

9. uninstall-operator

Arguments

Example

10. uninstall-catalog

Arguments

Example

11. install-operator-native

Arguments

Example

12. uninstall-operator-native

Arguments

Example

1. `configure-creds-airgap`

2. `init-registry`

3. `start-registry`

4. `mirror-images`

5. `stop-registry`

6. `configure-cluster-airgap`

7. `install-catalog`

`--registry`

8. `install-operator`

9. `uninstall-operator`

10. `uninstall-catalog`

11. `install-operator-native`

12. `uninstall-operator-native`