Installing the IBM Netcool Operations Insight Event Integrations Operator to a private container registry

Before you begin

You must complete the steps in the following sections before you begin generating mirror manifests:

• Prerequisites

• Prepare a host

• Set environment variables and download CASE files

Important: If you intend on installing using a private container registry, your cluster must support ImageContentSourcePolicy (ICSP).

Prerequisites

Regardless of whether you plan to mirror the images with a bastion host or to the file system, you must satisfy the following prerequisites:

• Red Hat®® OpenShift®® Container Platform requires you to have cluster admin access to run the install-operator command.

• An Red Hat® OpenShift® Container Platform cluster must be installed.

Note: IBM images located on Quay and Docker are being migrated to anonymous locations on icr.io. The following sites and ports might not be required depending on the version of software you are installing.

• Access to the following sites and ports:
  • *.docker.io and *.docker.com: For more information about specific sites to allow access to, see Docker Hub Hosts for Firewalls and HTTP Proxy Servers)
  • icr.io:443 for IBM Cloud® Container Registry, CASE OCI artifact, and IBM Cloud Pak® foundational services catalog source
  • github.com for CASEs and tools

oc ibm-pak config repo 'IBM Cloud-Pak OCI registry' -r oci:cp.icr.io/cpopen --enable

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.

The following table explains the software requirements for mirroring the IBM Netcool Operations Insight Event Integrations Operator images:

Complete the following steps on your host:

Create registry namespaces

Top-level namespaces are the namespaces which 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.

If you do not specify your own top-level namespace, the mirroring process will use the ones which are specified by the CASEs. For example, it will try to mirror the images at myregistry.com:5000/cp, myregistry.com:5000/cpopen etc.

So if your registry does not allow automatic creation of top-level namespaces and you are not going to use your own during generation of mirror manifests, then you must create the following namespaces at the root of your registry.

• cp
• cpopen

There can be more top-level namespaces that you might need to create. See section on Generate mirror manifests for information on how to use the oc ibm-pak describe command to list all the top-level namespaces.

Set environment variables and download CASE files

If your host must connect to the internet via a proxy, you must 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.

Mirror images to your private container registry

The process of mirroring images takes the image from the internet to your host, then effectively copies that image to your private container registry. After you mirror your images, you can configure your cluster and complete air-gapped installation.

Complete the following steps to mirror your images from your host to your private container registry:

1. Generate mirror manifests

2. Authenticating the registry

Complete the following steps to authenticate your registries:

3. Mirror images to final location

Complete the steps in this section on your host that is connected to both the local Docker registry and the Red Hat® OpenShift® Container Platform cluster.

Mirror images to the final location.

• For mirroring from a bastion host (connected mirroring):

  Mirror images to the TARGET_REGISTRY:

   oc image mirror \
     -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
     --filter-by-os '.*'  \
     -a $REGISTRY_AUTH_FILE \
     --insecure  \
     --skip-multiple-scopes \
     --max-per-registry=1 \
     --continue-on-error=true
  

   oc image mirror --help
  

  The above command can be used to see all the options available on the mirror command. Note that we use continue-on-error to indicate that command should try to mirror as much as possible and continue on errors.

  Note: Sometimes based on the number and size of images to be mirrored, the oc image mirror might take longer. If you are issuing the command on a remote machine it is recommended that you run the command in the background with a nohup so even if network connection to your remote machine is lost or you close the terminal the mirroring will continue. For example, the below command will start the mirroring process in background and write the log to my-mirror-progress.txt.

   nohup oc image mirror \
   -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
   -a $REGISTRY_AUTH_FILE \
   --filter-by-os '.*' \
   --insecure \
   --skip-multiple-scopes \
   --max-per-registry=1 \
   --continue-on-error=true > my-mirror-progress.txt  2>&1 &
  

  You can view the progress of the mirror by issuing the following command on the remote machine:

     tail -f my-mirror-progress.txt
  

• For mirroring from a file system (disconnected mirroring):

  Mirror images to your file system:

   export IMAGE_PATH=<image-path>
   oc image mirror \
     -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-to-filesystem.txt \
     --filter-by-os '.*'  \
     -a $REGISTRY_AUTH_FILE \
     --insecure  \
     --skip-multiple-scopes \
     --max-per-registry=1 \
     --continue-on-error=true \
     --dir "$IMAGE_PATH"
  

  The <image-path> refers to the local path to store the images. For example, in the previous section if provided file://local as input during generate mirror-manifests, then the preceding command will create a subdirectory v2/local inside directory referred by <image-path> and copy the images under it.

The following command can be used to see all the options available on the mirror command. Note that continue-on-error is used to indicate that the command should try to mirror as much as possible and continue on errors.

   oc image mirror --help

