Installing Guardium Insights manually offline

Manually install your Guardium Insights instance in an air-gap or offline environment.

Before you begin

Before proceeding with these steps, ensure that all necessary registries are properly configured and accessible on the correct port (they must be properly configured to use port 443). This configuration must be made globally and may require downtime.

Procedure

  1. Log in to your Red Hat® OpenShift® cluster instance. 
    oc login -u <KUBE_USER> -p <KUBE_PASS> [--insecure-skip-tls-verify=true]
    For example,
    oc login api.example.ibm.com:6443 -u kubeadmin -p xxxxx-xxxxx-xxxxx-xxxxx
  2. Prepare a private Docker registry that is accessible from both your local machine and the air-gapped cluster.
  3. Set these environment variables: 
    export LOCAL_REGISTRY_HOST=<host IP or FQDN:Listening port>
export LOCAL_REGISTRY_USER=<Username for your private registry>
export LOCAL_REGISTRY_PASS=<Password for your private registry>
export CP_REPO_USER=<Your Username to cp.icr.io>
export CP_REPO_PASS=<Your Password / Entitlement Key to cp.icr.io>
export NAMESPACE=<your chosen namespace>
  4. Create the Guardium Insights namespace and then switch to it: 
    oc create namespace ${NAMESPACE}
oc project ${NAMESPACE}
    Note: If IBM® Common Services is already created and installed, you do not need to create the namespace in this step (Guardium Insights uses the same namespace).
  5. Obtain the case bundle. For the most current version of Guardium Insights and CASE, see https://github.com/IBM/cloud-pak/blob/master/repo/case/ibm-guardium-insights/index.yaml.
    1. Version 3.3.x Choose the CASE version and specify the pre-defined local directory that you want to use:
      For example, to use CASE version 3.2.10, specify the 3.2.10 bundle file.
      export CASE_NAME=ibm-guardium-insights
export CASE_VERSION=3.2.10   #<YOUR_CASE_VERSION>
export LOCAL_CASE_DIR=$HOME/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION
    2. Version 3.3.x Save the CASE bundle locally: 
      oc ibm-pak get $CASE_NAME \
--version $CASE_VERSION \
--skip-verify
      Tips:
      • If you do not specify the CASE version, the most current version of CASE is downloaded.
      • If you encounter an error similar to this example, you might be experiencing a temporary communication problem with the remote repository. Wait a few minutes and try again.
        No Case registries found for case ibm-cert-manager->=1.3.0 <1.3.1.tgz with the given repository URL information
FAILED
    3. Version 3.3.x Create a namespace for the Guardium Insights installation: 
      oc create namespace ${NAMESPACE}
    4. Generate the mirror manifests: 
      oc ibm-pak generate mirror-manifests \
   $CASE_NAME \
   $LOCAL_REGISTRY_HOST \
   --version $CASE_VERSION

      You can use this command to list all images that are mirrored and the publicly accessible registries where those images are pulled from:

      oc ibm-pak describe $CASE_NAME --version $CASE_VERSION --list-mirror-images
    5. Configure your credentials to the cp.icr.io external registry. Alternatively, you can use podman login. 
      docker login cp.icr.io -u $CP_REPO_USER -p $CP_REPO_PASS
      Important: When you log in to cp.icr.io, you must specify the user as cp and for the password, specify your entitlement key from the IBM Cloud Container Registry.
    6. Configure internal registry air-gap credentials. Alternatively, you can use podman login.

      Run this command separately for each registry:

      docker login $LOCAL_REGISTRY_HOST -u $LOCAL_REGISTRY_USER -p $LOCAL_REGISTRY_PASS
  6. Mirror the installation images to your private registry.
    Important: The mirroring process depends on network bandwidth and might take up to a few hours to complete.
    1. Store authentication credentials for all source Docker registries.
      If you use docker login, the authentication file is typically located in $HOME/.docker/config.json on Linux or %USERPROFILE%/.docker/config.json on Windows. After you run docker login, export the REGISTRY_AUTH_FILE to point to that location. For example, on Linux, issue this command:
      export REGISTRY_AUTH_FILE=$HOME/.docker/config.json
      Note: If you use podman login, run the following command after you run podman login. Verify that the file is populated with registry credentials. If the file does not have the registry credentials, complete steps 5.e and 5.f again.
      export REGISTRY_AUTH_FILE=$HOME/.ibm-pak/auth.json
    2. Mirror the images to the final location: 
      oc image mirror \ 
