@@ -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 -}}
 
@@ -126,3 +126,74 @@ tests:
           path: kind
           value: MachineDeployment
           matchMany: true
+
+  # Regression guard for cozystack/cozystack#3231 — spec.replicas MUST reflect
+  # the nodeGroup's minReplicas, not a hardcoded 2. Two matched cases so a
+  # future refactor to a literal cannot silently regress both sides:
+  #   * minReplicas: 0 renders spec.replicas: 0 (the render-side OIDC test
+  #     path — no worker DataVolumes provisioned).
+  #   * minReplicas: 2 renders spec.replicas: 2 (the kubernetes-latest /
+  #     kubernetes-previous bats path — byte-identical to pre-PR behaviour).
+  - it: MachineDeployment.spec.replicas equals nodeGroup.minReplicas — zero 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:
+      - equal:
+          path: spec.replicas
+          value: 0
+        documentSelector:
+          path: kind
+          value: MachineDeployment
+          matchMany: true
+
+  - it: MachineDeployment.spec.replicas equals nodeGroup.minReplicas — nonzero 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:
+      - equal:
+          path: spec.replicas
+          value: 2
+        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": {`