Installing IEAM in an air-gapped environment

If your cluster is not connected to the internet, you can use a bastion host to install IEAM in your cluster.

Overview

It is common in production to have a cluster that does not have internet access. In these cases, you can still install IEAM, and OpenShift Container Platform in an air-gapped (otherwise known as offline or disconnected) environment. Unlike online installations, air-gapped installations require you to enable the IBM Operator Catalog to mimic a typical online installation using images in your own registry.

You can store the product code and images on a bastion host, and then transfer them to a local air-gapped network.

Air-gapped installation approach	Example	Description
bastion host	bastion host	A bastion server is a device that has access to both the public internet and the local intranet where a local registry and Red Hat OpenShift Container Platform clusters reside. Using the bastion server, you can replicate your images through the bastion server directly to the local, intranet registry behind the firewall.

From a high level, air-gapped installations consists of four steps:

Set up your image registry access and mirroring environment (One-time action)
Set environment variables and download CASE files
Install IBM Edge Application Manager by way of Red Hat OpenShift Container Platform

1. Set up your mirroring environment

Before you install IBM Edge Application Manager on an air-gapped environment, you must set up a host that can be connected to the internet to complete configuring your mirroring environment. To set up your mirroring environment, complete the following steps:

1.1 Prerequisites
1.2 Set up local image registry and access

1.1. Prerequisites

No matter what medium you choose for your air-gapped installation, you must satisfy the following prerequisites:

A OpenShift Container Platform cluster must be installed. For the supported OpenShift Container Platform versions, see Supported OpenShift versions and platforms.
A Docker V2 registry must be available and accessible from the OpenShift Container Platform cluster nodes. For more information, see 1.2 Set up local image registry and access.
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 Entitled Registry and IBM Edge Application Manager catalog source
- quay.io:443 for IBM Cloud Platform Common Services catalog and images
- github.com for CASEs and tools
- redhat.com for Red Hat OpenShift Container Platform upgrades

Prepare a host

Regardless of which type of host you're using, you must be able to connect it to the internet and to the air-gapped network with access to the OpenShift Container Platform cluster and the local, intranet Docker registry. Your host must be on a Linux® x86_64 or Mac platform with any operating system that the IBM Cloud Pak CLI and the OpenShift Container Platform CLI support. If you are on a Windows platform, you must execute the actions in a Linux® x86_64 VM or from a Windows Subsystem for Linux (WSL) terminal.

Your host must have sufficient storage to hold all of the software that is to be transferred to the local, intranet Docker registry.

The following table explains the software requirements for installing IBM Edge Application Manager in an air-gapped environment:

Table 2. Software requirements and purpose
Software	Purpose
OpenSSL	Validating certificates when you run the air-gapped install scripts
Docker	Container management
Podman	Container management
Apache httpd-tools	Creating an account when you run the air-gapped install scripts
IBM Cloud Pak CLI (cloudctl)	Running CASE commands
Red Hat OpenShift CLI (oc)	Red Hat OpenShift Container Platform administration
Skopeo	Working with container images and registries in an air-gapped environment

Complete the following steps on your host:

Install OpenSSL version 1.11.1 or higher.
Install Docker or Podman.
- To install Docker (for example, on Red Hat® Enterprise Linux®), run the following commands:
```
 yum check-update
 yum install docker
```
- To install Podman, see Podman Installation Instructions.
Install httpd-tools.
```
yum install httpd-tools
```
Download and install the most recent version of cloudctl-linux-amd64.tar.gz from the IBM/cloud-pak-cli repo.

Extract the binary file by entering the following command:

   tar -xf cloudctl-linux-amd64.tar.gz

Run the following command to modify the file:

   chmod 755 cloudctl-linux-amd64

Run the following command to move the file to the /usr/local/bin directory:

   mv cloudctl-linux-amd64 /usr/local/bin/cloudctl

Note: You can confirm that cloudctl is installed by entering the following command:

   cloudctl --help

The cloudctl usage is displayed.

Install the oc OpenShift Container Platform CLI tool. For more information, see OpenShift Container Platform CLI tools.
Install the skopeo CLI version 1.0.0 or higher. For more information, select install.md in the Skopeo repo.
Create a directory that serves as the offline store.

Following is an example directory, which is used in the subsequent steps.
```
mkdir $HOME/offline
```
Note: This offline store must be persistent to avoid transferring data more than once. The persistence also helps to run the mirroring process multiple times or on a schedule.

