Installing with a portable computer or storage device

You can use a portable device, such as a portal computer or a USB storage device, to perform an air-gapped installation of API Connect on Red Hat OpenShift Container Platform (OCP) when your cluster has no internet connectivity.

Before you begin

This task must be performed by a Red Hat OpenShift administrator.

About this task

If your cluster is not connected to the internet, you can mirror product images to a registry in your network-restricted environment by using a portable device. You can download images from the public registries on the internet to the portable device; then you can bring that portable device into the network-restricted environment (or transfer the files to a different device within the network-restricted environment) and mirror the images to the local registry. You can pull the images from the local registry to the target cluster for installation.

Procedure

Set up the mirroring environment.
1. Prepare the target cluster:
  - Deploy a supported version of Red Hat OpenShift Container Platform (OCP) as a cluster.
    For information, see Table 2 "API Connect and OpenShift Container Platform (OCP) compatibility matrix" in IBM API Connect Version 10 software product compatibility requirements.
  - Configure storage on the cluster and make sure that it is available.
2. Prepare the portable device:
  You must be able to connect your portable device to the internet and to the restricted network environment (with access to the Red Hat OpenShift Container Platform (OCP) cluster and the local registry). The portable device must be on a Linux x86_64 or Mac platform with any operating system that the Red Hat OpenShift Client supports (in Windows, execute the actions in a Linux x86_64 VM or from a Windows Subsystem for Linux terminal).
  1. Ensure that the portable device has sufficient storage to hold all of the software that is to be transferred to the local registry.
  2. On the portable device, install either Docker or Podman (not both).
    Docker and Podman are used for managing containers; you only need to install one of these applications.
    - To install Docker (for example, on Red Hat Enterprise Linux), run the following commands:
      yum check-update yum install docker
    - To install Podman, see the Podman installation instructions.
      For example, on Red Hat Enterprise Linux 9, install Podman with the following command:
      yum install podman
  3. Install the Red Hat OpenShift Client tool (oc) as explained in Getting started with the OpenShift CLI.
    The oc tool is used for managing Red Hat OpenShift resources in the cluster.
  4. Download the IBM Catalog Management Plug-in for IBM Cloud Paks version 1.1.0 or later from GitHub.
    The ibm-pak plug-in enables you to access hosted product images, and to run oc ibm-pak commands against the cluster. To confirm that ibm-pak is installed, run the following command and verify that the response lists the command usage:
    oc ibm-pak --help
3. Set up a local image registry and credentials.
  The local Docker registry stores the mirrored images in your network-restricted environment.
  1. Install a registry, or get access to an existing registry.
    You might already have access to one or more centralized, corporate registry servers to store the API Connect images. If not, then you must install and configure a production-grade registry before proceeding.
    The registry product that you use must meet the following requirements:
    
    Supports multi-architecture images through Docker Manifest V2, Schema 2
    For details, see Docker Manifest V2, Schema 2.
    
    Is accessible from the Red Hat OpenShift Container Platform cluster nodes
    
    Allows path separators in the image name
    Note: Do not use the Red Hat OpenShift image registry as your local registry because it does not support multi-architecture images or path separators in the image name.
  2. Configure the registry to meet the following requirements:
    - Supports auto-repository creation
    - Has sufficient storage to hold all of the software that is to be transferred
    - Has the credentials of a user who can create and write to repositories (the mirroring process uses these credentials)
    - Has the credentials of a user who can read all repositories (the Red Hat OpenShift Container Platform cluster uses these credentials)
  To access your registries during an air-gapped installation, use an account that can write to the target local registry. To access your registries during runtime, use an account that can read from the target local registry.
Set environment variables and download CASE files.

Create environment variables to use while mirroring images, connect to the internet, and download the API Connect CASE files.
1. Create the following environment variables with the installer image name and the image inventory on your portable device:
  Because you will use values from two different CASE files, you must create environment variables for both; notice that the variables for the foundational services (common services) CASE file are prefixed with "CS_" to differentiate them.
```
export CASE_NAME=ibm-apiconnect
export CASE_VERSION=4.0.10
export ARCH=amd64
```
  For information on API Connect CASE versions and their corresponding operators and operands, see Operator, operand, and CASE versions.
