Install using QHx CLI

Introduction

qhx install is the recommended way to install QHx on a ready Kubernetes cluster. The CLI contains the OCI and Helm logic it needs and supports four operator workflows:

• an interactive wizard: qhx install;
• unattended online installation: qhx install --online;
• release-package creation: qhx install --download;
• offline installation from a release package: qhx install --offline-install.

The online workflow retrieves QHx from the official registry. The download and offline workflows separate retrieval from installation so that the package can be transferred into a disconnected environment.

Prerequisites

For online or offline installation, you need:

• the qhx executable;
• a usable kubeconfig with a current context, either in the standard location or selected with --kubeconfig;
• an already functioning Kubernetes cluster with all nodes in Ready state;
• a supported, functioning CNI; QHx is currently tested and validated with Cilium (see Installation Requirements);
• a default StorageClass;
• Kubernetes access sufficient for the installer’s preflight checks and for installing namespaced and cluster-scoped QHx resources.

Online installation and package creation also require QHx customer deployment credentials. Offline installation instead requires an OCI mirror that the administrative host can push to and every target-cluster node can resolve and pull from.

Package creation does not require access to the target cluster. It also does not provision the cluster, CNI, default StorageClass, mirror registry, or the qhx executable needed in the disconnected environment.

External Helm and ORAS executables are not prerequisites for qhx install. They are used only by the advanced manual Helm workflow.

Interactive installation

Run the wizard from a terminal:

qhx install

The wizard asks you to select online installation, package creation, or offline installation. For connected modes it prompts for the QHx customer deployment username and a masked password. Online mode prompts for a version and defaults to latest; download mode defaults to latest and prompts for an output path, defaulting to qhx-release.tar.gz.

For offline installation, the wizard prompts for the package path, mirror authority, whether the mirror uses TLS, and optional mirror authentication. If a mirror username is supplied, it prompts for the password without displaying it.

The wizard does not prompt for a kubeconfig. Pass --kubeconfig to select a file; otherwise the CLI uses the standard kubeconfig loading rules and its current context.

Unattended installation

When standard input is not a terminal, explicitly select exactly one of --online, --download, or --offline-install. Selecting multiple modes is rejected, as are flags that do not apply to the selected mode.

Registry authorities and transport

--qhx-registry and --mirror-registry accept a registry authority in this form:

host[:port]

Do not include http://, https://, a repository path, or leading or trailing whitespace. The registry authority and its transport mode are separate inputs.

• --qhx-registry selects the official/source registry authority and defaults to oci.messier42.com.
• --qhx-insecure uses plain HTTP for the official/source registry.
• --mirror-registry selects the target mirror authority.
• --mirror-insecure uses plain HTTP for the target mirror.

Use an insecure flag only when that registry is intentionally configured for HTTP.

Online installation

Use an exact release version for a reproducible production installation:

qhx install --online \
  --kubeconfig ./kubeconfig \
  --qhx-username "$QHX_CUSTOMER_DEPLOYMENT_USERNAME" \
  --qhx-password "$QHX_CUSTOMER_DEPLOYMENT_PASSWORD" \
  --version v0.12.0 \
  --timeout 15m

Unattended online mode requires --version. The special value latest is supported, but an exact version is preferable for a controlled deployment.

Online mode resolves the requested release, performs cluster preflight, checks read access to the official registry, and resolves the release images required by the architectures detected on the target cluster. It then generates the Helm values and applies the qhx-core release.

The default timeout is 10 minutes. --timeout controls the Helm operation and readiness wait. If the fixed qhx-core release already exists, the command fails unless --upgrade explicitly authorizes an upgrade.

Release-package creation

Create a package on a connected administrative host:

qhx install --download \
  --qhx-username "$QHX_CUSTOMER_DEPLOYMENT_USERNAME" \
  --qhx-password "$QHX_CUSTOMER_DEPLOYMENT_PASSWORD" \
  --version v0.12.0 \
  --platform linux/amd64,linux/arm64 \
  --file qhx-v0.12.0.tar.gz

--file is required. When --version is omitted, download mode selects latest; use an exact version for a controlled deployment.

--platform accepts comma-separated os/architecture[/variant] values. When it is omitted, the CLI packages every platform common to the images in the selected release. Current QHx releases are built and tested for linux/amd64 and linux/arm64.

