Installing the IBM API Catalog service in an air-gapped environment

You must install IBM Cloud Pak foundational services before you install the IBM API Catalog service.

For more information about installing foundational services in an air-gapped environment, see Installing IBM Cloud Pak foundational services in an air-gapped environment.

Then, complete these steps to install the IBM API Catalog service.

• 1. Set environment variables and download CASE files
• 2. Mirror images to portable registry
  • 2.1. Mirror the images to the host
  • 2.2. Copy saved offline data (for a portable storage device only)
  • 2.3. Connect your host to your air-gapped environment and set up your container
  • 2.4. Mirror images to final location and configure the cluster
• 3. Create the service catalog source

The following table provides the IBM API Catalog service image version that can be used with the foundational services installer version:

1. Set environment variables and download CASE files

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:

1. Create the following environment variables with the IBM API Catalog service image name and the image inventory on your host.

   Bastion host

   On a bastion host:

    export CASE_NAME_API=ibm-apicatalog
    export CASE_VERSION_API=1.5.0
    export CASE_ARCHIVE_API=$CASE_NAME_API-$CASE_VERSION_API.tgz
    export CASE_INVENTORY_SETUP_API=apicatalogOperatorSetup
    export OFFLINEDIR=$HOME/offline
    export CASE_REPO_PATH=https://github.com/IBM/cloud-pak/raw/master/repo/case
    export CASE_LOCAL_PATH_API=$OFFLINEDIR/$CASE_ARCHIVE_API
   

   Portable compute Portable storage

   On a portable compute device or portable storage device:

    export CASE_NAME_API=ibm-apicatalog
    export CASE_VERSION_API=1.5.0
    export CASE_ARCHIVE_API=$CASE_NAME_API-$CASE_VERSION_API.tgz
    export CASE_INVENTORY_SETUP_API=apicatalogOperatorSetup
    export OFFLINEDIR=$HOME/offline
    export OFFLINEDIR_ARCHIVE_API=offline_api.tgz
    export CASE_REPO_PATH=https://github.com/IBM/cloud-pak/raw/master/repo/case
    export CASE_LOCAL_PATH_API=$OFFLINEDIR/$CASE_ARCHIVE_API
   
    export PORTABLE_DOCKER_REGISTRY_HOST=localhost
    export PORTABLE_DOCKER_REGISTRY_PORT=443
    export PORTABLE_DOCKER_REGISTRY=$PORTABLE_DOCKER_REGISTRY_HOST:$PORTABLE_DOCKER_REGISTRY_PORT
    export PORTABLE_DOCKER_REGISTRY_USER=localuser
    export PORTABLE_DOCKER_REGISTRY_PASSWORD=l0calPassword!
    export PORTABLE_DOCKER_REGISTRY_PATH=$OFFLINEDIR/imageregistry
   

2. Connect your host to the internet and disconnect it from the local air-gapped network.

3. Download the IBM API Catalog service image and image inventory to your host.

     cloudctl case save \
       --repo $CASE_REPO_PATH \
       --case $CASE_NAME_API \
       --version $CASE_VERSION_API \
       --outputdir $OFFLINEDIR
   

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

Important: For portable compute and portable storage devices only, a Docker registry service must run from your connected device (localhost) by completing the following steps:

1. Initialize the Docker registry:

   cloudctl case launch \
     --case $CASE_LOCAL_PATH_API \
     --inventory $CASE_INVENTORY_SETUP_API \
     --action init-registry \
     --args "--registry $PORTABLE_DOCKER_REGISTRY_HOST --user $PORTABLE_DOCKER_REGISTRY_USER --pass $PORTABLE_DOCKER_REGISTRY_PASSWORD --dir $PORTABLE_DOCKER_REGISTRY_PATH"
   

2. Start the Docker registry:

   cloudctl case launch \
     --case $CASE_LOCAL_PATH_API \
     --inventory $CASE_INVENTORY_SETUP_API \
     --action start-registry \
     --args "--registry $PORTABLE_DOCKER_REGISTRY_HOST --port $PORTABLE_DOCKER_REGISTRY_PORT --user $PORTABLE_DOCKER_REGISTRY_USER --pass $PORTABLE_DOCKER_REGISTRY_PASSWORD --dir $PORTABLE_DOCKER_REGISTRY_PATH"
   

2. Mirror images to portable registry

The process of mirroring images takes the image from the internet to your host, then effectively copies that image on to your air-gapped environment. 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 air-gapped environment:

• 2.1. Mirror the images to the host
• 2.2. Copy saved offline data (for a portable storage device only)
• 2.3. Connect your host to your air-gapped environment and set up your container
• 2.4. Mirror images to final location and configure the cluster

2.1. Mirror the images to the host

Complete these steps to mirror the images from the internet to your host:

Note: Don't use the tilde within double quotation marks in any command. For example, don't use args "--registry <registry> --user <registry userid> --pass {registry password} --inputDir ~/offline". The tilde does not expand and your commands might fail.