```
export CS_CASE_NAME=ibm-cp-common-services
export CS_CASE_VERSION=1.15.10
export CS_ARCH=amd64
```
  For example, for IBM Cloud Pak foundational services 3.19.X (Long Term Service Release), use version 1.15.10; for foundational services 3.23.X (Continuous Delivery), use version 1.19.2.
  
  For information on IBM Cloud Pak foundational services (common services) CASE versions, see "Table 1. Image versions for offline installation" in Installing IBM Cloud Pak foundational services in an air-gapped environment in the IBM Cloud Pak foundational services documentation.
2. Connect your portable device to the internet (it does not need to be connected to the network-restricted environment at this time).
3. Download the CASE files to your portable device:
  Be sure to download both CASE files as shown in the example:
```
oc ibm-pak get $CASE_NAME --version $CASE_VERSION
```
```
oc ibm-pak get $CS_CASE_NAME --version $CS_CASE_VERSION
```
  If you omit the --version parameter, the command downloads the latest version.
Mirror the images.

The process of mirroring images pulls the images from the internet and pushes them to your local registry. After mirroring your images, you can configure your cluster and pull the images to it before installing API Connect.
1. Generate mirror manifests.
  1. Define the environment variable $TARGET_REGISTRY by running the following command:
```
export TARGET_REGISTRY=<target-registry>
```
    Replace <target-registry> with the IP address (or host name) and port of the local registry; for example: 172.16.0.10:5000. If you want the images to use a specific namespace within the target registry, you can specify it here; for example: 172.16.0.10:5000/registry_ns.
  2. Generate mirror manifests by running the following command:
```
oc ibm-pak generate mirror-manifests $CASE_NAME file://integration --version $CASE_VERSION --final-registry $TARGET_REGISTRY
```
```
oc ibm-pak generate mirror-manifests $CS_CASE_NAME file://integration --version $CS_CASE_VERSION --final-registry $TARGET_REGISTRY
```
    If you need to filter for a specific image group, add the parameter --filter <image_group> to the command.
  The generate command creates the following files at ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION and ~/.ibm-pak/data/mirror/$CS_CASE_NAME/$CS_CASE_VERSION:
  - catalog-sources.yaml
  - catalog-sources-linux-<arch>.yaml (if there are architecture-specific catalog sources)
  - image-content-source-policy.yaml
  - images-mapping-to-filesystem.txt
  - images-mapping-from-filesystem.txt
  The files are used when mirroring the images to the TARGET_REGISTRY.
2. Obtain an entitlement key for the entitled registry where the images are hosted:
  1. Log in to the IBM Container Library.
  2. In the Container software library, select Get entitlement key.
  3. In the "Access your container software" section, click Copy key.
  4. Copy the key to a safe location; you will use it to log in to cp.icr.io in the next step.
3. Authenticate with the entitled registry where the images are hosted.
  The image pull secret allows you to authenticate with the entitled registry and access product images.
  1. Run the following command to export the path to the file that will store the authentication credentials that are generated on a Podman or Docker login:
```
export REGISTRY_AUTH_FILE=$HOME/.docker/config.json
```
    The authentication file is typically located at $HOME/.docker/config.json on Linux or %USERPROFILE%/.docker/config.json on Windows.
  2. Log in to the cp.icr.io registry with Podman or Docker; for example:
```
podman login cp.icr.io
```
    Use cp as the username and your entitlement key as the password.
4. Update the API Connect CASE manifest to correctly reference the DataPower Operator image.
  
  Files for the DataPower Operator are now hosted on icr.io; however, the CASE manifest still refers to docker.io as the image host. To work around this issue, visit Airgap install failure due to 'unable to retrieve source image docker.io' in the DataPower documentation and update the manifest as instructed. The manifest for API Connect (which uses the DataPower Operator) is stored in ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION.
  
  After the manifest is updated, continue to the next step in this procedure.
5. Mirror the images from the internet to the portable device.
  1. Define the environment variable $IMAGE_PATH by running the following command:
```
export IMAGE_PATH=<image-path>
```
    where <image-path> indicates where the files will be stored on the portable device's file system.
  2. Mirror the images to the portable device:
```
oc image mirror \
  -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-to-filesystem.txt \
  --filter-by-os '.*' \
  -a $REGISTRY_AUTH_FILE \
  --skip-multiple-scopes \
  --max-per-registry=1 \
  --dir "$IMAGE_PATH"
```
```
oc image mirror \
  -f ~/.ibm-pak/data/mirror/$CS_CASE_NAME/$CS_CASE_VERSION/images-mapping-to-filesystem.txt \
  --filter-by-os '.*' \
  -a $REGISTRY_AUTH_FILE \
  --skip-multiple-scopes \
  --max-per-registry=1 \
  --dir "$IMAGE_PATH"
```
    There might be a slight delay before you see a response to the command.
