dsx-ai-factory/run-ai/runai-docs-installation

NVIDIA Run:ai Installation Documentation

Use when a change affects the installation flow itself, system requirements, prerequisites or features, or the installer's configuration reference. Not for upgrades or post-install configuration — see docs/installation-and-configuration/upgrade/ and docs/installation-and-configuration/configuration/ for those.

The Two Install Paths

Guided Installation further splits into a 2×2 matrix: connected/ vs air-gapped/, each containing the same four files — preparations.md, same-cluster.md, multi-cluster.md, templates.md — with the same H2 section skeleton in both variants (content differs; structure doesn't). Manual Helm has no separate connected/air-gapped files — the same distinction is handled as <Accordion title="Connected"> / <Accordion title="Air-gapped"> blocks nested inside its Kubernetes/OpenShift subsections, in the same file.

Both paths share the same runai-installer binary for air-gapped bundle building (airgap pack / airgap load) — Manual Helm's own docs instruct users to download and run it before their Helm commands. Do not assume a concept is Guided-only just because it's the installer's binary; check whether Manual Helm's docs already reference it (see Verifying Against Source below).

installation/bcm-install.md (Base Command Manager) is a third, legacy path that only redirects to older-version instructions — out of scope for this skill.

Being linked to from other docs. Guided Installation is the default link target from anywhere outside installation/ — a feature doc mentioning a prerequisite (e.g. Knative) links to guided-installation/prerequisites-and-features.md, not the Helm version, unless the content is genuinely Helm-specific. See Links in docs/WRITING.md.

The System Requirements Tier

Not every product-level fact belongs inside installation/ at all. A third location sits above both paths: docs/installation-and-configuration/system-requirements/ (README.md, deployment-model.md, infrastructure-requirements.md, networking-setup.md, external-access-to-critical-services.md, third-party-services.md) — the single, tool-agnostic baseline both Guided Installation and Manual Helm require. Nearly every file under installation/ links back into it rather than restating it.

Check this before applying Verifying Against Source below — it decides whether a fact belongs in either path's docs at all:

• No per-path mechanism — a fact about the environment or infrastructure

that's true before a tool is even chosen (supported Kubernetes versions, hardware/GPU requirements, storage, the same-cluster vs multi-cluster deployment-model decision, which FQDNs and certificate types are needed in the abstract) → belongs in system-requirements/ only. Neither path's own docs restate it — they link to it, typically from a "Before You Start" section. Do not duplicate it into prerequisites-and-features.md or preparations.md on either side.

• Has a per-path mechanism — the requirement lives in

system-requirements/, but satisfying it differs by tool → the requirement itself stays a single edit there; the per-path how is handled separately per Verifying Against Source and Mapping Guided Installation to Manual Helm below. Example: which FQDNs and certificate types are needed lives in system-requirements/networking-setup.md; how each path actually provisions those certificates is per-path (Guided's tls.* config.yaml field, Manual Helm's manual secret creation) — those are two separate edits, neither of which touches networking-setup.md itself.

If it's unclear which tier a change belongs in, grep system-requirements/ for the topic first. If it's already covered there, that page is the requirement's home — any further doc change stays scoped to how each install path executes it, not to restating the requirement.

Several system-requirements/ pages already mention connected vs. air-gapped inline, as prose within one page — this is not the same as the per-path connectivity split under installation/. There are no separate system-requirements/connected/ and system-requirements/air-gapped/ files to mirror; a connectivity-dependent fact here just needs to stay accurate for both cases within the same paragraph or list.

On Activation

Before drafting anything:

1. Ask what's changing — the install flow itself, a system requirement, a

prerequisite/feature, or a config.yaml field/installer command. Do not ask the human which tier or path(s) it applies to — determine that in order: The System Requirements Tier first, then Verifying Against Source for path applicability. Only ask if both leave it genuinely ambiguous (e.g. a brand-new capability with no existing analog).

1. Read docs/AGENTS.md for writing rules, Fern components, and terminology.
2. Read the reference page(s) matched by the routing decision below, in

full, before editing.

Verifying Against Source

Path applicability is a fact to verify, not a guess from folder structure or from where you first noticed the change. Apply this test to any change, including ones with no precedent in the skill:

1. Is it a fact about what the product requires or does, or a fact about one tool's own mechanism? Both paths deploy the same control plane and cluster Helm charts with the same underlying requirements — TLS, registry auth, prerequisites, features, networking. They differ only in tooling: Guided Installation wraps chart deployment in config.yaml + runai-installer automation; Manual Helm runs helm install/upgrade directly, by hand.

• If the change is a fact about the product (a new TLS requirement, a new

prerequisite, a new supported registry auth method, a new feature) — it is real in both paths by default. Verify the requirement itself against product source (the relevant Helm chart's values.yaml/templates, or the controller/service that enforces it) — not against either doc, and not against installer source, which only tells you how Guided automates it.

• If the change has no equivalent in the other tool at all — an installer

preflight check that exists only because the installer automates a step a human does manually elsewhere, or a GitOps/Argo CD consideration specific to Manual Helm — it's genuinely single-path. Treat this as the exception: confirm it by checking whether the other path's docs already cover the same requirement in different words before concluding it's single-path.

2. For each path the change is real in, verify that path's own mechanism independently — never transfer one path's syntax into the other's docs:

• Guided's realization (a config.yaml field, a CLI flag, an installer

validation step) — verify against runai-installer/installer/internal/ (config, cli, inputcheck, step, prereq, etc.).

• Manual Helm's realization (a --set value, a manual Kubernetes step, a

cert/secret created by hand) — verify against the relevant Helm chart's values.yaml/templates, or the existing manual instructions.

