@@ -49,17 +49,16 @@ spec:
       resources: {}
       resourcesPreset: small
     replicas: 1
-  nodeGroups:
-    md0:
-      diskSize: 20Gi
-      gpus: []
-      instanceType: u1.micro
-      maxReplicas: 1
-      minReplicas: 0
-      resources: {}
-      roles:
-      - worker
-  storageClass: replicated
+  # nodeGroups intentionally omitted — this is a render-side test that
+  # only asserts on the KamajiControlPlane + the tenant-supplied issuer
+  # AuthenticationConfiguration Secret. With the schema default `{}`,
+  # the chart helper emits the default `md0` group with
+  # `minReplicas: 0` — exactly one MachineDeployment renders
+  # (API-surface completeness) but the chart no longer manages
+  # `spec.replicas`, so CAPI's defaulting webhook seeds it to 0
+  # from the autoscaler min-size annotation. Result: zero
+  # KubevirtMachines, zero worker DataVolumes, no DRBD churn between
+  # CI runs (see #3231).
   version: v1.35
   oidc:
     mode: CustomConfig
 
@@ -57,17 +57,19 @@ spec:
       resources: {}
       resourcesPreset: small
     replicas: 1
-  nodeGroups:
-    md0:
-      diskSize: 20Gi
-      gpus: []
-      instanceType: u1.micro
-      maxReplicas: 1
-      minReplicas: 0
-      resources: {}
-      roles:
-      - worker
-  storageClass: replicated
+  # nodeGroups intentionally omitted — this is a render-side test that
+  # only asserts on the KamajiControlPlane + the cozy-realm Keycloak
+  # objects. With the schema default `{}`, the chart helper emits the
+  # default `md0` group with `minReplicas: 0` — exactly one
+  # MachineDeployment renders (API-surface completeness) but the chart
+  # no longer manages `spec.replicas`, so CAPI's defaulting webhook
+  # seeds it to 0 from the autoscaler min-size annotation. Result:
+  # zero KubevirtMachines, zero worker DataVolumes, no DRBD churn
+  # overlapping `kubernetes-previous` (see #3231). Keeping an
+  # explicit nodeGroup here would previously provision two 20 GiB
+  # DRBD DataVolumes per `kubectl apply` because the chart hardcoded
+  # `spec.replicas: 2`; the paired chart edit in this PR removes
+  # that hardcoding.
   version: v1.35
   oidc:
     mode: System
 
@@ -124,6 +124,16 @@ re-add a baked-in default md0 on top of the user's groups, and because
 Kubernetes strips null values the default could never be removed. With the
 default applied only when the map is empty, users can freely choose their own
 node groups (and omit md0).
+
+The default carries `minReplicas: 0`, which now propagates through to
+`MachineDeployment.spec.replicas: 0` (see the templates/cluster.yaml comment
+next to that field). Consequence: an empty-`nodeGroups` install provisions
+NO workers until either the cluster-autoscaler responds to an unschedulable
+Pod or an operator explicitly scales the group up. If the operator plans to
+enable the ingress-nginx addon, either supply an explicit nodeGroup with
+`roles: [ingress-nginx]` and `minReplicas >= 1`, or accept that the
+autoscaler will bring the default md0 up in response to the ingress-nginx
+controller Pods becoming Pending on install.
 */}}
 {{- define "kubernetes.nodeGroups" -}}
 {{- if .Values.nodeGroups -}}
 
@@ -743,7 +743,29 @@ metadata:
     {{- end }}
 spec:
   clusterName: {{ $.Release.Name }}
