Kubernetes Job Spec Structure

Kubernetes Job Spec Structure is the schema and internal organization of the spec field on a batch/v1 Job object. It defines how a Job's desired behavior — how many Pods to run, how to run them, how to handle failures, and what template to use for each Pod — is expressed declaratively to the Kubernetes API server. Understanding the spec structure is a prerequisite to authoring correct, predictable batch workloads, since nearly every operational property of a Job (parallelism, retries, timeouts, indexing) is controlled through fields nested inside this single object.

At the top level, a Job manifest follows the standard Kubernetes resource shape: apiVersion, kind, metadata, and spec. The spec field is where Job-specific behavior is declared, and it in turn contains a nested template field describing the Pods the Job will create.

Top-Level Fields

apiVersion and kind

Jobs are defined under the batch/v1 API group, with kind: Job. Earlier Kubernetes versions used batch/v1beta1 for some batch resources, but stable Job support has long been part of batch/v1.

metadata

Standard object metadata: name, namespace, labels, and annotations. Labels on the Job's own metadata are distinct from labels applied to the Pod template, and are commonly used to group related Jobs (for example, all Jobs belonging to one CronJob) for querying with kubectl get jobs -l.

The spec Block

Completion and Concurrency Control

• completions (integer): total number of successful Pod completions required.
• parallelism (integer): maximum number of Pods running concurrently.
• completionMode (NonIndexed | Indexed): whether Pods receive a completion index.

Failure and Timeout Control

• backoffLimit (integer): number of retries before the Job is marked Failed.
• backoffLimitPerIndex (integer, Indexed Jobs only): per-index retry limit, allowing independent failure budgets for each shard.
• activeDeadlineSeconds (integer): total time budget for the Job before forced termination.
• podFailurePolicy (object): rules mapping Pod exit codes or conditions to actions (FailJob, Ignore, Count).

Lifecycle and Cleanup

• suspend (boolean): when true, the Job is created but no Pods are scheduled until it is set to false.
• ttlSecondsAfterFinished (integer): seconds after completion before the Job and its Pods are garbage collected.
• manualSelector (boolean): opts out of the default automatic Pod-selector generation, requiring the author to specify selector explicitly. This is rarely used outside of advanced controller integrations.

selector

An object of matchLabels and/or matchExpressions used internally to associate Pods with the Job. Kubernetes normally generates this automatically from a controller-uid label injected into the Pod template; manual selectors are an advanced, rarely needed override.

The Pod Template

template.metadata

Labels and annotations applied to every Pod the Job creates. Kubernetes injects a job-name label and a batch.kubernetes.io/job-name label automatically, which is how kubectl logs -l job-name=<name> is able to find the right Pods.

template.spec

This is a full PodSpec, identical in structure to the Pod template used by a Deployment, with a few conventions specific to Job workloads:

• restartPolicy must be either Never or OnFailure — Jobs cannot use Always, since that would prevent the Pod from ever being considered complete.
• containers and initContainers follow the standard container spec: image, command, args, env, resources, volumeMounts.
• activeDeadlineSeconds can also appear at the Pod level (distinct from the Job-level field) to bound an individual Pod's runtime.

Common template.spec Fields for Batch Workloads

• resources.requests / resources.limits: CPU and memory sizing, important for scheduler placement of batch Pods alongside long-running services.
• nodeSelector / affinity: constraining batch Pods to specific node pools, such as spot or preemptible instances.
• tolerations: allowing Pods to be scheduled onto tainted nodes reserved for batch workloads.
• volumes / volumeMounts: attaching shared storage for input/output data.

Full Structural Example

apiVersion: batch/v1
kind: Job
metadata:
  name: codartium-spec-example
  labels:
    app: codartium
    tier: batch
spec:
  completions: 4
  parallelism: 2
  completionMode: Indexed
  backoffLimit: 3
  backoffLimitPerIndex: 1
  activeDeadlineSeconds: 900
  ttlSecondsAfterFinished: 1800
  suspend: false
  podFailurePolicy:
    rules:
      - action: Ignore
        onPodConditions:
          - type: DisruptionTarget
      - action: FailJob
        onExitCodes:
          containerName: worker
          operator: In
          values: [1, 2]
  template:
    metadata:
      labels:
        app: codartium
        tier: batch
    spec:
      restartPolicy: Never
      containers:
        - name: worker
          image: codartium/worker:latest
          resources:
            requests:
              cpu: "250m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"
      tolerations:
        - key: "batch-only"
          operator: "Exists"
          effect: "NoSchedule"

kubectl apply -f job-spec-example.yaml
kubectl get job codartium-spec-example -o yaml
kubectl explain job.spec
kubectl explain job.spec.template.spec