6. Move the portable device to the restricted-network environment.
  The procedure depends on the type of device that you are using:
  If you are using a portable computer, disconnect the device from the internet and connect it to the restricted-network environment. The same environment variables can be used.
  If you are using portable storage, complete the following steps:
  1. Transfer the following files to a device in the restricted-network environment:
    
    The ~/.ibm-pak directory.
    
    The contents of the <image-path> that you specified in the previous step.
  2. Create the same environment variables as on the original device; for example:
    export CASE_NAME=ibm-apiconnect export CASE_VERSION=4.0.10 export ARCH=amd64
    export CS_CASE_NAME=ibm-cp-common-services export CS_CASE_VERSION=1.15.10 export CS_ARCH=amd64
    export REGISTRY_AUTH_FILE=$HOME/.docker/config.json
    export IMAGE_PATH=<image-path>
7. Authenticate with the local registry.
  Log in to the local registry using an account that can write images to that registry; for example:
```
podman login $TARGET_REGISTRY
```
  If the registry is insecure, add the following flag to the command: --tls-verify=false.
8. Mirror the product images to the target registry.
  1. If you are using a portable computer, connect it to the restricted-network environment that contains the local registry.
    If you are using portable storage, you already transferred files to a device within the restricted-network environment.
  2. Run the following command to copy the images to the local registry:
```
oc image mirror \
  -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping-from-filesystem.txt \
  -a $REGISTRY_AUTH_FILE \
  --filter-by-os '.*' \
  --skip-multiple-scopes \
  --max-per-registry=1 \
  --from-dir "$IMAGE_PATH"
```
```
oc image mirror \
  -f ~/.ibm-pak/data/mirror/$CS_CASE_NAME/$CS_CASE_VERSION/images-mapping-from-filesystem.txt \
  -a $REGISTRY_AUTH_FILE \
  --filter-by-os '.*' \
  --skip-multiple-scopes \
  --max-per-registry=1 \
  --from-dir "$IMAGE_PATH"
```
    Note: If the local registry is not secured by TLS, or the certificate presented by the local registry is not trusted by your device, add the --insecure option to the command.
    
    There might be a slight delay before you see a response to the command.
9. Configure the target cluster.
  Now that images have been mirrored to the local registry, the target cluster must be configured to pull the images from it. Complete the following steps to configure the cluster's global pull secret with the local registry's credentials and then instruct the cluster to pull the images from the local registry.
  1. Log in to your Red Hat OpenShift Container Platform cluster:
```
oc login <openshift_url> -u <username> -p <password> -n <namespace>
```
  2. Update the global image pull secret for the cluster as explained in the Red Hat OpenShift Container Platform documentation.
    Note: If you have an insecure registry, add the registry to the cluster's insecureRegistries list by running the following command:
    oc edit image.config.openshift.io/cluster -o yaml
    and add the TARGET_REGISTRY to spec.registrySources.insecureRegistries as shown in the following example:
    spec: registrySources: insecureRegistries: - insecure0.svc:5001 - <TARGET_REGISTRY>
    If the insecureRegistries field does not exist, you can add it.
  3. Create the ImageContentSourcePolicy, which instructs the cluster to pull the images from your local registry (run both commands):
```
oc apply -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml
```
```
oc apply -f ~/.ibm-pak/data/mirror/$CS_CASE_NAME/$CS_CASE_VERSION/image-content-source-policy.yaml
```
  4. Verify that each ImageContentSourcePolicy resource was created:
```
oc get imageContentSourcePolicy
```
  5. Verify your cluster node status:
```
oc get MachineConfigPool -w
```
    Wait for all nodes to be updated before proceeding to the next step.
Apply the catalog sources.

Now that you have mirrored images to the target cluster, apply the catalog sources.

In the following steps, replace <Architecture> with either amd64, s390x or ppc64le as appropriate for your environment.
1. Export the variables for the command line to use:
```
export CASE_NAME=ibm-apiconnect
export CASE_VERSION=4.0.10
export ARCH=amd64
```
```
export CS_CASE_NAME=ibm-cp-common-services
export CS_CASE_VERSION=1.15.10
export CS_ARCH=amd64
```
2. Generate the catalog sources and save them in another directory in case you need to replicate this installation in the future.
  1. Get the catalog sources:
