StatefulSet Primitive¶
The statefulset primitive wraps a Kubernetes StatefulSet and provides health tracking, suspension, volume claim
template management, and a typed mutation API for managing replicas, pod spec, and containers as part of the component
lifecycle.
Capabilities¶
| Lifecycle interface | Reported status values |
|---|---|
Alive |
Healthy, Creating, Updating, Scaling, Failing |
Graceful |
Healthy, Degraded, Down |
Suspendable |
PendingSuspension, Suspending, Suspended |
Guardable |
Blocked |
DataExtractable |
(side-effecting, no status) |
Building a StatefulSet Primitive¶
import "github.com/sourcehawk/operator-component-framework/pkg/primitives/statefulset"
base := &appsv1.StatefulSet{
ObjectMeta: metav1.ObjectMeta{
Name: "db",
Namespace: owner.Namespace,
},
Spec: appsv1.StatefulSetSpec{
ServiceName: "db-headless",
Selector: &metav1.LabelSelector{
MatchLabels: map[string]string{"app": "db"},
},
Template: corev1.PodTemplateSpec{
ObjectMeta: metav1.ObjectMeta{
Labels: map[string]string{"app": "db"},
},
Spec: corev1.PodSpec{
Containers: []corev1.Container{
{Name: "db", Image: "postgres:15"},
},
},
},
},
}
resource, err := statefulset.NewBuilder(base).
WithMutation(MyFeatureMutation(owner.Spec.Version)).
Build()
Mutations¶
Each mutation is a named statefulset.Mutation that receives a *statefulset.Mutator and records edits through typed
editors.
func StorageMutation(version string) statefulset.Mutation {
return statefulset.Mutation{
Name: "storage-backend",
Feature: feature.NewVersionGate(version, nil),
Mutate: func(m *statefulset.Mutator) error {
m.EditContainers(selectors.ContainerNamed("db"), func(e *editors.ContainerEditor) error {
e.EnsureEnvVar(corev1.EnvVar{Name: "PGDATA", Value: "/var/lib/postgresql/data"})
return nil
})
return nil
},
}
}
See the mutation system, boolean gating, and version gating.
Internal Mutation Ordering¶
Within each feature, edits run in this fixed category order:
| Step | Category | What it affects |
|---|---|---|
| 1 | Object metadata edits | Labels and annotations on the StatefulSet object |
| 2 | StatefulSetSpec edits | Replicas, service name, update strategy, etc. |
| 3 | Pod template metadata edits | Labels and annotations on the pod template |
| 4 | Pod spec edits | Volumes, tolerations, node selectors, service account, security context |
| 5 | Regular container presence | Adding or removing containers from spec.template.spec.containers |
| 6 | Regular container edits | Env vars, args, resources (snapshot taken after step 5) |
| 7 | Init container presence | Adding or removing containers from spec.template.spec.initContainers |
| 8 | Init container edits | Env vars, args, resources (snapshot taken after step 7) |
| 9 | Volume claim template operations | Adding or removing entries from spec.volumeClaimTemplates |
Container edits (steps 6 and 8) are evaluated against a snapshot taken after presence operations in the same feature.
Relevant Editors¶
For the generic editor and selector concepts, see mutation editors and container selectors.
StatefulSetSpecEditor¶
Controls statefulset-level settings via m.EditStatefulSetSpec.
Available methods: SetReplicas, SetServiceName, SetPodManagementPolicy, SetUpdateStrategy,
SetRevisionHistoryLimit, SetMinReadySeconds, SetPersistentVolumeClaimRetentionPolicy, Raw.
m.EditStatefulSetSpec(func(e *editors.StatefulSetSpecEditor) error {
e.SetReplicas(3)
e.SetServiceName("db-headless")
e.SetPodManagementPolicy(appsv1.ParallelPodManagement)
return nil
})
Use Raw() for fields the typed API does not cover:
m.EditStatefulSetSpec(func(e *editors.StatefulSetSpecEditor) error {
e.Raw().UpdateStrategy = appsv1.StatefulSetUpdateStrategy{
Type: appsv1.OnDeleteStatefulSetStrategyType,
}
return nil
})
PodSpecEditor¶
Manages pod-level configuration via m.EditPodSpec.
Available methods: SetServiceAccountName, EnsureVolume, RemoveVolume, EnsureToleration, RemoveTolerations,
EnsureNodeSelector, RemoveNodeSelector, EnsureImagePullSecret, RemoveImagePullSecret, SetPriorityClassName,
SetHostNetwork, SetHostPID, SetHostIPC, SetSecurityContext, Raw.
m.EditPodSpec(func(e *editors.PodSpecEditor) error {
e.SetServiceAccountName("db-sa")
e.EnsureVolume(corev1.Volume{
Name: "config",
VolumeSource: corev1.VolumeSource{
ConfigMap: &corev1.ConfigMapVolumeSource{
LocalObjectReference: corev1.LocalObjectReference{Name: "db-config"},
},
},
})
return nil
})
ContainerEditor¶
Modifies individual containers via m.EditContainers or m.EditInitContainers, combined with a
container selector.
Available methods: EnsureEnvVar, EnsureEnvVars, RemoveEnvVar, RemoveEnvVars, EnsureArg, EnsureArgs,
RemoveArg, RemoveArgs, SetResourceLimit, SetResourceRequest, SetResources, Raw.
m.EditContainers(selectors.ContainerNamed("db"), func(e *editors.ContainerEditor) error {
e.EnsureEnvVar(corev1.EnvVar{Name: "PGDATA", Value: "/var/lib/postgresql/data"})
e.SetResourceLimit(corev1.ResourceMemory, resource.MustParse("2Gi"))
return nil
})
ObjectMetaEditor¶
Modifies labels and annotations. Use m.EditObjectMetadata for the StatefulSet itself or m.EditPodTemplateMetadata
for the pod template.
Available methods: EnsureLabel, RemoveLabel, EnsureAnnotation, RemoveAnnotation, Raw.
m.EditObjectMetadata(func(e *editors.ObjectMetaEditor) error {
e.EnsureLabel("app.kubernetes.io/version", version)
return nil
})
m.EditPodTemplateMetadata(func(e *editors.ObjectMetaEditor) error {
e.EnsureAnnotation("prometheus.io/scrape", "true")
return nil
})
Convenience Methods¶
| Method | Equivalent to |
|---|---|
EnsureReplicas(n) |
EditStatefulSetSpec → SetReplicas(n) |
EnsureContainerEnvVar(ev) |
EditContainers(AllContainers(), ...) → EnsureEnvVar(ev) |
RemoveContainerEnvVar(name) |
EditContainers(AllContainers(), ...) → RemoveEnvVar(name) |
EnsureContainerArg(arg) |
EditContainers(AllContainers(), ...) → EnsureArg(arg) |
RemoveContainerArg(arg) |
EditContainers(AllContainers(), ...) → RemoveArg(arg) |
Workload-Kind-Agnostic Mutations¶
A mutation written against primitives.WorkloadMutator can be applied to a StatefulSet builder using
statefulset.LiftMutation. This lets one emitter function target StatefulSets, Deployments, and DaemonSets without
duplicating code.
See workload-kind-agnostic mutations for the full pattern.
Volume Claim Templates¶
EnsureVolumeClaimTemplate and RemoveVolumeClaimTemplate manage persistent storage templates:
m.EnsureVolumeClaimTemplate(corev1.PersistentVolumeClaim{
ObjectMeta: metav1.ObjectMeta{Name: "data"},
Spec: corev1.PersistentVolumeClaimSpec{
AccessModes: []corev1.PersistentVolumeAccessMode{corev1.ReadWriteOnce},
Resources: corev1.VolumeResourceRequirements{
Requests: corev1.ResourceList{
corev1.ResourceStorage: resource.MustParse("10Gi"),
},
},
},
})
VolumeClaimTemplates are immutable after creation
spec.volumeClaimTemplates cannot be changed once the StatefulSet exists in the cluster; the API server rejects
such updates. The mutator silently skips these operations on existing StatefulSets (identified by a non-empty
ResourceVersion). Plan your storage layout before the first creation.
Data Extraction¶
statefulset.ExtractInto declares that this StatefulSet produces the value of a data cell, such as the controller
revision the pods are currently running. The function receives a value copy of the reconciled StatefulSet after each
sync cycle:
currentRevision := concepts.NewData[string]("db-current-revision")
builder := statefulset.NewBuilder(base)
statefulset.ExtractInto(builder, currentRevision, func(sts appsv1.StatefulSet) (string, error) {
return sts.Status.CurrentRevision, nil
})
resource, err := builder.Build()
Resources registered later in the same component block on the cell with WithDataGuard(currentRevision) or read it
opportunistically with WithOptionalData(currentRevision). See Declared Data.
Suspension¶
When the component is suspended, the StatefulSet is scaled to zero replicas. The resource is not deleted.
DefaultSuspendMutationHandlercallsEnsureReplicas(0).DefaultSuspensionStatusHandlerreportsSuspendingwhileStatus.Replicas > 0, thenSuspended.DefaultDeleteOnSuspendHandlerreturnsfalse.
Override any handler via WithCustomSuspendMutation, WithCustomSuspendStatus, or WithCustomSuspendDeletionDecision
on the builder.
Status Handlers¶
The desired replica count is Spec.Replicas, or 1 when it is not set. Both default handlers use the same rule for a
healthy StatefulSet. All of these conditions must be true:
- The statefulset controller has observed the current spec:
Status.ObservedGeneration >= Generation. Status.ReadyReplicasequals the desired replica count.Status.Replicasis not more than the desired replica count, so a scale-down is complete. This applies to every update strategy, because the controller removes extra pods whatever the strategy is.- The rollout is complete for the update strategy of the StatefulSet. The table below gives the rule for each strategy.
| Update strategy | The rollout is complete when |
|---|---|
RollingUpdate (or no type) without a partition |
Status.UpdatedReplicas equals the desired count, and the revisions are equal. |
RollingUpdate with a partition more than zero |
Status.UpdatedReplicas is not less than the desired count minus the partition. |
OnDelete |
Always. |
The revisions are Status.CurrentRevision and Status.UpdateRevision. The statefulset controller sets
Status.CurrentRevision to Status.UpdateRevision only when a rolling update is complete. With a partition, the pods
with an ordinal less than Spec.Ordinals.Start plus the partition keep the current revision, so the revisions stay
different after the partitioned rollout is complete. With OnDelete, the controller does not replace pods. Pods move to
the update revision only when something outside the controller deletes them, so the handlers cannot wait for it. To
track an OnDelete rollout, use WithCustomConvergeStatus and WithCustomGraceStatus.
ConvergingStatus¶
DefaultConvergingStatusHandler reports Healthy when the StatefulSet is healthy. Otherwise it reports:
| Status | Condition |
|---|---|
Creating or Updating |
The controller has not observed the current spec. |
Creating, Updating, Scaling |
Status.ReadyReplicas differs from the desired replica count. |
Creating or Updating |
All desired replicas are ready, but the rollout is not complete. |
The status follows the operation of the apply. Created gives Creating. Updated gives Updating. None gives
Updating in the first and third rows, and Scaling in the second row.
GraceStatus¶
DefaultGraceStatusHandler categorizes health as:
| Status | Condition |
|---|---|
Healthy |
The StatefulSet is healthy. |
Down |
The desired replica count is more than zero and no replicas are ready. |
Degraded |
All other states: the spec is not observed, the ready count differs from the desired count, or the rollout is not complete. |
Because the two handlers use the same rule, a StatefulSet that does not converge before the grace period expires reports
Degraded or Down. Override the handlers with WithCustomConvergeStatus and WithCustomGraceStatus.
Full Example¶
func DatabaseMutation(version string) statefulset.Mutation {
return statefulset.Mutation{
Name: "database-storage",
Feature: feature.NewVersionGate(version, nil),
Mutate: func(m *statefulset.Mutator) error {
m.EditStatefulSetSpec(func(e *editors.StatefulSetSpecEditor) error {
e.SetReplicas(3)
e.SetPodManagementPolicy(appsv1.OrderedReadyPodManagement)
return nil
})
m.EnsureVolumeClaimTemplate(corev1.PersistentVolumeClaim{
ObjectMeta: metav1.ObjectMeta{Name: "data"},
Spec: corev1.PersistentVolumeClaimSpec{
AccessModes: []corev1.PersistentVolumeAccessMode{corev1.ReadWriteOnce},
Resources: corev1.VolumeResourceRequirements{
Requests: corev1.ResourceList{
corev1.ResourceStorage: resource.MustParse("50Gi"),
},
},
},
})
m.EditContainers(selectors.ContainerNamed("db"), func(e *editors.ContainerEditor) error {
e.Raw().VolumeMounts = append(e.Raw().VolumeMounts, corev1.VolumeMount{
Name: "data",
MountPath: "/var/lib/postgresql/data",
})
return nil
})
return nil
},
}
}
Guidance¶
Use a StatefulSet for stateful workloads requiring pod identity. StatefulSets provide stable network identities
(pod-0, pod-1, ...) and support VolumeClaimTemplates. For stateless workloads where pod identity does not matter, a
Deployment is simpler.
Feature: nil applies unconditionally. Omit Feature for mutations that should always run. Use
feature.NewVersionGate(version, constraints) for version-based gating and chain .When(bool) for runtime boolean
conditions.
Register mutations in dependency order. If mutation B relies on a container added by mutation A, register A first. Internal ordering within each mutation handles intra-mutation dependencies automatically.
Prefer EnsureContainer over direct slice manipulation. The mutator tracks presence operations so selectors in the
same mutation resolve correctly and reconciliation remains idempotent.
VolumeClaimTemplates are immutable. Plan your storage layout before the first creation. Changing the templates requires recreating the StatefulSet.