Installing License Service Reporter on disconnected and air gapped cluster

To install License Service Reporter offline by using the ibm-pak plug-in, complete the following steps to download the CASE bundle, mirror images from your host to your private container registry, and create catalog sources:

Prerequisites

Access to the following sites and ports:

Tip: With ibm-pak plug-in version 1.2.0, you can eliminate the port for github.com to retrieve CASES and tooling by configuring 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.

Set the environment and download the 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.

  1. Create the following environment variables with the installer image name and the version.

    export CASE_NAME=ibm-license-service-reporter-bundle
export CASE_VERSION=4.2.4

    To find the CASE name and version, see IBM: Product CASE to Application Version.

  2. Connect your host to the intranet.

  3. The plug-in can detect the locale of your environment and provide textual help and messages. You can optionally set the locale by running the following command:

    oc ibm-pak config locale -l LOCALE

    Where LOCALE can be one of 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 License Service Reporter 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 License Service Reporter to your host.

    Tip: If you do not specify the CASE version, it downloads the latest CASE.

    oc ibm-pak get \
ibm-license-service-reporter-bundle \
--version 4.2.4

By default, the root directory that is used by plug-in is ~/.ibm-pak. This means that the preceding command will download the CASE under ~/.ibm-pak/data/cases/ibm-license-service-reporter-bundle/4.2.4. You can configure this root directory by setting the IBMPAK_HOME environment variable. Assuming IBMPAK_HOME is set, the preceding command will download the CASE under $IBMPAK_HOME/.ibm-pak/data/cases/ibm-license-service-reporter-bundle/4.2.4.

If the download fails, you can try to increase the default values of the HTTP timeout and maximum HTTP retry attempts as required in the IBMPAK_HTTP_TIMEOUT and IBMPAK_HTTP_RETRY flags.

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

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

See the following notes:

Generate mirror manifests

Notes:

Example ~/.ibm-pak directory structure for connected mirroring

The ~/.ibm-pak directory structure is built over time as you save CASEs and mirror. The following tree shows an example of the ~/.ibm-pak directory structure for connected mirroring:

tree ~/.ibm-pak
/root/.ibm-pak
├── config
│   └── config.yaml
├── data
│   ├── cases
│   │   └── $CASE_NAME
│   │       └── $CASE_VERSION
│   │           ├── XXXXX
│   │           ├── XXXXX
│   └── mirror
│       └── $CASE_NAME
│           └── $CASE_VERSION
│               ├── catalog-sources.yaml
│               ├── image-content-source-policy.yaml
│               └── images-mapping.txt
└── logs
   └── oc-ibm_pak.log

Notes: A new directory ~/.ibm-pak/mirror is created when you issue the oc ibm-pak generate mirror-manifests command. This directory holds the image-content-source-policy.yaml, images-mapping.txt, and catalog-sources.yaml files.

Tip: 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:

export ORGANIZATION=<your-organization>
oc ibm-pak generate mirror-manifests
ibm-license-service-reporter-bundle
$TARGET_REGISTRY/$ORGANIZATION
--version 4.2.4

You can also generate manifests to mirror images to an intermediate registry server, then mirroring to a final registry server. This is done by passing the final registry server as an argument to --final-registry:

export INTERMEDIATE_REGISTRY=<your intermediate registry>
export FINAL_REGISTRY=<your final registry>

oc ibm-pak generate mirror-manifests \
   ibm-license-service-reporter-bundle \
   $INTERMEDIATE_REGISTRY \
   --version 4.2.4
   --final-registry $FINAL_REGISTRY

In this case, in place of a single mapping file (images-mapping.txt), two mapping files are created.

  1. images-mapping-to-registry.txt

  2. images-mapping-from-registry.txt

  3. Run the following commands to generate mirror manifests to be used when mirroring from a file system (disconnected mirroring):

oc ibm-pak generate mirror-manifests \
   ibm-license-service-reporter-bundle \
   file://local \
   --final-registry $TARGET_REGISTRY

Example ~/.ibm-pak directory structure for disconnected mirroring

The following tree shows an example of the ~/.ibm-pak directory structure for disconnected mirroring:

   tree ~/.ibm-pak
   /root/.ibm-pak
   ├── config
   │   └── config.yaml
   ├── data
   │   ├── cases
   │   │   └── $CASE_NAME
   │   │       └── $CASE_VERSION
   │   │           ├── XXXX
   │   │           ├── XXXX
   │   └── mirror
   │       └── $CASE_NAME
   │           └── $CASE_VERSION
   │               ├── catalog-sources.yaml
   │               ├── image-content-source-policy.yaml
   │               ├── images-mapping-to-filesystem.txt
   │               └── images-mapping-from-filesystem.txt
   └── logs
      └── oc-ibm_pak.log

