If your Mage app is deployed in a Kubernetes cluster, you can configure the Kubernetes Executor (executor_type: k8s) to run each block in its own Kubernetes pod. Defaults in Mage Pro:
  • Namespace: default
  • Job name format: mage-data-prep-block-{block_run_id}
You can override these defaults at the block level, project level, or with a full Kubernetes job template.

​
Basic Setup

To configure a pipeline block to use Kubernetes executor, you simply just need to update the executor_type of the block to k8s in pipeline’s metadata.yaml: 
blocks:
- uuid: example_data_loader
  type: data_loader
  upstream_blocks: []
  downstream_blocks: []
  executor_type: k8s
  ...
By default, Mage uses default as the Kubernetes namespace. You can customize the namespace by setting the KUBE_NAMESPACE environment variable. 
export KUBE_NAMESPACE=my-namespace

​
Configuration Methods

You can configure Kubernetes Executor in three ways:

​
1. Block-Level Configuration

Add executor_config to a block in metadata.yaml: 
blocks:
- uuid: example_data_loader
  type: data_loader
  executor_type: k8s
  executor_config:
    namespace: default
    resource_limits:
      cpu: 1000m
      memory: 2048Mi
    resource_requests:
      cpu: 500m
      memory: 1024Mi
✅ Use when: You only want to:
  • Run certain blocks in the Kubernetes executor
  • Override the k8s executor config for specific blocks

​
2. Project-Level Configuration (applies to all k8s executor blocks)

Set k8s_executor_config in the project’s metadata.yaml: 
k8s_executor_config:
  job_name_prefix: data-prep
  namespace: default
  resource_limits:
    cpu: 1000m
    memory: 2048Mi
  resource_requests:
    cpu: 500m
    memory: 1024Mi
  service_account_name: default
  • The Kubernetes job name is in this format: mage-{job_name_prefix}-block-{block_run_id}. The default job_name_prefix is data-prep. You can customize it in the k8s_executor_config. You can interpolate the trigger name in the job_name_prefix field with the format {trigger_name}.
  • GPU Support: 
    k8s_executor_config:
  resource_limits:
    nvidia.com/gpu: 1  # request 1 GPU
    Make sure GPU device plugins are installed.
  • Custom container & job spec: 
    k8s_executor_config:
  container_config:
    image: mageai/mageai:0.9.7
    env:
    - name: USER_CODE_PATH
      value: /home/src/k8s_project
  job:
    active_deadline_seconds: 120
    backoff_limit: 3
    ttl_seconds_after_finished: 86400
✅ Use when: You want consistent settings for all blocks using the Kubernetes Executor in the project.

​
3. Full Kubernetes Job Template (maximum control)

Set the K8S_CONFIG_FILE environment variable to the path of a YAML configuration file. Example template: 
metadata:
  annotations:
    application: "mage"
    component: "executor"
  labels:
    application: "mage"
    type: "spark"
  namespace: "default"

pod:
  service_account_name: ""
  image_pull_secrets: "secret"
  volumes:
  - name: data-pvc
    persistent_volume_claim:
      claim_name: pvc-name

container:
  name: "mage-data"
  image: "mageai/mageai:latest"
  image_pull_policy: "IfNotPresent"
  env:
    - name: "KUBE_NAMESPACE"
      value: "default"
    - name: "secret_key"
      value: "somesecret"
  resources:
    limits:
      cpu: "1"
      memory: "1Gi"
    requests:
      cpu: "0.1"
      memory: "0.5Gi"
  volume_mounts:
    - mount_path: "/tmp/data"
      name: "data-pvc"
✅ Use when: You need full control over pod specs, annotations, volume mounts, and other Kubernetes settings.

​
Multi-Container Pods

If your Mage deployment runs in a multi-container pod, set the MAGE_CONTAINER_NAME environment variable to specify which container runs Mage: 
env:
  - name: MAGE_CONTAINER_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
If not set, Mage defaults to the first container in the pod.

​
Environment Variables Reference

VariablePurposeDefault
KUBE_NAMESPACENamespace for job executiondefault
K8S_CONFIG_FILEPath to full Kubernetes job config file—
MAGE_CONTAINER_NAMEContainer to run Mage in multi-container pods—