fix(helm): support quickstart image overrides

Author: ecolternv

deployments/charts/osmo/README.md

@@ -75,6 +75,24 @@ helm --kube-context kind-osmo upgrade --install osmo deployments/charts/osmo \
   --timeout 20m
 ```
 
+For prerelease OSMO images published below `nvcr.io/nvstaging/osmo`, set the
+registry and repository defaults separately. The runtime init and client images
+use the same location and tag:
+
+```bash
+helm --kube-context kind-osmo upgrade --install osmo deployments/charts/osmo \
+  --namespace osmo \
+  --create-namespace \
+  --values deployments/charts/osmo/profiles/quickstart.yaml \
+  --set-string compute.backendName=default \
+  --set-string imageRegistry=nvcr.io \
+  --set-string imageRepository=nvstaging/osmo \
+  --set-string imageTag=2026.8.28.3b3d1b0a2.ecolter3910-amd64 \
+  --set-string 'imagePullSecrets[0].name=osmo-nvcr-pull' \
+  --wait \
+  --timeout 20m
+```
+
 Inspect the release without reading generated Secret values:
 
 ```bash
@@ -510,14 +528,19 @@ above.
 
 ## Optional configuration
 
-- Configure the OSMO image registry under `imageRegistry`, a shared
-  OSMO component tag under `imageTag`, pull credentials under
-  `imagePullSecrets`, and workflow init/client images under `runtimeImage`.
-  The chart writes those workflow images into the managed API configuration
-  unless `configuration.workflow.backend_images` overrides them. Configure
-  per-component image overrides in each component's `image` block. Configure
-  dependency images and pull credentials in their native values blocks; for
-  example, Valkey uses `valkey.image` and `valkey.imagePullSecrets`.
+- Configure the OSMO image registry and base repository under `imageRegistry`
+  and `imageRepository`, a shared OSMO component tag under `imageTag`, pull
+  credentials under `imagePullSecrets`, and workflow init/client image
+  overrides under `runtimeImage`. Top-level pull credentials are used as
+  defaults for workflow pod templates unless a template defines its own list.
+  A non-empty service-specific
+  `image.registry` or `image.repository` takes precedence over these
+  top-level defaults; otherwise the chart uses `nvcr.io/nvidia/osmo` and the
+  component name. The chart writes the resolved workflow images into the
+  managed API configuration unless `configuration.workflow.backend_images`
+  overrides them. Configure dependency images and pull credentials in their
+  native values blocks; for example, Valkey uses `valkey.image` and
+  `valkey.imagePullSecrets`.
 - Configure replicas, autoscaling, resources, disruption budgets, scheduling,
   security contexts, probes, volumes, and ServiceAccounts under `services`,
   `gateway`, and `podDefaults`. Directly owned workload extensions use

deployments/charts/osmo/profiles/README.md

@@ -11,7 +11,7 @@ values take precedence.
 
 | File | Directly installable | Required environment input |
 | --- | --- | --- |
-| `quickstart.yaml` | Yes, on a development cluster | KAI Scheduler, the CloudNativePG operator, and a default dynamic StorageClass installed separately; `compute.backendName` set explicitly at install time |
+| `quickstart.yaml` | Yes, on a development cluster | KAI Scheduler, the CloudNativePG operator, and a default dynamic StorageClass installed separately; the pre-created `osmo-nvcr-pull` Secret; `compute.backendName` set explicitly at install time |
 | `kind-self-contained.yaml` | Yes, on kind | KAI Scheduler and the CloudNativePG operator installed separately; `compute.backendName` set explicitly at install time |
 | `split-plane-control.yaml` | Base overlay | PostgreSQL, Valkey, and object-storage endpoints; Kubernetes Secrets; and `externalUrl` |
 | `split-plane-compute.yaml` | Base overlay | A control-plane `externalUrl`, a compute authentication Secret, and `compute.backendName` set explicitly at install time |
@@ -20,8 +20,11 @@ The quick-start profile is the smallest complete control-and-compute deployment
 for browser, CLI, and CPU hello-world verification. It exposes the UI and API
 through gateway NodePort `30080` while omitting other optional services. The kind
 profile retains a broader local-development surface. Both profiles are
-development-only and intentionally use `latest` OSMO images, one replica per
-component, generated credentials, and embedded stateful dependencies. The split
+development-only and intentionally use `latest` OSMO images by default, one
+replica per component, generated credentials, and embedded stateful dependencies.
+The quick-start profile also references `osmo-nvcr-pull` for OSMO and workflow
+images; override it through top-level `imagePullSecrets` when using another
+Secret. The split
 profiles contain example names and endpoints; copy them into an environment
 values file before installation.
 

deployments/charts/osmo/profiles/quickstart.yaml

@@ -12,8 +12,8 @@ planes:
 fullnameOverride: osmo
 
 imageTag: latest
-runtimeImage:
-  tag: latest
+imagePullSecrets:
+- name: osmo-nvcr-pull
 
 externalUrl: http://osmo-gateway
 

deployments/charts/osmo/templates/_gateway-envoy-config.tpl

@@ -78,7 +78,9 @@ setting detects this rotation and triggers Envoy to reload.
 {{- fail "services.mcp.scopes entries must not be empty" }}
 {{- end }}
 {{- end }}
-{{- $_ := required "services.mcp.image.repository is required when MCP is enabled" $mcp.image.repository }}
+{{- if and (not $mcp.image.repository) (not $mcp.image.name) }}
+{{- fail "services.mcp.image.repository or image.name is required when MCP is enabled" }}
+{{- end }}
 {{- if or (lt (int $mcp.port) 1) (gt (int $mcp.port) 65535) }}
 {{- fail "services.mcp.port must be between 1 and 65535" }}
 {{- end }}

deployments/charts/osmo/templates/_helpers.tpl

@@ -90,10 +90,19 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 {{- $root := .root -}}
 {{- $image := .image -}}
 {{- $registry := $image.registry -}}
-{{- if .useSharedRegistry -}}
+{{- $repository := $image.repository -}}
+{{- if hasKey $image "name" -}}
+{{- $registry = $registry | default $root.Values.imageRegistry | default "nvcr.io" -}}
+{{- $repository = $repository | default $root.Values.imageRepository | default "nvidia/osmo" -}}
+{{- if not $image.repository -}}
+{{- $repository = printf "%s/%s" (trimSuffix "/" $repository) $image.name -}}
+{{- end -}}
+{{- else -}}
+{{- if and .useSharedRegistry (not $root.Values.imageRepository) -}}
 {{- $registry = $root.Values.imageRegistry | default $registry -}}
 {{- end -}}
-{{- $repository := required "image.repository is required" $image.repository -}}
+{{- $repository = required "image.repository is required" $repository -}}
+{{- end -}}
 {{- $base := ternary (printf "%s/%s" $registry $repository) $repository (ne $registry "") -}}
 {{- if $image.digest -}}
 {{- printf "%s@%s" $base $image.digest -}}
@@ -111,12 +120,13 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 {{- end -}}
 
 {{- define "osmo.component.imageRepository" -}}
-{{- $registry := .Values.imageRegistry | default .Values.runtimeImage.registry -}}
-{{- ternary (printf "%s/%s" $registry .Values.runtimeImage.repository) .Values.runtimeImage.repository (ne $registry "") -}}
+{{- $registry := .Values.runtimeImage.registry | default .Values.imageRegistry | default "nvcr.io" -}}
+{{- $repository := .Values.runtimeImage.repository | default .Values.imageRepository | default "nvidia/osmo" -}}
+{{- printf "%s/%s" (trimSuffix "/" $registry) (trimSuffix "/" $repository) -}}
 {{- end -}}
 
 {{- define "osmo.component.imageTag" -}}
-{{- .Values.runtimeImage.tag | default .Chart.AppVersion -}}
+{{- .Values.runtimeImage.tag | default .Values.imageTag | default .Chart.AppVersion -}}
 {{- end -}}
 
 {{- define "osmo.compute.agentNamespace" -}}

deployments/charts/osmo/templates/configs.yaml

@@ -69,8 +69,20 @@ data:
       {{- toYaml $cfg.pools | nindent 6 }}
     {{- end }}
     {{- if $cfg.podTemplates }}
+    {{- $podTemplates := deepCopy $cfg.podTemplates }}
+    {{- if gt (len .Values.imagePullSecrets) 0 }}
+    {{- range $_, $podTemplate := $podTemplates }}
+    {{- if kindIs "map" $podTemplate }}
+    {{- $spec := index $podTemplate "spec" | default dict }}
+    {{- if and (kindIs "map" $spec) (not (hasKey $spec "imagePullSecrets")) }}
+    {{- $_ := set $spec "imagePullSecrets" $.Values.imagePullSecrets }}
+    {{- $_ := set $podTemplate "spec" $spec }}
+    {{- end }}
+    {{- end }}
+    {{- end }}
+    {{- end }}
     pod_templates:
-      {{- toYaml $cfg.podTemplates | nindent 6 }}
+      {{- toYaml $podTemplates | nindent 6 }}
     {{- end }}
     {{- if $cfg.resourceValidations }}
     resource_validations:

deployments/charts/osmo/tests/test_osmo_charts.sh

@@ -641,6 +641,46 @@ test_control_umbrella() {
     require_not_contains "$TEST_DIRECTORY/kind-self-contained-ui.yaml" \
         "scheme: HTTPS"
 
+    local quickstart_runtime_tag=2026.8.28.3b3d1b0a2.ecolter3910-amd64
+    helm_template_with_backend quick-start-runtime "$charts_copy/osmo" \
+        --namespace osmo \
+        --api-versions postgresql.cnpg.io/v1 \
+        -f "$charts_copy/osmo/profiles/quickstart.yaml" \
+        --set-string imageRegistry=nvcr.io \
+        --set-string imageRepository=nvstaging/osmo \
+        --set-string imageTag="$quickstart_runtime_tag" \
+        --set-string 'imagePullSecrets[0].name=osmo-nvcr-pull' \
+        >"$TEST_DIRECTORY/quickstart-runtime.yaml"
+    resource_document "$TEST_DIRECTORY/quickstart-runtime.yaml" ConfigMap \
+        osmo-api-config >"$TEST_DIRECTORY/quickstart-runtime-config.yaml"
+    require_contains "$TEST_DIRECTORY/quickstart-runtime-config.yaml" \
+        "init: nvcr.io/nvstaging/osmo/init-container:$quickstart_runtime_tag"
+    require_contains "$TEST_DIRECTORY/quickstart-runtime-config.yaml" \
+        "client: nvcr.io/nvstaging/osmo/client:$quickstart_runtime_tag"
+    require_contains "$TEST_DIRECTORY/quickstart-runtime-config.yaml" \
+        "imagePullSecrets:"
+    require_contains "$TEST_DIRECTORY/quickstart-runtime-config.yaml" \
+        "name: osmo-nvcr-pull"
+    resource_document "$TEST_DIRECTORY/quickstart-runtime.yaml" Deployment \
+        osmo-api >"$TEST_DIRECTORY/quickstart-runtime-api.yaml"
+    require_contains "$TEST_DIRECTORY/quickstart-runtime-api.yaml" \
+        "image: nvcr.io/nvstaging/osmo/service:$quickstart_runtime_tag"
+    require_occurrences "$TEST_DIRECTORY/quickstart-runtime.yaml" \
+        "image: nvcr.io/nvstaging/osmo/service:$quickstart_runtime_tag" 2
+
+    helm_template_with_backend quick-start-workflow-pull-secret "$charts_copy/osmo" \
+        --namespace osmo \
+        --api-versions postgresql.cnpg.io/v1 \
+        -f "$charts_copy/osmo/profiles/quickstart.yaml" \
+        --set-string 'imagePullSecrets[0].name=sentinel-pull-secret' \
+        >"$TEST_DIRECTORY/quickstart-workflow-pull-secret.yaml"
+    resource_document "$TEST_DIRECTORY/quickstart-workflow-pull-secret.yaml" ConfigMap \
+        osmo-api-config >"$TEST_DIRECTORY/quickstart-workflow-pull-secret-config.yaml"
+    require_contains "$TEST_DIRECTORY/quickstart-workflow-pull-secret-config.yaml" \
+        "name: sentinel-pull-secret"
+    require_not_contains "$TEST_DIRECTORY/quickstart-workflow-pull-secret-config.yaml" \
+        "name: osmo-nvcr-pull"
+
     helm_template_with_backend quick-start "$charts_copy/osmo" \
         --namespace osmo \
         --api-versions postgresql.cnpg.io/v1 \
@@ -3627,6 +3667,58 @@ EOF
     require_contains "$TEST_DIRECTORY/osmo-image-mirror.yaml" \
         "name: mirror-secret"
 
+    helm_template image-family-override "$charts_copy/osmo" \
+        -f "$CHARTS_ROOT/osmo/tests/control-external-values.yaml" \
+        --set-string imageRegistry=nvcr.io \
+        --set-string imageRepository=nvstaging/osmo \
+        --set-string imageTag=2026.8.28.3b3d1b0a2.ecolter3910-amd64 \
+        --set imagePullSecrets[0].name=nvcr-pull-secret \
+        >"$TEST_DIRECTORY/osmo-image-family-override.yaml"
+    require_contains "$TEST_DIRECTORY/osmo-image-family-override.yaml" \
+        "image: nvcr.io/nvstaging/osmo/worker:2026.8.28.3b3d1b0a2.ecolter3910-amd64"
+    require_contains "$TEST_DIRECTORY/osmo-image-family-override.yaml" \
+        'image: "docker.io/envoyproxy/envoy:v1.38.1"'
+
+    helm_template image-priority "$charts_copy/osmo" \
+        -f "$CHARTS_ROOT/osmo/tests/control-external-values.yaml" \
+        --set-string imageRegistry=nvcr.io \
+        --set-string imageRepository=nvstaging/osmo \
+        --set-string services.worker.image.registry=registry.example.com \
+        --set-string services.worker.image.repository=custom/team/worker \
+        --set-string services.worker.image.tag=v2 \
+        >"$TEST_DIRECTORY/osmo-image-priority.yaml"
+    require_contains "$TEST_DIRECTORY/osmo-image-priority.yaml" \
+        "image: registry.example.com/custom/team/worker:v2"
+
+    helm_template image-field-priority "$charts_copy/osmo" \
+        -f "$CHARTS_ROOT/osmo/tests/control-external-values.yaml" \
+        --set-string imageRegistry=registry.example.com \
+        --set-string imageRepository=team/osmo \
+        --set-string imageTag=v1 \
+        --set-string services.worker.image.registry=service.example.com \
+        --set-string services.router.image.repository=service/router \
+        >"$TEST_DIRECTORY/osmo-image-field-priority.yaml"
+    require_contains "$TEST_DIRECTORY/osmo-image-field-priority.yaml" \
+        "image: service.example.com/team/osmo/worker:v1"
+    require_contains "$TEST_DIRECTORY/osmo-image-field-priority.yaml" \
+        "image: registry.example.com/service/router:v1"
+
+    helm_template runtime-priority "$charts_copy/osmo" \
+        -f "$CHARTS_ROOT/osmo/tests/control-external-values.yaml" \
+        --set-string imageRegistry=nvcr.io \
+        --set-string imageRepository=nvstaging/osmo \
+        --set-string runtimeImage.registry=registry.example.com \
+        --set-string runtimeImage.repository=custom/runtime \
+        --set-string runtimeImage.tag=v3 \
+        >"$TEST_DIRECTORY/osmo-runtime-priority.yaml"
+    resource_document "$TEST_DIRECTORY/osmo-runtime-priority.yaml" Deployment \
+        runtime-priority-osmo-api \
+        >"$TEST_DIRECTORY/osmo-runtime-priority-api.yaml"
+    require_contains "$TEST_DIRECTORY/osmo-runtime-priority-api.yaml" \
+        "registry.example.com/custom/runtime"
+    require_contains "$TEST_DIRECTORY/osmo-runtime-priority-api.yaml" \
+        '"v3"'
+
     helm_template embedded-image-pull-secret "$charts_copy/osmo" \
         -f "$charts_copy/osmo/profiles/split-plane-control.yaml" \
         -f "$CHARTS_ROOT/osmo/tests/control-external-values.yaml" \

deployments/charts/osmo/values.schema.json

@@ -27,6 +27,7 @@
     "nameOverride": { "type": "string" },
     "fullnameOverride": { "type": "string" },
     "imageRegistry": { "type": "string" },
+    "imageRepository": { "type": "string" },
     "imageTag": { "type": "string" },
     "imagePullSecrets": { "$ref": "#/definitions/imagePullSecrets" },
     "runtimeImage": { "$ref": "#/definitions/runtimeImage" },
@@ -104,7 +105,7 @@
       }
     }
   },
-  "required": ["planes", "compute", "embeddedDependencies", "externalDependencies", "imageRegistry", "imageTag", "imagePullSecrets", "runtimeImage", "externalUrl", "ingress", "httproute", "monitoring", "secrets", "services", "gateway"],
+  "required": ["planes", "compute", "embeddedDependencies", "externalDependencies", "imageRegistry", "imageRepository", "imageTag", "imagePullSecrets", "runtimeImage", "externalUrl", "ingress", "httproute", "monitoring", "secrets", "services", "gateway"],
   "definitions": {
     "enabledBlock": {
       "type": "object",
@@ -562,7 +563,7 @@
       "type": "object",
       "properties": {
         "registry": { "type": "string" },
-        "repository": { "type": "string", "minLength": 1 },
+        "repository": { "type": "string" },
         "tag": { "type": "string" }
       },
       "required": ["registry", "repository", "tag"]
@@ -571,12 +572,17 @@
       "type": "object",
       "properties": {
         "registry": { "type": "string" },
-        "repository": { "type": "string", "minLength": 1 },
+        "repository": { "type": "string" },
+        "name": { "type": "string", "minLength": 1 },
         "tag": { "type": "string" },
         "digest": { "type": "string", "pattern": "^$|^sha256:[A-Fa-f0-9]{64}$" },
         "pullPolicy": { "type": "string", "enum": ["Always", "IfNotPresent", "Never"] }
       },
-      "required": ["registry", "repository", "tag", "digest", "pullPolicy"]
+      "required": ["registry", "repository", "tag", "digest", "pullPolicy"],
+      "anyOf": [
+        { "required": ["name"] },
+        { "properties": { "repository": { "minLength": 1 } } }
+      ]
     },
     "probe": {
       "type": "object",