Helm-Based Installation

Prerequisites

See Overview.

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:

1. Determine the QHx release version to install.

2. Install the QHx CLI on the administrator’s machine.

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

Retrieving QHx CLI tools

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

Confirming kubectl functionality

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

  Installing QHx via Helm (online install)

  $ helm install qhx oci://oci.messier42.com/qhx/charts/qhx-core \
      --version <VERSION-TO-INSTALL> \
      --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:

  Installing QHx via Helm (package file install)

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

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.

Exporting OCI images

# 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 '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.

This process is suitable for advanced users who wish to manage their own OCI registry in an air-gapped environment. Users not requiring this level of control should instead consider using the Zarf-based installation process for a simpler installation process in air-gapped environments.

Verifying the installation

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

Confirming installation of QHx components

$ kubectl get pods -n qhx-system