-  replicas: 2
+  # `spec.replicas` is intentionally omitted so the field is owned by
+  # the cluster-autoscaler alone. Two independent CAPI mechanisms —
+  # not Server-Side-Apply field managers — carry the guarantee:
+  #   1. Create: the MachineDeployment defaulting webhook seeds
+  #      `spec.replicas` from the `cluster-api-autoscaler-node-group-
+  #      min-size` annotation (see
+  #      https://cluster-api.sigs.k8s.io/tasks/automated-machine-management/autoscaling).
+  #   2. Update: `calculateMachineDeploymentReplicas` preserves the
+  #      existing live value (`oldMD.Spec.Replicas`) whenever the
+  #      incoming spec has `replicas: nil`, clamping into
+  #      `[min, max]` if it drifts outside — so a cluster the
+  #      autoscaler holds above min-size is not drained by a
+  #      `helm upgrade` that would otherwise re-render this field.
+  # Flux helm-controller applies this chart through the Helm SDK
+  # three-way merge (not SSA), so field-manager ownership is not the
+  # mechanism at play. The chart guarantee reduces to "leave the
+  # field out of the rendered manifest and let CAPI's update-time
+  # defaulting keep the live value stable". Emitting a chart-managed
+  # `replicas: N` here (as this chart did before
+  # cozystack/cozystack#3231) drains workers on every `helm upgrade`
+  # action until the autoscaler notices unschedulable Pods and
+  # scales back up — a real disruption window on every routine
+  # platform bump.
   strategy:
     rollingUpdate:
       maxSurge: {{ $group.maxReplicas }}
 
@@ -126,3 +126,121 @@ tests:
           path: kind
           value: MachineDeployment
           matchMany: true
