Theory

Updated

October 30, 2026

Theory: workloadRef Lets a Rollout Adopt a Deployment

Migration is changing the controller that owns ReplicaSets without changing the pod spec. workloadRef points at an existing Deployment. StatefulSets often cannot follow this path.

Invariants

  1. Git (Argo) must stop managing the old Deployment’s replica field.
  2. Aborts during migration need a rehearsed rollback.
  3. Stateful identity (ordinals, PVCs) does not map to canary ReplicaSets cleanly.
Deployment  --workloadRef-->  Rollout takes over RS
Git desired: Rollout, not Deployment replicas

What can break

  • Both Deployment and Rollout controllers racing on the same RS.

How to read this chapter

workloadRef, conversion, canary migration, StatefulSet limits.