Installing with a bastion host

This task must be performed by a Red Hat OpenShift or Kubernetes administrator. 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 bastion host. A bastion host has access to both the public internet and the network-restricted environment where the target clusters reside. You can fetch product images from the internet and push them to a local registry; then you can pull the images from the local registry to the target cluster for installation.

1. Set up the mirroring environment.
   1. Prepare the target cluster:
      • Deploy a supported version of Red Hat OpenShift Container Platform (OCP) or Native Kubernetes (K8S) as a cluster.
      • Configure storage on the cluster and make sure that it is available.
   2. Prepare the bastion host:

      You must be able to connect your bastion host to the internet and to the restricted network environment (with access to the Red Hat OpenShift Container Platform (OCP) or Native Kubernetes (K8S) cluster and the local registry) at the same time. Your host must be on a Linux x86_64 or Mac platform with any operating system that the Red Hat OpenShift Client or Native Kubernetes (K8S) supports (in Windows, execute the actions in a Linux x86_64 VM or from a Windows Subsystem for Linux terminal).

      1. Ensure that the sites and ports listed in Table 1 can be reached from the bastion host:

         Table 1. Sites that must be reached from the bastion host

         Site	Description
         icr.io:443	IBM entitled registry
         cp.icr.io:443	IBM Cloudpak registry
         quay.io:443	Local API Connect for GraphQL Software image repository
         github.com	CASE files and tools
         redhat.com	Red Hat OpenShift Container Platform (OCP) upgrades

      2. Install the dependency packages on the bastion host.
         • For Red Hat OpenShift environment
           1. install Podman. Podman is used for managing containers. 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

           2. 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.

           3. 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

         • For Native Kubernetes environment
           1. Install skopeo. skopeo is used for managing containers.
              For example, on Red Hat Enterprise Linux 9, install skopeo using the following command:

              yum install skopeo

           2. Install kubectl tool.
           3. Download the IBM Catalog Management Plug-in for IBM Cloud Pak version 1.1.0 or later from GitHub. After extracting the IBM Cloud Pak version, enter the following command inside the extracted IBM Cloud Pak folder.

              cp oc-ibm_pak-<OS>-<architecture type> /usr/local/bin/kubectl-ibm_pak

              For example, in case of Linux OS:

              cp oc-ibm_pak-linux-amd64 /usr/local/bin/kubectl-ibm_pak

              The ibm-pak plug-in enables you to access hosted product images, and to run kubectl 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:

              kubectl 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 Essentials 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.

2. [This is applicable only for Red Hat OpenShift environment.] Mirror the cert-manager operator for Red Hat OpenShift.

   It is recommended to use the cert-manager operator for Red Hat OpenShift. Mirror the operator as explained in the Red Hat instructions: Mirroring images for a disconnected installation using the oc-mirror plugin .

   When you modify the ImageSetConfiguration, include openshift-cert-manager-operator at channel stable-v1 as one of the packages, as shown in the following example:

       packages:
       - name: openshift-cert-manager-operator
         channels:
         - name: stable-v1

3. Set environment variables and download CASE files.

   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.

   1. Create the following environment variables with the installer image name and the image inventory on your host:

      export CASE_NAME=ibm-stepzen-case
      export CASE_VERSION=<version+timestamp>
      export ARCH=amd64

   2. Connect your host 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:

      For Red Hat OpenShift envt: oc ibm-pak get $CASE_NAME --version $CASE_VERSION
      For Native Kubernetes envt: kubectl ibm-pak get $CASE_NAME --version $CASE_VERSION
      

