Helm-Based Installation

Prerequisites

In addition to the prerequisites discussed on that page, you will require network connectivity from the cluster to either the Internet, or to an OCI registry that you operate yourself on which you host mirrored copies of the QHx OCI images.

Installation Process

The installation process comprises the following steps:

Determine the QHx release version to install.
Install the QHx CLI on the administrator’s machine.
Install the QHx release onto the cluster.

Installing the QHx CLI

The QHx CLI (qhx) is distributed as an artifact via the OCI repository. You can use the ORAS tool to retrieve it:

# Login to the OCI registry.
~$ oras login oci.messier42.com
Username: <CUSTOMER-REGISTRY-USERNAME>
Password: <CUSTOMER-REGISTRY-KEY>

# Download the QHx CLI binary.
~$ mkdir qhx-cli && cd qhx-cli
~/qhx-cli$ oras pull --platform linux/amd64 oci.messier42.com/qhx/cli-oras:latest

# You can copy the CLI binary to a suitable location (e.g. `/usr/local/bin`) so
# that it is readily available to you:
~/qhx-cli$ sudo install -Dm755 bin/qhx

# The QHx CLI is now available:
~/qhx-cli$ qhx help

Installing the QHx release onto the cluster

Confirm cluster status. Ensure you can access your target cluster and that the cluster is functioning:

$ kubectl get nodes

Installation. QHx is deployed onto the cluster as a standard Helm chart.

You can install QHx using the Helm charts from the QHx distribution registry, or using the Helm package file provided as part of the release.

Install using Helm registry. If you are installing the Helm chart using the registry, login to the QHx distribution registry using your customer credentials:
Authenticate to the QHx distribution registry
```
$ helm registry login oci.messier42.com
Username: <CUSTOMER-REGISTRY-USERNAME>
Password: <CUSTOMER-REGISTRY-KEY>
```
You will also need to pass your provisioned customer credentials as part of the installation process as shown below.

The kubernetesVariant setting below should be set to a supported value, such as eks, kind, microk8s, or unknown.
Installing QHx via Helm (online install)
```
$ helm install qhx oci://oci.messier42.com/qhx/charts/qhx-core \
    --version <VERSION-TO-INSTALL> \
    --set kubernetesVariant=unknown \
    --set ociUsername=<CUSTOMER-REGISTRY-USERNAME> \
    --set ociPassword=<CUSTOMER-REGISTRY-KEY> \
    [--set arg=value ...]
```

Install using Helm package file. If you want to install using a Helm package file, instead pass the path to the package file:

$ helm install qhx ./qhx-core-<VERSION-TO-INSTALL>.tgz \
    --set ociUsername=<CUSTOMER-REGISTRY-USERNAME> \
    --set ociPassword=<CUSTOMER-REGISTRY-KEY> \
    [--set arg=value ...]

Persistent storage. QHx packages the Khaled key server as part of the CABE architecture, which requires a persistent storage volume. Khaled is enabled by default; therefore, a QHx installation requires a configured storage class on your cluster. If you do not have one available, for example on a cluster confiugred for test or development purposes, you can disable Khaled by passing --set khaled.enable=false.

Options. For a full list of supported Helm values which allow you to customise the installation options, see Helm values reference.

Manual image hosting in air-gapped environments

If you are installing QHx into an air-gapped environment, you will need to host the OCI images comprising QHx and use the relevant Helm values to customise the OCI image references to refer to the QHx images hosted at your own OCI registry. The regctl tool can be used to export and import OCI images to OCI files.

The following shell commands will export all needed OCI images to .oci files which can be imported to an OCI registry hosted in an air-gapped environment.

# Login and export images on an internet-connected host
$ helm login oci.messier42.com
$ regctl login oci.messier42.com
$ helm show values oci://oci.messier42.com/qhx/charts/qhx-core:${VERSION} \
    | grep -i 'image:\s' > images.yaml
$ for x in $(cat images.yaml | cut -d' ' -f2-); do
    regctl image export --compress "$x" "$(basename "$x").oci";
  done

# Import images on an air-gapped host
$ for x in *.oci; do
    regctl image import "example.local/qhx/$(basename "$x" .oci)" "$x";
  done

The images.yaml file then contains the Helm values which should be customised to point to the correct OCI image identifiers in the air-gapped environment when deploying the Helm chart.

Verifying the installation

After installation, QHx system components are installed into the qhx-system Kubernetes namespace. You can verify this:

$ kubectl get pods -n qhx-system