Note: A new directory ~/.ibm-pak/mirror is created when you issue the oc ibm-pak generate mirror-manifests command. This directory holds the image-content-source-policy.yaml, images-mapping-to-filesystem.txt, images-mapping-from-filesystem.txt, and catalog-sources.yaml files.

Tip: Some products support the ability to generate mirror manifests only for a subset of images by using the --filter argument and image grouping. The --filter argument provides the ability to customize which images are mirrored during an air-gapped installation. As an example for this function, ibm-license-service-reporter-bundle CASE can be used, which contains groups that allow mirroring-specific variant of ibm-license-service-reporter-bundle (Standard or Enterprise). Use the --filter argument to target a variant of ibm-license-service-reporter-bundle to mirror rather than the entire library. The filtering can be applied for groups and architectures. Consider the following command:

   oc ibm-pak generate mirror-manifests \
      ibm-license-service-reporter-bundle \
      file://local \
      --final-registry $TARGET_REGISTRY \
      --filter $GROUPS

The command was updated with a --filter argument. For example, for $GROUPS equal to ibmEdbStandard the mirror manifests will be generated only for the images associated with ibm-license-service-reporter-bundle in its Standard variant. The resulting image group consists of images in the ibm-license-service-reporter-bundle image group in addition to any images that are not associated with any groups. This allows products to include common images and the ability to reduce the number of images that you need to mirror.

Note: You can use the following command to list all the images that will be mirrored and the publicly accessible registries from where those images will be pulled from:

   oc ibm-pak describe ibm-license-service-reporter-bundle --version 4.2.4 --list-mirror-images

Tip: The output of the preceding command will have two sections:

  1. Mirroring Details from Source to Target Registry

  2. Mirroring Details from Target to Final Registry. A connected mirroring path that does not involve an intermediate registry will only have the first section.

    Note down the Registries found sub sections in the preceding command output. You will need to authenticate against those registries so that the images can be pulled and mirrored to your local registry. See the next steps on authentication. The Top-level namespaces found section shows the list of namespaces under which the images will be mirrored. These namespaces should be created manually in your registry (which appears in the Destination column in the preceding command output) root path if your registry does not allow automatic creation of namespaces.

Authenticating the registry

Complete the following steps to authenticate your registries:

  1. Store authentication credentials for all source Docker registries.

    Your product might require one or more authenticated registries. The following registries require authentication:

    • cp.icr.io
    • registry.redhat.io
    • registry.access.redhat.com

    You must run the following command to configure credentials for all target registries that require authentication. Run the command separately for each registry:

    Note: The export REGISTRY_AUTH_FILE command only needs to run once.

    export REGISTRY_AUTH_FILE=<path to the file which will store the auth credentials generated on podman login>
podman login <TARGET_REGISTRY>

    Important: When you log in to cp.icr.io, you must specify the user as cp and the password, which is your Entitlement key from the IBM Cloud Container Registry. For example:

    podman login cp.icr.io
Username: cp
Password:
Login Succeeded!

For example, if you export REGISTRY_AUTH_FILE=~/.ibm-pak/auth.json, then after performing podman login, you can see that the file is populated with registry credentials.

If you use docker login, the authentication file is typically at $HOME/.docker/config.json on Linux or %USERPROFILE%/.docker/config.json on Windows. After docker login you should export REGISTRY_AUTH_FILE to point to that location. For example, in Linux you can issue the following command:

export REGISTRY_AUTH_FILE=$HOME/.docker/config.json
Table 2. Directory description
Directory Description
~/.ibm-pak/config Stores the default configuration of the plug-in and has information about the public GitHub URL from where the cases are downloaded.
~/.ibm-pak/data/cases This directory stores the CASE files when they are downloaded by issuing the oc ibm-pak get command.
~/.ibm-pak/data/mirror This directory stores the image-mapping files, ImageContentSourcePolicy manifest in image-content-source-policy.yaml and CatalogSource manifest in one or more catalog-sourcesXXX.yaml. The files images-mapping-to-filesystem.txt and images-mapping-from-filesystem.txt are input to the oc image mirror command, which copies the images to the file system and from the file system to the registry respectively.
~/.ibm-pak/data/logs This directory contains the oc-ibm_pak.log file, which captures all the logs that are generated by the plug-in.

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 OpenShift Container Platform cluster.

  1. 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/ibm-license-service-reporter-bundle/4.2.4/images-mapping.txt \
   --filter-by-os '.*'  \
   -a $REGISTRY_AUTH_FILE \
   --insecure  \
   --skip-multiple-scopes \
   --max-per-registry=1 \
   --continue-on-error=true

      If you generated manifests in the previous steps to mirror images to an intermediate registry server followed by a final registry server, run the following commands:

      1. Mirror images to the intermediate registry server:

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

      2. Mirror images from the intermediate registry server to the final registry server:

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

        The oc image mirror --help command can be run to see all the options available on the mirror command. Note that we use continue-on-error 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 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 following 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/ibm-license-service-reporter-bundle/4.2.4/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/ibm-license-service-reporter-bundle/4.2.4/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 that is 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/ibm-license-service-reporter-bundle/4.2.4/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

  2. For disconnected mirroring only: Continue to move the following items to your file system:

    • The <image-path> directory that you specified in the previous step
    • The auth file referred by $REGISTRY_AUTH_FILE
    • ~/.ibm-pak/data/mirror/ibm-license-service-reporter-bundle/4.2.4/images-mapping-from-filesystem.txt

  3. For disconnected mirroring only: Mirror images to the target registry from file system

    Complete the steps in this section on your file system to copy the images from the file system to the $TARGET_REGISTRY. Your file system must be connected to the target docker registry.

    Important: If you used the placeholder value of TARGET_REGISTRY as a parameter to --final-registry at the time of generating mirror manifests, then before running the following command, find and replace the placeholder value of TARGET_REGISTRY in the file, images-mapping-from-filesystem.txt, with the actual registry where you want to mirror the images. For example, if you want to mirror images to myregistry.com/mynamespace then replace TARGET_REGISTRY with myregistry.com/mynamespace.

    1. Run the following command to copy the images (referred in the images-mapping-from-filesystem.txt file) from the directory referred by <image-path> to the final target registry:

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

Configure the cluster

  1. Update the global image pull secret for your Red Hat OpenShift Container Platform cluster. Follow the steps in Updating the global cluster pull secret.

    The documented steps in the link enable your cluster to have proper authentication credentials in place to pull images from your TARGET_REGISTRY as specified in the image-content-source-policy.yaml which you will apply to your cluster in the next step.

  2. Create ImageContentSourcePolicy

    Important:

    • Before you run the command in this step, you must be logged in to your OpenShift cluster. 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.

      • If you used the placeholder value of TARGET_REGISTRY as a parameter to --final-registry at the time of generating mirror manifests, then before running the following command, find and replace the placeholder value of TARGET_REGISTRY in file, ~/.ibm-pak/data/mirror/ibm-license-service-reporter-bundle/4.2.4/image-content-source-policy.yaml with the actual registry where you want to mirror the images. For example, replace TARGET_REGISTRY with myregistry.com/mynamespace.

    Run the following command to create ImageContentSourcePolicy:

       oc apply -f  ~/.ibm-pak/data/mirror/ibm-license-service-reporter-bundle/4.2.4/image-content-source-policy.yaml

    If you are using Red Hat OpenShift Container Platform version 4.7 or earlier, this step might cause your cluster nodes to drain and restart sequentially to apply the configuration changes.

  3. Verify that the ImageContentSourcePolicy resource is created.

    oc get imageContentSourcePolicy

  4. Verify your cluster node status and wait for all the nodes to be restarted before proceeding.

    oc get MachineConfigPool

    $ oc get MachineConfigPool -w
NAME     CONFIG                                             UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
master   rendered-master-53bda7041038b8007b038c08014626dc   True      False      False      3              3                   3                     0                      10d
worker   rendered-worker-b54afa4063414a9038958c766e8109f7   True      False      False      3              3                   3                     0                      10d

    After the ImageContentsourcePolicy and global image pull secret are applied, the configuration of your nodes will be updated sequentially. Wait until all MachineConfigPools are in the UPDATED=True status before proceeding.

  5. Create a new project for the CASE commands by running the following commands:

    Note: You must be logged in to a cluster before performing the following steps.

    export LSR_NAMESPACE=<YOUR_NAMESPACE>

    oc new-project $LSR_NAMESPACE

  6. Optional: If you use an insecure registry, you must add the target registry to the cluster insecureRegistries list.

    oc patch image.config.openshift.io/cluster --type=merge \
-p '{"spec":{"registrySources":{"insecureRegistries":["'${TARGET_REGISTRY}'"]}}}'

  7. Verify your cluster node status and wait for all the nodes to be restarted before proceeding.

    oc get MachineConfigPool -w

    After the ImageContentsourcePolicy and global image pull secret are applied, the configuration of your nodes will be updated sequentially. Wait until all MachineConfigPools are updated.

