Installing the Manager in an offline environment

If you are working in an environment where your cluster is not connected to the internet, you can install Event Endpoint Management by using the container-based software that is provided as a Container Application Software for Enterprises (CASE) bundle.

CASE is a specification that defines metadata and structure for packaging, managing, and unpacking containerized applications. When deploying in an offline (also referred to as air-gapped or disconnected) environment, you mimic a typical online installation by using images in your own registry. You can use the CASE content to mirror images to an internal registry within your restricted environment, and to install the images from that registry.

Follow the instructions to download the Event Endpoint Management CASE bundle, mirror the image, apply the catalog source, and install the operator on OpenShift and other Kubernetes platforms.

Note: For completing tasks by using the command line, you can use both kubectl and oc commands if your deployment is on the OpenShift Container Platform. This documentation set includes instructions that use the kubectl command, except for cases where the task is specific to OpenShift.

Prerequisites

Ensure you have the following set up for your environment:

A computer with access to both the public internet and the network-restricted environment on which you can run the required commands. This computer must also have access to a local registry and to the OpenShift Container Platform clusters, and is referred to as a bastion host.
Docker or Podman CLI installed.
A private container registry that can be accessed by the cluster and the bastion host, and which will be used to store all images in your restricted network.

Important: If your private container registry is using a self-signed certificate, ensure that the certificate is trusted by your OpenShift or Kubernetes cluster. Contact your cluster vendor for more information.
The IBM Catalog Management Plug-in for IBM Cloud Paks (ibm-pak) installed. This plug-in allows you to run kubectl ibm-pak commands against the cluster. To run kubectl ibm-pak commands, complete the following steps:
1. Download the recent version of the ibm-pak plug-in for your architecture and operating system.
2. Extract the downloaded plug-in and add the plug-in to the kubectl-ibm_pak directory. For example, to add the oc-ibm_pak-darwin-arm64.tar.gz plug-in to the kubectl-ibm_pak directory, run:
```
KUBECTL_PATH="$(dirname $(which kubectl))"
tar xvf oc-ibm_pak-darwin-arm64.tar.gz -C ${KUBECTL_PATH} --exclude LICENSE
mv ${KUBECTL_PATH}/oc-ibm_pak-darwin-arm64 ${KUBECTL_PATH}/oc-ibm_pak
ln ${KUBECTL_PATH}/oc-ibm_pak ${KUBECTL_PATH}/kubectl-ibm_pak
```
  Note: If you are running on macOS, remove the quarantine:
```
xattr -d com.apple.quarantine /opt/homebrew/bin/oc-ibm_pak
```
3. Run the following command to confirm that ibm-pak is installed:
```
kubectl ibm-pak --help
```

If you are using Red Hat OpenShift Container Platform, ensure you have the following set up for your environment:

A supported version of OpenShift Container Platform installed. For supported versions, see the support matrix.
The OpenShift Container Platform CLI (oc) installed.

If you are using other Kubernetes platforms, ensure you have the following set up for your environment:

A supported version of a Kubernetes platform installed. For supported versions, see the support matrix.
The Kubernetes command-line tool (kubectl) installed.
The Helm command-line tool (helm) installed.
Skopeo installed to move images from one repository to another.

Prepare your host

You must be able to connect your bastion host to the internet and to the restricted network environment (with access to the OpenShift Container Platform cluster and the local registry) at the same time.

Ensure that the prerequisites are set up and that the bastion host can access:

The public internet to download the CASE and images.
The target (internal) image registry where all the images will be mirrored to.
The OpenShift or other Kubernetes cluster to install the operator on.

Note: In the absence of a bastion host, prepare a portable device with public internet access to download the CASE and images and a target registry where the images will be mirrored.

Important: Ensure you have access to the Kubernetes cluster by running the kubectl get namespaces command which lists all the available namespaces.

Download the CASE bundle

Before mirroring your images, set the environment variables for the CASE images on your host, and then download the CASE by following these instructions:

Configure the GitHub repository to download the CASE:

kubectl ibm-pak config repo 'default' -r "https://github.com/IBM/cloud-pak/raw/master/repo/case/" --enable

Run the following command to download, validate, and extract the latest Event Endpoint Management CASE version.

kubectl ibm-pak get ibm-eventendpointmanagement

The CASE is downloaded in ~/.ibm-pak and the following output is displayed:

Downloading and extracting the CASE ...
- Success
Retrieving CASE version ...
- Success
Validating the CASE ...
Validating the signature for the ibm-eventendpointmanagement CASE...
- Success
Creating inventory ...
- Success
Finding inventory items
- Success
Resolving inventory items ...
Parsing inventory items
- Success
Download of CASE: ibm-eventendpointmanagement, version: 11.2.3 is complete

Note: You can also specify the version of the CASE you want to install by using --version <case-version>.

Verify that the CASE and images (.csv) files have been generated for Event Endpoint Management.

For example, ensure that the following files have been generated for Event Endpoint Management.

tree ~/.ibm-pak