If you are installing IBM Edge Application Manager by using a bastion host, the bastion server must be configured.

1.2. Set up local image registry and access

You must use a local Docker registry to store all of your images in your intranet network. Many customers have one or more centralized, corporate registry servers to store production container images. If a local registry is not available, a production-grade registry will need to be installed and configured. To access your registries during an air-gapped installation, you must use an account that the username and password are associated with a user who can write to the target local registry from a storage device and read from the target local registry that is on the OpenShift cluster nodes. You must create such a registry and the registry must meet the following requirements:

Supports Docker Manifest V2, Schema 2.
Supports multi-architecture images.
Is accessible from the OpenShift Container Platform cluster nodes.
Allows path separators in the image name.

Note: Do not use OpenShift image registry as your local, intranet registry. The OpenShift registry does not support multi-architecture images or path separators in the image name.

After you create the internal Docker registry, you must configure the registry:

Create registry namespaces.

A registry namespace is the first component in the image name. For example: in the image name, icr.io/cpopen/myproduct, the namespace portion of the image name is cpopen.

If you are using different registry providers, you must create separate registry Kubernetes namespaces for each public registry source. These Kubernetes namespaces are used as the location that the contents of the CASE file gets pushed into when you run your CASE commands.

The following registry namespaces might be used by the CASE command:
- cp - Namespace to store the IBM images from the cp.icr.io/cp repository.
  
  The cp namespace is for the images in the IBM Entitled Registry that require a product entitlement key and credentials to pull.
- cpopen - Namespace to store the operator related IBM images from the icr.io/cpopen repository.
  
  The cpopen namespace is for publicly available images hosted by IBM® that don't require credentials to pull.
- opencloudio - Namespace to store the images from quay.io/opencloudio.
  
  The opencloudio namespace is for select IBM open source component images that are available on quay.io. The IBM Edge Application Manager images are hosted on opencloudio.
Verify that each namespace meets the following requirements:
- Supports auto-repository creation.
- Has credentials of a user who can write and create repositories. The external host uses these credentials.
- Has credentials of a user who can read all repositories. The OpenShift Container Platform cluster uses these credentials.

2. Set environment variables and download CASE files

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:

Set up environment variables:

   CASE_NAME=ibm-eamhub
   CASE_VERSION=1.1.6
   CASE_ARCHIVE=$CASE_NAME-$CASE_VERSION.tgz
   CASE_INVENTORY_SETUP=ibmEamhubOperatorSetup
   OFFLINEDIR=$HOME/offline
   CASE_REPO_PATH=https://github.com/IBM/cloud-pak/raw/master/repo/case
   USER_GENERATED_USERNAME=admin
   USER_GENERATED_PASS=changeme
   CASE_LOCAL_PATH=$OFFLINEDIR/$CASE_ARCHIVE
   CP_USER=cp
   CP_PASS=changeme
   REGISTRY_MIRROR=$(hostname -A | awk '{print $1}')
   REGISTRY_PORT=5000

   oc login --token=yourtokeninfogoeshere --server=yourairgapcluster
   oc new-project ibm-edge

Download the IEAM CASE bundle:

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

Initialize a container registry:

   cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --inventory ibmEamhubOperatorSetup \
   --action init-registry \
   --args "--user $USER_GENERATED_USERNAME --pass $USER_GENERATED_PASS" \
   --tolerance 1

Start the container registry:

   cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --inventory ibmEamhubOperatorSetup \
   --action start-registry \
   --tolerance 1

Download the certificate to the registry server and make OCP trust it:

   oc create configmap registry-cas -n openshift-config --from-file=$REGISTRY_MIRROR..$REGISTRY_PORT=/tmp/docker-registry/certs/ca.crt
   oc patch image.config.openshift.io/cluster --patch '{"spec":{"additionalTrustedCA":{"name":"registry-cas"}}}' --type=merge