-f $HOME/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/images-mapping.txt \ 
-a $REGISTRY_AUTH_FILE \ 
--filter-by-os '.*' \ 
--insecure \ 
--skip-multiple-scopes \ 
--max-per-registry=1 \ 
--continue-on-error=false > my-mirror-progress.txt
  7. Configure the cluster and the content image source policy for air gap installation.
    Version 3.3.x Run the following command:
    oc apply -f $HOME/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml
    Note:
    • This action causes all nodes to restart. During the restart, nodes show as Ready,SchedulingDisabled or NotReady,SchedulingDisabled.
    • If your OpenShift Container Platform has issues, the nodes might not restart properly. Verify that the nodes restarted properly before you proceed. For more information, see Understanding node rebooting.
    • If you're using an insecure registry (no TLS or a self-signed certificate), configure the cluster to allow the insecure registry:
      oc patch image.config.openshift.io/cluster --type=merge -p '{"spec":{"registrySources":{"insecureRegistries":["'${LOCAL_REGISTRY_HOST}'"]}}}'
    1. Update your global pull secret with your LOCAL_REGISTRY_HOST, LOCAL_REGISTRY_USERNAME, and LOCAL_REGISTRY_PASSWORD. For more information, see Updating the global cluster pull secret (https://docs.openshift.com/container-platform/4.12/openshift_images/managing_images/using-image-pull-secrets.html#images-update-global-pull-secret_using-image-pull-secrets).
    2. Apply the ImageContentSourcePolicy: 
      oc apply -f  $HOME/.ibm-pak/data/mirror/$CASE_NAME/$CASE_VERSION/image-content-source-policy.yaml
      Note: This step might cause your cluster nodes to drain and restart sequentially as they apply the configuration changes.
    3. Verify that the ImageContentSourcePolicy resource is created: 
      oc get imageContentSourcePolicy
    4. Verify your cluster node status and wait for all the nodes to restart before you proceed: 
      oc get MachineConfigPool

$ oc get MachineConfigPool -w
NAME     CONFIG                                             UPDATED   UPDATING   DEGRADED   MACHINECOUNT   READYMACHINECOUNT   UPDATEDMACHINECOUNT   DEGRADEDMACHINECOUNT   AGE
master   rendered-master-53bda7041038b8007b038c08014626dc   True      False      False      3              3                   3                     0                      10d
worker   rendered-worker-b54afa4063414a9038958c766e8109f7   True      False      False      3              3                   3                     0                      10d
      After the ImageContentsourcePolicy and global image pull secret are applied, the configuration of your nodes will be updated sequentially. Wait until all MachineConfigPools are in the UPDATED=True status before proceeding.
  8. Optional: Version 3.3.x If you are using an unsecure registry (no TLS or a self-signed certificate), configure the cluster to allow the unsecure registry: 
    oc patch image.config.openshift.io/cluster --type=merge -p '{"spec":{"registrySources":{"insecureRegistries":["'${LOCAL_REGISTRY_HOST}'"]}}}'
  9. Verify that all nodes returned to the Ready state: 
    oc get nodes

    This process can take a minimum of 5 minutes.

  10. Version 3.4.x and later Install the IBM Certificate Manager and IBM Common Services by completing steps 4-14 in Installing IBM Cloud Pak® foundational services.
  11. Install the Guardium Insights operator and related components:
    1. Run the pre-install script. This script sets up secrets and parameters for the Guardium Insights instance. 
      oc ibm-pak launch $CASE_NAME \
--version $CASE_VERSION \
--namespace ${NAMESPACE} \
--inventory install \
--action preInstall \
--tolerance 1 \
--args "-n ${NAMESPACE} -h <DB_worker_host> -l <true/false> -q <true/false>"
      The pre-install script supports these parameters:
      Table 1. Parameters for preInstall.sh
      Name Description Type
      -n or --i-namespace Guardium Insights OpenShift namespace (this value must be 10 or fewer characters) Mandatory
      -h or --host-datanodes Specify the comma-delimited host names of the data nodes that you designate for data computation (you can determine the host names by running oc get nodes).
      Important: When you manage Hardware cluster requirements, use the larger set of Guardium Insights nodes as your data nodes. To determine which node has the most free requests, issue the oc describe nodes command and then look in the Allocation section.
      		 Mandatory
      -l or --label-datanodes If you specify true, the data nodes are labeled as dedicated for data service usage. If you specify false, labeling is skipped. The default value is true. Mandatory
      -t or --taint-datanodes If you specify true, the data nodes are tainted and dedicated for data service usage. If you specify false, tainting is skipped. Do not use false to skip tainting for production deployments. Optional
      -k or --ingress-keystore

      The path of the TLS certificate that is associated with the Guardium Insights application domain.

      If you supply a custom ingress, provide the path to its key file. This file can contain only newline (\n) delimiters. If you do not supply a custom ingress, a default of none is assumed.

      For more information, see Domain name and TLS certificates.

      		 Optional
      -f or --ingress-cert

      The path of the TLS key that is associated with the Guardium Insights application domain.

      If you supply a custom ingress, provide the path to its cert file. This file can contain only newline (\n) delimiters. If you do not include this, a default of none is assumed.

      For more information, see Domain name and TLS certificates.

      		 Optional
      -c or --ingress-ca

      The path of the custom TLS certificate that is associated with the Guardium Insights application domain.

      If you supply a custom ingress, provide the path to its certificate authority (CA) file. This file can contain only newline (\n) delimiters. If you do not include this, a default of none is assumed.

      For more information, see Domain name and TLS certificates.

      		 Optional
      Version 3.4-q or --custom-scc If you specify true, Guardium Insights pods use a custom scc with a default name of gi-odf-scc. If you pass in another value, it applies that value as the scc name. For a list of available SCCs, run oc get scc. Guardium Insights normally runs in restricted-v2 SCC. Defaults to false with no custom scc applied.
      Important: This parameter is only required for Guardium Insights installations that use the storage classes that are provided by OpenShift Data Foundation (ODF) Version 4.14 on non-ROSA and non-ARO deployments.
      		 Optional
      -help or --help Displays the preInstall.sh parameters. Optional
    2. Install the catalogs. 
      oc ibm-pak launch $CASE_NAME \
  --version $CASE_VERSION \
 --namespace openshift-marketplace \
 --inventory install \
 --action install-catalog \
 --tolerance 1 \
 --args "--registry ${LOCAL_REGISTRY_HOST} --inputDir ${LOCAL_CASE_DIR}"
      To verify that the catalogs are installed, issue this command:
      oc get pod -n openshift-marketplace
      The following example shows a successful output:
      ibm-cloud-databases-redis-operator-catalog-ms97x                  1/1     Running     0          12m
ibm-db2uoperator-catalog-k8pwc                                    1/1     Running     0          13m
    3. Install the operators. 
      oc ibm-pak launch $CASE_NAME \
  --version $CASE_VERSION \
  --namespace ${NAMESPACE} \
  --inventory install \
  --tolerance 1 \
  --action install-operator \
  --args "--registry ${LOCAL_REGISTRY_HOST} --user ${LOCAL_REGISTRY_USER} --pass ${LOCAL_REGISTRY_PASS} --secret ibm-entitlement-key --inputDir ${LOCAL_CASE_DIR}"
      To verify that the operators are installed, issue this command:
      oc get pods
      The following example shows a successful output:
      NAME                                                              READY   STATUS             RESTARTS   AGE
guardiuminsights-controller-manager-6c5f8c685c-85d7s              1/1     Running            0          6m22s
ibm-cloud-databases-redis-operator-54f95f8d48-csrxj               1/1     Running            0          6m20s
mongodb-kubernetes-operator-745746b45c-jz7hw                      1/1     Running            0          6m37s

What to do next

Follow the Creating a Guardium Insights instance by using a custom resource (CR).