3. Before editing, grep both doc trees for the exact term — command name, flag, field, or product name — under docs/installation-and-configuration/installation/guided-installation/ and .../install-using-helm/. Do this even for a change you've already classified as single-path: the other path may still reference it (a cross-link, a shared prerequisite mention) and need a smaller update even without a new section.

Worked Examples

• `airgap pack`/`airgap load` fix: a fact about tooling, but the tooling

(the runai-installer binary) is shared — Manual Helm's own docs instruct users to run it. Grepping install-using-helm/ for airgap confirms this (finds it in preparations.md). Both paths need the fix.

• New prerequisite/operator: a fact about the product (something the

cluster needs), so real in both paths by rule 1. Whether Guided documents it as installer-automatable depends on rule 2 — check runai-installer/installer/internal/prereq/registry.go (and its ids/ components packages); if it's registered, use mode: install/ mode: skip language matching GPU Operator's existing entry, otherwise document it as always mode: skip with manual installation, the same way unregistered prerequisites already are. Manual Helm documents it as manual installation either way, independent of what the installer registry says.

• New TLS requirement: a fact about the product (both paths deploy

ingress/TLS on the same charts), so real in both by rule 1 — verify the requirement itself against the chart or the service enforcing it. Then verify each path's syntax separately by rule 2: Guided's tls.* config.yaml fields against runai-installer/installer/internal/step/ (see tls_secret_step.go) and internal/inputcheck/; Manual Helm's certificate handling against its existing Control Plane Certificate/Cluster TLS Certificates sections in install-using-helm/preparations.md, which already documents the manual, by-hand equivalent. Finding those exact locations in each path is not structural — see Mapping Guided to Manual Helm below.

Mapping Guided Installation to Manual Helm

Once Verifying Against Source says a change is real in both paths, this answers where in each, and what should read the same vs. different once you're there. Unlike connected/ vs air-gapped/ (identical files, identical section skeletons — see Mirroring below), Guided Installation and Manual Helm are not structural mirrors. Guided organizes files by installation concern (preparations.md, same-cluster.md, multi-cluster.md, templates.md); Manual Helm organizes by installed component (preparations.md, install-control-plane.md, helm-install.md). There is no heading-to-heading match — find the corresponding content by topic, not by structure: