Skip to content

Commit 946085b

Browse files
sebv004armrugbartolinimnencia
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]>
1 parent 1e7a2da commit 946085b

9 files changed

Lines changed: 154 additions & 3 deletions

‎.wordlist-en-custom.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,7 @@ GoogleCredentials
203203
Grafana
204204
GrantUsageSpecType
205205
HH
206+
HPA
206207
HashiCorp
207208
HistoryTags
208209
Homebrew
@@ -564,6 +565,7 @@ VLDBs
564565
VM
565566
VMs
566567
VOLNAME
568+
VPA
567569
ValidationError
568570
VirtualBox
569571
VolumeSnapshot
@@ -636,6 +638,7 @@ authn
636638
authz
637639
autocompletion
638640
autoscaler
641+
autoscalers
639642
autovacuum
640643
availableArchitectures
641644
availablearchitecture
@@ -957,6 +960,7 @@ historyTags
957960
hostPort
958961
hostname
959962
hostssl
963+
hpa
960964
href
961965
html
962966
http
@@ -1614,6 +1618,7 @@ volumeSnapshot
16141618
volumeSnapshots
16151619
volumesnapshot
16161620
volumesnapshotconfiguration
1621+
vpa
16171622
waitForArchive
16181623
wal
16191624
walCapabilities

