Prerequisites before you begin generating mirror manifests

Ensure that you meet the requirements, host is prepared, environment variables are set, and CASE files are downloaded before you begin generating mirror manifests in an air gap environment.

Prerequisites

Regardless of whether you plan to mirror the images with a bastion host or to the file system, you must meet the following prerequisites:
  • Cluster admin access to run the install-operator command.
  • Access to icr.io:443 for IBM Cloud Container Registry, CASE OCI artifact, and IBM Sterling Order Management Operator catalog source.

Prepare a host

If you are in an air-gapped environment, you must be able to connect a host to the internet and mirror registry for connected mirroring or mirror images to file system which can be brought to a restricted environment for disconnected mirroring.

For information about the latest supported operating systems, see ibm-pak plugin install documentation.

The following table explains the software requirements for mirroring the IBM Sterling Order Management Operator images:

Software Purpose
Docker Container management
Podman Container management
Red Hat OpenShift CLI (oc) Red Hat OpenShift Container Platform administration

Complete the following steps on your host:

  1. Install Docker or Podman.
    • To install Docker, for example on Red Hat Enterprise Linux, run the following command:
      yum check-update
yum install docker
    • To install Podman, see Podman installation instructions.
  2. Install the oc Red Hat OpenShift Container Platform CLI tool.
  3. Download and install the latest version of IBM Catalog Management Plug-in for IBM Cloud Paks from the IBM/ibm-pak. Extract the binary file by entering the following command:
    tar -xf oc-ibm_pak-linux-amd64.tar.gz
    • Run the following command to move the file to the /usr/local/bin directory:
      Note: If you are installing as a non-root user, you must use sudo. For more information, see Podman or Docker documentation to install as a non-root user.
      mv oc-ibm_pak-linux-amd64 /usr/local/bin/oc-ibm_pak
      Note: Download the plug-in based on the host operating system. You can confirm that oc ibm-pak -h is installed by running the following command:
      oc ibm-pak --help
      The plug-in usage is displayed. For more information on plug-in commands, see command-help.

      The plug-in is also provided in a container image cp.icr.io/cpopen/cpfs/ibm-pak:TAGwhere TAG should be replaced with the corresponding plug-in version. For example, the TAG (plug-in version) in cp.icr.io/cpopen/cpfs/ibm-pak:v1.2.0 is v1.2.0.

      The following command creates a container and copy the plug-ins for all the supported platforms in a directory, plugin-dir. You can specify any directory name and it is created while copying. After copying, it deletes the temporary container. The plugin-dir contains binaries and other artifacts that are available in IBM/ibm-pak GitHub release and repo.
      id=$(docker create cp.icr.io/cpopen/cpfs/ibm-pak:TAG - )
docker cp $id:/ibm-pak plugin-dir
docker rm -v $id
cd plugin-dir

Creating registry namespaces

Top-level namespaces are the namespaces that appear at the root path of your private registry. For example, if your registry is hosted at myregistry.com:5000, then mynamespace in myregistry.com:5000/mynamespace is defined as a top-level namespace. There can be many top-level namespaces.

When the images are mirrored to your private registry, it is required that the top-level namespace where images are getting mirrored already exists or can be automatically created during the image push. If your registry does not allow automatic creation of top-level namespaces, you must create them manually.

When you generate mirror manifests, you can specify the top-level namespace where you want to mirror the images by setting TARGET_REGISTRY to myregistry.com:5000/mynamespace which has the benefit of needing to create only one namespace, mynamespace in your registry if it does not allow automatic creation of namespaces. The top-level namespaces can also be provided in the final registry by using --final-registry.
  • cp
  • cpopen
There can be more top-level namespaces that you might need to create. For more information about using the oc ibm-pak describe command to list all the top-level namespaces, see Generating mirror manifests.

Set environment variables and download CASE files

To connect your host to the internet via a proxy, set environment variables on the machine that accesses the internet via the proxy server.

