Configuration Reference

The runai-installer CLI reads a configuration YAML file specified with the --config flag. This reference describes every supported configuration field.

Fields marked Required must be specified. All other fields are optional.

Configuration Overview

Core Installation Settings

• Installation Settings - Installation mode (full, control-plane-only, or cluster-only) and network connectivity model (connected or air-gapped); determines which other sections apply.
• Registry Configuration - Credentials for pulling NVIDIA Run:ai images and Helm charts: token authentication (NGC), basic authentication (Harbor and other OCI registries), or no authentication.
• Default TLS Configuration - Default TLS certificates for the control plane and cluster: certificate, key, CA chain, or a self-signed option for non-production use. Component-level tls blocks override these defaults.

NVIDIA Run:ai Components

• Control Plane Configuration - Control plane deployment: whether to install it, its domain, version, TLS, and custom Helm values.
• Cluster Configuration - Common cluster settings plus multi-cluster registration fields.

Prerequisites and Features

• Prerequisite Configuration - Infrastructure components the installer can set up before NVIDIA Run:ai: GPU Operator, Prometheus, and Network Operator, each independently set to install or skip.
• Feature Configuration - Components that extend NVIDIA Run:ai for specific workload types: Knative for standard inference, LWS for distributed inference, Kubeflow and MPI Operator for distributed training, plus NIM Operator, Grove, and Dynamo.
• Common Prerequisite and Feature Fields - Fields shared by every prerequisite and feature, such as mode, version, and customHelmValues.

Networking and Nodes

• External Connection - How external traffic reaches NVIDIA Run:ai services: Kubernetes Ingress or Gateway API. Omitted entirely on OpenShift, where Routes are configured automatically.
• System Nodes - Dedicating specific nodes to NVIDIA Run:ai system components, with a preferred or required scheduling mode and automatic node labeling.

OpenShift

• OpenShift Configuration - Installer-wide OpenShift settings, such as a mirrored OperatorHub catalog source for air-gapped OpenShift environments.
• Per-Component OpenShift Fields - OpenShift-specific fields available under individual prerequisites and features.

Air-Gapped Installation

• Air-Gapped Installation Configuration - Bundle path, working directory, and extraction behavior for an air-gapped installation. Required when install.connectivity is air_gapped.
• Pack an Air-Gapped Bundle - Configuration for the separate airgap pack command, which builds an air-gapped bundle from a release’s artifacts.
• Load an Air-Gapped Bundle - Configuration for the separate airgap load command, which pushes a bundle’s images to your registry and writes the Helm values install consumes.

Core Installation Settings

Installation Settings

Controls the installation type and network connectivity model. mode is based on your deployment model - same-cluster or multi-cluster:

• full_installation - Same-cluster deployments.
• runai_control_plane_only and runai_cluster_only - Multi-cluster deployments, one per component.

install:
  mode: full_installation
  connectivity: connected
  kubernetesDistribution: ""

Registry Configuration

Configures the registry credentials used to pull NVIDIA Run:ai images and Helm charts. Which method you need depends on your installation:

• Open Source installation (type: ngc, no credentials) - Pulls NVIDIA Run:ai’s publicly accessible images from NGC without credentials. host can be omitted; it defaults to NGC’s registry (nvcr.io).
• Token authentication (type with token or tokenPath) - For an NVIDIA Run:ai Support-Entitled Release installation, pulling from NVIDIA’s own NGC registry (type: ngc). For any other registry secured by a base64-encoded .dockerconfigjson pull secret instead of NGC credentials, use type: dockerconfig.
• Basic authentication (username with password or passwordPath) - For a private registry you control, such as Harbor or another OCI-compliant registry - for example, an internal mirror populated for an air-gapped install, which always uses basic authentication rather than a token.
• No authentication, custom registry (host only, no type) - For any other unauthenticated registry. host is required in this case, since there’s no default to fall back to.

These methods are mutually exclusive. The --ngc-token-path and --registry-token-path command-line flags override the corresponding value in this section - use --ngc-token-path for NGC token authentication, and --registry-token-path for a .dockerconfigjson token.