├── config
│   └── config.yaml
├── data
│   ├── cases
│   │   └── ibm-eventendpointmanagement
│   │       └── 11.2.3
│   │           ├── caseDependencyMapping.csv
│   │           ├── charts
|   |           |   ├── ibm-eem-operator-11.2.3.tgz
|   |           |   └── ibm-eem-operator-crd-11.2.3.tgz
│   │           ├── component-set-config.yaml
│   │           ├── ibm-eventendpointmanagement-11.2.3-airgap-metadata.yaml
│   │           ├── ibm-eventendpointmanagement-11.2.3-charts.csv
│   │           ├── ibm-eventendpointmanagement-11.2.3-images.csv
│   │           ├── ibm-eventendpointmanagement-11.2.3.tgz
│   │           └── resourceIndexes
│   │               └── ibm-eventendpointmanagement-resourcesIndex.yaml
│   └── mirror
└── logs
   └── oc-ibm_pak.log

9 directories, 8 files

Configure registry authentication

To mirror images across both the source registry and the target (internal) registry where all images are available publicly, you must create an authentication secret for each. A Docker CLI login (docker login) or Podman CLI login (podman login) is required for configuring the registry.

A Skopeo CLI login (skopeo login) is also required for Kubernetes platforms other than OpenShift.

For Event Endpoint Management, all images are either present in the IBM Entitled Registry (cp.icr.io), which requires authentication, or in the IBM Container Registry (icr.io/cpopen), which does not.

Creating an authentication secret for the source registry

Run the following command to create an authentication secret for the source registry:

docker login <source-registry> --username <source-registry-user> --password <source-registry-pass>

Where:

<source-registry> is the Entitled Registry (cp.icr.io).
<source-registry-user> is your username.
<source-registry-pass> is your entitlement key.

Additionally, if you are installing on Kubernetes platforms other than OpenShift, run the following command:

skopeo login <source-registry> -u <source-registry-user> -p <source-registry-pass>

Creating an authentication secret for the target registry

Run the following command to create an authentication secret for the target registry:

docker login <target-registry> --username <target-registry-user> --password <target-registry-pass>

Additionally, if you are running on Kubernetes platforms other than OpenShift, run the following command:

skopeo login <target-registry> -u <target-registry-user> -p <target-registry-pass>

Where:

<target-registry> is the internal container image registry.
<target-registry-user> is the username for the internal container image registry.
<target-registry-pass> is the password for the internal container image registry.

Mirror the images

The process of mirroring images pulls the image from the internet and pushes it to your local registry. After mirroring your images, you can configure your cluster and complete the offline installation.

Complete the following steps to mirror the images from your host to your offline environment:

Run the following command to generate mirror manifests:
```
kubectl ibm-pak generate mirror-manifests ibm-eventendpointmanagement <target-registry>
```
Where <target-registry> is the internal container image registry.

Note: To filter for a specific image group, add the parameter --filter <image_group> to the previous command.

The previous command generates the following files based on the target internal registry provided:
- catalog-sources.yaml
- catalog-sources-linux-<arch>.yaml (if there are architecture specific catalog sources)
- image-content-source-policy.yaml
- images-mapping.txt

Run the following command to copy the images to the local registry. Your device must be connected to both the internet and the restricted network environment that contains the local registry.

If you are installing on the OpenShift Container Platform, run the following command:

oc image mirror -f ~/.ibm-pak/data/mirror/ibm-eventendpointmanagement/<case-version>/images-mapping.txt --filter-by-os '.*' --insecure --skip-multiple-scopes --max-per-registry=1

If you are installing on Kubernetes platforms other than OpenShift, run the following command:

cat ~/.ibm-pak/data/mirror/ibm-eventendpointmanagement/<case-version>/images-mapping.txt | awk -F'=' '{ print "skopeo copy --all docker://"$1" docker://"$2 }' | xargs -I {} sh -c 'echo {}; {}'

Note: If you are using a macOS system and encounter the xargs: command line cannot be assembled, too long error, add -S1024 to xargs, and run the command as follows:

cat ~/.ibm-pak/data/mirror/ibm-eventendpointmanagement/<case-version>/images-mapping.txt | awk -F'=' '{ print "skopeo copy --all docker://"$1" docker://"$2 }' | xargs -S1024 -I {} sh -c 'echo {}; {}'

Where:

<case-version> is the version of the CASE file to be copied.

Ensure that all the images have been mirrored to the target registry by checking the registry.

Create `ImageContentSourcePolicy` on OpenShift platform

Note: Only applicable when installing Event Endpoint Management on the OpenShift Container Platform.

Log in to your Red Hat OpenShift Container Platform as a cluster administrator by using the oc CLI (oc login).
Update the global image pull secret for your OpenShift cluster by following the steps in OpenShift documentation. This enables your cluster to have proper authentication credentials to pull images from your target-registry, as specified in the image-content-source-policy.yaml.
Apply ImageContentSourcePolicy YAML by running the following command:
```
oc apply -f  ~/.ibm-pak/data/mirror/ibm-eventendpointmanagement/<case-version>/image-content-source-policy.yaml
```
Where <case-version> is the version of the CASE file.
Additionally, a global image pull secret must be added so that images can be pulled from the target registry. Follow the instructions in the OpenShift documentation to add credentials for the target registry.