1. Store authentication credentials for all source Docker registries.

   All IBM Cloud Pak foundational services credentials are stored in public registries that don't require authentication. However, other products and third-party components require one or more authenticated registries. The following registries require authentication:

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

   For more information about these registries, see Create registry namespaces - Bastion host, Create registry namespaces - portable compute device, or Create registry namespaces - portable storage device.

   During foundational services installation, you must have configured the credentials for all registries that require authentication. For more information, see Mirror the images to the host - Bastion host, Mirror the images to the host - portable compute device, or Mirror the images to the host - portable storage device.

2. Store authentication credentials of the host Docker registry:

   Portable storage

   On a portable storage device:

     cloudctl case launch \
       --case $CASE_LOCAL_PATH_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action configure-creds-airgap \
       --args "--registry $PORTABLE_DOCKER_REGISTRY --user $PORTABLE_DOCKER_REGISTRY_USER --pass $PORTABLE_DOCKER_REGISTRY_PASSWORD"
   

   The command stores and caches the registry credentials in a file on your file system in the $HOME/.airgap/secrets location.

3. Mirror the images to the registry on the host.

     cloudctl case launch \
       --case $CASE_LOCAL_PATH_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action mirror-images \
       --args "--registry $PORTABLE_DOCKER_REGISTRY --inputDir $OFFLINEDIR --filter amd64"
   

4. Save the Docker registry image.

If your air-gapped network doesn’t have a Docker registry image, you can save the image and copy it later to the host in your air-gapped environment:

docker save docker.io/library/registry:2.6 -o $PORTABLE_DOCKER_REGISTRY_PATH/registry-image.tar

2.2. Copy saved offline data (for a portable storage device only)

1. Connect the portable storage device, such as a USB drive or external HDD, to this external host.

2. Archive the offline data for transfer:

    tar -cvzf $OFFLINEDIR_ARCHIVE_API -C $OFFLINEDIR .
   

3. Copy the preceding TAR file to the portable storage.

   Physically transfer your portable storage device from the machine that has a public internet connection to the machine that has no internet connectivity (your air-gapped environment).

4. Proceed to the next section to set up your cluster.

2.3. Connect your host to your air-gapped environment and set up your container

1. Connect your host device to the air-gapped network and disconnect it from the internet.

2. Log in to the OpenShift Container Platform cluster as a cluster administrator. The following sample command logs in to the OpenShift Container Platform cluster:

    oc login <cluster host:port> --username=<cluster admin user> --password=<cluster admin password>
   

You must install the IBM API Catalog service in the same namespace where you installed foundational services. The NAMESPACE environment variable already has the this namespace value from your foundational services installation.

2.4. Mirror images to final location and configure the cluster

Complete these steps on your host that is connected to both the local Docker registry and the OpenShift Container Platform cluster:

1. Create environment variables with the local Docker registry connection information.

   Bastion host Portable compute

   On a bastion host or portable compute device:

    export CASE_NAME_API=ibm-apicatalog
    export CASE_VERSION_API=1.5.0
    export CASE_ARCHIVE_API=$CASE_NAME_API-$CASE_VERSION_API.tgz
    export CASE_INVENTORY_SETUP_API=apicatalogOperatorSetup
    export OFFLINEDIR=$HOME/offline
    export OFFLINEDIR_ARCHIVE_API=offline_api.tgz
    export CASE_REPO_PATH=https://github.com/IBM/cloud-pak/raw/master/repo/case
    export CASE_LOCAL_PATH_API=$OFFLINEDIR/$CASE_ARCHIVE_API
   
    export LOCAL_DOCKER_REGISTRY_HOST=<IP_or_FQDN_of_local_docker_registry>
    export LOCAL_DOCKER_REGISTRY_PORT=443
    export LOCAL_DOCKER_REGISTRY=$LOCAL_DOCKER_REGISTRY_HOST:$LOCAL_DOCKER_REGISTRY_PORT
    export LOCAL_DOCKER_USER=<username>
    export LOCAL_DOCKER_PASSWORD=<password>
   

   Portable storage

   On a portable storage device:

    export CASE_NAME_API=ibm-apicatalog
    export CASE_VERSION_API=1.5.0
    export CASE_ARCHIVE_API=$CASE_NAME_API-$CASE_VERSION_API.tgz
    export CASE_INVENTORY_SETUP_API=apicatalogOperatorSetup
    export OFFLINEDIR=$HOME/offline
    export OFFLINEDIR_ARCHIVE_API=offline_api.tgz
    export CASE_REPO_PATH=https://github.com/IBM/cloud-pak/raw/master/repo/case
    export CASE_LOCAL_PATH_API=$OFFLINEDIR/$CASE_ARCHIVE_API
   
    export PORTABLE_DOCKER_REGISTRY_HOST=localhost
    export PORTABLE_DOCKER_REGISTRY_PORT=443
    export PORTABLE_DOCKER_REGISTRY=$PORTABLE_DOCKER_REGISTRY_HOST:$PORTABLE_DOCKER_REGISTRY_PORT
    export PORTABLE_DOCKER_REGISTRY_USER=localuser
    export PORTABLE_DOCKER_REGISTRY_PASSWORD=l0calPassword!
    export PORTABLE_DOCKER_REGISTRY_PATH=$OFFLINEDIR/imageregistry
   
    export LOCAL_DOCKER_REGISTRY_HOST=<IP_or_FQDN_of_local_docker_registry>
    export LOCAL_DOCKER_REGISTRY_PORT=443
    export LOCAL_DOCKER_REGISTRY=$LOCAL_DOCKER_REGISTRY_HOST:$LOCAL_DOCKER_REGISTRY_PORT
    export LOCAL_DOCKER_REGISTRY_USER=<username>
    export LOCAL_DOCKER_REGISTRY_PASSWORD=<password>
   

   Note: The Docker registry uses standard ports such as 80 or 443. If your Docker registry uses a non-standard port, specify the port by using the syntax <host>:<port>. For example, export LOCAL_DOCKER_REGISTRY=myregistry.local:5000.

   Portable storage

