​

Prerequisites

​

Install Helm

brew install helm

​

Setup a Kubernetes Cluster

​

Local

• Kind
• Minikube

​

AWS EKS

​

Google Kubernetes Engine (GKE)

​

Deploy Mage using Helm

​

Add Helm repository

helm repo add mageai https://mage-ai.github.io/helm-charts

​

Install with default config

helm install my-mageai mageai/mageai

​

Get the default values

helm show values mageai/mageai > values.yaml

helm install --values values.yaml my-mageai mageai/mageai
# or
helm upgrade --install my-mageai mageai/mageai --values values.yaml

​

Customize deployment

​

Deployment topology

• replicaCount — Number of Mage replicas (default: 1). Increase for high availability or more concurrent requests and pipeline runs. When using multiple replicas, you must enable Redis (see Dependencies).
• standaloneScheduler — When true, splits Mage into separate web server and scheduler deployments so you can scale and schedule them independently. Use scheduler.replicaCount and webServer.replicaCount instead of replicaCount when enabled.

​

Dependencies

• PostgreSQL (postgresql.enabled) — Required for production: pipelines, triggers, and metadata. Enable and set auth.username, auth.password, and auth.database (or use an external database and configure Mage accordingly).
• Redis (redis.enabled) — Required when replicaCount > 1, for distributed locking and caching. You can use an external Redis by setting customRedisURL and leaving redis.enabled: false.

​

Container image

• image.repository, image.tag, image.pullPolicy — Control which Mage image is used (default repository: mageai/mageai).
• imagePullSecrets — Use for private registries or Mage Pro registry; the secret must exist in the target namespace.

​

Storage and volumes

1. extraVolumes / extraVolumeMounts (default) — The chart typically mounts a volume named mage-fs at /home/src. Point it to your project:
   • Local / hostPath: set extraVolumes to a hostPath with your Mage project path.
   • Cloud (EKS, GKE, AKS): provision a ReadWriteMany PersistentVolume (e.g. EFS, Filestore, Azure Files) and a PersistentVolumeClaim, then use that claim in extraVolumes / extraVolumeMounts.
2. persistence.enabled: true — Use the chart’s built-in PersistentVolume. Set persistence.storageClassName and persistence.size (e.g. 5Gi). For cloud filesystems (e.g. EFS), you can use persistence.csi if supported by the chart.

​

Example: PVC for project code (EKS / GKE / Azure)

extraVolumeMounts:
  - name: mage-fs
    mountPath: /home/src

extraVolumes:
  - name: mage-fs
    persistentVolumeClaim:
      claimName: your-pvc-name

​

Service and ingress

• service.type — Default is LoadBalancer; set to ClusterIP or NodePort if needed. service.port defaults to 6789.
• service.annotations — Use for cloud load balancers (e.g. AWS NLB, GCP).
• ingress — Set ingress.enabled: true and configure ingress.className, ingress.hosts, and ingress.tls for external access. For production, consider the Mage-Ingress chart.

​

Environment and configuration

• config — Key-value environment variables for the Mage container (e.g. USER_CODE_PATH: /home/src/default_repo).
• secrets — Chart-created secrets injected as env vars. Prefer a secret manager (e.g. Vault, AWS Secrets Manager) in production.
• existingSecret — Use an existing Secret for env vars; takes precedence over secrets if both are set.
• extraEnvs — Additional env vars, including valueFrom (e.g. downward API for metadata.namespace).

​

Resources and scheduling

• resources — Set CPU/memory limits and requests for the Mage container.
• nodeSelector, tolerations, affinity — Control pod placement.
• livenessProbe / readinessProbe — Default to /api/status on the http port; customize or replace with customLivenessProbe / customReadinessProbe.
• hpa — Horizontal Pod Autoscaler (commented out by default).

​

Quick reference: common overrides

​

Default workspace and K8s executor config

• workspaceConfig — Default workspace configuration (e.g. container_config, service_account_name, lifecycle_config). The chart creates a ConfigMap, mounts it on the control plane at /etc/mage/workspace-config.yaml, and sets WORKSPACE_DEFAULT_CONFIG_PATH. See Workspaces — Default config file.
• k8sExecutorConfig — Default K8s executor configuration (e.g. resource_limits, resource_requests, pod). The chart creates a ConfigMap, mounts it at /etc/mage/k8s-executor-config.yaml, and sets K8S_DEFAULT_CONFIG_PATH. See K8s executor — Default config file.

​

Further reading

• Mage Helm Chart source and values — full values reference in the chart repo
• Helm chart releases
• Mage Pro Workspaces
• Kubernetes Executor