Helm-Based Installation

This is the advanced manual installation path. For normal connected and air-gapped deployments, use the recommended qhx install workflow, which embeds the Helm and OCI operations described here.

Need the qhx executable? Use the canonical QHx CLI installation guide. The CLI is not required for the manual Helm steps below.

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:

Determine the QHx release version to install.
Install the QHx release onto the cluster.

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 openshift, 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 configured 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 registry 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