Create the catalog source and install License Service Reporter

Important: Before you run any of the oc ibm-pak launch command, you must be logged in to your cluster. 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.

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

    export CASE_INVENTORY_SETUP=<YOUR_CASE_INVENTORY_SETUP>

  2. 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/ibm-license-service-reporter-bundle/4.2.4/catalog_sources.yaml

  3. Verify that the CatalogSource for your License Service Reporter operator is created.

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

Installing the operator from OperatorHub (console)

  1. In the All Items field, enter IBM License Service Reporter. The IBM License Service Reporter operator is displayed.

  2. Click the IBM License Service Reporter tile. The IBM License Service Reporter window is displayed.

  3. Click Install. You see the Install Operator page.

  4. Set Update Channel to the v4.2 version.

  5. Set Installation Mode to All namespaces on the cluster (default).

  6. Set Update approval to Automatic.

  7. Click Install.

Installing the operator using CLI

Run the following command:

cat <<EOF | oc apply -f -
apiVersion: v1
kind: Namespace
metadata:
  name: ${LSR_NAMESPACE}
---
apiVersion: operators.coreos.com/v1alpha2
kind: OperatorGroup
metadata:
  name: operatorgroup
  namespace: ${LSR_NAMESPACE}
spec:
  targetNamespaces:
  - ${LSR_NAMESPACE}
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-license-service-reporter-operator
  namespace: ${LSR_NAMESPACE}
spec:
  channel: v4.2
  installPlanApproval: Automatic
  name: ibm-license-service-reporter-operator
  source: ibm-license-service-reporter-bundle-catalog
  sourceNamespace: openshift-marketplace
EOF

Installing the operator using script

  1. If you want to migrate IBM License Service Reporter and licensing, you can add ./setup_singleton.sh --license-accept --operator-namespace <Cloud Pak 2 Fooundational Service Namespace> --enable-licensing.

    Note: Ensure that IBM License Service Reporter and licensing catalogsources exist in the openshift-marketplace namespace.

  2. If it is a fresh install, execute the following script:

    ./setup_singleton.sh --license-accept --enable-licensing

Create the License Service Reporter instance

Creating a License Service Reporter instance in the OpenShift console

Complete the following steps to create the License Service Reporter instance with the OpenShift console:

  1. Log in to your OpenShift cluster console.

  2. Go to Operators > Installed Operators.

  3. Set the project to All Projects.

  4. Find and select the IBM License Service Reporter.

  5. On the IBM License Service Reporter tile, click Create IBMLicenseServiceReporter.

    The image shows the IBM License Service Reporter view in the cluster console.

  6. Review the contents of the editor and make sure that the content matches the following definition:

     apiVersion: operator.ibm.com/v1alpha1
 kind: IBMLicenseServiceReporter
 metadata:
   name: ibm-lsr-instance
   namespace: <your License Service Reporter namespace>
   labels:
     app.kubernetes.io/created-by: ibm-license-service-reporter-operator
     app.kubernetes.io/instance: ibmlicenseservicereporter-instance
     app.kubernetes.io/name: ibmlicenseservicereporter
     app.kubernetes.io/part-of: ibm-license-service-reporter-operator
 spec:
   license:
     accept: true
   authentication:
     useradmin:
       enabled: true

    Note: License Service Reporter uses the default storage class. To use a different storage class, add and define the 'storageClass' parameter in the spec section. For example:

    spec:
   storageClass: storage-class-internal

  7. To apply the changes, click Create.

Creating the License Service Reporter instance with the CLI

  1. Create the license-reporter.yaml file with the following content:

    apiVersion: operator.ibm.com/v1alpha1
kind: IBMLicenseServiceReporter
metadata:
  name: ibm-lsr-instance
  namespace: ${LSR_NAMESPACE}
  labels:
    app.kubernetes.io/created-by: ibm-license-service-reporter-operator
    app.kubernetes.io/instance: ibmlicenseservicereporter-instance
    app.kubernetes.io/name: ibmlicenseservicereporter
    app.kubernetes.io/part-of: ibm-license-service-reporter-operator
spec:
  license:
    accept: true
  authentication:
    useradmin:
      enabled: true

    Note: License Service Reporter uses the default storage class. To use a different storage class, add and define the 'storageClass' parameter in the spec section in the license-reporter.yaml file. For example:

    spec:
  storageClass: storage-class-internal

  2. Run the following command:

    envsubst < license-reporter.yaml | oc apply -f -