Downloading the Certified Container Software

Before you install IBM Certified Container Software for Sterling Secure Proxy, ensure that the installation files are available on your client system.

Depending on the availability of internet on the cluster, the following procedures can be followed. Choose the one which applies best for your environment.

Online Cluster

The cluster which has access to the internet is called Online cluster. You may have a Kubernetes or OpenShift cluster and it has access to the internet. The process to get required installation files consists of two steps:

Create the entitled registry secret: Complete the following steps to create a secret with the entitled registry key value:
1. Ensure that you have obtained the entitlement key that is assigned to your ID.
  1. Log in to My IBM Container Software Library by using the IBM ID and password that are associated with the entitled software.
  2. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.
  3. Save the entitlement key to a safe location for later use.
    To confirm that your entitlement key is valid, click View library that is provided in the left of the page. You can view the list of products that you are entitled to. If IBM® Sterling Secure Proxy is not listed, or if the View library link is disabled, it indicates that the identity with which you are logged in to the container library does not have an entitlement for IBM Sterling Secure Proxy. In this case, the entitlement key is not valid for installing the software.
2. Set the entitled registry information by completing the following steps:
  1. Log on to machine from where the cluster is accessible
  2. export ENTITLED_REGISTRY=cp.icr.io
  3. export ENTITLED_REGISTRY_USER=cp
  4. export ENTITLED_REGISTRY_KEY=<entitlement_key>
3. This step is optional. Log on to the entitled registry with the following docker login command:
```
   docker login "$ENTITLED_REGISTRY" -u "$ENTITLED_REGISTRY_USER" -p "$ENTITLED_REGISTRY_KEY"
```
4. Create a Docker-registry secret:
```
 kubectl create secret docker-registry <any_name_for_the_secret> --dockerusername=$ ENTITLED_REGISTRY_USER --docker-password=$ENTITLED_REGISTRY_KEY --dockeremail=<your_docker_email_address> --docker-server=$ENTITLED_REGISTRY -n <your namespace/project name>
```
5. Update the service account or helm chart image pull secret configurations using `image.imageSecrets` parameter with the above secret name.
Download the Helm chart: You can follow the steps below to download the helm chart from the repository.
1. Make sure that the helm client (CLI) is present on your machine. Execute/run helm CLI on machine and you should be able to see the usage of helm CLI.
```
helm
```
2. Check the ibm-helm repository in your helm CLI.
```
helm repo list
```
  If the ibm-helm repository already exists with URL https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm, then update the local repository else add the repository.
3. Update the local repository, if ibm-helm repository already exists on helm CLI.
```
helm repo update
```
4. Add the helm chart repository to local helm CLI if it does not exist.
```
helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
```
5. Download the helm chart.
  IBM Sterling Secure Proxy Configuration Manager:
```
helm pull ibm-helm/ibm-ssp-cm
```
  IBM Sterling Secure Proxy Engine:
```
  helm pull ibm-helm/ibm-ssp-engine
```
  IBM Sterling Secure Proxy Perimeter Server:
```
helm pull ibm-helm/ibm-ssp-ps
```
  At this point we have a locally present helm chart and an Entitled registry secret. Make sure you configure the helm chart to use the Entitled registry secret to download the required container image for deploying IBM Sterling Secure Proxy.

Offline (Airgap) Cluster

You have a Kubernetes or OpenShift cluster but it is a private cluster which means it does not have the internet access. Depending upon the cluster, follow the below procedures to get the installation files.

For Kubernetes Cluster

Since, your Kubernetes cluster is private and it does not have internet access, you cannot download the required installation files directly from the server. By following steps below, you can get the required files.

Get an RHEL machine which has
- internet access
- docker or podman
- helm
Download the Helm chart by following the steps mentioned in the Online installation section above.
Extract the downloaded helm chart.
IBM Sterling Secure Proxy Configuration Manager:
```
  tar -zxf <ibm-ssp-cm-helm chart-name>
```
IBM Sterling Secure Proxy Engine:
```
 tar -zxf <ibm-ssp-engine-helm chart-name>
```
IBM Sterling Secure Proxy Perimeter Server:
```
   tar -zxf <ibm-ssp-ps-helm chart-name>  
```

Get the container image detail:

IBM Sterling Secure Proxy Configuration Manager:

export SSP_CM_IMAGE=$(grep -w "repository:" ibm-ssp-cm/values.yaml |cut -d '"' -f 2):$(grep -w "tag:" ibm-ssp-cm/values.yaml | cut -d '"' -f 2)

IBM Sterling Secure Proxy Engine:

export SSP_ENGINE_IMAGE=$(grep -w "repository:" ibm-ssp-engine/values.yaml |cut -d '"' -f 2):$(grep -w "tag:" ibm-ssp-engine/values.yaml | cut -d '"' -f 2)

IBM Sterling Secure Proxy Perimeter Server:

 export SSP_PS_IMAGE=$(grep -w "repository:" ibm-ssp-ps/values.yaml |cut -d '"' -f 2):$(grep -w "tag:" ibm-ssp-ps/values.yaml | cut -d '"' -f 2)