+
+  # Regression guard for cozystack/cozystack#3231. The chart intentionally
+  # OMITS `MachineDeployment.spec.replicas` so the cluster-autoscaler owns
+  # the field alone. Two independent CAPI mechanisms carry the guarantee:
+  # the defaulting webhook seeds `spec.replicas` from the
+  # `cluster-api-autoscaler-node-group-min-size` annotation on Create, and
+  # `calculateMachineDeploymentReplicas` preserves the existing live
+  # value on Update when the incoming spec has `replicas: nil` — so a
+  # `helm upgrade` re-rendering this template does not drain workers the
+  # autoscaler has scaled above min-size. Flux helm-controller applies
+  # this chart through the Helm SDK three-way merge (not SSA), so field-
+  # manager ownership is not the mechanism at play; the guarantee is
+  # purely "field absent from the rendered manifest → CAPI's update-time
+  # defaulting preserves the live value". Two matched cases so a future
+  # refactor cannot silently re-hardcode the field nor break the
+  # annotation-driven min/max wiring:
+  #   * minReplicas: 0 (the render-side OIDC bats path — MachineDeployment
+  #     emitted with the min-size annotation "0", no chart-owned replicas
+  #     field, no worker DataVolumes provisioned until scale-out).
+  #   * minReplicas: 2 (the kubernetes-latest / kubernetes-previous bats
+  #     path — MachineDeployment emitted with the min-size annotation "2",
+  #     no chart-owned replicas field, defaulting webhook fills it to 2 on
+  #     Create).
+  - it: MachineDeployment omits chart-managed spec.replicas — zero-minReplicas case
+    release:
+      name: test-k8s
+      namespace: tenant-test
+    set:
+      _namespace:
+        etcd: etcd
+        ingress: nginx
+        host: example.com
+      _cluster:
+        cluster-domain: cozy.local
+      nodeGroups:
+        worker0:
+          minReplicas: 0
+          maxReplicas: 10
+          instanceType: "u1.medium"
+          diskSize: 20Gi
+          storageClass: ""
+          roles:
+          - worker
+          resources: {}
+          gpus: []
+          kubelet: {}
+    asserts:
+      # spec.replicas must not appear in the rendered manifest — CAPI's
+      # defaulting webhook will seed it from the annotation on Create.
+      - notExists:
+          path: spec.replicas
+        documentSelector:
+          path: kind
+          value: MachineDeployment
+          matchMany: true
+      # Autoscaler annotation wiring stays intact.
+      - equal:
+          path: metadata.annotations["cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size"]
+          value: "0"
+        documentSelector:
+          path: kind
+          value: MachineDeployment
+          matchMany: true
+      - equal:
+          path: metadata.annotations["cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size"]
+          value: "10"
+        documentSelector:
+          path: kind
+          value: MachineDeployment
+          matchMany: true
+
+  - it: MachineDeployment omits chart-managed spec.replicas — nonzero-minReplicas case
+    release:
+      name: test-k8s
+      namespace: tenant-test
+    set:
+      _namespace:
+        etcd: etcd
+        ingress: nginx
+        host: example.com
+      _cluster:
+        cluster-domain: cozy.local
+      nodeGroups:
+        worker0:
+          minReplicas: 2
+          maxReplicas: 10
+          instanceType: "u1.medium"
+          diskSize: 20Gi
+          storageClass: ""
+          roles:
+          - worker
+          resources: {}
+          gpus: []
+          kubelet: {}
+    asserts:
+      - notExists:
+          path: spec.replicas
+        documentSelector:
+          path: kind
+          value: MachineDeployment
+          matchMany: true
+      - equal:
+          path: metadata.annotations["cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size"]
+          value: "2"
+        documentSelector:
+          path: kind
+          value: MachineDeployment
+          matchMany: true
+      # Symmetric with the zero-minReplicas case above — both annotations
+      # must land, because CAPI's calculateMachineDeploymentReplicas
+      # defaults to 1 (not to minSize) if either annotation is missing.
+      - equal:
+          path: metadata.annotations["cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size"]
+          value: "10"
+        documentSelector:
+          path: kind
+          value: MachineDeployment
+          matchMany: true
@@ -17,7 +17,7 @@
       }
     },
     "nodeGroups": {
-      "description": "Worker nodes configuration map. When left empty, a single default node group `md0` (one `ingress-nginx` worker) is provisioned. Provide your own groups to take full control — they are not merged with the default, so you may name and omit groups freely.",
+      "description": "Worker nodes configuration map. When left empty, a default node group `md0` is emitted with `minReplicas: 0` and `roles: [ingress-nginx]` — the MachineDeployment renders but provisions no workers until an unschedulable Pod triggers the cluster-autoscaler (or an operator scales the group manually). Enabling `addons.ingressNginx.enabled: true` on a CR with default `nodeGroups: {}` therefore requires either supplying a nodeGroup with `roles: [ingress-nginx]` and `minReplicas \u003e= 1`, or waiting for the autoscaler to bring up the default md0 in response to the ingress-nginx controller Pods becoming Pending. Provide your own groups to take full control — they are not merged with the default, so you may name and omit groups freely.",
       "type": "object",
       "default": {},
       "additionalProperties": {
 
@@ -89,7 +89,7 @@ storageClass: replicated
 ## @field {[]GPU} gpus - List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM).
 ## @field {Kubelet} [kubelet] - Kubelet resource reservations for this node group.
 
-## @param {map[string]NodeGroup} nodeGroups - Worker nodes configuration map. When left empty, a single default node group `md0` (one `ingress-nginx` worker) is provisioned. Provide your own groups to take full control — they are not merged with the default, so you may name and omit groups freely.
+## @param {map[string]NodeGroup} nodeGroups - Worker nodes configuration map. When left empty, a default node group `md0` is emitted with `minReplicas: 0` and `roles: [ingress-nginx]` — the MachineDeployment renders but provisions no workers until an unschedulable Pod triggers the cluster-autoscaler (or an operator scales the group manually). Enabling `addons.ingressNginx.enabled: true` on a CR with default `nodeGroups: {}` therefore requires either supplying a nodeGroup with `roles: [ingress-nginx]` and `minReplicas >= 1`, or waiting for the autoscaler to bring up the default md0 in response to the ingress-nginx controller Pods becoming Pending. Provide your own groups to take full control — they are not merged with the default, so you may name and omit groups freely.
 nodeGroups: {}
 
 ##
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@`
`17`	`17`	`}`
`18`	`18`	`},`
`19`	`19`	`"nodeGroups": {`
`20`		- "description": "Worker nodes configuration map. When left empty, a single default node group `md0` (one `ingress-nginx` worker) is provisioned. Provide your own groups to take full control — they are not merged with the default, so you may name and omit groups freely.",
	`20`	+ "description": "Worker nodes configuration map. When left empty, a default node group `md0` is emitted with `minReplicas: 0` and `roles: [ingress-nginx]` — the MachineDeployment renders but provisions no workers until an unschedulable Pod triggers the cluster-autoscaler (or an operator scales the group manually). Enabling `addons.ingressNginx.enabled: true` on a CR with default `nodeGroups: {}` therefore requires either supplying a nodeGroup with `roles: [ingress-nginx]` and `minReplicas \u003e= 1`, or waiting for the autoscaler to bring up the default md0 in response to the ingress-nginx controller Pods becoming Pending. Provide your own groups to take full control — they are not merged with the default, so you may name and omit groups freely.",
`21`	`21`	`"type": "object",`
`22`	`22`	`"default": {},`
`23`	`23`	`"additionalProperties": {`