You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 946085b
Browse filesBrowse the repository at this point in the historyBrowse files
authored
feat: add label selector to the Cluster scale subresource (#8996)
The `Cluster` scale subresource exposed `spec.instances` and
`status.instances` but no selector. Standard Kubernetes tooling expects
the scale subresource to publish a label selector identifying the pods
it counts; without one, autoscalers cannot map a `Cluster` to its
instance pods.
Populate a `status.selector` field and wire it into the scale
subresource:
- Add the `status.selector` field, set it from `updateResourceStatus`
via the new `Cluster.GetInstancesSelector()`, which returns the
canonical serialised selector (`cluster=<name>,role=instance`) built
with `labels.SelectorFromSet`.
- Add `selectorpath=.status.selector` to the
`+kubebuilder:subresource:scale` marker and regenerate the CRD and API
docs.
This makes a `Cluster` a valid `targetRef` for the Vertical Pod
Autoscaler (`VPA`), which can now observe the instance pods and emit
CPU/memory recommendations, and lets a `HorizontalPodAutoscaler` (`HPA`)
scale `spec.instances`.
Document recommended `VPA` usage (recommendation-only `updateMode: Off`,
with a warning against `Auto`/`Recreate`/`Initial` to avoid ping-pong
restarts against the operator's drift reconciliation) and `HPA` caveats
for a stateful database. Add a unit test that verifies the selector
format and that it matches the labels applied to every instance pod.
Closes#2574
Signed-off-by: Sebastien Villanueva <[email protected]>
Signed-off-by: Sebastien Villanueva <[email protected]>
Signed-off-by: Armando Ruocco <[email protected]>
Signed-off-by: Gabriele Bartolini <[email protected]>
Signed-off-by: Marco Nenciarini <[email protected]>
Co-authored-by: Armando Ruocco <[email protected]>
Co-authored-by: Gabriele Bartolini <[email protected]>
Co-authored-by: Marco Nenciarini <[email protected]>
Copy file name to clipboardExpand all lines: docs/src/cloudnative-pg.v1.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -656,6 +656,7 @@ _Appears in:_
656
656
| --- | --- | --- | --- | --- |
657
657
|`instances`_integer_| The total number of PVC Groups detected in the cluster. It may differ from the number of existing instance pods. ||||
658
658
|`readyInstances`_integer_| The total number of ready instances in the cluster. It is equal to the number of ready instance pods. ||||
659
+
|`selector`_string_| Selector is the serialized form of the label selector that identifies<br />the pods managed by this cluster. Populated by the operator and exposed<br />through the scale sub-resource so an autoscaler (such as HPA or VPA)<br />can discover the managed instance pods. ||||
659
660
|`instancesStatus`_object (keys:[PodStatus](#podstatus), values:string array)_| InstancesStatus indicates in which status the instances are ||||
660
661
|`instancesReportedState`_object (keys:[PodName](#podname), values:[InstanceReportedState](#instancereportedstate))_| The reported state of the instances during the last reconciliation loop ||||
661
662
|`managedRolesStatus`_[ManagedRoles](#managedroles)_| ManagedRolesStatus reports the state of the managed roles in the cluster ||||
Copy file name to clipboardExpand all lines: docs/src/resource_management.md
+73-1Lines changed: 73 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -115,4 +115,76 @@ section in the PostgreSQL documentation.
115
115
For more details on resource management, please refer to the
116
116
["Managing Compute Resources for Containers"](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
117
117
page from the Kubernetes documentation.
118
-
:::
118
+
:::
119
+
120
+
## Integration with the Vertical Pod Autoscaler (VPA)
121
+
122
+
The `Cluster` CRD exposes the `scale` subresource together with the label
123
+
selector for its instance pods. This makes a `Cluster` a valid `targetRef` for the
124
+
[Vertical Pod Autoscaler](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler) <!-- wokeignore:rule=master -->
125
+
(VPA), so VPA can observe the instance pods and emit CPU and memory
126
+
recommendations for them.
127
+
128
+
We recommend running VPA in **recommendation-only** mode
129
+
(`updatePolicy.updateMode: Off`). In this mode VPA only reports its
130
+
recommendations, which an operator can then apply to `spec.resources` of the
131
+
`Cluster`through a normal manifest update; CloudNativePG performs the rolling
132
+
update of the instances using its usual switchover-aware procedure. VPA
133
+
produces a recommendation per container: use the one for the `postgres`
134
+
container, since that is what `spec.resources` configures.
135
+
136
+
Example targeting a `Cluster`:
137
+
138
+
```yaml
139
+
apiVersion: autoscaling.k8s.io/v1
140
+
kind: VerticalPodAutoscaler
141
+
metadata:
142
+
name: cluster-example-vpa
143
+
spec:
144
+
targetRef:
145
+
apiVersion: postgresql.cnpg.io/v1
146
+
kind: Cluster
147
+
name: cluster-example
148
+
updatePolicy:
149
+
updateMode: "Off"
150
+
```
151
+
152
+
:::warning
153
+
Do not use `updateMode: Auto`, `Recreate`, or `Initial` against a
154
+
CloudNativePG-managed `Cluster`. The operator owns the pod specification and
155
+
treats `spec.resources` of the `Cluster` as the source of truth: it does not
156
+
adopt the resources VPA writes onto a running pod, so the live pod and the
157
+
declared `spec.resources` silently diverge. Any tuning you sized against the
158
+
declared resources (for example a `shared_buffers` value the operator
159
+
validated against the memory request) no longer matches the pod's actual
160
+
limits. VPA also evicts pods through the Kubernetes eviction API, bypassing
161
+
the operator's switchover-aware sequencing; the default primary
162
+
`PodDisruptionBudget`then blocks eviction of the primary, so VPA stalls
163
+
instead of completing. Apply the VPA recommendations to the `Cluster` manifest
164
+
manually instead.
165
+
:::
166
+
167
+
## Integration with the Horizontal Pod Autoscaler (HPA)
168
+
169
+
The `scale` subresource also exposes `spec.instances`, so a
170
+
[Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
171
+
(HPA) can technically change the number of instances in a `Cluster`.
172
+
In practice this is **not recommended** for a PostgreSQL cluster, for several
173
+
reasons.
174
+
175
+
Scaling a `Cluster` only adds or removes standby replicas; it never relieves
176
+
write load on the primary. The selector exposed through the scale subresource
177
+
matches the primary and all replicas, which have opposite workload profiles
178
+
(write-heavy primary, read-only replicas), so the per-pod average that HPA
179
+
computes from a CPU or memory metric is not a meaningful signal for any of
180
+
them. Adding a replica only dilutes that average further without addressing a
181
+
hot primary.
182
+
183
+
HPA is also unaware of CloudNativePG's own constraints on `spec.instances`. If
184
+
you configure synchronous replicas, a scale-down below `maxSyncReplicas + 1`
185
+
instances is rejected by the validating webhook, and HPA keeps retrying a
186
+
value it cannot satisfy.
187
+
If you nonetheless drive `spec.instances` from an HPA, base it on a custom
188
+
metric that actually reflects read replica load, and set `minReplicas` above
189
+
the synchronous-replica floor. Review the impact on replication and quorum
0 commit comments