Note: Sometimes based on the number and size of images to be mirrored, the oc image mirror might take longer. If you are issuing the command on a remote machine, it is recommended that you run the command in the background with nohup so that even if you lose network connection to your remote machine or you close the terminal, the mirroring will continue. For example, the following command will start the mirroring process in the background and write the log to my-mirror-progress.txt.

    export IMAGE_PATH=<image-path>
    nohup oc image mirror \
      -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-to-filesystem.txt \
      --filter-by-os '.*' \
      -a $REGISTRY_AUTH_FILE \
      --insecure \
      --skip-multiple-scopes \
      --max-per-registry=1 \
      --continue-on-error=true \
      --dir "$IMAGE_PATH" > my-mirror-progress.txt  2>&1 &

You can view the progress of the mirror by issuing the following command on the remote machine:

   tail -f my-mirror-progress.txt

4. Configure the cluster

5. Install IBM Netcool Operations Insight Event Integrations Operator by way of Red Hat Open Shift Container Platform

Now that your images are mirrored to your air-gapped environment, you can deploy your IBM Cloud® Paks to that environment. When you mirrored your environment, you created a parallel offline version of everything that you needed to install an operator into Red Hat® OpenShift® Container Platform.

5.1 Create the catalog source and install the IBM Netcool Operations Insight Event Integrations Operator

Important: Before you run any of the oc ibm-pak launch \ command, you must be logged into your cluster. Using theoc login command, log in to the Red Hat OpenShift Container Platform cluster where your final location resides. You can identify your specific oc login by clicking the user drop-down menu in the Red Hat OpenShift Container Platform console, then clicking Copy Login Command.

1. Set the namespace to install the IBM Netcool Operations Insight Event Integrations Operator catalog:

   export NAMESPACE=<YOUR_NAMESPACE>
   

2. Set the environment variable of the --inventory parameter:

   export CASE_INVENTORY_SETUP=netcoolIntegrationsOperatorSetup
   

3. Create and configure a catalog source.

   The recommended way to install the catalog is to run the following command:

   oc apply -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/catalog-sources-linux-amd64.yaml
    

   The following command can also be used to install the catalog:

      oc ibm-pak launch \
      $CASE_NAME \
        --version $CASE_VERSION \
        --action install-catalog \
        --inventory $CASE_INVENTORY_SETUP \
        --namespace $NAMESPACE \
        --args "--registry $TARGET_REGISTRY --recursive \
        --inputDir ~/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION"
   

   .

4. Verify that the CatalogSource for your IBM Netcool Operations Insight Event Integrations Operator is created.

   oc get pods -n openshift-marketplace
   oc get catalogsource -n openshift-marketplace
   

5. Install your IBM Netcool Operations Insight Event Integrations Operator.

   Note: You must have cluster admin access to run the install-operator command. However, you do not need cluster admin access for mirroring.

   oc ibm-pak launch \
      $CASE_NAME \
      --version $CASE_VERSION \
      --inventory $CASE_INVENTORY_SETUP \
      --action install-operator \
      --namespace $NAMESPACE
   

6. Using the oc login command, log in to the Red Hat® OpenShift® Container Platform cluster where your final location resides. You can identify your specific oc login by clicking the user drop-down menu in the Red Hat OpenShift Container Platform console, then clicking Copy Login Command.

7. Verify that your IBM Netcool Operations Insight Event Integrations Operator is installed:

   oc get pod -n $NAMESPACE
   

   It might take up to 15 minutes for all the pods to show the Running status.

Set up a repeatable mirroring process

Once you complete a CASE save, you can mirror the CASE as many times as you want to. This approach allows you to mirror a specific version of the IBM Netcool Operations Insight Event Integrations Operator into development, test, and production stages using a private container registry.

Follow the steps in this section if you want to save the CASE to multiple registries (per environment) once and be able to run the CASE in the future without repeating the CASE save process.

1. Run the following command to save the CASE to ~/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION which can be used as an input during the mirror manifest generation:

   oc ibm-pak get \
   $CASE_NAME \
   --version $CASE_VERSION
   

2. Run the oc ibm-pak generate mirror-manifests command to generate the image-mapping.txt:

   oc ibm-pak generate mirror-manifests \
   $CASE_NAME \
   $TARGET_REGISTRY \
   --version $CASE_VERSION
   

   Note: If you are using a Red Hat® Quay.io registry and need to mirror images to a specific organization in the registry, you can target that organization by specifying:

   oc ibm-pak generate mirror-manifests \
      $CASE_NAME \
      $TARGET_REGISTRY \
      --version $CASE_VERSION
   

   Then add the image-mapping.txt to the oc image mirror command:

   oc image mirror \
     -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
     --filter-by-os '.*'  \
     -a $REGISTRY_AUTH_FILE \
     --insecure  \
     --skip-multiple-scopes \
     --max-per-registry=1 \
     --continue-on-error=true
   

If you want to make this repeatable across environments, you can reuse the same saved CASE cache (~/.ibm-pak/$CASE_NAME/$CASE_VERSION) instead of executing a CASE save again in other environments. You do not have to worry about updated versions of dependencies being brought into the saved cache.