Get the Entitled registry entitlement key by following steps a and b explained under Create the entitled registry .
Get the container image downloaded in docker registry:
```
docker login "$ENTITLED_REGISTRY" -u "$ENTITLED_REGISTRY_USER" -p "$ENTITLED_REGISTRY_KEY"
```
IBM Sterling Secure Proxy Configuration Manager:
```
docker pull $SSP_CM_IMAGE
```
IBM Sterling Secure Proxy Engine:
```
docker pull $SSP_ENGINE_IMAGE
```
IBM Sterling Secure Proxy Perimeter Server:
```
docker pull $SSP_PS_IMAGE
```
Note: Skip step 7, 8, and 9, if the cluster where deployment will be performed is accessible from this machine and cluster can fetch container images from registry running on this machine.

Save the container image.

IBM Sterling Secure Proxy Configuration Manager:

docker save -o <container image file name.tar> $SSP_CM_IMAGE

IBM Sterling Secure Proxy Engine:

  docker save -o <container image file name.tar> $SSP_ENGINE_IMAGE

IBM Sterling Secure Proxy Perimeter Server:

docker save -o <container image file name.tar> $SSP_PS_IMAGE

Copy/Transfer the installation files to your cluster. At this point you have both downloaded container image and helm chart for IBM Sterling Secure Proxy. You need to transfer these two file to a machine from where you can access your cluster and its registry.
After transferring the files, load the container image into your registry.
```
docker load -i <container image file name.tar>
```

For OpenShift Cluster

Since, air gap environments do not have access to the public internet. We must have a bastion host. Ensure that the bastion host can access:

The public internet to download the CASE and images.
The target (air gap) image registry where all the images will be mirrored to.
The OpenShift cluster where deployment will be performed.

Follow the below steps:

Prepare the Bastion host: Ensure you have the following tools installed on the Bastion host:
- Docker CLI (docker) or Podman CLI (podman)
- IBM Cloud Pak CLI (cloudctl)
- OpenShift Container Platform CLI (oc)

Download the CASE:

Note: Do not execute all the commands at a same time, you must execute the commends mentioned in steps 2 to 7 sequentially either for Configuration Manager, Engine or Perimeter Server.

Save the CASE.

IBM Sterling Secure Proxy Configuration Manager:

 cloudctl case save -t 1 --case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-ssp-cm/<version>/ibm-ssp-cm-<version>.tgz --outputdir download_dir/ && tar -xf download_dir/ibm-ssp-cm-<version>.tgz

IBM Sterling Secure Proxy Engine:

cloudctl case save -t 1 --case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-ssp-engine/<version>/ibm-ssp-engine-<version>.tgz --outputdir download_dir/ && tar -xf download_dir/ibm-ssp-engine-<version>.tgz

IBM Sterling Secure Proxy Perimeter Server:

cloudctl case save -t 1 --case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-ssp-ps/<version>/ibm-ssp-ps-<version>.tgz --outputdir download_dir/ && tar -xf download_dir/ibm-ssp-ps-<version>.tgz

<version> should be desired version of the case to be downloaded
download_dir should be the path where case is to be downloaded

The following output is displayed:

 Downloading and extracting the CASE ...
	  - Success
	  Retrieving CASE version ...
	  - Success
	  Validating the CASE ...
	  - Success
	  Creating inventory ...
	  - Success
	  Finding inventory items
	  - Success
	  Resolving inventory items ...
	  Parsing inventory items

Verify the CASE (.tgz) file and images (.csv) file have been downloaded:

IBM Sterling Secure Proxy Configuration Manager:

ls download_dir
      charts
      ibm-ssp-cm-<version>-charts.csv
      ibm-ssp-cm-<version>-images.csv
      ibm-ssp-cm-<version>.tgz

IBM Sterling Secure Proxy Engine:

ls download_dir
      charts
      ibm-ssp-engine-<version>-charts.csv
      ibm-ssp-engine-<version>-images.csv
      ibm-ssp-engine-<version>.tgz

IBM Sterling Secure Proxy Perimeter Server:

ls download_dir
      charts
      ibm-ssp-ps-<version>-charts.csv
      ibm-ssp-ps-<version>-images.csv
      ibm-ssp-ps-<version>.tgz

Log in to the OCP cluster as cluster-admin role
```
oc login -u <cluster user> -p <user password>
```
Get the Entitled registry key by following steps a1, a2 and a3 as mentioned under Create the entitled registry .

Configure Registry Authentication Secret.

Create authentication secret for source image registry: The images are available on Entitled Registry and it is a private registry. So, credentials are needed to access this registry. Execute the following command to create the authentication secret:

IBM Sterling Secure Proxy Configuration Manager:

cloudctl case launch --case ibm-ssp-cm --inventory ibmSspCm --action configure-creds-airgap --args "--registry $ENTITLED_REGISTRY --user $ENTITLED_REGISTRY_USER --pass $ENTITLED_REGISTRY_KEY" -t 1