```
cat ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml
```
```
cat ~/.ibm-pak/data/mirror/${CS_CASE_NAME}/${CS_CASE_VERSION}/catalog-sources.yaml
```
  2. Get any architecture-specific catalog sources that you need to back up as well:
```
cat ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources-linux-${ARCH}.yaml
```
  You can also navigate to the directory in your file browser to copy these artifacts into files that you can keep for re-use or for pipelines.
3. Apply the catalog sources to the cluster.
  1. Apply the universal catalog sources:
```
oc apply -f ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml
```
```
oc apply -f ~/.ibm-pak/data/mirror/${CS_CASE_NAME}/${CS_CASE_VERSION}/catalog-sources.yaml
```
  2. Apply any architecture-specific catalog sources:
```
oc apply -f ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources-linux-${ARCH}.yaml
```
  3. Confirm that the catalog sources were created in the openshift-marketplace namespace:
```
oc get catalogsource -n openshift-marketplace
```
Create the namespace where you will install API Connect.
1. Specify the namespace where you want to install the operator:
```
export NAMESPACE=<APIC-namespace>
```
  The namespace where you install API Connect must meet the following requirements:
  - Red Hat OpenShift Container Platform (OCP): Only one top-level CR (APIConnectCluster) can be deployed in each namespace.
  - Cloud Pak for Integration: Only one API Connect capability can be deployed in each namespace.
  - The following namespaces cannot be used to install API Connect because Red Hat OpenShift Container Platform (OCP) restricts the use of default namespaces for installing non-cluster services:
    - default
    - kube-system
    - kube-public
    - openshift-node
    - openshift-infra
    - openshift
2. Create a new namespace for installing the operator:
```
oc new-project $NAMESPACE
```
3. Create an OperatorGroup:
  1. Create a YAML file called apiconnect-operator-group.yaml similar to the following example, replacing <APIC-namespace> with your new namespace:
```
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: ibm-apiconnect-operatorgroup
spec:
  targetNamespaces:
  - <APIC-namespace>
```
  2. Add the new operator group to your namespace:
```
oc apply -f apiconnect-operator-group.yaml -n ${NAMESPACE}
```
(10.0.5.3 and later) Create the ibm-common-services-operator subscription, if it does not already exist.

This step only applies when you install version 10.0.5.3 or later. If you are installing an older version of API Connect, skip this step.

The ibm-common-services-operator is provided by IBM Cloud Pak foundational services.
1. Create a file called common-services-sub.yaml and paste in the following contents:
```
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-common-service-operator
  namespace: <APIC-namespace>
spec:
  channel: <channel>
  installPlanApproval: Automatic
  name: ibm-common-service-operator
  source: opencloud-operators
  sourceNamespace: openshift-marketplace
```
  Where:
  - <APIC-namespace> the namespace where you will install API Connect.
  - <channel> is one of the following values:
    - v3.23 if you are using IBM Cloud Pak foundational services for Continuous Delivery
    - v3 if you are using IBM Cloud Pak foundational services for Long Term Service Release
2. Apply the subscription with the following command:
```
oc apply -f common-services-sub.yaml
```
3. Select Operators > Installed Operators, and ensure that Project: All Projects is selected.
  If any operators such as ibm-apiconnect or ibm-cert-manager-operator show the status of "Upgrade available", approve the upgrade by completing the following steps:
  1. Click Upgrade available.
  2. Click Preview InstallPlan.
  3. Click Approve.
  4. Check the ibm-common-services namespace and ensure that all operators with a status of "Upgrade available" are approved.
  5. Wait for the IBM Cloud Pak foundational services, IBM NamespaceScope, and Operand Deployment Lifecycle Manager operators to install.
(10.0.5.3 and later) Install cert manager:

This step only applies when you install version 10.0.5.3 or later. If you are installing an older version of API Connect, skip this step.
1. Create a file called cert-manager-operand-request.yaml and paste in the following content:
```
apiVersion: operator.ibm.com/v1alpha1
kind: OperandRequest
metadata:
  name: ibm-apiconnect-cert-manager
  namespace: <APIC-namespace>
spec:
  requests:
  - operands:
    - name: ibm-cert-manager-operator
    registry: common-service
    registryNamespace: ibm-common-services
```
2. Create the operandRequest for cert-manager by running the following command:
```
oc apply -f cert-manager-operand-request.yaml
```
3. Select Operators > Installed Operators, and ensure that Project: All Projects is selected.
  Wait for the ibm-cert-manager-operator to display and if it shows the status of "Upgrade available", approve the upgrade by completing the following steps:
  1. Click Upgrade available.
  2. Click Preview InstallPlan.
  3. Click Approve.
  4. Wait for the IBM Cert Manager operator to install.