4. 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 for GraphQL Software.

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

         For Red Hat OpenShift envt: oc ibm-pak generate mirror-manifests $CASE_NAME --version $CASE_VERSION $TARGET_REGISTRY
         For Native Kubernetes envt: kubectl ibm-pak generate mirror-manifests $CASE_NAME --version $CASE_VERSION $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:

      • catalog-sources.yaml
      • catalog-sources-linux-<arch>.yaml (if there are architecture-specific catalog sources)
      • image-content-source-policy.yaml
      • images-mapping.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.
         1. For Red Hat OpenShift, use Podman; for example:

            podman login cp.icr.io

            Use cp as the username and your entitlement key as the password.

         2. For Native Kubernetes, use skopeo; for example:

            skopeo login cp.icr.io

   4. Authenticate with the local registry.
      1. For Red Hat OpenShift, use Podman; for example:

         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.

      2. For Native Kubernetes, use skopeo; for example:

         Log in to the local registry using an account that can write images to that registry; for example:

         skopeo login $TARGET_REGISTRY

         If the registry is insecure, add the following flag to the command: --tls-verify=false.

   5. Mirror the product images.
      1. Connect the bastion host to both the internet and the restricted-network environment that contains the local registry.
      2. Run the following commands to copy the images to the local registry:
         1. For Red Hat OpenShift Container Platform, use the following command:

            oc image mirror \
              -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \
              -a $REGISTRY_AUTH_FILE \
              --filter-by-os '.*' \
              --skip-multiple-scopes \
              --max-per-registry=1

            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.

         2. For Native Kubernetes environment, use the following command:

            cat ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt | awk -F'=' '{ print "skopeo copy --all docker://"$1" docker://"$2 }'

            This command generates the list of skopeo commands as shown in the example.Execute these commands sequentially.
   6. Configure the target cluster.
      • For Red Hat OpenShift Container Platform, perform the following steps:

        1. After mirroring the images to the local registry, you need to configure the target cluster to pull images from it. Follow these steps to set up the cluster's global pull secret with the local registry's credentials and direct the cluster to retrieve 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:

              oc apply -f ~/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml

           4. Verify that the 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.

      • For Native Kubernetes environment, perform the followings steps:
        1. Add host aliases for cp.icr.io and icr.io so that it points to your local registry. You can set the host aliases based on pod level or cluster level settings. Refer to Adding entries to Pod /etc/hosts with HostAliases for more details.
        2. Make sure that the host aliases redirects to your target mirrored registry.
   7. Install the operator.
      1. Create a namespace (project).
         1. (Optional) Update the operator to define a custom namespace.

            By default, the operator looks for a namespace called stepzen. If you want to use the stepzen namespace, skip this step.

            Run the following command to replace all occurrences of the stepzen namespace in the operator.yaml file with your custom namespace, replacing <my-namespace> with your own name:

            sed -i.orig 's/namespace: stepzen/namespace: <my-namespace>/g' operator.yaml

         2. Create a namespace, and then set the context to the new namespace.

            Run the following commands, replacing <my-namespace> with the name of your namespace (stepzen if you did not update the operator.yaml) file:

            Red Hat OpenShift:

            oc new-project <my-namespace>
            oc project <my-namespace>

            Kubernetes:

            kubectl create namespace <my-namespace>
            kubectl config set-context --current --namespace=<my-namespace>

      2. Create the secrets.

         The operator requires two secrets: an image pull secret of the type kubernetes.io/dockerconfigjson, and the data source name (DSN) of your PostgreSQL database.

         1. Create an image pull secret using your IBM entitlement key.

            Create an image pull secret named ibm-entitlement-key (for OpenShift, replace kubectl with oc):

            kubectl create secret docker-registry ibm-entitlement-key --docker-server=cp.icr.io --docker-username=cp --docker-password=<IBM entitlement key>

         2. Create a generic secret for the PostgreSQL server.

            Create a generic secret containing the key DSN with a DSN pointing to your PostgreSQL server (for OpenShift, replace kubectl with oc):

            kubectl create secret generic db-secret --from-literal=DSN=<dsn>

            where <dsn> is a string of the form postgresql://user:password@host/database.

         You can choose different secret names than those used in the examples. If you do, keep a record of the names and remember to use your own secrets when configuring the service).

      3. Download and extract the CASE bundle.
         1. Navigate to the ibm-stepzen-case folder:

            cd $HOME/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION

         2. Extract the CASE bundle by running the following command:

            tar zxvf ibm-stepzen-case--<$CASE_VERSION>.tgz

            The contents are the CASE bundle are stored in a new directory called ibm-stepzen-case.

      4. Apply the operator manifest files to your cluster.
         1. In the extracted CASE, navigate to the following directory, where the installation files are stored:

            ibm-stepzen-case/inventory/stepzenGraphOperator/files/deploy

         2. In the /deploy folder, locate the following files:
            • crd.yaml is the operator Custom Resource Definition (CRD), a schema for the Custom Resource (CR) used to configure the operator.
            • operator.yaml defines the operator resources, including the active service account and associated roles, webhook, and operator deployment configuration.
         3. Apply the files by running the following commands (for OpenShift, replace kubectl with oc):

            kubectl apply -f crd.yaml 
            kubectl apply -f operator.yaml 

      5. Create a custom resource (CR) that defines the configuration settings for your deployment.

         The /deploy folder also contains a sample custom resource (CR) file named cr.yaml. Modify the CR to customize your GraphQL server.

         At minimum, make the following changes to enable installation:

         Tip: For information on settings, see CR configuration settings.
         1. Accept the license agreement.

            Review the API Connect for GraphQL License agreement, and then set the key spec.licence.accept to true in the CR file to indicate your agreement.

         2. Add your registry access token.

            Set spec.imagePullSecrets to contain the name of the registry access token you created in step ii a.

         3. Add your PostgreSQL secret.

            Set spec.controlDatabaseSecret to the name of the secret containing the PostgreSQL DSN (that is, containing a DSN key), which you created in step ii b.

            The following snippet shows an example CR with minimal contents, which configures horizontal pod autoscaling (HPA) for the graph and graph subscription services:

            apiVersion: stepzen-graph.ibm.com/v1beta1
            kind: StepZenGraphServer
            metadata:
              name: stepzen
            spec:
              license:
                accept: true
              controlDatabaseSecret: db-secret
              imagePullSecrets: 
                - ibm-entitlement-key
              graphServer:
                hpa:
                  minReplicas: 1
                  maxReplicas: 10
                  targetCPUUtilizationPercentage: 80
              graphServerSubscription:
                hpa:
                  minReplicas: 1
                  maxReplicas: 5
                  targetCPUUtilizationPercentage: 80

         For more information on the settings available in the CR, see Configuring API Connect for GraphQL Software.

      6. Configure API Connect for GraphQL Software by applying the CR.
         1. Apply the CR by running the following command (for OpenShift, replace kubectl with oc):

            kubectl apply -f cr.yaml

         2. Verify that the operator is running (for OpenShift, replace kubectl with oc):

            kubectl get StepZenGraphServer 

      When the installation completes successfully, you see a message similar to the following example, which indicates that the API Connect for GraphQL Software Graph Service is now running in your cluster:

      NAME      STATUS   SUMMARY              AGE
      stepzen   Ready    Services are ready   1m

      When you run oc get pods, you see three types of pods running:

      • stepzen-graph-operator-xxxx: Operator pod managing the service
      • stepzen-graph-server-xxxx: Graph Server handling single GraphQL requests (queries and mutations)
      • stepzen-graph-server-subscription-xxxx: Graph Server handling GraphQL subscriptions (persistent queries)