Customizing Base Job Templates

This guide provides comprehensive examples for customizing the Kubernetes base job template. These examples demonstrate common configuration patterns for environment variables, secrets, resource limits, and image pull secrets.

Understanding the Base Job Template Structure

The base job template uses a two-part structure:

variables: Define configurable parameters with defaults and descriptions
job_configuration: Reference variables using {{ variable_name }} syntax to apply them to the Kubernetes job manifest

Variables defined in the variables section must be explicitly referenced in job_configuration using {{ variable_name }} syntax to take effect. If you customize the template and remove a variable reference from job_configuration, that variable’s value will not be passed to the worker, even if it’s defined in variables.

Accessing the Base Job Template

You can customize the base job template in two ways:

Through the UI: Navigate to your work pool → Advanced tab → Edit the JSON representation
Through the CLI: Get the default template to use as a starting point:

prefect work-pool get-default-base-job-template --type kubernetes

Common Configuration Patterns

Environment Variables

Configure environment variables to pass configuration to your flow runs:

{
  "variables": {
    "env": {
      "title": "Environment Variables",
      "description": "Environment variables to set in the container",
      "default": {},
      "type": "object",
      "additionalProperties": {"type": "string"}
    }
  },
  "job_configuration": {
    "job_manifest": {
      "spec": {
        "template": {
          "spec": {
            "containers": [
              {
                "name": "prefect-job",
                "env": "{{ env }}"
              }
            ]
          }
        }
      }
    }
  }
}

Secret References

Reference Kubernetes secrets to inject sensitive data:

{
  "variables": {
    "secret_name": {
      "title": "Secret Name",
      "description": "Name of the Kubernetes secret containing credentials",
      "default": null,
      "type": "string"
    }
  },
  "job_configuration": {
    "job_manifest": {
      "spec": {
        "template": {
          "spec": {
            "containers": [
              {
                "name": "prefect-job",
                "envFrom": [
                  {
                    "secretRef": {
                      "name": "{{ secret_name }}"
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

Image Pull Secrets

Configure authentication for private container registries:

{
  "variables": {
    "image_pull_secrets": {
      "title": "Image Pull Secrets",
      "description": "Names of Kubernetes secrets for pulling images from private registries",
      "default": [],
      "type": "array",
      "items": {"type": "string"}
    }
  },
  "job_configuration": {
    "job_manifest": {
      "spec": {
        "template": {
          "spec": {
            "imagePullSecrets": "{{ image_pull_secrets }}"
          }
        }
      }
    }
  }
}

Resource Limits and Requests

Set CPU and memory resource constraints:

{
  "variables": {
    "cpu_request": {
      "title": "CPU Request",
      "description": "CPU allocation to request for this pod",
      "default": "100m",
      "type": "string"
    },
    "cpu_limit": {
      "title": "CPU Limit",
      "description": "Maximum CPU allocation for this pod",
      "default": "1000m",
      "type": "string"
    },
    "memory_request": {
      "title": "Memory Request",
      "description": "Memory allocation to request for this pod",
      "default": "256Mi",
      "type": "string"
    },
    "memory_limit": {
      "title": "Memory Limit",
      "description": "Maximum memory allocation for this pod",
      "default": "1Gi",
      "type": "string"
    }
  },
  "job_configuration": {
    "job_manifest": {
      "spec": {
        "template": {
          "spec": {
            "containers": [
              {
                "name": "prefect-job",
                "resources": {
                  "requests": {
                    "cpu": "{{ cpu_request }}",
                    "memory": "{{ memory_request }}"
                  },
                  "limits": {
                    "cpu": "{{ cpu_limit }}",
                    "memory": "{{ memory_limit }}"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

Combining Multiple Configurations

These examples show individual configurations. In practice, you’ll combine multiple configurations in a single base job template. Remember that any modifications replace the entire default configuration, so include all necessary fields when customizing.

When combining configurations, merge the variables and job_configuration sections. For example, to combine environment variables with resource limits:

{
  "variables": {
    "env": {
      "title": "Environment Variables",
      "description": "Environment variables to set in the container",
      "default": {},
      "type": "object",
      "additionalProperties": {"type": "string"}
    },
    "cpu_request": {
      "title": "CPU Request",
      "description": "CPU allocation to request for this pod",
      "default": "100m",
      "type": "string"
    },
    "memory_request": {
      "title": "Memory Request",
      "description": "Memory allocation to request for this pod",
      "default": "256Mi",
      "type": "string"
    }
  },
  "job_configuration": {
    "job_manifest": {
      "spec": {
        "template": {
          "spec": {
            "containers": [
              {
                "name": "prefect-job",
                "env": "{{ env }}",
                "resources": {
                  "requests": {
                    "cpu": "{{ cpu_request }}",
                    "memory": "{{ memory_request }}"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

Workflows

Deployments

Automations

Workflow Infrastructure

Platform

Extensibility

Customizing Base Job Templates

Understanding the Base Job Template Structure

Accessing the Base Job Template

Common Configuration Patterns

Environment Variables

Secret References

Image Pull Secrets

Resource Limits and Requests

Combining Multiple Configurations

Next Steps

​Understanding the Base Job Template Structure

​Accessing the Base Job Template

​Common Configuration Patterns

​Environment Variables

​Secret References

​Image Pull Secrets

​Resource Limits and Requests

​Combining Multiple Configurations

​Next Steps

Understanding the Base Job Template Structure

Accessing the Base Job Template

Common Configuration Patterns

Environment Variables

Secret References

Image Pull Secrets

Resource Limits and Requests

Combining Multiple Configurations

Next Steps