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.

Installer progress is written to standard error as named stages with elapsed times. Standard output remains reserved for the final result or a dry-run manifest, so unattended callers can capture it without parsing diagnostic logs. Pass -v 1 or higher (for example, -v 10), or --debug, to add per-image, platform, transport, and stage context.

If qhx is not yet installed, start with Install the QHx CLI.

Prerequisites

For online or offline installation, you need:

• the qhx executable installed for the administrative host’s architecture;
• 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 runtime prerequisites for qhx install. ORAS is one supported way to acquire the CLI itself; the advanced manual Helm workflow uses external artifact tools directly.

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 first checks supported environment and Docker/OCI credential sources, then prompts for any credentials still missing. Passwords entered at the prompt are masked. 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

--mirror-registry accepts a registry authority in this form:

host[:port]

--qhx-registry also accepts an optional QHx repository prefix:

host[:port][/repository-prefix]

When the prefix is omitted, qhx is used for compatibility. Do not include http://, https://, or whitespace. Registry location and transport mode are separate inputs.

• --qhx-registry selects the official/source registry root and defaults to oci.messier42.com/qhx.
• --qhx-insecure uses plain HTTP for the official/source registry.
• --qhx-ca-file <path> keeps HTTPS and adds the PEM certificates in the local file to normal system trust for the official/source registry.
• --mirror-registry selects the target mirror authority.
• --mirror-insecure uses plain HTTP for the target mirror.
• --mirror-ca-file <path> keeps HTTPS and adds the PEM certificates in the local file to normal system trust for the target mirror.

Use an insecure flag only when that registry is intentionally configured for HTTP. It is not a way to accept an untrusted HTTPS certificate. Use the corresponding CA-file flag for an HTTPS registry issued by an internal or private CA. A CA-file flag and its insecure flag are mutually exclusive.

Source-registry credentials

Online installation and package creation select credentials in this order:

1. --qhx-username and --qhx-password;
2. QHX_CUSTOMER_DEPLOYMENT_USERNAME and QHX_CUSTOMER_DEPLOYMENT_PASSWORD;
3. credentials for the selected --qhx-registry host from standard Docker/OCI configuration, including configured credential helpers or stores;
4. an interactive username and masked-password prompt.

Each source is treated as a pair. If the highest-priority selected source is partial, an interactive terminal asks only for the missing value; unattended operation fails clearly instead of combining credentials from different sources. Run docker login <registry-host> or oras login <registry-host> to populate standard credential configuration.

Source credentials are used only by connected online/download workflows. Offline mirror authentication remains separate on --mirror-username and --mirror-password.

Online installation

Use an exact release version for a reproducible production installation:

qhx install --online \
  --kubeconfig ./kubeconfig \
  --version v0.12.0 \
  --timeout 15m

If the selected source registry uses private PKI, add --qhx-ca-file ./source-registry-ca.pem; keep --qhx-insecure disabled so the connection remains HTTPS.

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.

Add --dry-run to perform the same resolution, preflight, values merge, and Helm rendering without modifying the cluster. The rendered manifest is written to standard output; registry credentials and Secret manifests are hidden.

Supported Helm value overrides

Online installation, offline installation, and their upgrades accept a controlled subset of Helm’s familiar value inputs:

qhx install --online \
  --version v0.12.0 \
  --values ./site-values.yaml \
  --set khaled.storageClassName=nfs-client \
  --set khaled.podSecurityContext.fsGroup=2000 \
  --set-string khaled.storageSize=20Gi

The same --values, --set, and --set-string flags work with --offline-install and --upgrade. Repeat each flag as needed. Values files must be local YAML files; URLs and standard-input (-) values files are not accepted.

Precedence follows Helm: values files are merged in command order, later files win, --set entries win over files, and --set-string entries win last while preserving their values as strings. The chart’s defaults remain below all user inputs.

The installer owns kubernetesVariant, ociSecretBase64, and every image value declared by the selected release (for example, managerImage and khaled.image). Attempts to set those fields, or replace a parent map that contains one, fail explicitly. This keeps online source references and offline mirror references digest-pinned. Other supported chart values, including Khaled storage and pod/container security contexts, remain configurable.

Release-package creation

Create a package on a connected administrative host:

qhx install --download \
  --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

For an HTTPS mirror whose certificate is issued by a private CA, add its local CA bundle without enabling HTTP:

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

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 and must trust its HTTPS certificate independently; --mirror-ca-file configures the administrative CLI’s registry operations, not node-level container-runtime trust. 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

For an offline dry run:

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 or whitespace; no mode or multiple modes; missing or partial QHx credentials; a credential-helper failure; 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.
source registry preflight	QHx customer deployment credentials, CA trust, and connectivity to the source registry.
validate 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.
prepare Helm configuration	A malformed local values file or --set input, a reserved installer-owned value, or a release image inventory that does not match the packaged image mappings.
Helm install/upgrade and workload readiness wait	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.

Default stage lines confirm that the installer is still making progress. Use -v 1 or higher for safe operational detail; --debug also enables installer diagnostics and the CLI’s development logger. Diagnostic output includes timing, selected platforms, image names, and registry transport mode, but not credential material or rendered Secret contents.

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. Prefer an organization-approved Docker credential helper/store when available. The interactive wizard reads passwords without displaying them. For unattended use, protect the supported environment variables according to your organization’s secret-handling policy and unset them when the operation is complete. Treat values files as sensitive when they contain organization data. The CLI never logs discovered secrets or Helm value contents and does not provide secret-file flags.