Create a Subscription for the

IBM
APIConnect

operator.

Create a YAML file called apic-sub.yaml similar to the following example:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-apiconnect
spec:
  channel: v3.9
  name: ibm-apiconnect
  source: ibm-apiconnect-catalog
  sourceNamespace: openshift-marketplace

Apply the new subscription to your namespace:
```
oc apply -f apic-sub.yaml -n ${NAMESPACE}
```

Install API Connect (the operand).

API Connect provides one top-level CR that includes all of the API Connect subsystems (Management, Developer Portal, Analytics, and Gateway).

Important: When you install API Connect, you must configure secure communication between subsystems. Use mTLS or JWT for management to portal and analytics subsystems. Use JWT for management to gateway communication. For more information on inter-subsystem communication, see Network requirements for inter-subsystem communication.

Tip: Before you install API Connect, you can customize the configuration of the analytics subsystem. Review the information in Planning your analytics deployment to choose configuration options, and then configure the settings as explained in Analytics subsystem CR configured settings.. If you are installing with the top-level APIConnectClusterCR, add your configuration settings to the spec.analytics section of the CR; if you are installing the subsystems individually, make your changes to the AnalyticsCluster CR.
1. Create a YAML file to use for deploying the top-level APIConnectCluster CR. Use the template that applies to your deployment (non-production or production).
  Note: The values shown in the following examples might not be suitable for your deployment. For information on the license, profile, and version settings, as well as additional configuration settings, see API Connect configuration settings.
  - Example CR settings for a one replica deployment:
```
apiVersion: apiconnect.ibm.com/v1beta1
kind: APIConnectCluster
metadata:
  labels:
    app.kubernetes.io/instance: apiconnect
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: apiconnect-minimum
  name: <name_of_your_instance> 
  namespace: <APIC-namespace> 
spec:
  license:
    accept: true
    license: L-VQYA-YNM22H
    metric: PROCESSOR_VALUE_UNIT
    use: nonproduction
  profile: n1xc17.m48
  version: 10.0.5.9
  storageClassName: <default-storage-class>
```
  - Example CR settings for a three replica deployment:
```
apiVersion: apiconnect.ibm.com/v1beta1
kind: APIConnectCluster
metadata:
  labels:
    app.kubernetes.io/instance: apiconnect
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: apiconnect-production
  name: <name_of_your_instance> 
  namespace: <APIC-namespace>
spec:
  license:
    accept: true
    license: L-VQYA-YNM22H
    metric: PROCESSOR_VALUE_UNIT
    use: production
  profile: n3xc16.m48
  version: 10.0.5.9
  storageClassName: <default-storage-class>
```
2. Optional: If you don't want to use Cloud Pak endpoints in Cloud Pak for Integration 2022.2.1 or 2022.4.1, add the following annotation to the metadata section of your CR:
```
metadata:
  annotations:
    apiconnect-operator/cp4i: "false"
```
3. Apply the YAML file:
```
oc apply -f <your_yaml_file>
```
4. To verify your API Connect cluster is successfully installed, run the following command:
```
oc get apic -n <APIC-namespace>
```
5. Verify that you can log in to the API Connect Cloud Manager UI:
  To determine the location for logging in, view all the endpoints:
```
oc get routes -n <APIC-namespace>
```
6. Locate the mgmt-admin-apic endpoint, and access the Cloud Manager UI.
7. Login as the API Connect administrator.
  When you install with the top-level CR, the password is auto-generated. To get the password:
```
oc get secret -n <APIC-namespace> | grep mgmt-admin-pass 
oc get secret -n <APIC-namespace> <secret_name_from_previous command> -o jsonpath="{.data.password}" | base64 -d && echo
```
Optional: Increase the timeout settings for the API Connect management endpoints, particularly for large deployments. See Configuring timeouts for management endpoints.

What to do next

When you finish installing API Connect, prepare your deployment for disaster recovery so that your data can be restored in the event of an emergency.