Important: Cluster resources must adjust to the new pull secret, which can temporarily limit the access to the cluster. Applying the ImageSourceContentPolicy causes cluster nodes to recycle, which results in limited access to the cluster until all the nodes are ready.
Verify that the ImageContentSourcePolicy resource is created:
```
oc get imageContentSourcePolicy
```
Important: After the ImageContentsourcePolicy and global image pull secret are applied, you might see the node status as Ready, Scheduling, or Disabled. Wait until all the nodes show a Ready status.
Verify your cluster node status and wait for all nodes to be updated before proceeding:
```
oc get MachineConfigPool -w
```

Apply catalog sources to your cluster on OpenShift platform

Note: Only applicable when you install Event Endpoint Management on the OpenShift Container Platform.

Apply the catalog sources for the operator to the cluster by running the following command:

oc apply -f ~/.ibm-pak/data/mirror/ibm-eventendpointmanagement/<case-version>/catalog-sources.yaml

Where <case-version> is the version of the CASE you want to install.

Install the operator

If you are installing the operator for the first time, complete the instructions in the following sections to install it on the platform that you are using.

If you are upgrading an existing offline installation, follow the upgrading instructions to upgrade your operator to the version that you downloaded and mirrored earlier.

Important: You can only install one version of the Event Endpoint Management operator on a cluster. Installing multiple versions on a single cluster is not supported due to possible compatibility issues as they share the same Custom Resource Definitions (CRDs), making them unsuitable for coexistence.

Installing on OpenShift

After you consider the operator requirements, resource requirements, and cluster-scoped permissions, you can install the operator by using the OpenShift Container Platform web console or command line. For more information, see the instructions for installing the Event Endpoint Management operator.

Installing on other Kubernetes platforms by using the `kubectl`

Complete the following steps to install the operator:

Create a namespace where you want to install the operator:
```
kubectl create namespace <target-namespace>
```
Create an image pull secret called ibm-entitlement-key in the namespace where you want to install the Event Endpoint Management operator. The secret enables container images to be pulled from the target registry:
```
kubectl create secret docker-registry ibm-entitlement-key --docker-username="<target-registry-user>" --docker-password="<target-registry-password>" --docker-server="<target-registry>" -n <target-namespace>
```
Where:
- <target-registry-user> is the username that you provide to authenticate with your internal registry.
- <target-registry-password> is the password associated with the <target-registry-user>.
- <target-registry> is the internal registry hosting the operator images.
- <target-namespace> is the namespace where you want to install Event Endpoint Management.
Note: If you are installing the instance in a different namespace, create the image pull secret (ibm-entitlement-key) again in the namespace where you want to install the instance.
Install the operator Custom Resource Definitions (CRD) by using the Helm CLI:
```
helm install <release-name> ~/.ibm-pak/data/cases/ibm-eventendpointmanagement/<case-version>/charts/ibm-eem-operator-crd-<case-version>.tgz -n <target-namespace>
```
Where:
- <release-name> is the name that you provide to identify the Helm release of the CRDs.
- <case-version> is the CASE version.
- <target-namespace> is the namespace where you want to install Event Endpoint Management.
- <target-registry> is the internal container image registry.

Install the operator by using the Helm CLI:

helm install <release-name> ~/.ibm-pak/data/cases/ibm-eventendpointmanagement/<case-version>/charts/ibm-eem-operator-<case-version>.tgz -n <target-namespace> --set imagePullPolicy="Always" --set public.repo=<target-registry> --set public.path="cpopen/" --set private.repo=<target-registry> --set private.path="cp/ibm-eventendpointmanagement/" --set watchAnyNamespace=<true/false>

Where:

<release-name> is the name that you provide to identify your operator.
<target-namespace> is the namespace where you want to install the Event Endpoint Management.
<case-version> is the CASE version.
<target-registry> is the internal container image registry.

Wait for the installation to complete.

Install an instance

Event Manager and Event Gateway instances can be created after the operators are installed. You can install the instances by using the OpenShift Container Platform web console. For more information, see the instructions for installing the Event Manager instance on OpenShift, or on other Kubernetes platforms.

Follow the instructions in installing an Event Gateway to install an Event Gateway on the same cluster.

Note: Stand-alone Event Gateway instances can only be installed in an online environment.

Prerequisites

Prepare your host

Download the CASE bundle

Configure registry authentication

Creating an authentication secret for the source registry

Creating an authentication secret for the target registry

Mirror the images

Create ImageContentSourcePolicy on OpenShift platform

Apply catalog sources to your cluster on OpenShift platform

Install the operator

Installing on OpenShift

Installing on other Kubernetes platforms by using the kubectl

Install an instance

Create `ImageContentSourcePolicy` on OpenShift platform

Installing on other Kubernetes platforms by using the `kubectl`