Store authentication credentials for container registry by executing the following 3 case stanzas:

   cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --namespace ibm-edge \
   --inventory ibmEamhubOperatorSetup \
   --action configure-creds-airgap \
   --args "--registry cp.icr.io --user $CP_USER --pass $CP_PASS" \
   --tolerance 1

   cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --namespace ibm-edge \
   --inventory ibmEamhubOperatorSetup \
   --action configure-creds-airgap \
   --args "--registry $REGISTRY_MIRROR:$REGISTRY_PORT --user $USER_GENERATED_USERNAME --pass $USER_GENERATED_PASS" \
   --tolerance 1

   cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --namespace ibm-edge \
   --inventory ibmEamhubOperatorSetup \
   --action configure-cluster-airgap \
   --args "--registry $REGISTRY_MIRROR:$REGISTRY_PORT --inputDir $OFFLINEDIR" \
   --tolerance 1

Mirror the CASE bundle images to the container registry:

   cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --namespace ibm-edge \
   --inventory ibmEamhubOperatorSetup \
   --action mirror-images \
   --args "--registry $REGISTRY_MIRROR:$REGISTRY_PORT --inputDir $OFFLINEDIR --recursive" \
   --tolerance 1

Create and configure a catalog source:

   cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --namespace ibm-edge \
   --inventory ibmEamhubOperatorSetup \
   --action install-catalog \
   --args "--inputDir $OFFLINEDIR --registry $REGISTRY_MIRROR:$REGISTRY_PORT --recursive" \
   --tolerance 1

Install the IBM Edge Application Manager operator:

  cloudctl case launch \
  --case $CASE_LOCAL_PATH \
  --namespace ibm-edge \
  --inventory ibmEamhubOperatorSetup \
  --action install-operator \
  --args "--recursive --registry $REGISTRY_MIRROR:$REGISTRY_PORT --inputDir $OFFLINEDIR" \
  --tolerance 1

Create the IEAM Custom Resource:

cat <<EOF | oc apply -f -
apiVersion: eam.edge.ibm.com/v1beta1
kind: EamHub
metadata:
  name: ibm-edge
  namespace: ibm-edge
spec:
  license:
    accept: true
EOF

Verify that the IBM Edge Application Manager is installed:
```
  oc get pod -n ibm-edge
```

3. Install IEAM by way of Red Hat OpenShift Container Platform

Now that your images are mirrored to your air-gapped environment, you can deploy your IBM Cloud Pak® to that that environment. When you mirrored your environment, you created a parallel offline version of everything that you needed to install an operator into OpenShift Container Platform. To install the IBM Edge Application Manager, complete the following steps:

3.1. Create the catalog source and install IBM Edge Application Manager
3.2. Access the management console
3.3. Retrieve your management console username and password

3.1. Create the catalog source and install IBM Edge Application Manager

Set the namespace to install the IBM Edge Application Manager catalog:
```
export NAMESPACE=ibm-edge
```

Create and configure a catalog source.

cloudctl case launch \
  --case $CASE_LOCAL_PATH \
  --inventory $CASE_INVENTORY_SETUP \
  --action install-catalog \
  --namespace $NAMESPACE \
  --args "--registry $LOCAL_DOCKER_REGISTRY" \

Verify that the CatalogSource for IBM Edge Application Manager installer operator is created.
```
oc get pods -n openshift-marketplace
oc get catalogsource -n openshift-marketplace
```

Install the IBM Edge Application Manager operator.

 cloudctl case launch \
   --case $CASE_LOCAL_PATH \
   --inventory $CASE_INVENTORY_SETUP \
   --action install-operator \
   --namespace $NAMESPACE \

Verify that the IBM Edge Application Manager is installed:
```
oc get pod -n ibm-edge
```

3.2. Access the management console

Use the following command to get the URL to access the management console:

   oc get route -n ibm-common-services cp-console -o jsonpath=‘{.spec.host}’

This command results in the following output:

   cp-console.apps.mycluster.mydomain.com

Based on the example output, your console URL would be https://cp-console.apps.mycluster.mydomain.com.

3.3. Retrieve your management console username and password

The default username to access the management console is admin.

You can get the password for the admin username by running the following command:

   oc -n ibm-common-services get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d

The following password is an example of the output of the preceding command:

   EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA

Based on the example output, you would then use EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA as the password.

You can change the default password at any time. For more information, see Changing the cluster administrator access credentials.

Note: Any user with access to the ibm-common-services namespace can retrieve this password since it is stored in a secret in the ibm-common-services namespace. To minimize password exposure, allow limited users to access the ibm-common-services namespace.

You have now successfully created and deployed your air-gapped instance of IBM Edge Application Manager.

For more information about troubleshooting your air-gapped installation, see Troubleshooting install. -->