✦ For everyone, free.

Practical knowledge for real and everyday life

Home

Kubernetes CronJob Spec Structure

Kubernetes CronJob Spec Structure defines how to schedule and manage recurring tasks with key components like schedule, job template, and concurrency policies.

Kubernetes CronJob Spec Structure is the schema and internal organization of the spec field on a batch/v1 CronJob object, defining how a recurring schedule, a nested Job template, and a set of scheduling-and-history policies are expressed together in a single declarative resource. Unlike a plain Job, whose spec directly describes the workload, a CronJob's spec is one layer removed: most of its fields govern when and how often Jobs are created, while the actual workload definition is nested one level deeper inside jobTemplate.

Understanding this two-layer structure — CronJob-level scheduling fields wrapping a Job-level spec — is what makes it possible to reason correctly about which settings affect the recurrence behavior versus which affect each individual run's execution.

Top-Level Fields

apiVersion and kind

CronJobs are defined under batch/v1 with kind: CronJob. Earlier Kubernetes releases used batch/v1beta1, which has since been removed in favor of the now-stable batch/v1 API.

metadata

Standard object metadata (name, namespace, labels, annotations). Labels here identify the CronJob itself and are distinct from labels applied to the Jobs and Pods it generates, which are set separately within jobTemplate.

The CronJob spec Block

Scheduling Fields

  • schedule (string): a five-field cron expression determining when new Jobs are created.
  • timeZone (string): the IANA time zone the schedule is evaluated in.
  • startingDeadlineSeconds (integer): how late a missed scheduled run may still be started before being skipped.

Concurrency and Lifecycle Fields

  • concurrencyPolicy (Allow | Forbid | Replace): how overlapping runs are handled.
  • suspend (boolean): when true, stops new Jobs from being created without affecting existing ones.

History Fields

  • successfulJobsHistoryLimit (integer, default 3): number of completed Jobs retained.
  • failedJobsHistoryLimit (integer, default 1): number of failed Jobs retained.

jobTemplate

jobTemplate is the nested field containing a full JobTemplateSpec — itself composed of metadata and spec, where spec is exactly the same batch/v1 Job spec structure used by a standalone Job (completions, parallelism, backoffLimit, activeDeadlineSeconds, ttlSecondsAfterFinished, template, and so on).

Nested Job Template Structure

jobTemplate.metadata

Labels and annotations applied to every Job the CronJob creates. Kubernetes injects a job-name-style naming convention combining the CronJob name and a timestamp-derived suffix, and adds an owner reference linking each generated Job back to the CronJob, which is what allows kubectl delete cronjob to cascade through to its Jobs by default.

jobTemplate.spec

Everything available on a standalone Job's spec is available here unmodified: completions, parallelism, completionMode, backoffLimit, backoffLimitPerIndex, podFailurePolicy, activeDeadlineSeconds, ttlSecondsAfterFinished, and the Pod template itself with its own metadata and spec.

Full Structural Example

apiVersion: batch/v1
kind: CronJob
metadata:
  name: codartium-cronjob-spec-example
  labels:
    app: codartium
spec:
  schedule: "*/15 * * * *"
  timeZone: "UTC"
  startingDeadlineSeconds: 120
  concurrencyPolicy: Forbid
  suspend: false
  successfulJobsHistoryLimit: 5
  failedJobsHistoryLimit: 3
  jobTemplate:
    metadata:
      labels:
        app: codartium
        tier: batch
    spec:
      backoffLimit: 2
      activeDeadlineSeconds: 300
      ttlSecondsAfterFinished: 3600
      template:
        metadata:
          labels:
            app: codartium
            tier: batch
        spec:
          restartPolicy: OnFailure
          containers:
            - name: poller
              image: codartium/poller:latest
              resources:
                requests:
                  cpu: "100m"
                  memory: "64Mi"
                limits:
                  cpu: "200m"
                  memory: "128Mi"

Inspecting the Spec

kubectl explain cronjob.spec
kubectl explain cronjob.spec.jobTemplate.spec
kubectl get cronjob codartium-cronjob-spec-example -o yaml

kubectl explain on the nested jobTemplate.spec path is a reliable way to confirm exactly which Job-level fields are valid at each version of the cluster's Kubernetes API, since the nested schema mirrors the standalone Job spec but is reachable only through this longer field path.

Related content