Token authentication (NGC):

registry:
  type: ngc
  tokenPath: /path/to/ngc-token # Support-Entitled Release only

Token authentication (dockerconfig):

registry:
  type: dockerconfig
  tokenPath: /path/to/dockerconfigjson-token

Basic authentication:

registry:
  host: <REGISTRY_HOST>
  username: runai
  passwordPath: /path/to/password
  caChainPath: /path/to/ca-chain.pem

No authentication:

registry:
  host: <REGISTRY_HOST>

Default TLS Configuration

Configures the default TLS settings used by the control plane and cluster components. A component that defines its own tls block (controlPlane.tls, cluster.tls, or cluster.inference.wildcardTls) uses that block instead of this one; a component that omits tls falls back to these top-level settings.

tls:
  certPath: /path/to/cert.pem
  keyPath: /path/to/key.pem
  caChainPath: /path/to/ca-chain.pem
  generateSelfSigned: false

NVIDIA Run:ai Components

Control Plane Configuration

Configures the NVIDIA Run:ai control plane. The NVIDIA Run:ai control plane is installed once, regardless of deployment model - in a same-cluster deployment it runs alongside the NVIDIA Run:ai cluster component; in a multi-cluster deployment it is installed on its own, separately from each NVIDIA Run:ai cluster.

controlPlane:
  enabled: true
  version: ""
  multiTenant: false
  domain: <DOMAIN>
  tls:
    certPath: /path/to/cert.pem
    keyPath: /path/to/key.pem
  customHelmValues: {}

Cluster Configuration

Configures the NVIDIA Run:ai cluster component. In a multi-cluster deployment, this section is applied once per NVIDIA Run:ai cluster.

Multi-cluster only: domain, controlPlaneUrl, and the cluster registration fields (uid, bootstrapTokenPath, clientSecretPath, or controlPlaneCredentials) are used when the NVIDIA Run:ai cluster component is installed on a different Kubernetes cluster than the NVIDIA Run:ai control plane. Omit them for same-cluster installations unless otherwise noted.

cluster:
  enabled: true
  version: ""
  name: <CLUSTER_NAME>
  domain: ""
  workloadRouting: path
  tls:
    certPath: /path/to/cert.pem
    keyPath: /path/to/key.pem
  inference:
    wildcardDomain: "*.<INFERENCE_WILDCARD_DOMAIN>"
    wildcardTls:
      certPath: /path/to/wildcard-cert.pem
      keyPath: /path/to/wildcard-key.pem
  controlPlaneUrl: ""
  uid: "" # alternative to controlPlaneCredentials, together with bootstrapTokenPath or clientSecretPath
  bootstrapTokenPath: ""
  controlPlaneCredentials:
    tokenPath: ""
  customHelmValues: {}

Common Fields

Multi-Cluster Fields

Prerequisites and Features

Prerequisite Configuration

Configures the infrastructure components that the installer can set up before deploying NVIDIA Run:ai. Each of gpuOperator, prometheus, and networkOperator accepts the same set of fields - see Common Prerequisite and Feature Fields, below. For what each component does and when you need it, see Prerequisites in Prerequisites and Features.

prerequisites:
  skip: false
  gpuOperator:
    mode: install
  prometheus:
    mode: skip
  networkOperator:
    mode: skip

Feature Configuration

Configures components that extend NVIDIA Run:ai with support for specific workload types. Each component accepts the same fields as prerequisites - see Common Prerequisite and Feature Fields, below. For what each component does and when you need it, see Features in Prerequisites and Features.

The features you enable determine which workload types the cluster supports:

features:
  skip: false
  knative:
    mode: install
  kubeflow:
    mode: install
  mpiOperator:
    mode: install
  lws:
    mode: install
  nimOperator:
    mode: skip
  grove:
    mode: skip
  dynamo:
    mode: skip

Common Prerequisite and Feature Fields

gpuOperator, prometheus, networkOperator (prerequisites) and knative, kubeflow, mpiOperator, lws, nimOperator, grove, dynamo (features) all accept the following fields:

