ReplicaSet Primitive¶
The replicaset primitive wraps a Kubernetes ReplicaSet and provides health tracking, suspension, and a typed
mutation API for managing replicas, pod spec, and containers as part of the component lifecycle.
ReplicaSets are rarely managed directly by operators. Deployments own and manage ReplicaSets automatically. This primitive is intended for operators that explicitly own ReplicaSet objects, such as custom rollout controllers that manage sets of pods without Deployment's rollout semantics.
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 ReplicaSet Primitive¶
import "github.com/sourcehawk/operator-component-framework/pkg/primitives/replicaset"
base := &appsv1.ReplicaSet{
ObjectMeta: metav1.ObjectMeta{
Name: "worker",
Namespace: owner.Namespace,
},
Spec: appsv1.ReplicaSetSpec{
Selector: &metav1.LabelSelector{
MatchLabels: map[string]string{"app": "worker"},
},
Template: corev1.PodTemplateSpec{
ObjectMeta: metav1.ObjectMeta{
Labels: map[string]string{"app": "worker"},
},
Spec: corev1.PodSpec{
Containers: []corev1.Container{
{Name: "worker"},
},
},
},
},
}
resource, err := replicaset.NewBuilder(base).
WithMutation(MyFeatureMutation(owner.Spec.Version)).
Build()
Mutations¶
Each mutation is a named replicaset.Mutation that receives a *replicaset.Mutator and records edits through typed
editors.
func WorkerConfigMutation(version string) replicaset.Mutation {
return replicaset.Mutation{
Name: "worker-config",
Feature: feature.NewVersionGate(version, nil),
Mutate: func(m *replicaset.Mutator) error {
m.EnsureContainerEnvVar(corev1.EnvVar{Name: "WORKER_THREADS", Value: "4"})
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 ReplicaSet object |
| 2 | ReplicaSetSpec edits | Replicas, min ready seconds |
| 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) |
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.
ReplicaSetSpecEditor¶
Controls replicaset-level settings via m.EditReplicaSetSpec.
Available methods: SetReplicas, SetMinReadySeconds, Raw.
m.EditReplicaSetSpec(func(e *editors.ReplicaSetSpecEditor) error {
e.SetReplicas(3)
e.SetMinReadySeconds(10)
return nil
})
spec.selector is immutable
spec.selector cannot be changed after the ReplicaSet is created. Set it in the desired object passed to
NewBuilder; it is not exposed by ReplicaSetSpecEditor.
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("worker-sa")
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("worker"), func(e *editors.ContainerEditor) error {
e.EnsureEnvVar(corev1.EnvVar{Name: "LOG_LEVEL", Value: "info"})
e.SetResourceLimit(corev1.ResourceCPU, resource.MustParse("500m"))
return nil
})
ObjectMetaEditor¶
Modifies labels and annotations. Use m.EditObjectMetadata for the ReplicaSet itself or m.EditPodTemplateMetadata
for the pod template.
Available methods: EnsureLabel, RemoveLabel, EnsureAnnotation, RemoveAnnotation, Raw.
Convenience Methods¶
| Method | Equivalent to |
|---|---|
EnsureReplicas(n) |
EditReplicaSetSpec → 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¶
The replicaset.Mutator does not implement primitives.WorkloadMutator and therefore does not have a LiftMutation
adapter. Workload-kind-agnostic mutations target the Deployment, StatefulSet, and DaemonSet mutators. If you need to
share container or env-var mutations across those kinds and a ReplicaSet, write the shared logic as a plain function
that accepts *replicaset.Mutator and call it directly from a replicaset.Mutation.
See workload-kind-agnostic mutations for the cross-kind pattern.
Data Extraction¶
replicaset.ExtractInto declares that this ReplicaSet produces the value of a data cell, such as the number of pods
reporting ready. The function receives a value copy of the reconciled ReplicaSet after each sync cycle:
readyReplicas := concepts.NewData[int32]("worker-ready-replicas")
builder := replicaset.NewBuilder(base)
replicaset.ExtractInto(builder, readyReplicas, func(rs appsv1.ReplicaSet) (int32, error) {
return rs.Status.ReadyReplicas, nil
})
resource, err := builder.Build()
Resources registered later in the same component block on the cell with WithDataGuard(readyReplicas) or read it
opportunistically with WithOptionalData(readyReplicas). See Declared Data.
Suspension¶
When the component is suspended, the ReplicaSet 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 ReplicaSet. All of these conditions must be true:
- The replicaset controller has observed the current spec:
Status.ObservedGeneration >= Generation. Status.ReadyReplicasequals the desired replica count.- The scale-down is complete:
Status.Replicasis not more than the desired replica count.
A ReplicaSet does not roll out a new pod template, so the handlers have no rollout check. The scale-down check is
necessary because a pod that is not ready can wait for removal while Status.ReadyReplicas already equals the desired
count.
ConvergingStatus¶
DefaultConvergingStatusHandler reports Healthy when the ReplicaSet 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 scale-down 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 ReplicaSet 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 scale-down is not complete. |
Because the two handlers use the same rule, a ReplicaSet that does not converge before the grace period expires reports
Degraded or Down. Override the handlers with WithCustomConvergeStatus and WithCustomGraceStatus.
Full Example¶
func WorkerMutation(version string, replicas int32) replicaset.Mutation {
return replicaset.Mutation{
Name: "worker-sizing",
Feature: feature.NewVersionGate(version, nil),
Mutate: func(m *replicaset.Mutator) error {
m.EnsureReplicas(replicas)
m.EditContainers(selectors.ContainerNamed("worker"), func(e *editors.ContainerEditor) error {
e.EnsureEnvVar(corev1.EnvVar{Name: "WORKER_THREADS", Value: "4"})
e.SetResourceLimit(corev1.ResourceCPU, resource.MustParse("500m"))
e.SetResourceLimit(corev1.ResourceMemory, resource.MustParse("256Mi"))
return nil
})
m.EditPodSpec(func(e *editors.PodSpecEditor) error {
e.SetServiceAccountName("worker-sa")
return nil
})
return nil
},
}
}
Guidance¶
Prefer Deployments over direct ReplicaSet management. Deployments add rolling-update semantics and revision history. Use this primitive only when you are building a custom rollout controller or you have a specific reason to own ReplicaSet objects directly.
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.
Use selectors for precision. Targeting AllContainers() when you only mean to modify the primary container can
cause unexpected behavior if sidecar containers are present.