Configuration Reference

The runai-installer CLI reads a configuration YAML file specified with the --config flag. This reference describes every supported configuration field, for both installing the control plane in multi-tenant mode and installing a tenant’s cluster.

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

Configuration Overview

Core Installation Settings

• Installation Settings - Installation mode and network connectivity model.
• 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 certificate for the control plane or cluster. The component-level tls block overrides this default.

NVIDIA Run:ai Components

• Control Plane Configuration - Control plane deployment: whether to install it, its wildcard domain, version, TLS, multi-tenant mode, and custom Helm values.
• Cluster Configuration - Tenant cluster settings, including how to register it with its tenant using an identity obtained from the control plane’s Management API.

Prerequisites and Features

• Prerequisite Configuration - Infrastructure components the installer can set up on a tenant cluster before NVIDIA Run:ai: GPU Operator, Prometheus, and Network Operator, each independently set to install or skip.
• Feature Configuration - Components that extend a tenant cluster 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 the control plane or a tenant cluster: Kubernetes Ingress or Gateway API. Omitted entirely on OpenShift, where Routes are configured automatically.
• System Nodes - Dedicating specific nodes to control plane or cluster system components, with a preferred or required scheduling mode and automatic node labeling.

OpenShift

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

Core Installation Settings

Installation Settings

Controls the installation type and network connectivity model.

install:
  mode: runai_control_plane_only
  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.
• 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

No authentication:

registry:
  host: <REGISTRY_HOST>

Default TLS Configuration

Configures the default TLS settings used by the control plane. A configuration that defines its own controlPlane.tls block uses that block instead of this one; a configuration that omits controlPlane.tls falls back to these top-level settings.

tls:
  certPath: /path/to/cert.pem
  keyPath: /path/to/key.pem
  generateSelfSigned: false

NVIDIA Run:ai Components

Control Plane Configuration

Configures the NVIDIA Run:ai control plane.

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

Cluster Configuration

Configures a tenant’s NVIDIA Run:ai cluster component. This section is applied once per tenant cluster, in its own configuration file. The cluster must already be registered with its tenant through the control plane’s Management API before running the installer - the installer consumes that registration, it does not perform it.

cluster:
  enabled: true
  version: ""
  name: <CLUSTER_NAME>
  domain: <CLUSTER_DOMAIN>
  workloadRouting: host
  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: https://<CONTROL_PLANE_DOMAIN>
  uid: <CLUSTER_UUID>
  bootstrapTokenPath: /path/to/bootstrap-token
  customHelmValues: {}

Prerequisites and Features

Prerequisite Configuration

Configures the infrastructure components that the installer can set up on a tenant cluster before deploying the NVIDIA Run:ai cluster component. Each of gpuOperator, prometheus, and networkOperator accepts the same set of fields - see Common Prerequisite and Feature Fields, below.

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

Feature Configuration

Configures components that extend a tenant cluster with support for specific workload types. Each component accepts the same fields as prerequisites - see Common Prerequisite and Feature Fields, below.

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: {}

Networking and Nodes

External Connection

Configures how the control plane’s or a tenant cluster’s chart exposes its services - as Kubernetes Ingress objects or Gateway API Gateway/HTTPRoute objects. This assumes the matching controller is already running on the target cluster (an Ingress Controller such as HAProxy, or a Gateway API implementation such as KGateway) - see Ingress Controller for setup. Omit this section entirely on OpenShift, where OpenShift Routes are configured automatically.

externalConnection:
  type: ingress
  ingress:
    className: haproxy

System Nodes

Configures dedicated nodes for the control plane’s or a tenant cluster’s system components.

By default, these 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 to tenant clusters only, when install.kubernetesDistribution: openshift. The NVIDIA Run:ai control plane runs on Kubernetes. Skip this section for every other supported distribution.

OpenShift Configuration

Configures OpenShift-specific installer settings for a tenant cluster.

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.