2. On a portable storage device only, extract the transferred offline data:

    mkdir -p $OFFLINEDIR
    tar -xvf $OFFLINEDIR_ARCHIVE_API -C $OFFLINEDIR
   

   Portable storage

3. On a portable storage device only, set up the registry. Run the local Docker registry as a container. The registry then points to the Docker file system directory that is transferred from the external host:

     cloudctl case launch \
       --case $CASE_LOCAL_PATH_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action start-registry \
       --args "--registry $PORTABLE_DOCKER_REGISTRY_HOST --port $PORTABLE_DOCKER_REGISTRY_PORT --user $PORTABLE_DOCKER_REGISTRY_USER --pass $PORTABLE_DOCKER_REGISTRY_PASSWORD --dir $PORTABLE_DOCKER_REGISTRY_PATH"
   

4. Configure an authentication secret for the Docker registry. Note: This step needs to be done only one time.

   Bastion host Portable compute

   On a bastion host or portable compute device:

     cloudctl case launch \
       --case $HOME/offline/$CASE_ARCHIVE_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action configure-creds-airgap \
       --args "--registry $LOCAL_DOCKER_REGISTRY --user $LOCAL_DOCKER_USER --pass $LOCAL_DOCKER_PASSWORD"
   

   Portable storage

   On a portable storage device, store credentials of the registry that is running on the internal host (created in the previous step):

     cloudctl case launch \
       --case $CASE_LOCAL_PATH_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action configure-creds-airgap \
       --args "--registry $PORTABLE_DOCKER_REGISTRY --user $PORTABLE_DOCKER_REGISTRY_USER --pass $PORTABLE_DOCKER_REGISTRY_PASSWORD"
   

   Then, store credentials of the registry that is going to serve images to the cluster/workloads:

     cloudctl case launch \
       --case $CASE_LOCAL_PATH_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action configure-creds-airgap \
       --args "--registry $LOCAL_DOCKER_REGISTRY --user $LOCAL_DOCKER_REGISTRY_USER --pass $LOCAL_DOCKER_REGISTRY_PASSWORD"
   

   The command stores and caches the registry credentials in a file on your file system in the $HOME/.airgap/secrets location.

5. Mirror images to the local image registry:

   Portable compute Portable storage

   On a portable compute device or portable storage device, mirror the images from the portable registry to the target registry on your cluster.

     cloudctl case launch \
       --case $CASE_LOCAL_PATH_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action mirror-images \
       --args "--fromRegistry $PORTABLE_DOCKER_REGISTRY --registry $LOCAL_DOCKER_REGISTRY --inputDir $OFFLINEDIR --filter amd64"
   

   Bastion host

   On a bastion server:

     cloudctl case launch \
       --case $CASE_LOCAL_PATH_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action mirror-images \
       --args "--registry $LOCAL_DOCKER_REGISTRY --inputDir $OFFLINEDIR --filter amd64"
   

6. Configure a global image pull secret and ImageContentSourcePolicy.

     cloudctl case launch \
       --case $HOME/offline/$CASE_ARCHIVE_API \
       --inventory $CASE_INVENTORY_SETUP_API \
       --action configure-cluster-airgap \
       --namespace $NAMESPACE \
       --args "--registry $LOCAL_DOCKER_REGISTRY --user $LOCAL_DOCKER_USER --pass $LOCAL_DOCKER_PASSWORD --inputDir $OFFLINEDIR"
   

7. Verify that the ImageContentSourcePolicy resource is created.

    oc get imageContentSourcePolicy
   

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

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

9. Verify your cluster node status.

    oc get nodes
   

   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.

3. Create the service catalog source

Now that your images are mirrored to your air-gapped environment, you can create the IBM API Catalog service catalog source. Complete the following steps:

1. Create and configure a catalog source.

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

2. Verify that the CatalogSource is created.

    oc get pods -n openshift-marketplace
    oc get catalogsource -n openshift-marketplace
    oc get catalogsource ibm-apicatalog-catalog -n openshift-marketplace -o yaml
   

You now successfully created and deployed your air-gapped instance of IBM API Catalog service.