‎api/v1/cluster_funcs.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ import (
3737
corev1 "k8s.io/api/core/v1"
3838
"k8s.io/apimachinery/pkg/api/resource"
3939
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
40+
"k8s.io/apimachinery/pkg/labels"
4041
"k8s.io/apimachinery/pkg/runtime/schema"
4142
"k8s.io/apimachinery/pkg/types"
4243

@@ -715,6 +716,17 @@ func (cluster *Cluster) GetServiceReadWriteName() string {
715716
return fmt.Sprintf("%v%v", cluster.Name, ServiceReadWriteSuffix)
716717
}
717718

719+
// GetInstancesSelector returns the serialized label selector that matches all
720+
// the instance pods managed by this cluster. It is published in the status and
721+
// exposed through the scale sub-resource so that autoscalers (such as HPA or
722+
// VPA) can discover the managed pods.
723+
func (cluster *Cluster) GetInstancesSelector() string {
724+
return labels.SelectorFromSet(labels.Set{
725+
utils.ClusterLabelName: cluster.Name,
726+
utils.PodRoleLabelName: string(utils.PodRoleInstance),
727+
}).String()
728+
}
729+
718730
// GetMaxStartDelay get the amount of time of startDelay config option
719731
func (cluster *Cluster) GetMaxStartDelay() int32 {
720732
if cluster.Spec.MaxStartDelay > 0 {

‎api/v1/cluster_types.go‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -855,6 +855,13 @@ type ClusterStatus struct {
855855
// +optional
856856
ReadyInstances int `json:"readyInstances,omitempty"`
857857

858+
// Selector is the serialized form of the label selector that identifies
859+
// the pods managed by this cluster. Populated by the operator and exposed
860+
// through the scale sub-resource so an autoscaler (such as HPA or VPA)
861+
// can discover the managed instance pods.
862+
// +optional
863+
Selector string `json:"selector,omitempty"`
864+
858865
// InstancesStatus indicates in which status the instances are
859866
// +optional
860867
InstancesStatus map[PodStatus][]string `json:"instancesStatus,omitempty"`
@@ -2650,7 +2657,7 @@ type RoleConfiguration struct {
26502657
// +kubebuilder:object:root=true
26512658
// +kubebuilder:storageversion
26522659
// +kubebuilder:subresource:status
2653-
// +kubebuilder:subresource:scale:specpath=.spec.instances,statuspath=.status.instances
2660+
// +kubebuilder:subresource:scale:specpath=.spec.instances,statuspath=.status.instances,selectorpath=.status.selector
26542661
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
26552662
// +kubebuilder:printcolumn:name="Instances",type="integer",JSONPath=".status.instances",description="Number of instances"
26562663
// +kubebuilder:printcolumn:name="Ready",type="integer",JSONPath=".status.readyInstances",description="Number of ready instances"

‎config/crd/bases/postgresql.cnpg.io_clusters.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7411,6 +7411,13 @@ spec:
74117411
description: The resource version of the "postgres" user secret
74127412
type: string
74137413
type: object
7414+
selector:
7415+
description: |-
7416+
Selector is the serialized form of the label selector that identifies
7417+
the pods managed by this cluster. Populated by the operator and exposed
7418+
through the scale sub-resource so an autoscaler (such as HPA or VPA)
7419+
can discover the managed instance pods.
7420+
type: string
74147421
switchReplicaClusterStatus:
74157422
description: SwitchReplicaClusterStatus is the status of the switch
74167423
to replica cluster
@@ -7504,6 +7511,7 @@ spec:
75047511
storage: true
75057512
subresources:
75067513
scale:
7514+
labelSelectorPath: .status.selector
75077515
specReplicasPath: .spec.instances
75087516
statusReplicasPath: .status.instances
75097517
status: {}

‎docs/src/cloudnative-pg.v1.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -656,6 +656,7 @@ _Appears in:_
656656
| --- | --- | --- | --- | --- |
657657
| `instances` _integer_ | The total number of PVC Groups detected in the cluster. It may differ from the number of existing instance pods. | | | |
658658
| `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. | | | |
659660
| `instancesStatus` _object (keys:[PodStatus](#podstatus), values:string array)_ | InstancesStatus indicates in which status the instances are | | | |
660661
| `instancesReportedState` _object (keys:[PodName](#podname), values:[InstanceReportedState](#instancereportedstate))_ | The reported state of the instances during the last reconciliation loop | | | |
661662
| `managedRolesStatus` _[ManagedRoles](#managedroles)_ | ManagedRolesStatus reports the state of the managed roles in the cluster | | | |

‎docs/src/operator_capability_levels.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -589,7 +589,12 @@ The operator allows you to scale up and down the number of instances in a
589589
PostgreSQL cluster. New replicas are started up from the
590590
primary server and participate in the cluster's HA infrastructure.
591591
The CRD declares a "scale" subresource that allows you to use the
592-
`kubectl scale` command.
592+
`kubectl scale` command. The scale subresource also publishes the label
593+
selector of the managed instance pods, which lets autoscalers discover them.
594+
See the [Vertical Pod Autoscaler integration](resource_management.md#integration-with-the-vertical-pod-autoscaler-vpa)
595+
for the recommended use, and the
596+
[Horizontal Pod Autoscaler integration](resource_management.md#integration-with-the-horizontal-pod-autoscaler-hpa)
597+
for the caveats that apply to HPA.
593598

594599
### Maintenance window and PodDisruptionBudget for Kubernetes nodes
595600

@@ -638,6 +643,10 @@ to clone the data from the primary again.
638643
The operator allows administrators to control and manage resource usage by
639644
the cluster's pods in the `resources` section of the manifest. In
640645
particular, you can set `requests` and `limits` values for both CPU and RAM.
646+
Because the `Cluster` exposes a label selector through its scale subresource,
647+
it can also be used as a target for the
648+
[Vertical Pod Autoscaler](resource_management.md#integration-with-the-vertical-pod-autoscaler-vpa)
649+
in recommendation-only mode, to obtain sizing suggestions for these values.
641650

642651
### Connection pooling with PgBouncer
643652

‎docs/src/resource_management.md‎

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,4 +115,76 @@ section in the PostgreSQL documentation.
115115
For more details on resource management, please refer to the
116116
["Managing Compute Resources for Containers"](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
117117
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
190+
carefully first.

‎internal/controller/cluster_status.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,10 @@ func (r *ClusterReconciler) updateResourceStatus(
247247
cluster.Status.WriteService = cluster.GetServiceReadWriteName()
248248
cluster.Status.ReadService = cluster.GetServiceReadName()
249249

250+
// Expose the label selector for the scale sub-resource so autoscalers
251+
// (HPA, VPA) can discover the instance pods managed by this cluster.
252+
cluster.Status.Selector = cluster.GetInstancesSelector()
253+
250254
// If we are switching, check if the target primary is still active
251255
// Ignore this check if current primary is empty (it happens during the bootstrap)
252256
if cluster.Status.TargetPrimary != cluster.Status.CurrentPrimary &&

‎internal/controller/cluster_status_test.go‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,18 +21,21 @@ package controller
2121

2222
import (
2323
"context"
24+
"fmt"
2425

2526
batchv1 "k8s.io/api/batch/v1"
2627
corev1 "k8s.io/api/core/v1"
2728
"k8s.io/apimachinery/pkg/api/meta"
2829
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
30+
"k8s.io/apimachinery/pkg/labels"
2931
"k8s.io/apimachinery/pkg/types"
3032
"k8s.io/apimachinery/pkg/util/rand"
3133

3234
apiv1 "github.com/cloudnative-pg/cloudnative-pg/api/v1"
3335
"github.com/cloudnative-pg/cloudnative-pg/pkg/certs"
3436
"github.com/cloudnative-pg/cloudnative-pg/pkg/postgres"
3537
"github.com/cloudnative-pg/cloudnative-pg/pkg/reconciler/persistentvolumeclaim"
38+
"github.com/cloudnative-pg/cloudnative-pg/pkg/utils"
3639

3740
. "github.com/onsi/ginkgo/v2"
3841
. "github.com/onsi/gomega"
@@ -176,6 +179,36 @@ var _ = Describe("cluster_status unit tests", func() {
176179
}))
177180
})
178181
})
182+
183+
It("produces a scale-subresource selector matching managed instance pods", func() {
184+
// updateResourceStatus publishes cluster.GetInstancesSelector() into
185+
// .status.selector so VPA/HPA can discover instance pods through the scale
186+
// subresource. We exercise the production code (GetInstancesSelector) and
187+
// verify both that it has the expected format and that it actually matches
188+
// the labels the operator applies to every instance pod.
189+
namespace := newFakeNamespace(env.client)
190+
cluster := newFakeCNPGCluster(env.client, namespace)
191+
pods := generateFakeClusterPods(env.client, cluster, true)
192+
Expect(pods).ToNot(BeEmpty())
193+
194+
selectorString := cluster.GetInstancesSelector()
195+
196+
// GetInstancesSelector serializes through labels.SelectorFromSet, which
197+
// sorts requirements by key. The cluster label key sorts before the pod
198+
// role label key, so the expected string lists them in that order.
199+
expected := fmt.Sprintf("%s=%s,%s=%s",
200+
utils.ClusterLabelName, cluster.Name,
201+
utils.PodRoleLabelName, string(utils.PodRoleInstance))
202+
Expect(selectorString).To(Equal(expected))
203+
204+
selector, err := labels.Parse(selectorString)
205+
Expect(err).ToNot(HaveOccurred())
206+
207+
for i := range pods {
208+
Expect(selector.Matches(labels.Set(pods[i].Labels))).To(BeTrue(),
209+
"selector %q must match pod %s labels %v", selectorString, pods[i].Name, pods[i].Labels)
210+
}
211+
})
179212
})
180213

181214
var _ = Describe("updateClusterStatusThatRequiresInstancesState tests", func() {

0 commit comments

Comments
 (0)