If you are mirroring via connected mirroring, set the following environment variables on the machine that accesses the internet via the proxy server.
export https_proxy=http://proxy-server-hostname:port
export http_proxy=http://proxy-server-hostname:port

# Example:
export https_proxy=http://server.proxy.xyz.com:5018
export http_proxy=http://server.proxy.xyz.com:5018

Before mirroring your images, you can set the environment variables on your mirroring device, and connect to the internet so that you can download the corresponding CASE files. To finish preparing your host, complete the following steps:

Note: Save a copy of your environment variable values to a text editor. You can use that file as a reference to cut and paste from when you finish mirroring images to your registry.
  1. Create the following environment variables with the installer image name and the version.
    export CASE_NAME=<case name> # ibm-oms-pro-case for Professional Edition and ibm-oms-ent-case for Enterprise Edition
export CASE_VERSION=<YOUR_CASE_VERSION> # the case number you want to use

    To find the CASE name and version, see IBM Sterling Order Management Professional Case or IBM Sterling Order Management Enterprise Case.

  2. Connect your host to the intranet.
  3. The plug-in can detect the locale of your environment and provide textual helps and messages accordingly. You can optionally set the locale by running the following command:
    oc ibm-pak config locale -l LOCALE
    The LOCALE in the command can be any of these values, de_DE, en_US, es_ES, fr_FR, it_IT, ja_JP, ko_KR, pt_BR, zh_Hans, zh_Hant.
  4. Configure the plug-in to download CASEs as OCI artifacts from IBM Cloud Container Registry (ICCR).
    oc ibm-pak config repo 'IBM Cloud-Pak OCI registry' -r oci:cp.icr.io/cpopen --enable
  5. Enable color output (optional with v1.4.0 and later).
    oc ibm-pak config color --enable true
  6. Download the image inventory for your IBM Sterling Order Management Operator to your host.
    Tip: If you do not specify the CASE version, the latest CASE is downloaded.
    oc ibm-pak get $CASE_NAME --version $CASE_VERSION

    By default, the root directory that is used by plug-in is ~/.ibm-pak. This means that the preceding command downloads the CASE under ~/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION. You can configure this root directory by setting the IBMPAK_HOME environment variable. Assuming IBMPAK_HOME is set, the preceding command downloads the CASE under $IBMPAK_HOME/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION.

    The logs files are available at $IBMPAK_HOME/.ibm-pak/logs/oc-ibm_pak.log.

    Your host is now configured and you are ready to mirror your images.

Note:
  • Starting with v1.4.0, the plug-in creates a file, component-set-config.yaml, in the directory~/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION to download the CASEs with oc ibm-pak get. This file captures all the CASEs that were downloaded, pinning down their exact versions during this particular download. You can use this file later to download the same CASEs with same versions in another environment. You can check in this file to see your source code repository and re-create the same environment each time you use this to download the CASEs. Run the following command:
    oc ibm-pak get -c file:///home/user/ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION/component-set-config.yaml
  • The path after file:// must be an absolute path.
  • You can also edit this file which defines the CASEs with pinned down versions that should include your product, as shown in the following my-csc.yaml example.
       yaml
   name: "example-product"                         # <required> defines the name for the "product"; this is NOT a CASE name, but follows IBM CASE name rules. For more information, see https://ibm.biz/case-yaml
   version: "1.0.0"                                # <required> defines a version for the "product"
   description: "an example product targeting OCP 4.9" # <optional, but recommended> defines a human readable description for this listing of components
   cases:                                          # list of CASEs. First item in the list is assumed to be the "top-level" CASE, and all others are dependencies
  - name: ibm-mas
    version: 5.5.2
    launch: true                                  # Exactly one CASE should have this field set to true. The launch scripts of that CASE are used as an entry point while executing 'ibm-pak launch' with a ComponentSetConfig
  - name: ibm-cp-common-services
    version: 1.15.2