CloudNativePG Job Management#

Overview#

CloudNativePG uses short-lived Kubernetes batch/v1 Jobs to execute every lifecycle operation that initializes PostgreSQL data directories before an instance Pod starts. Each Job runs the operator manager binary (/controller/manager) inside the PostgreSQL image and exits on completion. Instance Pods are only created after their Jobs finish and mark their PVCs as ready.

Job Types#

Six job roles are defined in pkg/specs/jobs.go:

Each role maps to a public factory function in pkg/specs/jobs.go:

• CreatePrimaryJobViaInitdb — builds initdb flags (encoding, locale, data checksums, WAL segment size, post-init SQL) and delegates to CreatePrimaryJob
• CreatePrimaryJobViaRecovery — issues instance restore
• CreatePrimaryJobViaRestoreSnapshot — issues instance restoresnapshot with backup-label/tablespacemap annotations from the VolumeSnapshot
• CreatePrimaryJobViaPgBaseBackup — issues instance pgbasebackup
• JoinReplicaInstance — issues instance join --parent-node <rw-service>
• RestoreReplicaInstance — issues instance restoresnapshot --immediate for replica bootstrap from a VolumeSnapshot

Job Pod Specification#

All six roles are assembled through the central CreatePrimaryJob function. The resulting batchv1.Job pod template deliberately mirrors the steady-state instance Pod structure to keep container behavior consistent:

• Init container (bootstrap-controller): runs the operator image with manager bootstrap /controller/manager to copy the operator binary into the shared volume before the main container starts 1. The identical container appears in instance Pods via createClusterPodSpec.
• Main container: named after the job role, runs the PostgreSQL image with the appropriate instance <subcommand> 2.
• RestartPolicy: Never 3 — failed Jobs leave their Pod in Failed state so logs are preserved for debugging.
• Volumes and mounts: createPostgresVolumes and CreatePostgresVolumeMounts are called from the same helpers as instance Pods .
• Scheduling: SchedulerName, Affinity, Tolerations, NodeSelector, TopologySpreadConstraints, PriorityClassName, and ServiceAccountName are carried from cluster.Spec .
• Security context: GetSecurityContext and GetPodSecurityContext are the same functions used by instance Pods — runAsNonRoot: true, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false, all capabilities dropped 6.
• AppArmor: propagated from cluster annotations if present 7.
• Subdomain: set to the cluster's "any" service when CreateAnyService is enabled 8.

For initdb jobs that create an application database, the APP_USERNAME env var is injected from the application secret to enforce that the secret exists before cluster initialization proceeds 9.

Resource Allocation#

Both the init container and the main container in Jobs set Resources directly from cluster.Spec.Resources — the same field used by the steady-state postgres container in instance Pods 10:

• Main container: Resources: cluster.Spec.Resources
• Init container (createBootstrapContainer): Resources: cluster.Spec.Resources

There is no separate resource field for Jobs. Bootstrap jobs run with exactly the same CPU/memory constraints as steady-state instance Pods. See CloudNativePG Bootstrap Job Resources for known limitations and workarounds (e.g., namespace-scoped LimitRange injection) when environments require explicit resource declarations on every pod.

Controller Flow#

Job creation is driven from internal/controller/cluster_create.go:

1. Primary bootstrap — createPrimaryInstance checks cluster initialization state, resolves the recovery source (backup or VolumeSnapshot), generates a node serial, creates PVCs, then calls buildPrimaryInstanceJob which dispatches to the appropriate factory based on cluster.Spec.Bootstrap.
2. Replica join — joinReplicaInstance calls JoinReplicaInstance; if a VolumeSnapshot backup is available for the replica, it calls RestoreReplicaInstance instead.
3. Missing bootstrap Job recovery — ensureInstancesAreCreated detects PVCs not yet marked ready and calls ensurePrimaryBootstrapJob to recreate a missing primary bootstrap Job (guards against optimistic-lock race conditions where a Job is lost between PVC creation and Job creation).

After building the Job, the controller:

• Sets the Cluster as the Job owner via ctrl.SetControllerReference 11
• Propagates inherited annotations and labels to both the Job and its pod template via inheritJobMetadata
• Adopts an already-existing Job (idempotency for stale-cache scenarios) via ensureJobAdoptable

Naming and Labels#

Job names follow the pattern <cluster-name>-<serial>-<role> (e.g., mycluster-1-initdb). Both the Job and its pod template share the same label set 12:

Key Source Files#