The package contains a release descriptor, the selected QHx Helm chart, a package manifest, and the OCI content needed for the selected platforms. When the package is opened, the CLI validates its format and declared paths, sizes, and SHA-256 digests; it also verifies the release descriptor, chart digest and size, and packaged OCI content digests.

Transfer the package and the appropriate qhx executable through your organization’s approved process. Package creation does not install or configure any target-environment prerequisite.

Offline installation

For an authenticated TLS mirror:

qhx install --offline-install \
  --kubeconfig ./kubeconfig \
  --file qhx-v0.12.0.tar.gz \
  --mirror-registry registry.example.mil:5000 \
  --mirror-username "$MIRROR_REGISTRY_USERNAME" \
  --mirror-password "$MIRROR_REGISTRY_PASSWORD" \
  --timeout 15m

Mirror credentials are optional when the mirror allows unauthenticated access:

qhx install --offline-install \
  --kubeconfig ./kubeconfig \
  --file qhx-v0.12.0.tar.gz \
  --mirror-registry registry.example.mil:5000 \
  --timeout 15m

Provide both a username and its required password when mirror authentication is used. A password without a username is rejected. Add --mirror-insecure only for a mirror intentionally served over plain HTTP.

Both --file and --mirror-registry are required. Offline mode validates and opens the package, performs cluster preflight, and verifies access to the mirror. It imports the packaged OCI content into mirror repositories, computes mirror-hosted digest references, generates Helm values containing those pinned references, and applies the release.

The target nodes must be able to resolve and reach the mirror. With a complete package and functioning prerequisites, neither the administrative host nor the cluster needs access to public registries during the offline installation phase. The CLI does not install a CNI or StorageClass.

Offline dry run

--dry-run applies only to offline installation:

qhx install --offline-install \
  --kubeconfig ./kubeconfig \
  --file qhx-v0.12.0.tar.gz \
  --mirror-registry registry.example.mil:5000 \
  --dry-run

A dry run reads and validates the package, performs cluster preflight and a non-writing mirror check, calculates the mirror references, generates Helm values, and renders the manifest. It does not import OCI content or modify the cluster. It also does not prove that the administrative host can push every image or that target nodes can pull them.

Upgrades and rollback

The CLI manages a fixed Helm release named qhx-core in the default namespace. It detects an existing release and refuses to replace it unless --upgrade is supplied. The flag authorizes the Helm upgrade; it does not promise migration between versions beyond what the selected release supports.

Failed non-dry-run installations are configured to roll back. Failed non-dry-run upgrades are configured to roll back and clean up failed upgrade resources.

Architecture and platform behavior

Package platforms and cluster platforms answer different questions:

• --platform controls which architectures are stored in a downloaded package.
• Online installation detects target-node architectures and resolves matching release images.
• Offline installation uses the already selected package content. Ensure that the package includes every architecture used by the target cluster.

The release format accepts os/architecture[/variant], but this does not imply that every named architecture is released. QHx currently builds and tests linux/amd64 and linux/arm64.

Troubleshooting

Installer errors identify the stage that failed. Use the stage and the nested error to focus the first check:

Stage	First checks
Before workflow execution	A registry value containing a URL scheme, path, or whitespace; no mode or multiple modes; missing QHx credentials; a missing package or mirror authority.
resolve release or resolve release images	Source-registry authentication, requested release availability, and whether every required or requested architecture exists.
cluster preflight	Kubernetes API access, nodes not Ready, a missing default StorageClass, insufficient permissions, and the supported CNI’s health. CNI health itself is not proven by preflight.
official registry preflight	QHx customer deployment credentials and connectivity to the source registry.
load release package	Package transfer damage, a descriptor or manifest mismatch, a missing chart or OCI object, and content-digest validation.
mirror registry preflight or mirror release images	Mirror authentication, whether the administrative host can push, the authority’s TLS/HTTP setting, and available storage.
generate Helm values	A release image inventory that does not match the packaged image mappings.
install QHx	An existing release without --upgrade, timeout, unready workloads, an unhealthy CNI, target nodes unable to pull from the mirror, or a cluster architecture absent from the package.

For workload-level diagnosis, inspect QHx pods and Kubernetes events as shown in the Quick Start Guide.

Credential safety

Do not put literal credentials in scripts, examples, or command history. The interactive wizard reads passwords without displaying them. For unattended use, protect environment variables according to your organization’s secret handling policy, quote every expansion as shown above, and unset them when the operation is complete. The CLI does not provide secret-file flags.