IBM Sterling Secure Proxy Engine:

cloudctl case launch --case ibm-ssp-engine --inventory ibmSspEngine --action configure-creds-airgap --args "--registry $ENTITLED_REGISTRY --user $ENTITLED_REGISTRY_USER --pass $ENTITLED_REGISTRY_KEY" -t 1

IBM Sterling Secure Proxy Perimeter Server:

cloudctl case launch --case ibm-ssp-ps --inventory ibmSspPs --action configure-creds-airgap --args "--registry $ENTITLED_REGISTRY --user $ENTITLED_REGISTRY_USER --pass $ENTITLED_REGISTRY_KEY" -t 1

Create authentication secret for target image registry: This step is optional if the registry is not a secure registry which means the registry can be accessed without authentication. The target registry is OpenShift cluster accessible registry from where images could be pulled in to the registry when a chart is deployed. Execute the following command to create the authentication secret:

IBM Sterling Secure Proxy Configuration Manager:

cloudctl case launch --case ibm-ssp-cm --inventory ibmSspCm --action configure-creds-airgap --args "--registry <Local_Docker_Registry URL> --user <Local_Docker_Registry username> --pass <Local_Docker_Registry password>" -t 1

IBM Sterling Secure Proxy Engine:

cloudctl case launch --case ibm-ssp-engine --inventory ibmSspEngine --action configure-creds-airgap --args "--registry <Local_Docker_Registry URL> --user <Local_Docker_Registry username> --pass <Local_Docker_Registry password>" -t 1

IBM Sterling Secure Proxy Perimeter Server:

cloudctl case launch --case ibm-ssp-ps --inventory ibmSspPs --action configure-creds-airgap --args "--registry <Local_Docker_Registry URL> --user <Local_Docker_Registry username> --pass <Local_Docker_Registry password>" -t 1

Note: The credentials are now saved to ~/.airgap/secrets/<registry-name>.json.

Mirror images to target registry: This step would mirror the image present on the Source registry to the Target using the secrets created in the previous step. Execute the following command to mirror the images:

IBM Sterling Secure Proxy Configuration Manager:

cloudctl case launch --case ibm-ssp-cm --inventory ibmSspCm --namespace <namespace name> --action mirror-images --args "--registry <Local_Docker_Registry URL> --inputDir download_dir/" -t 1

IBM Sterling Secure Proxy Engine:

cloudctl case launch --case ibm-ssp-engine --inventory ibmSspEngine --namespace <namespace name> --action mirror-images --args "--registry <Local_Docker_Registry URL> --inputDir download_dir/" -t 1

IBM Sterling Secure Proxy Perimeter Server:

cloudctl case launch --case ibm-ssp-ps --inventory ibmSspPs --namespace <namespace name> --action mirror-images --args "--registry <Local_Docker_Registry URL> --inputDir download_dir/" -t 1

Configure cluster for Air gap: This step does the following:
- creates a global image pull secret for the target registry (skipped if target registry is unauthenticated)
- creates a imagesourcecontentpolicy
  Warning:
  - Cluster resources must adjust to the new pull secret, which can temporarily limit the usability of the cluster. Authorization credentials are stored in $HOME/.airgap/secrets and /tmp/airgap* to support this action.
  - Applying imagesourcecontentpolicy causes cluster nodes to recycle. This might take 20 minutes to complete.
1. Configure a global image pull secret and ImageContentSourcePolicy resource by running following command:
  IBM Sterling Secure Proxy Configuration Manager:
```
cloudctl case launch --case ibm-ssp-cm --inventory ibmSspCm --namespace <namespace name> --action configure-cluster-airgap --args "--registry <Local_Docker_Registry URL> --inputDir download_dir/" -t 1
```
  IBM Sterling Secure Proxy Engine:
```
cloudctl case launch --case ibm-ssp-engine --inventory ibmSspEngine --namespace <namespace name> --action configure-cluster-airgap --args "--registry <Local_Docker_Registry URL> --inputDir download_dir/" -t 1
```
  IBM Sterling Secure Proxy Perimeter Server:
```
cloudctl case launch --case ibm-ssp-ps --inventory ibmSspPs --namespace <namespace name> --action configure-cluster-airgap --args "--registry <Local_Docker_Registry URL> --inputDir download_dir/" -t 1
```
2. Optional: If you are using an insecure target registry, you must add the target registry to the cluster insecureRegistries list by executing the following command:
```
 oc patch image.config.openshift.io/cluster --type=merge	-p '{"spec":{"registrySources":{"insecureRegistries":["'<Local_Docker_Registry URL>'"]}}}'
```
At this point your cluster is ready for IBM Sterling Secure Proxy deployment. The helm chart is present in download_dir/charts directory. Use it for deployment.
Configuration required in Helm chart: To use the image mirroring in OpenShift cluster, helm chart should be configured to use the digest value for referring to container image. Set image.digest.enabled to true in values.yaml file or pass this parameter using Helm CLI.