Setup¶

Tools needed¶

The examples in this repositories require the following:

a container tool, such as Docker or Podman
optionally a container management tool, such as Skopeo
access to a Kubernetes or OpenShift cluster.

Info

The examples in this repo have been written using a local, bare metal OpenShift cluster, but the examples could be adapted to a Kubernetes cluster or a cluster hosted on a cloud provider

Warning

Make sure your Docker or Podman environment has sufficient resources. A single CPU with 2MB of memory will not be sufficient, suggest using at least 4 CPUs with 8096 MB of memory

Info

Using an Apple Silicon apple mac needs the container runtime to be able to run amd64 images, as the Watson Libraries are only published using amd64 architecture. Ensure that no podman machine exists then setup podman like:

podman machine init --cpus 6 -m 8096 --rootful --now
podman machine ssh

# run the following inside the podman shell
sudo -i
rpm-ostree install qemu-user-static
systemctl reboot

Local bare metal cluster¶

install OCP
install Operators from Operator Hub catalog:
- OpenShift Data Foundation
- Red Hat Quay
  
  Warning
  
  There is a bug in Quay 3.7.10 that prevents large container layers from being stored, which means the Watson Libraries images cannot be stored. This article explains how to deploy a workaround

Accessing container images on IBM Container Registry¶

The IBM Watson Libraries for Embed container images are provided on the IBM Container Registry service, but requires an entitlement key to access them. Once you have a key you need to use it when accessing them.

Local Docker / Podman / Skopeo¶

When accessing the images on your local machine using Docker or Podman you need to login to the IBM container registry:

DockerPodmanSkopeo

docker login cp.icr.io --username cp --password <entitlement_key>

podman login cp.icr.io --username cp --password <entitlement_key>

skopeo login cp.icr.io --username cp --password <entitlement_key>

Kubernetes / OpenShift¶

When accessing the images from a Kubernetes of OpenShift cluster, you need to setup a secret on the cluster then refer to it in a deployment manifest.

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

within a deployment manifest add an imagePullSecret to the template section:

spec:
    ...
    template:
        ...
        spec:
            ...
            imagePullSecrets:
            - name: ibm-entitlement-key

Setting up a local mirror¶

Some of the image sizes of the IBM Watson Libraries for Embed containers are extremely large, running into multiple megabytes, so it can be advantageous to work against a local mirror.

The example configuration installs Quay on the demo cluster. This can be used to hold local mirrors of the IBM Watson for Embed container images.

To mirror the images the Quay mirror repository can be used to automatically mirror the images, or Skopeo can be used to copy the images from the IBM Container Registry to the local Quay registry.

Using the local mirror¶

The local Quay registry has a self-signed SSL certificate by default, so docker, podman, Skopeo and Kubernetes/OpenShift need to be configured to accept or ignore the self-signed X509 certificate when accessing the local registry.

DockerPodmanSkopeoOpenShift / Kubernetes

Docker Desktop and Engine have a configuration file which allow insecure registries to be configured. You need to add the insecure-registries to the configuration file. In Docker for Desktop this can be found in the Preferences panel under the Docker Engine section. On Linux this configuration file is usually found at location /etc/docker/daemon.json. Add the section, so the file looks similar to this:

{
    "builder": {
        "gc": {
        "defaultKeepStorage": "20GB",
        "enabled": true
        }
    },
    "experimental": true,
    "features": {
        "buildkit": true
    },
    "insecure-registries": [
        "https://lab-registry-quay-openshift-operators.apps.ocp.lab.home"
    ]
}

additional details of the configuration can be found in the docker documentation

Podman accepts the --tls-verify=false command line argument, so if added to any command it will ignore any TLS errors.

Skopeo accepts the --src-tls-verify=false and dest-tls-verify=false command line arguments, so if added to the copy command it will ignore TLS errors from the source and/or the destination registries.

Enable OpenShift to pull images from local Quay container registry (using self-signed X509 certificate) by adding the self-signed certificate to the cluster configuration. This can be achieved by running the following as a cluster admin:

- *Modify the REGISTRY_HOSTNAME value on the first line to match your installation*

```shell
export REGISTRY_HOSTNAME=lab-registry-quay-openshift-operators.apps.ocp.lab.home
export REGISTRY_PORT=443
echo "" | openssl s_client -showcerts -prexit -connect "${REGISTRY_HOSTNAME}:${REGISTRY_PORT}" 2> /dev/null | sed -n -e '/BEGIN CERTIFICATE/,/END CERTIFICATE/ p' > tmp.crt
openssl x509 -in tmp.crt -text | grep Issuer
oc create configmap registry-quay -n openshift-config --from-file="${REGISTRY_HOSTNAME}=$(pwd)/tmp.crt"
oc patch image.config.openshift.io/cluster --patch '{"spec":{"additionalTrustedCA":{"name":"registry-quay"}}}' --type=merge
oc get image.config.openshift.io/cluster -o yaml
```