gpuOperator:
  mode: install
  type: real
  version: ""
  customHelmValues: {}
  openshift:
    installPlanApproval: manual

Networking and Nodes

External Connection

Configures how NVIDIA Run:ai’s own charts expose their services - as Kubernetes Ingress objects or Gateway API Gateway/HTTPRoute objects. This assumes the matching controller is already running on your cluster (an Ingress Controller such as HAProxy, or a Gateway API implementation such as KGateway) - see Ingress Controller for setup. Switching between the two after an initial install requires a manual migration; see Kubernetes Gateway API.

Required on standard Kubernetes clusters - set type to ingress or gatewayApi. Omit this section entirely on OpenShift, where OpenShift Routes are configured automatically; on OpenShift you may still set type: gatewayApi if you also want Gateway API routing alongside the Route, but type: ingress is rejected there. route is never a value you set explicitly - even on OpenShift, setting type: route is rejected; Routes are only ever configured automatically when the section is omitted.

externalConnection:
  type: ingress
  ingress:
    className: haproxy

System Nodes

Configures dedicated nodes for NVIDIA Run:ai system components, including the control plane services and cluster agents.

By default, NVIDIA Run:ai system components can be scheduled on any available node.

systemNodes:
  enabled: true
  mode: preferred
  label: runai.ai/system-node
  manageLabels: true
  nodes:
    - node-1
    - node-2

OpenShift

Applies only when install.kubernetesDistribution: openshift. Skip this section for every other supported distribution.

OpenShift Configuration

Configures OpenShift-specific installer settings.

openshift:
  olmCatalog:
    source: my-mirrored-catalog
    sourceNamespace: openshift-marketplace

Per-Component OpenShift Fields

Set under any prerequisite’s or feature’s own openshift block (for example, gpuOperator.openshift) when that component installs via OperatorHub (OLM) instead of Helm. This is separate from the OpenShift Configuration section, above, which determines the catalog source these operators are pulled from in the first place - these fields configure how each operator behaves once it is installed from that catalog.

Air-Gapped Installation

Air-gapped is a connectivity model (install.connectivity: air_gapped), not a separate deployment model - the same mode values (full_installation, runai_control_plane_only, runai_cluster_only) still apply.

Air-Gapped Installation Configuration

Configures the air-gapped installation bundle. Required when install.connectivity is set to air_gapped. Air-gapped installs authenticate to the registry with registry.username/registry.password (or passwordPath) only - token authentication (registry.type/token/tokenPath) is rejected. Prerequisites and features generally cannot be installed from the offline bundle, since it only contains the NVIDIA Run:ai charts; set prerequisites.skip/features.skip (or mode: skip per component) for anything not already present on the cluster.

airgap:
  bundlePath: /data/runai-airgap-bundle.tar.gz
  workingDir: /data/runai-airgap
  valuesDir: /data/runai-airgap
  skipPrepare: false

Air-Gapped Bundle Commands

airgap pack and airgap load are separate commands from install, each with its own configuration file passed via its own --config flag - unlike airgap above, which is part of the install configuration.

Pack an Air-Gapped Bundle

Configures the airgap pack command, which builds an air-gapped bundle from a release’s artifacts on a connected machine. See Air-Gapped Bundle for the full procedure.

settings:
  runaiVersion: 3.0.2
  architecture: amd64
  output: /path/to/runai-airgap.tar
imageOverrides:
  - name: keycloak
    source: <your-registry>/keycloak:<tag>
registryAuth:
  - registry: <your-registry-host>
    username: <username>
    passwordPath: /path/to/registry-password

Load an Air-Gapped Bundle

Configures the airgap load command, which extracts an air-gapped bundle, pushes its images to your internal registry, and writes the Helm values files consumed by install’s own airgap configuration. See Air-Gapped Bundle for the full procedure.

settings:
  bundlePath: /path/to/runai-airgap.tar
  workingDir: /data/runai-airgap
  valuesDir: /data/runai-airgap
registry:
  url: <your-registry-host>
  username: <username>
  passwordPath: /path/to/registry-password