From a0c8e03f24ca31cd2dbfaf374382ff1e40adec9c Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 15:49:04 -0700 Subject: [PATCH 1/8] Add dependency validation init container --- README.md | 33 +++- charts/mageai/Chart.yaml | 2 +- charts/mageai/templates/_helpers.tpl | 87 +++++++++ charts/mageai/templates/deployment.yaml | 11 +- charts/mageai/templates/scheduler.yaml | 7 +- charts/mageai/templates/webservice.yaml | 7 +- .../tests/dependency_validation_test.yaml | 172 ++++++++++++++++++ charts/mageai/values.yaml | 20 ++ 8 files changed, 327 insertions(+), 12 deletions(-) create mode 100644 charts/mageai/tests/dependency_validation_test.yaml diff --git a/README.md b/README.md index e42ed9d..a276c24 100644 --- a/README.md +++ b/README.md @@ -1 +1,32 @@ -# helm-charts \ No newline at end of file +# Mage Helm charts + +## Validate dependencies before Mage starts + +The Mage chart can run the image's normal startup dependency setup in an init +container, then check the resulting Python environment without starting the web +server or scheduler. This is available for both Mage OSS and Mage Pro images and +is disabled by default. + +```yaml +dependencyValidation: + enabled: true +``` + +The default command reruns the project requirements installation with fail-fast +behavior, runs `python -m pip check`, and imports the Mage server module. Override +`dependencyValidation.command` to add project-specific checks. Any command that +exits nonzero prevents the Mage application container from starting. + +The validator and application container use separate writable filesystem layers. +Packages installed by the init container are not carried into the application +container unless their install location is backed by a shared volume, so the +application still performs its normal dependency setup and may install packages +a second time. The default command is a fail-fast compatibility check, not a way +to preinstall dependencies for the application container. + +The startup script can treat some dependency-installation failures as warnings and +continue. The default validation command therefore repeats the requirements install +with fail-fast behavior. Preserve an equivalent strict install and an explicit +compatibility check when supplying a custom command so Kubernetes blocks startup +when a requested dependency cannot be installed or the resulting environment is +incompatible. diff --git a/charts/mageai/Chart.yaml b/charts/mageai/Chart.yaml index c0c88df..b0077d2 100644 --- a/charts/mageai/Chart.yaml +++ b/charts/mageai/Chart.yaml @@ -80,4 +80,4 @@ type: application # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. # Versions are expected to follow Semantic Versioning (https://semver.org/) -version: 0.2.16 +version: 0.2.17 diff --git a/charts/mageai/templates/_helpers.tpl b/charts/mageai/templates/_helpers.tpl index bb40b14..9b021b4 100644 --- a/charts/mageai/templates/_helpers.tpl +++ b/charts/mageai/templates/_helpers.tpl @@ -78,6 +78,93 @@ Generate chart secret name {{ default (printf "%s-secret-env" (include "mageai.fullname" .)) .Values.existingSecret }} {{- end -}} +{{/* +Render the Mage image reference shared by application and validation containers. +*/}} +{{- define "mageai.image" -}} +{{- if .Values.image.digest -}} +{{ .Values.image.repository }}@{{ .Values.image.digest }} +{{- else -}} +{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }} +{{- end -}} +{{- end -}} + +{{/* +Render the optional dependency validation init container. The caller may pass +an instanceType so split web server and scheduler deployments validate with the +same workload-specific environment as their main containers. +*/}} +{{- define "mageai.dependencyValidationInitContainer" -}} +{{- $root := .root -}} +{{- $instanceType := default "" .instanceType -}} +{{- if not $root.Values.dependencyValidation.command -}} +{{- fail "dependencyValidation.command must not be empty when dependencyValidation.enabled=true" -}} +{{- end -}} +- name: validate-dependencies + securityContext: + {{- toYaml $root.Values.securityContext | nindent 4 }} + image: {{ include "mageai.image" $root | quote }} + imagePullPolicy: {{ $root.Values.image.pullPolicy }} + command: + {{- toYaml $root.Values.dependencyValidation.command | nindent 4 }} + resources: + {{- toYaml $root.Values.dependencyValidation.resources | nindent 4 }} + {{- if or $root.Values.config $root.Values.existingSecret $root.Values.secrets }} + envFrom: + {{- if $root.Values.config }} + - configMapRef: + name: {{ include "mageai.fullname" $root }}-env + {{- end }} + {{- if or $root.Values.existingSecret $root.Values.secrets }} + - secretRef: + name: {{ include "mageai.secretName" $root }} + {{- end }} + {{- end }} + env: + {{- if $root.Values.env }} + {{- toYaml $root.Values.env | nindent 4 }} + {{- else if $root.Values.extraEnvs }} + {{- toYaml $root.Values.extraEnvs | nindent 4 }} + {{- end }} + {{- if $root.Values.redis.enabled }} + - name: REDIS_URL + value: redis://{{ $root.Release.Name }}-redis-headless:6379/0 + {{- else if $root.Values.redis.customRedisURL }} + - name: REDIS_URL + value: {{ $root.Values.redis.customRedisURL }} + {{- end }} + {{- if $root.Values.postgresql.enabled }} + - name: MAGE_DATABASE_CONNECTION_URL + value: postgresql://{{ $root.Values.postgresql.auth.username }}:{{ $root.Values.postgresql.auth.password }}@{{ $root.Values.postgresql.fullnameOverride }}:5432/{{ $root.Values.postgresql.auth.database }} + {{- end }} + {{- if $instanceType }} + - name: INSTANCE_TYPE + value: {{ $instanceType }} + {{- end }} + {{- if and $root.Values.workspaceConfig $root.Values.workspaceConfig.enabled }} + - name: WORKSPACE_DEFAULT_CONFIG_PATH + value: /etc/mage/workspace-config.yaml + {{- end }} + {{- if and $root.Values.k8sExecutorConfig $root.Values.k8sExecutorConfig.enabled }} + - name: K8S_DEFAULT_CONFIG_PATH + value: /etc/mage/k8s-executor-config.yaml + {{- end }} + volumeMounts: + {{- include "mageai.projectVolumeMounts" $root | nindent 4 }} + {{- if and $root.Values.workspaceConfig $root.Values.workspaceConfig.enabled }} + - name: workspace-config + mountPath: /etc/mage/workspace-config.yaml + subPath: config.yaml + readOnly: true + {{- end }} + {{- if and $root.Values.k8sExecutorConfig $root.Values.k8sExecutorConfig.enabled }} + - name: k8s-executor-config + mountPath: /etc/mage/k8s-executor-config.yaml + subPath: config.yaml + readOnly: true + {{- end }} +{{- end -}} + {{/* Resolve the OpenSearch host. When opensearch.enabled=true and logSearch.opensearch.host is not explicitly set, diff --git a/charts/mageai/templates/deployment.yaml b/charts/mageai/templates/deployment.yaml index 79a991e..33d8bee 100644 --- a/charts/mageai/templates/deployment.yaml +++ b/charts/mageai/templates/deployment.yaml @@ -38,7 +38,7 @@ spec: serviceAccountName: {{ include "mageai.serviceAccountName" . }} securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }} - {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled }} + {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled .Values.dependencyValidation.enabled }} initContainers: {{- if or .Values.redis.enabled .Values.redis.customRedisURL }} - name: wait-for-redis @@ -58,16 +58,15 @@ spec: image: {{ .Values.initContainerImages.busybox }} command: ['sh', '-c', 'until nc -z {{ .Values.postgresql.fullnameOverride }} 5432; do echo waiting for postgres; sleep 2; done;'] {{- end }} + {{- if .Values.dependencyValidation.enabled }} + {{- include "mageai.dependencyValidationInitContainer" (dict "root" .) | nindent 8 }} + {{- end }} {{- end }} containers: - name: {{ .Chart.Name }} securityContext: {{- toYaml .Values.securityContext | nindent 12 }} - {{- if .Values.image.digest }} - image: "{{ .Values.image.repository }}@{{ .Values.image.digest }}" - {{- else }} - image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}" - {{- end }} + image: {{ include "mageai.image" . | quote }} imagePullPolicy: {{ .Values.image.pullPolicy }} ports: - name: http diff --git a/charts/mageai/templates/scheduler.yaml b/charts/mageai/templates/scheduler.yaml index 42d5c02..91128a4 100644 --- a/charts/mageai/templates/scheduler.yaml +++ b/charts/mageai/templates/scheduler.yaml @@ -34,7 +34,7 @@ spec: serviceAccountName: {{ include "mageai.serviceAccountName" . }} securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }} - {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled }} + {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled .Values.dependencyValidation.enabled }} initContainers: {{- if or .Values.redis.enabled .Values.redis.customRedisURL }} - name: wait-for-redis @@ -54,12 +54,15 @@ spec: image: {{ .Values.initContainerImages.busybox }} command: ['sh', '-c', 'until nc -z {{ .Values.postgresql.fullnameOverride }} 5432; do echo waiting for postgres; sleep 2; done;'] {{- end }} + {{- if .Values.dependencyValidation.enabled }} + {{- include "mageai.dependencyValidationInitContainer" (dict "root" . "instanceType" "scheduler") | nindent 8 }} + {{- end }} {{- end }} containers: - name: {{ .Chart.Name }} securityContext: {{- toYaml .Values.securityContext | nindent 12 }} - image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}" + image: {{ include "mageai.image" . | quote }} imagePullPolicy: {{ .Values.image.pullPolicy }} ports: - name: http diff --git a/charts/mageai/templates/webservice.yaml b/charts/mageai/templates/webservice.yaml index dd624f9..361603b 100644 --- a/charts/mageai/templates/webservice.yaml +++ b/charts/mageai/templates/webservice.yaml @@ -29,7 +29,7 @@ spec: serviceAccountName: {{ include "mageai.serviceAccountName" . }} securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }} - {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled }} + {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled .Values.dependencyValidation.enabled }} initContainers: {{- if or .Values.redis.enabled .Values.redis.customRedisURL }} - name: wait-for-redis @@ -49,12 +49,15 @@ spec: image: {{ .Values.initContainerImages.busybox }} command: ['sh', '-c', 'until nc -z {{ .Values.postgresql.fullnameOverride }} 5432; do echo waiting for postgres; sleep 2; done;'] {{- end }} + {{- if .Values.dependencyValidation.enabled }} + {{- include "mageai.dependencyValidationInitContainer" (dict "root" . "instanceType" "web_server") | nindent 8 }} + {{- end }} {{- end }} containers: - name: {{ .Chart.Name }} securityContext: {{- toYaml .Values.securityContext | nindent 12 }} - image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}" + image: {{ include "mageai.image" . | quote }} imagePullPolicy: {{ .Values.image.pullPolicy }} ports: - name: http diff --git a/charts/mageai/tests/dependency_validation_test.yaml b/charts/mageai/tests/dependency_validation_test.yaml new file mode 100644 index 0000000..7bd4c70 --- /dev/null +++ b/charts/mageai/tests/dependency_validation_test.yaml @@ -0,0 +1,172 @@ +suite: dependency validation init container rendering +templates: + - templates/deployment.yaml + - templates/scheduler.yaml + - templates/webservice.yaml +tests: + - it: does not render dependency validation by default + template: templates/deployment.yaml + set: + postgresql.enabled: false + redis.enabled: false + asserts: + - isNull: + path: spec.template.spec.initContainers + + - it: renders validation with the Mage startup environment and project mounts + template: templates/deployment.yaml + set: + postgresql.enabled: false + redis.enabled: false + dependencyValidation.enabled: true + image.repository: example/mageai + image.tag: test + image.pullPolicy: IfNotPresent + config: + USER_CODE_PATH: project + secrets: + TEST_SECRET: secret + extraEnvs: + - name: EXTRA_SETTING + value: enabled + extraVolumeMounts: + - name: mage-fs + mountPath: /home/src + subPath: project + extraVolumes: + - name: mage-fs + persistentVolumeClaim: + claimName: mage-project + asserts: + - equal: + path: spec.template.spec.initContainers[0].name + value: validate-dependencies + - equal: + path: spec.template.spec.initContainers[0].image + value: example/mageai:test + - equal: + path: spec.template.spec.initContainers[0].imagePullPolicy + value: IfNotPresent + - equal: + path: spec.template.spec.initContainers[0].command[0] + value: /app/run_app.sh + - equal: + path: spec.template.spec.initContainers[0].command[3] + value: | + PROJECT_PATH="${USER_CODE_PATH:-default_repo}" + REQUIREMENTS_FILE="${PROJECT_PATH}/requirements.txt" + if [ -f "${REQUIREMENTS_FILE}" ]; then + python -m pip install -r "${REQUIREMENTS_FILE}" + fi + python -m pip check + python -c "import mage_ai.server.server" + - equal: + path: spec.template.spec.initContainers[0].envFrom[0].configMapRef.name + value: mageai-env + - equal: + path: spec.template.spec.initContainers[0].envFrom[1].secretRef.name + value: mageai-secret-env + - equal: + path: spec.template.spec.initContainers[0].env[0].name + value: EXTRA_SETTING + - equal: + path: spec.template.spec.initContainers[0].volumeMounts[0].mountPath + value: /home/src + - equal: + path: spec.template.spec.initContainers[0].volumeMounts[0].subPath + value: project + + - it: renders after the existing dependency readiness containers + template: templates/deployment.yaml + set: + dependencyValidation.enabled: true + postgresql.enabled: true + redis.enabled: true + asserts: + - equal: + path: spec.template.spec.initContainers[0].name + value: wait-for-redis + - equal: + path: spec.template.spec.initContainers[1].name + value: wait-for-postgres + - equal: + path: spec.template.spec.initContainers[2].name + value: validate-dependencies + + - it: renders for the standalone web server with its instance type + template: templates/webservice.yaml + set: + standaloneScheduler: true + postgresql.enabled: false + redis.enabled: false + dependencyValidation.enabled: true + asserts: + - equal: + path: spec.template.spec.initContainers[0].name + value: validate-dependencies + - contains: + path: spec.template.spec.initContainers[0].env + content: + name: INSTANCE_TYPE + value: web_server + + - it: renders for the standalone scheduler with its instance type + template: templates/scheduler.yaml + set: + standaloneScheduler: true + postgresql.enabled: false + redis.enabled: false + dependencyValidation.enabled: true + asserts: + - equal: + path: spec.template.spec.initContainers[0].name + value: validate-dependencies + - contains: + path: spec.template.spec.initContainers[0].env + content: + name: INSTANCE_TYPE + value: scheduler + + - it: uses the same digest image for validation and the application + template: templates/scheduler.yaml + set: + standaloneScheduler: true + postgresql.enabled: false + redis.enabled: false + dependencyValidation.enabled: true + image.repository: example/mageai + image.digest: sha256:abcdef + asserts: + - equal: + path: spec.template.spec.initContainers[0].image + value: example/mageai@sha256:abcdef + - equal: + path: spec.template.spec.containers[0].image + value: example/mageai@sha256:abcdef + + - it: permits a custom validation command + template: templates/deployment.yaml + set: + postgresql.enabled: false + redis.enabled: false + dependencyValidation.enabled: true + dependencyValidation.command: + - /app/run_app.sh + - python + - -c + - import mage_ai + asserts: + - equal: + path: spec.template.spec.initContainers[0].command[3] + value: import mage_ai + + - it: rejects an empty validation command + template: templates/deployment.yaml + set: + postgresql.enabled: false + redis.enabled: false + dependencyValidation.enabled: true + dependencyValidation.command: [] + asserts: + - failedTemplate: + errorMessage: dependencyValidation.command must not be empty when dependencyValidation.enabled=true diff --git a/charts/mageai/values.yaml b/charts/mageai/values.yaml index 18506d9..caef674 100644 --- a/charts/mageai/values.yaml +++ b/charts/mageai/values.yaml @@ -143,6 +143,26 @@ initContainerImages: # Default is public Docker Hub BusyBox image. busybox: busybox +# Validate project dependencies before starting Mage. The validator uses the +# same Mage image, configuration, and project mounts as the application +# container, but runs the startup dependency setup followed by these checks +# without starting the web server or scheduler. +dependencyValidation: + enabled: false + command: + - /app/run_app.sh + - /bin/bash + - -ec + - | + PROJECT_PATH="${USER_CODE_PATH:-default_repo}" + REQUIREMENTS_FILE="${PROJECT_PATH}/requirements.txt" + if [ -f "${REQUIREMENTS_FILE}" ]; then + python -m pip install -r "${REQUIREMENTS_FILE}" + fi + python -m pip check + python -c "import mage_ai.server.server" + resources: {} + # ------------------------------------------------------------------------------ # Naming and RBAC # ------------------------------------------------------------------------------ From d9f638f09cdb5dbc28af85884811b1b42d566948 Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 15:53:43 -0700 Subject: [PATCH 2/8] Support dependency validation with reused values --- charts/mageai/templates/_helpers.tpl | 7 +++---- charts/mageai/tests/dependency_validation_test.yaml | 10 +++++++--- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/charts/mageai/templates/_helpers.tpl b/charts/mageai/templates/_helpers.tpl index 9b021b4..544a246 100644 --- a/charts/mageai/templates/_helpers.tpl +++ b/charts/mageai/templates/_helpers.tpl @@ -97,16 +97,15 @@ same workload-specific environment as their main containers. {{- define "mageai.dependencyValidationInitContainer" -}} {{- $root := .root -}} {{- $instanceType := default "" .instanceType -}} -{{- if not $root.Values.dependencyValidation.command -}} -{{- fail "dependencyValidation.command must not be empty when dependencyValidation.enabled=true" -}} -{{- end -}} +{{- $defaultCommand := list "/app/run_app.sh" "/bin/bash" "-ec" (printf "%s\n%s\n%s\n%s\n%s\n%s\n%s" "PROJECT_PATH=\"${USER_CODE_PATH:-default_repo}\"" "REQUIREMENTS_FILE=\"${PROJECT_PATH}/requirements.txt\"" "if [ -f \"${REQUIREMENTS_FILE}\" ]; then" " python -m pip install -r \"${REQUIREMENTS_FILE}\"" "fi" "python -m pip check" "python -c \"import mage_ai.server.server\"") -}} +{{- $command := default $defaultCommand $root.Values.dependencyValidation.command -}} - name: validate-dependencies securityContext: {{- toYaml $root.Values.securityContext | nindent 4 }} image: {{ include "mageai.image" $root | quote }} imagePullPolicy: {{ $root.Values.image.pullPolicy }} command: - {{- toYaml $root.Values.dependencyValidation.command | nindent 4 }} + {{- toYaml $command | nindent 4 }} resources: {{- toYaml $root.Values.dependencyValidation.resources | nindent 4 }} {{- if or $root.Values.config $root.Values.existingSecret $root.Values.secrets }} diff --git a/charts/mageai/tests/dependency_validation_test.yaml b/charts/mageai/tests/dependency_validation_test.yaml index 7bd4c70..a13988c 100644 --- a/charts/mageai/tests/dependency_validation_test.yaml +++ b/charts/mageai/tests/dependency_validation_test.yaml @@ -160,7 +160,7 @@ tests: path: spec.template.spec.initContainers[0].command[3] value: import mage_ai - - it: rejects an empty validation command + - it: falls back to the safe default when an upgraded release has no command template: templates/deployment.yaml set: postgresql.enabled: false @@ -168,5 +168,9 @@ tests: dependencyValidation.enabled: true dependencyValidation.command: [] asserts: - - failedTemplate: - errorMessage: dependencyValidation.command must not be empty when dependencyValidation.enabled=true + - equal: + path: spec.template.spec.initContainers[0].command[0] + value: /app/run_app.sh + - matchRegex: + path: spec.template.spec.initContainers[0].command[3] + pattern: 'python -m pip install -r' From 4c82d7de097382483caf6955f4552240423e0c7b Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 15:59:27 -0700 Subject: [PATCH 3/8] Limit validation to Mage startup imports --- README.md | 2 +- charts/mageai/templates/_helpers.tpl | 2 +- charts/mageai/tests/dependency_validation_test.yaml | 5 ++++- charts/mageai/values.yaml | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a276c24..4483063 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ dependencyValidation: ``` The default command reruns the project requirements installation with fail-fast -behavior, runs `python -m pip check`, and imports the Mage server module. Override +behavior, then imports the Mage server and scheduler startup modules. Override `dependencyValidation.command` to add project-specific checks. Any command that exits nonzero prevents the Mage application container from starting. diff --git a/charts/mageai/templates/_helpers.tpl b/charts/mageai/templates/_helpers.tpl index 544a246..821623b 100644 --- a/charts/mageai/templates/_helpers.tpl +++ b/charts/mageai/templates/_helpers.tpl @@ -97,7 +97,7 @@ same workload-specific environment as their main containers. {{- define "mageai.dependencyValidationInitContainer" -}} {{- $root := .root -}} {{- $instanceType := default "" .instanceType -}} -{{- $defaultCommand := list "/app/run_app.sh" "/bin/bash" "-ec" (printf "%s\n%s\n%s\n%s\n%s\n%s\n%s" "PROJECT_PATH=\"${USER_CODE_PATH:-default_repo}\"" "REQUIREMENTS_FILE=\"${PROJECT_PATH}/requirements.txt\"" "if [ -f \"${REQUIREMENTS_FILE}\" ]; then" " python -m pip install -r \"${REQUIREMENTS_FILE}\"" "fi" "python -m pip check" "python -c \"import mage_ai.server.server\"") -}} +{{- $defaultCommand := list "/app/run_app.sh" "/bin/bash" "-ec" (printf "%s\n%s\n%s\n%s\n%s\n%s\n%s" "PROJECT_PATH=\"${USER_CODE_PATH:-default_repo}\"" "REQUIREMENTS_FILE=\"${PROJECT_PATH}/requirements.txt\"" "if [ -f \"${REQUIREMENTS_FILE}\" ]; then" " python -m pip install -r \"${REQUIREMENTS_FILE}\"" "fi" "python -c \"import mage_ai.server.server\"" "python -c \"import mage_ai.server.scheduler_manager; import mage_ai.orchestration.job_manager; import mage_ai.orchestration.triggers.loop_time_trigger\"") -}} {{- $command := default $defaultCommand $root.Values.dependencyValidation.command -}} - name: validate-dependencies securityContext: diff --git a/charts/mageai/tests/dependency_validation_test.yaml b/charts/mageai/tests/dependency_validation_test.yaml index a13988c..74237cb 100644 --- a/charts/mageai/tests/dependency_validation_test.yaml +++ b/charts/mageai/tests/dependency_validation_test.yaml @@ -58,8 +58,8 @@ tests: if [ -f "${REQUIREMENTS_FILE}" ]; then python -m pip install -r "${REQUIREMENTS_FILE}" fi - python -m pip check python -c "import mage_ai.server.server" + python -c "import mage_ai.server.scheduler_manager; import mage_ai.orchestration.job_manager; import mage_ai.orchestration.triggers.loop_time_trigger" - equal: path: spec.template.spec.initContainers[0].envFrom[0].configMapRef.name value: mageai-env @@ -174,3 +174,6 @@ tests: - matchRegex: path: spec.template.spec.initContainers[0].command[3] pattern: 'python -m pip install -r' + - matchRegex: + path: spec.template.spec.initContainers[0].command[3] + pattern: 'mage_ai.server.scheduler_manager' diff --git a/charts/mageai/values.yaml b/charts/mageai/values.yaml index caef674..d066493 100644 --- a/charts/mageai/values.yaml +++ b/charts/mageai/values.yaml @@ -159,8 +159,8 @@ dependencyValidation: if [ -f "${REQUIREMENTS_FILE}" ]; then python -m pip install -r "${REQUIREMENTS_FILE}" fi - python -m pip check python -c "import mage_ai.server.server" + python -c "import mage_ai.server.scheduler_manager; import mage_ai.orchestration.job_manager; import mage_ai.orchestration.triggers.loop_time_trigger" resources: {} # ------------------------------------------------------------------------------ From 27a94948cac1e2bd5f8b97e476d03da45f00c82e Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 16:09:40 -0700 Subject: [PATCH 4/8] Expand Helm chart README --- README.md | 305 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 283 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 4483063..15db436 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,293 @@ # Mage Helm charts +Helm charts for running [Mage](https://www.mage.ai/) on Kubernetes. The main +chart deploys Mage OSS or Mage Pro and can optionally deploy PostgreSQL, Redis, +OpenSearch, persistent storage, ingress, and separate web-server and scheduler +workloads. + +## Charts + +| Chart | Description | Source | +| --- | --- | --- | +| `mageai` | Mage application, service, optional dependencies, storage, and operational configuration | [`charts/mageai`](charts/mageai) | +| `mageai-ingress` | Standalone ingress configuration for an existing Mage service | [`charts/ingress`](charts/ingress) | + +The chart repository is published at +. + +## Prerequisites + +- Kubernetes cluster access through `kubectl`. +- Helm 3. +- A storage plan for project code and Mage data. The default values contain a + placeholder `hostPath`; replace it before deploying outside a local test. +- A PostgreSQL database for production workloads. The chart can deploy its + bundled PostgreSQL dependency, or Mage can use an external database through + `MAGE_DATABASE_CONNECTION_URL`. + +## Install + +Add and update the Mage chart repository: + +```bash +helm repo add mageai https://mage-ai.github.io/helm-charts/ +helm repo update +``` + +Create a values file for your environment. This minimal example runs the project +included in the image without mounting host storage and uses the bundled +PostgreSQL chart: + +```yaml +# values.yaml +postgresql: + enabled: true + auth: + username: mage + password: replace-me + database: mage + +service: + type: ClusterIP + +extraVolumeMounts: [] +extraVolumes: [] +``` + +Install Mage: + +```bash +helm upgrade --install mageai mageai/mageai \ + --namespace mageai \ + --create-namespace \ + --values values.yaml +``` + +For production, store credentials in Kubernetes Secrets or an external secret +manager rather than committing them to a values file. + +Check the rollout: + +```bash +helm status mageai --namespace mageai +kubectl get pods --namespace mageai +``` + +For a `ClusterIP` service, open Mage locally with port forwarding: + +```bash +kubectl port-forward --namespace mageai service/mageai 6789:6789 +``` + +Then visit . + +## Common configuration + +### Use a custom image + +```yaml +image: + repository: mageai/mageai + tag: "0.9.79" + pullPolicy: IfNotPresent +``` + +For a private registry, set `image.repository` and configure +`imagePullSecrets` with Secrets that already exist in the release namespace. + +### Configure project storage + +Mount an existing claim at `/home/src`: + +```yaml +extraVolumeMounts: + - name: mage-fs + mountPath: /home/src + +extraVolumes: + - name: mage-fs + persistentVolumeClaim: + claimName: mage-project +``` + +Use storage that supports the access pattern of your deployment. Multiple Mage +replicas or split web-server/scheduler deployments generally require storage +that can be mounted by every participating pod. + +### Use an existing Secret + +```yaml +existingSecret: mage-environment +``` + +The Secret keys are exposed as environment variables in the Mage container. +Use `config` for non-sensitive key-value configuration and `extraEnvs` for +entries that require `valueFrom`. + +### Run separate web-server and scheduler workloads + +```yaml +standaloneScheduler: true + +webServer: + replicaCount: 2 + +scheduler: + replicaCount: 1 +``` + +This creates independent Deployments so the web server and scheduler can be +scaled and resourced separately. Configure shared storage and a shared metadata +database before enabling this topology. + +### Enable Redis + +```yaml +redis: + enabled: true +``` + +Redis is recommended when multiple Mage replicas need distributed locking or +caching. Set `redis.customRedisURL` instead to use an external Redis service. + +### Expose Mage + +The main chart supports `ClusterIP`, `NodePort`, and `LoadBalancer` Services. It +also retains an ingress configuration for backward compatibility, though a +separate ingress deployment is recommended for production. + +```yaml +service: + type: LoadBalancer + port: 6789 +``` + +The repository also includes the `mageai-ingress` chart for managing ingress +separately. + ## Validate dependencies before Mage starts -The Mage chart can run the image's normal startup dependency setup in an init -container, then check the resulting Python environment without starting the web -server or scheduler. This is available for both Mage OSS and Mage Pro images and -is disabled by default. +Dependency validation is disabled by default. When enabled, the chart runs +Mage's dependency setup in an init container and starts the main container only +after project requirements install and the server and scheduler startup modules +import successfully. + +```yaml +dependencyValidation: + enabled: true + resources: + requests: + cpu: 100m + memory: 256Mi + limits: + cpu: "1" + memory: 1Gi +``` + +The validator uses the Mage workload image and inherits `config`, the configured +Secret, `env` or `extraEnvs`, Redis/PostgreSQL connection variables, project +mounts, and enabled workspace or Kubernetes-executor configuration mounts. It +runs after the optional Redis and PostgreSQL readiness init containers. With +`standaloneScheduler: true`, both the web-server and scheduler Deployments +receive a validator with their corresponding `INSTANCE_TYPE`. Feature-specific +sidecar settings, such as OpenSearch TLS mounts, are not automatically copied to +the validator container. + +The default command: + +1. Runs `/app/run_app.sh` to prepare the normal Mage dependency environment. +2. Installs the project `requirements.txt` with fail-fast behavior. +3. Imports the Mage server module. +4. Imports the scheduler startup modules. + +Any nonzero exit prevents the main Mage container from starting. During a +rolling deployment, existing ready pods remain available until the new pod +passes validation and readiness. + +You can replace the complete validation command: ```yaml dependencyValidation: enabled: true + command: + - /app/run_app.sh + - /bin/bash + - -ec + - | + python -c "import mage_ai.server.server" + python -c "import mage_ai.server.scheduler_manager" + python -c "import my_project.validation" +``` + +`command` replaces rather than extends the default. Keep `/app/run_app.sh` when +the check depends on Mage's managed dependency environment, and ensure custom +checks are read-only and return a nonzero exit when validation fails. + +The init container and application container have separate writable image +layers, but mounted volumes are shared. Avoid validation commands that mutate +shared project state or a shared dependency cache. Mage still performs its +normal dependency setup when the main container starts, so validation can add +startup time and duplicate dependency work. + +## Upgrade + +Refresh repository metadata and upgrade with your existing values file: + +```bash +helm repo update +helm upgrade mageai mageai/mageai \ + --namespace mageai \ + --values values.yaml \ + --atomic \ + --wait +``` + +Review the proposed change before applying it when the Helm diff plugin is +available: + +```bash +helm diff upgrade mageai mageai/mageai \ + --namespace mageai \ + --values values.yaml +``` + +Pin chart and application image versions for repeatable production upgrades. +Use `helm history` and `helm rollback` to return to an earlier release revision. + +## Uninstall + +```bash +helm uninstall mageai --namespace mageai +``` + +PersistentVolumes, PersistentVolumeClaims, external databases, and external +Secrets may outlive the Helm release. Review and remove retained resources only +when their data is no longer needed. + +## Examples and reference + +- [`charts/mageai/values.yaml`](charts/mageai/values.yaml) documents all main + chart values and defaults. +- [`examples/aws-eks`](examples/aws-eks) contains EKS storage and log-search + examples. +- [`examples/local`](examples/local) contains local Kubernetes overrides. +- [Mage documentation](https://docs.mage.ai/) covers product configuration and + deployment concepts beyond the chart itself. + +## Contributing + +Before opening a pull request, render and validate the affected chart: + +```bash +helm dependency build charts/mageai +helm lint charts/mageai +helm unittest charts/mageai +helm template mageai charts/mageai --values your-values.yaml ``` -The default command reruns the project requirements installation with fail-fast -behavior, then imports the Mage server and scheduler startup modules. Override -`dependencyValidation.command` to add project-specific checks. Any command that -exits nonzero prevents the Mage application container from starting. - -The validator and application container use separate writable filesystem layers. -Packages installed by the init container are not carried into the application -container unless their install location is backed by a shared volume, so the -application still performs its normal dependency setup and may install packages -a second time. The default command is a fail-fast compatibility check, not a way -to preinstall dependencies for the application container. - -The startup script can treat some dependency-installation failures as warnings and -continue. The default validation command therefore repeats the requirements install -with fail-fast behavior. Preserve an equivalent strict install and an explicit -compatibility check when supplying a custom command so Kubernetes blocks startup -when a requested dependency cannot be installed or the resulting environment is -incompatible. +Chart changes must increment the chart version in the corresponding +`Chart.yaml`. Pull requests run chart-testing and Kubernetes schema validation. + +## License + +This repository is licensed under the [Apache License 2.0](LICENSE). From 15b40860c470ec8ae97b3ae66f1386b1d44dd137 Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 16:10:51 -0700 Subject: [PATCH 5/8] Handle missing dependency validation values --- charts/mageai/templates/_helpers.tpl | 8 ++++++++ charts/mageai/templates/deployment.yaml | 4 ++-- charts/mageai/templates/scheduler.yaml | 4 ++-- charts/mageai/templates/webservice.yaml | 4 ++-- charts/mageai/tests/dependency_validation_test.yaml | 10 ++++++++++ 5 files changed, 24 insertions(+), 6 deletions(-) diff --git a/charts/mageai/templates/_helpers.tpl b/charts/mageai/templates/_helpers.tpl index 821623b..c0c5fea 100644 --- a/charts/mageai/templates/_helpers.tpl +++ b/charts/mageai/templates/_helpers.tpl @@ -89,6 +89,14 @@ Render the Mage image reference shared by application and validation containers. {{- end -}} {{- end -}} +{{/* +Return "true" when dependency validation is enabled. Older releases upgraded +with --reuse-values may not have the dependencyValidation map at all. +*/}} +{{- define "mageai.dependencyValidationEnabled" -}} +{{- if and .Values.dependencyValidation .Values.dependencyValidation.enabled }}true{{ end -}} +{{- end -}} + {{/* Render the optional dependency validation init container. The caller may pass an instanceType so split web server and scheduler deployments validate with the diff --git a/charts/mageai/templates/deployment.yaml b/charts/mageai/templates/deployment.yaml index 33d8bee..2db64da 100644 --- a/charts/mageai/templates/deployment.yaml +++ b/charts/mageai/templates/deployment.yaml @@ -38,7 +38,7 @@ spec: serviceAccountName: {{ include "mageai.serviceAccountName" . }} securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }} - {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled .Values.dependencyValidation.enabled }} + {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled (include "mageai.dependencyValidationEnabled" .) }} initContainers: {{- if or .Values.redis.enabled .Values.redis.customRedisURL }} - name: wait-for-redis @@ -58,7 +58,7 @@ spec: image: {{ .Values.initContainerImages.busybox }} command: ['sh', '-c', 'until nc -z {{ .Values.postgresql.fullnameOverride }} 5432; do echo waiting for postgres; sleep 2; done;'] {{- end }} - {{- if .Values.dependencyValidation.enabled }} + {{- if include "mageai.dependencyValidationEnabled" . }} {{- include "mageai.dependencyValidationInitContainer" (dict "root" .) | nindent 8 }} {{- end }} {{- end }} diff --git a/charts/mageai/templates/scheduler.yaml b/charts/mageai/templates/scheduler.yaml index 91128a4..c4c876f 100644 --- a/charts/mageai/templates/scheduler.yaml +++ b/charts/mageai/templates/scheduler.yaml @@ -34,7 +34,7 @@ spec: serviceAccountName: {{ include "mageai.serviceAccountName" . }} securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }} - {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled .Values.dependencyValidation.enabled }} + {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled (include "mageai.dependencyValidationEnabled" .) }} initContainers: {{- if or .Values.redis.enabled .Values.redis.customRedisURL }} - name: wait-for-redis @@ -54,7 +54,7 @@ spec: image: {{ .Values.initContainerImages.busybox }} command: ['sh', '-c', 'until nc -z {{ .Values.postgresql.fullnameOverride }} 5432; do echo waiting for postgres; sleep 2; done;'] {{- end }} - {{- if .Values.dependencyValidation.enabled }} + {{- if include "mageai.dependencyValidationEnabled" . }} {{- include "mageai.dependencyValidationInitContainer" (dict "root" . "instanceType" "scheduler") | nindent 8 }} {{- end }} {{- end }} diff --git a/charts/mageai/templates/webservice.yaml b/charts/mageai/templates/webservice.yaml index 361603b..ec14d7b 100644 --- a/charts/mageai/templates/webservice.yaml +++ b/charts/mageai/templates/webservice.yaml @@ -29,7 +29,7 @@ spec: serviceAccountName: {{ include "mageai.serviceAccountName" . }} securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }} - {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled .Values.dependencyValidation.enabled }} + {{- if or .Values.redis.enabled .Values.redis.customRedisURL .Values.postgresql.enabled (include "mageai.dependencyValidationEnabled" .) }} initContainers: {{- if or .Values.redis.enabled .Values.redis.customRedisURL }} - name: wait-for-redis @@ -49,7 +49,7 @@ spec: image: {{ .Values.initContainerImages.busybox }} command: ['sh', '-c', 'until nc -z {{ .Values.postgresql.fullnameOverride }} 5432; do echo waiting for postgres; sleep 2; done;'] {{- end }} - {{- if .Values.dependencyValidation.enabled }} + {{- if include "mageai.dependencyValidationEnabled" . }} {{- include "mageai.dependencyValidationInitContainer" (dict "root" . "instanceType" "web_server") | nindent 8 }} {{- end }} {{- end }} diff --git a/charts/mageai/tests/dependency_validation_test.yaml b/charts/mageai/tests/dependency_validation_test.yaml index 74237cb..8af68fc 100644 --- a/charts/mageai/tests/dependency_validation_test.yaml +++ b/charts/mageai/tests/dependency_validation_test.yaml @@ -13,6 +13,16 @@ tests: - isNull: path: spec.template.spec.initContainers + - it: supports reused values that do not contain the dependency validation map + template: templates/deployment.yaml + set: + postgresql.enabled: false + redis.enabled: false + dependencyValidation: null + asserts: + - isNull: + path: spec.template.spec.initContainers + - it: renders validation with the Mage startup environment and project mounts template: templates/deployment.yaml set: From 91e6afa520461390326cf5033ca23b349717783c Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 16:14:31 -0700 Subject: [PATCH 6/8] Isolate dependency validation environment --- README.md | 16 ++++--- charts/mageai/templates/_helpers.tpl | 19 +++++++- charts/mageai/templates/deployment.yaml | 4 ++ charts/mageai/templates/scheduler.yaml | 4 ++ charts/mageai/templates/webservice.yaml | 4 ++ .../tests/dependency_validation_test.yaml | 44 +++++++++++++++++++ charts/mageai/values.yaml | 4 +- 7 files changed, 87 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 15db436..1801348 100644 --- a/README.md +++ b/README.md @@ -193,9 +193,15 @@ receive a validator with their corresponding `INSTANCE_TYPE`. Feature-specific sidecar settings, such as OpenSearch TLS mounts, are not automatically copied to the validator container. +The chart sets `MAGE_DATA_DIR` to an init-container-local path so Mage creates +the validator's managed virtual environment outside mounted project storage. +Installing or resolving dependencies during validation therefore cannot modify +the cached virtual environment used by pods from the existing release. The +isolated environment is discarded with the init container. + The default command: -1. Runs `/app/run_app.sh` to prepare the normal Mage dependency environment. +1. Runs `/app/run_app.sh` to prepare the isolated Mage dependency environment. 2. Installs the project `requirements.txt` with fail-fast behavior. 3. Imports the Mage server module. 4. Imports the scheduler startup modules. @@ -224,10 +230,10 @@ the check depends on Mage's managed dependency environment, and ensure custom checks are read-only and return a nonzero exit when validation fails. The init container and application container have separate writable image -layers, but mounted volumes are shared. Avoid validation commands that mutate -shared project state or a shared dependency cache. Mage still performs its -normal dependency setup when the main container starts, so validation can add -startup time and duplicate dependency work. +layers, but project volumes remain shared. Custom validation commands should be +read-only and must not mutate project files or other mounted state. Mage still +performs its normal dependency setup when the main container starts, so +validation can add startup time and duplicate dependency work. ## Upgrade diff --git a/charts/mageai/templates/_helpers.tpl b/charts/mageai/templates/_helpers.tpl index c0c5fea..5862cbc 100644 --- a/charts/mageai/templates/_helpers.tpl +++ b/charts/mageai/templates/_helpers.tpl @@ -129,10 +129,23 @@ same workload-specific environment as their main containers. {{- end }} env: {{- if $root.Values.env }} - {{- toYaml $root.Values.env | nindent 4 }} + {{- range $root.Values.env }} + {{- if ne .name "MAGE_DATA_DIR" }} + {{- toYaml (list .) | nindent 4 }} + {{- end }} + {{- end }} {{- else if $root.Values.extraEnvs }} - {{- toYaml $root.Values.extraEnvs | nindent 4 }} + {{- range $root.Values.extraEnvs }} + {{- if ne .name "MAGE_DATA_DIR" }} + {{- toYaml (list .) | nindent 4 }} + {{- end }} + {{- end }} {{- end }} + # Keep preflight dependency writes in the init container's ephemeral layer. + # This entry intentionally follows user-provided environment variables so + # validation cannot reuse or mutate the running deployment's cached venv. + - name: MAGE_DATA_DIR + value: /tmp/mage-validation-data {{- if $root.Values.redis.enabled }} - name: REDIS_URL value: redis://{{ $root.Release.Name }}-redis-headless:6379/0 @@ -158,6 +171,8 @@ same workload-specific environment as their main containers. {{- end }} volumeMounts: {{- include "mageai.projectVolumeMounts" $root | nindent 4 }} + - name: dependency-validation-data + mountPath: /tmp/mage-validation-data {{- if and $root.Values.workspaceConfig $root.Values.workspaceConfig.enabled }} - name: workspace-config mountPath: /etc/mage/workspace-config.yaml diff --git a/charts/mageai/templates/deployment.yaml b/charts/mageai/templates/deployment.yaml index 2db64da..df861aa 100644 --- a/charts/mageai/templates/deployment.yaml +++ b/charts/mageai/templates/deployment.yaml @@ -197,6 +197,10 @@ spec: {{- end }} volumes: {{- include "mageai.projectVolumes" . | nindent 8 }} + {{- if include "mageai.dependencyValidationEnabled" . }} + - name: dependency-validation-data + emptyDir: {} + {{- end }} {{- if and .Values.workspaceConfig .Values.workspaceConfig.enabled }} - name: workspace-config configMap: diff --git a/charts/mageai/templates/scheduler.yaml b/charts/mageai/templates/scheduler.yaml index c4c876f..2c045d9 100644 --- a/charts/mageai/templates/scheduler.yaml +++ b/charts/mageai/templates/scheduler.yaml @@ -168,6 +168,10 @@ spec: {{- end }} volumes: {{- include "mageai.projectVolumes" . | nindent 8 }} + {{- if include "mageai.dependencyValidationEnabled" . }} + - name: dependency-validation-data + emptyDir: {} + {{- end }} {{- if and .Values.workspaceConfig .Values.workspaceConfig.enabled }} - name: workspace-config configMap: diff --git a/charts/mageai/templates/webservice.yaml b/charts/mageai/templates/webservice.yaml index ec14d7b..5e06328 100644 --- a/charts/mageai/templates/webservice.yaml +++ b/charts/mageai/templates/webservice.yaml @@ -190,6 +190,10 @@ spec: {{- end }} volumes: {{- include "mageai.projectVolumes" . | nindent 8 }} + {{- if include "mageai.dependencyValidationEnabled" . }} + - name: dependency-validation-data + emptyDir: {} + {{- end }} {{- if and .Values.workspaceConfig .Values.workspaceConfig.enabled }} - name: workspace-config configMap: diff --git a/charts/mageai/tests/dependency_validation_test.yaml b/charts/mageai/tests/dependency_validation_test.yaml index 8af68fc..3d0c9ba 100644 --- a/charts/mageai/tests/dependency_validation_test.yaml +++ b/charts/mageai/tests/dependency_validation_test.yaml @@ -79,12 +79,26 @@ tests: - equal: path: spec.template.spec.initContainers[0].env[0].name value: EXTRA_SETTING + - equal: + path: spec.template.spec.initContainers[0].env[1].name + value: MAGE_DATA_DIR + - equal: + path: spec.template.spec.initContainers[0].env[1].value + value: /tmp/mage-validation-data - equal: path: spec.template.spec.initContainers[0].volumeMounts[0].mountPath value: /home/src - equal: path: spec.template.spec.initContainers[0].volumeMounts[0].subPath value: project + - equal: + path: spec.template.spec.initContainers[0].volumeMounts[1].name + value: dependency-validation-data + - equal: + path: spec.template.spec.initContainers[0].volumeMounts[1].mountPath + value: /tmp/mage-validation-data + - isNotNull: + path: spec.template.spec.volumes[1].emptyDir - it: renders after the existing dependency readiness containers template: templates/deployment.yaml @@ -119,6 +133,11 @@ tests: content: name: INSTANCE_TYPE value: web_server + - contains: + path: spec.template.spec.initContainers[0].env + content: + name: MAGE_DATA_DIR + value: /tmp/mage-validation-data - it: renders for the standalone scheduler with its instance type template: templates/scheduler.yaml @@ -136,6 +155,11 @@ tests: content: name: INSTANCE_TYPE value: scheduler + - contains: + path: spec.template.spec.initContainers[0].env + content: + name: MAGE_DATA_DIR + value: /tmp/mage-validation-data - it: uses the same digest image for validation and the application template: templates/scheduler.yaml @@ -170,6 +194,26 @@ tests: path: spec.template.spec.initContainers[0].command[3] value: import mage_ai + - it: overrides a shared dependency data directory for validation + template: templates/deployment.yaml + set: + postgresql.enabled: false + redis.enabled: false + dependencyValidation.enabled: true + extraEnvs: + - name: MAGE_DATA_DIR + value: /home/src/mage_data + asserts: + - equal: + path: spec.template.spec.initContainers[0].env[0].name + value: MAGE_DATA_DIR + - equal: + path: spec.template.spec.initContainers[0].env[0].value + value: /tmp/mage-validation-data + - lengthEqual: + path: spec.template.spec.initContainers[0].env + count: 1 + - it: falls back to the safe default when an upgraded release has no command template: templates/deployment.yaml set: diff --git a/charts/mageai/values.yaml b/charts/mageai/values.yaml index d066493..638e5f7 100644 --- a/charts/mageai/values.yaml +++ b/charts/mageai/values.yaml @@ -146,7 +146,9 @@ initContainerImages: # Validate project dependencies before starting Mage. The validator uses the # same Mage image, configuration, and project mounts as the application # container, but runs the startup dependency setup followed by these checks -# without starting the web server or scheduler. +# without starting the web server or scheduler. Its managed dependency +# environment is stored in the init container's ephemeral writable layer so +# validation cannot mutate the running deployment's cached environment. dependencyValidation: enabled: false command: From b0e22ef80235bb223b5d0dd86c44cea932fe651f Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 16:30:10 -0700 Subject: [PATCH 7/8] Document standalone digest precedence --- README.md | 19 ++++++++++++ charts/mageai/tests/image_rendering_test.yaml | 29 +++++++++++++++++++ charts/mageai/values.yaml | 3 ++ 3 files changed, 51 insertions(+) create mode 100644 charts/mageai/tests/image_rendering_test.yaml diff --git a/README.md b/README.md index 1801348..69982cb 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,19 @@ image: pullPolicy: IfNotPresent ``` +To pin the image by digest instead, set `image.digest`: + +```yaml +image: + repository: mageai/mageai + digest: "sha256:0123456789abcdef..." +``` + +When `image.digest` is non-empty, it takes precedence over `image.tag` for the +combined Deployment and for both standalone web-server and scheduler +Deployments. The same selected image is used by dependency validation when it +is enabled. + For a private registry, set `image.repository` and configure `imagePullSecrets` with Secrets that already exist in the release namespace. @@ -260,6 +273,12 @@ helm diff upgrade mageai mageai/mageai \ Pin chart and application image versions for repeatable production upgrades. Use `helm history` and `helm rollback` to return to an earlier release revision. +Standalone releases now honor `image.digest` consistently with the combined +Deployment. When upgrading a standalone release that carries both `image.tag` +and a non-empty `image.digest`, verify that the digest identifies the intended +image: the digest will be selected and can cause the web-server and scheduler +pods to roll even when dependency validation is disabled. + ## Uninstall ```bash diff --git a/charts/mageai/tests/image_rendering_test.yaml b/charts/mageai/tests/image_rendering_test.yaml new file mode 100644 index 0000000..b95bf0d --- /dev/null +++ b/charts/mageai/tests/image_rendering_test.yaml @@ -0,0 +1,29 @@ +suite: Mage application image rendering +templates: + - templates/deployment.yaml + - templates/scheduler.yaml + - templates/webservice.yaml +tests: + - it: standalone web server prefers the configured digest over the tag + template: templates/webservice.yaml + set: + standaloneScheduler: true + image.repository: example/mageai + image.tag: stable + image.digest: sha256:abcdef + asserts: + - equal: + path: spec.template.spec.containers[0].image + value: example/mageai@sha256:abcdef + + - it: standalone scheduler prefers the configured digest over the tag + template: templates/scheduler.yaml + set: + standaloneScheduler: true + image.repository: example/mageai + image.tag: stable + image.digest: sha256:abcdef + asserts: + - equal: + path: spec.template.spec.containers[0].image + value: example/mageai@sha256:abcdef diff --git a/charts/mageai/values.yaml b/charts/mageai/values.yaml index 638e5f7..5d3fe2d 100644 --- a/charts/mageai/values.yaml +++ b/charts/mageai/values.yaml @@ -126,6 +126,9 @@ image: pullPolicy: Always # Overrides the image tag whose default is the chart appVersion. tag: "" + # Optional immutable image digest. When set, this takes precedence over tag + # for combined and standalone web-server/scheduler Deployments. + digest: "" # List of imagePullSecrets to use for pulling images from private registries. # These must already exist in the target namespace. From fb4b2a8f5308af1c2cf8ab9bb8172f85d2c64ee0 Mon Sep 17 00:00:00 2001 From: wangxiaoyou1993 Date: Fri, 23 Oct 2026 16:50:54 -0700 Subject: [PATCH 8/8] Clarify dependency validation configuration --- charts/mageai/values.yaml | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/charts/mageai/values.yaml b/charts/mageai/values.yaml index 5d3fe2d..1709aa7 100644 --- a/charts/mageai/values.yaml +++ b/charts/mageai/values.yaml @@ -147,11 +147,14 @@ initContainerImages: busybox: busybox # Validate project dependencies before starting Mage. The validator uses the -# same Mage image, configuration, and project mounts as the application -# container, but runs the startup dependency setup followed by these checks -# without starting the web server or scheduler. Its managed dependency -# environment is stored in the init container's ephemeral writable layer so -# validation cannot mutate the running deployment's cached environment. +# Mage workload image and inherits config/Secret environment variables, +# env or extraEnvs, Redis/PostgreSQL connection variables, project mounts, and +# enabled workspace or Kubernetes-executor configuration mounts. Other +# feature-specific environment variables and mounts are not automatically +# copied. It runs dependency setup followed by these checks without starting +# the web server or scheduler. Its managed dependency environment is stored in +# the init container's ephemeral writable layer so validation cannot mutate the +# running deployment's cached environment. dependencyValidation: enabled: false command: