K8SPG-864: add `sidecarPVCs` and `sidecarVolumes` by pooknull · Pull Request #1394 · percona/percona-postgresql-operator

pooknull · 2026-01-08T10:13:28Z

https://perconadev.atlassian.net/browse/K8SPG-864

DESCRIPTION

This PR adds the following fields to the cr.yaml:

.spec.instances[].sidecarPVCs
.spec.instances[].sidecarVolumes
.spec.proxy.pgBouncer.sidecarPVCs
.spec.proxy.pgBouncer.sidecarVolumes
.spec.backups.pgbackrest.repoHost.sidecarPVCs
.spec.backups.pgbackrest.repoHost.sidecarVolumes

The sidecarPVCs field defines PersistentVolumeClaims that should be created and associated with a specific resource. Example:

sidecarPVCs:
- name: sidecar-volume-claim
  spec:
    resources:
      requests:
        storage: 1Gi
    volumeMode: Filesystem
    accessModes:
      - ReadWriteOnce

The sidecarVolumes field defines volumes that should be attached to a specific resource. Example:

sidecarVolumes:
- name: sidecar-secret
  secret:
    secretName: mysecret
- name: sidecar-config
  configMap:
    name: myconfigmap
- name: backup-nfs
  nfs:
    server: "nfs-service.storage.svc.cluster.local"
    path: "/pg-some-name"

Helm PR: percona/percona-helm-charts#783

CHECKLIST

Jira

Is the Jira ticket created and referenced properly?
Does the Jira ticket have the proper statuses for documentation (Needs Doc) and QA (Needs QA)?
Does the Jira ticket link to the proper milestone (Fix Version field)?

Tests

Is an E2E test/test case added for the new feature/change?
Are unit tests added where appropriate?

Config/Logging/Testability

Are all needed new/changed options added to default YAML files?
Are all needed new/changed options added to the Helm Chart?
Did we add proper logging messages for operator actions?
Did we ensure compatibility with the previous version or cluster upgrade process?
Does the change support oldest and newest supported PG version?
Does the change support oldest and newest supported Kubernetes version?

https://perconadev.atlassian.net/browse/K8SPG-864

egegunes · 2026-01-14T05:41:31Z

internal/controller/postgrescluster/instance.go

+	if cluster.CompareVersion("2.9.0") >= 0 {
+		for _, p := range spec.SidecarPVCs {
+			instance.Spec.VolumeClaimTemplates = append(instance.Spec.VolumeClaimTemplates, corev1.PersistentVolumeClaim{
+				ObjectMeta: metav1.ObjectMeta{Name: p.Name},
+				Spec:       p.Spec,
+			})
+		}
+	}


does this mean that users can only add sidecar PVCs while creating clusters? i guess we had the same limitation in other operators.

egegunes · 2026-01-14T05:43:55Z

percona/controller/pgcluster/pvc.go

but if we are creating PVCs ourselves why don't we just add them into statefulset volumes so they can also be added after cluster creation?

ok, i now realized we're doing this only for pgbouncer because it's a deployment. but if we do this for all, we'd overcome the limitation of adding sidecar pvcs after creation

egegunes · 2026-02-03T10:32:58Z

build/crd/crunchy/generated/postgres-operator.crunchydata.com_postgresclusters.yaml

i don't think we should downgrade

egegunes · 2026-02-11T05:57:02Z

hack/tools/.gitignore

why this was deleted?

gkech · 2026-02-11T11:36:41Z

percona/controller/pgcluster/pvc.go

should we have some sort of labels added here so that we know that these pvcs are created by the operator?

gkech · 2026-02-11T11:37:16Z

percona/controller/pgcluster/pvc.go

+		err := cl.Get(ctx, client.ObjectKeyFromObject(pvc), &corev1.PersistentVolumeClaim{})
+		if err == nil {
+			// already exists
+			continue


What should happen if the pvcs are updated in terms of specs? should we update them of skip?

gkech · 2026-02-11T11:54:14Z

let's check also why unit tests are failing on this pr

Run make check
REGISTRY_NAME is not set
Updated IMAGE to: docker.io/perconalab/percona-postgresql-operator:head
docker.io/perconalab/percona-postgresql-operator:head
git -C 'hack/tools/' clone https://github.com/CrunchyData/pgmonitor.git || git -C 'hack/tools/pgmonitor' fetch origin
fatal: cannot change to 'hack/tools/': No such file or directory
fatal: cannot change to 'hack/tools/pgmonitor': No such file or directory
make: *** [Makefile:49: get-pgmonitor] Error 128
Error: Process completed with exit code 2.

Copilot

Pull request overview

Adds support for configuring extra volumes and operator-managed PVCs for sidecar containers across instance pods, pgBouncer, and pgBackRest repoHost, along with the necessary API/plumbing, RBAC, and tests.

Changes:

Extend CRDs/types with sidecarVolumes and sidecarPVCs for instances, pgBouncer, and pgBackRest repoHost.
Reconcile pod specs to mount the configured sidecar volumes/PVCs, and add a controller reconciler to create/update the defined PVCs.
Update RBAC and sidecar-related unit/E2E tests to cover the new fields.

Reviewed changes

Copilot reviewed 20 out of 28 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
pkg/apis/postgres-operator.crunchydata.com/v1beta1/zz_generated.deepcopy.go	Deepcopy updates for new fields and new `SidecarPVC` type.
pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go	Adds `sidecarVolumes/sidecarPVCs` to instance set spec + defines `SidecarPVC`.
pkg/apis/postgres-operator.crunchydata.com/v1beta1/pgbouncer_types.go	Adds `sidecarVolumes/sidecarPVCs` to pgBouncer pod spec.
pkg/apis/postgres-operator.crunchydata.com/v1beta1/pgbackrest_types.go	Adds `sidecarVolumes/sidecarPVCs` to pgBackRest repoHost spec.
pkg/apis/pgv2.percona.com/v2/zz_generated.deepcopy.go	Deepcopy updates for new Percona API fields.
pkg/apis/pgv2.percona.com/v2/perconapgcluster_types.go	Adds Percona-level fields and maps them through `ToCrunchy()`.
percona/controller/pgcluster/pvc.go	New reconciler to create/update PVCs declared via `sidecarPVCs`.
percona/controller/pgcluster/controller_test.go	Extends sidecar tests to assert volumes + PVC-backed volumes are present.
percona/controller/pgcluster/controller.go	Calls PVC reconciler and adds PVC RBAC marker.
internal/postgres/reconcile.go	Adds `sidecarVolumes` to instance pods (version-gated).
internal/pgbouncer/reconcile.go	Adds `sidecarVolumes` and PVC-backed volumes to pgBouncer pod spec (version-gated).
internal/controller/postgrescluster/pgbackrest.go	Adds `sidecarVolumes` and PVC-backed volumes to repoHost pod template (version-gated).
internal/controller/postgrescluster/instance.go	Adds PVC-backed volumes to instance StatefulSet pod template (version-gated).
e2e-tests/tests/sidecars/01-create-cluster.yaml	Sets `sidecarVolumes/sidecarPVCs` fields in the sidecars E2E test.
e2e-tests/tests/sidecars/01-assert.yaml	Adds assertions for PVC creation/binding in the sidecars E2E test.
deploy/rbac.yaml	Grants PVC verbs in deployment RBAC.
deploy/cw-rbac.yaml	Same RBAC updates for cw deployment.
config/rbac/namespace/role.yaml	Grants PVC verbs in generated namespace Role.
config/rbac/cluster/role.yaml	Grants PVC verbs in generated cluster Role.
Makefile	Minor formatting/line fix in after-release target.

pkg/apis/postgres-operator.crunchydata.com/v1beta1/pgbouncer_types.go

pkg/apis/pgv2.percona.com/v2/perconapgcluster_types.go

percona/controller/pgcluster/pvc.go

internal/controller/postgrescluster/instance.go

pkg/apis/postgres-operator.crunchydata.com/v1beta1/pgbackrest_types.go

pkg/apis/pgv2.percona.com/v2/perconapgcluster_types.go

percona/controller/pgcluster/pvc.go

percona/controller/pgcluster/controller.go

e2e-tests/tests/sidecars/01-assert.yaml

pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go

hors

@pooknull please check sidecars test

Copilot

Pull request overview

Copilot reviewed 20 out of 28 changed files in this pull request and generated 5 comments.

Copilot · 2026-02-18T12:40:15Z

e2e-tests/tests/sidecars/01-create-cluster.yaml

+        | yq eval '.spec.instances[0].sidecarVolumes = [{"name": "sidecar-secret", "secret": {"secretName": "mysecret"}}]' - \
+        | yq eval '.spec.instances[0].sidecarPVCs = [{"name": "sidecar-instance-claim", "spec": {"resources": {"requests": {"storage": "1Gi"}}, "volumeMode": "Filesystem", "accessModes": ["ReadWriteOnce"]}}]' - \
      	| yq eval '.spec.proxy.pgBouncer.sidecars = [{"name": "sidecar1", "image": "busybox", "command": ["sleep", "30d"]}]' - \
+        | yq eval '.spec.proxy.pgBouncer.sidecarVolumes = [{"name": "sidecar-secret", "secret": {"secretName": "mysecret"}}]' - \
+        | yq eval '.spec.proxy.pgBouncer.sidecarPVCs = [{"name": "sidecar-pgbouncer-claim", "spec": {"resources": {"requests": {"storage": "1Gi"}}, "volumeMode": "Filesystem", "accessModes": ["ReadWriteOnce"]}}]' - \
+      	| yq eval '.spec.backups.pgbackrest.repoHost.sidecars = [{"name": "sidecar1", "image": "busybox", "command": ["sleep", "30d"]}]' - \
+        | yq eval '.spec.backups.pgbackrest.repoHost.sidecarVolumes = [{"name": "sidecar-secret", "secret": {"secretName": "mysecret"}}]' - \
+        | yq eval '.spec.backups.pgbackrest.repoHost.sidecarPVCs = [{"name": "sidecar-repohost-claim", "spec": {"resources": {"requests": {"storage": "1Gi"}}, "volumeMode": "Filesystem", "accessModes": ["ReadWriteOnce"]}}]' - \


Problem: The E2E test references a secret named "mysecret" that doesn't appear to be created in the test setup.

Why it matters: If the secret doesn't exist, the sidecarVolumes configuration will fail when Kubernetes tries to mount it, causing pods to be stuck in a pending or error state. The test may pass if the volume is defined but never actually mounted by a sidecar container, masking this issue.

Fix: Either create the secret "mysecret" in the test setup (e.g., in 00-deploy-operator.yaml or a new 00-create-secret.yaml step), or use a volume type that doesn't require external resources (like emptyDir) if the test is only validating that volumes are properly added to the pod spec.

Copilot · 2026-02-18T12:40:16Z

percona/controller/pgcluster/pvc.go

+	for _, sidecarPVC := range pvcs {
+		pvc := new(corev1.PersistentVolumeClaim)
+		pvc.Name = sidecarPVC.Name
+		pvc.Namespace = cr.Namespace
+
+		if err := cl.Get(ctx, client.ObjectKeyFromObject(pvc), pvc); err != nil {
+			if !k8serrors.IsNotFound(err) {
+				return errors.Wrapf(err, "get %s", client.ObjectKeyFromObject(pvc).String())
+			}
+			pvc.Spec = sidecarPVC.Spec
+			pvc.Labels = ls
+			if err := cl.Create(ctx, pvc); err != nil {
+				return errors.Wrap(err, "failed to create pvc")
+			}
+			continue


Problem: PVCs created by this function do not have a controller reference set.

Why it matters: Without a controller reference, these PVCs will not be garbage-collected when the cluster is deleted. This leads to resource leaks where PVCs persist after cluster deletion, potentially causing issues with storage quotas and requiring manual cleanup.

Fix: Add a controller reference using controllerutil.SetControllerReference before creating the PVC. This ensures proper ownership and automatic cleanup. See percona/controller/pgcluster/backup.go:191 and percona/controller/pgcluster/patroniversion.go:180 for examples of this pattern in the codebase.

Copilot · 2026-02-18T12:40:16Z

percona/controller/pgcluster/pvc.go

+func ensureSidecarPVCs(
+	ctx context.Context,
+	cl client.Client,
+	cr *v2.PerconaPGCluster,
+	pvcs []v1beta1.SidecarPVC,
+	ls map[string]string,
+) error {
+	for _, sidecarPVC := range pvcs {
+		pvc := new(corev1.PersistentVolumeClaim)
+		pvc.Name = sidecarPVC.Name
+		pvc.Namespace = cr.Namespace
+
+		if err := cl.Get(ctx, client.ObjectKeyFromObject(pvc), pvc); err != nil {
+			if !k8serrors.IsNotFound(err) {
+				return errors.Wrapf(err, "get %s", client.ObjectKeyFromObject(pvc).String())
+			}
+			pvc.Spec = sidecarPVC.Spec
+			pvc.Labels = ls
+			if err := cl.Create(ctx, pvc); err != nil {
+				return errors.Wrap(err, "failed to create pvc")
+			}
+			continue
+		}
+		if v := pvc.Labels[naming.LabelPerconaManagedBy]; v != "percona-postgresql-operator" {
+			return errors.Errorf("PersistentVolumeClaim %s already exists and not managed by percona-postgresql-operator: %s", client.ObjectKeyFromObject(pvc).String(), v)
+		}
+		if v := pvc.Labels[naming.LabelPerconaInstance]; v != cr.Name {
+			return errors.Errorf("PersistentVolumeClaim %s already exists and belongs to another cluster %s", client.ObjectKeyFromObject(pvc).String(), v)
+		}
+
+		if err := retry.RetryOnConflict(retry.DefaultRetry, func() error {
+			if err := cl.Get(ctx, client.ObjectKeyFromObject(pvc), pvc); err != nil {
+				return err
+			}
+			maps.Copy(pvc.Labels, ls)
+
+			// It's only allowed to update resources.requests and volumeAttributesClassName
+			pvc.Spec.Resources.Requests = sidecarPVC.Spec.Resources.Requests
+			pvc.Spec.VolumeAttributesClassName = sidecarPVC.Spec.VolumeAttributesClassName
+
+			return cl.Update(ctx, pvc)
+		}); err != nil {
+			return errors.Wrapf(err, "update PersistentVolumeClaim %s", client.ObjectKeyFromObject(pvc).String())
+		}
+	}
+
+	return nil
+}


Problem: Missing logging for important operator actions during PVC reconciliation.

Why it matters: According to the coding guideline "Add logging for important operator actions (reconcile steps, errors, retries)", logging helps track operator behavior and debug issues in production. PVC creation, updates, and conflicts are important reconcile steps that should be logged.

Fix: Add structured logging using logging.FromContext(ctx) with appropriate log levels (Info for creation/updates, Error for failures). For example, log when creating a PVC, when updating an existing PVC, and when encountering conflicts.

Copilot · 2026-02-18T12:40:16Z

pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go

+// K8SPG-864
+type SidecarPVC struct {
+	Name string `json:"name"`
+


Problem: Missing documentation comments for the SidecarPVC type.

Why it matters: The SidecarPVC type is a new public API type that will be used by end-users in their CR YAML files. Following codebase conventions, API types should have documentation describing their purpose and fields.

Fix: Add a documentation comment above the SidecarPVC type definition explaining what it is and how it's used, similar to other type definitions in this file. Also add comments for the Name and Spec fields.

Suggested change

// K8SPG-864

type SidecarPVC struct {

Name string `json:"name"`

// K8SPG-864

// SidecarPVC describes a PersistentVolumeClaim that should be created and

// mounted for a sidecar container.

type SidecarPVC struct {

// Name is the name of the PersistentVolumeClaim used by the sidecar.

Name string `json:"name"`

// Spec defines the desired specification of the PersistentVolumeClaim.

Copilot · 2026-02-18T12:40:17Z

pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go

+type SidecarPVC struct {
+	Name string `json:"name"`
+
+	Spec corev1.PersistentVolumeClaimSpec `json:"spec"`
+}


Problem: The SidecarPVC type lacks validation annotations.

Why it matters: Other API types in this codebase use kubebuilder validation annotations (e.g., +kubebuilder:validation:Required) to enforce constraints and provide clear error messages to users. The Name field should be validated (e.g., pattern, required) to ensure proper resource naming in Kubernetes.

Fix: Add appropriate validation annotations. At minimum, the Name field should have +kubebuilder:validation:Required and likely a pattern constraint similar to other name fields in the codebase (e.g., see postgrescluster_types.go:480).

JNKPercona · 2026-02-18T21:06:47Z

Test Name	Result	Time
backup-enable-disable	passed	00:05:40
builtin-extensions	passed	00:04:53
custom-envs	passed	00:19:38
custom-extensions	passed	00:13:43
custom-tls	passed	00:05:13
database-init-sql	passed	00:02:35
demand-backup	passed	00:24:22
demand-backup-offline-snapshot	passed	00:13:10
dynamic-configuration	passed	00:03:11
finalizers	passed	00:03:43
init-deploy	passed	00:02:46
huge-pages	passed	00:03:04
monitoring	passed	00:06:55
monitoring-pmm3	passed	00:11:40
one-pod	passed	00:05:55
operator-self-healing	passed	00:08:59
pitr	passed	00:11:59
scaling	passed	00:04:45
scheduled-backup	passed	00:27:21
self-healing	passed	00:08:43
sidecars	passed	00:02:50
standby-pgbackrest	passed	00:12:01
standby-streaming	passed	00:09:15
start-from-backup	passed	00:10:56
tablespaces	passed	00:06:47
telemetry-transfer	passed	00:03:40
upgrade-consistency	passed	00:04:39
upgrade-minor	passed	00:05:01
users	passed	00:04:36

Summary	Value
Tests Run	29/29
Job Duration	01:29:20
Total Test Time	04:08:14

commit: 4866e97
image: perconalab/percona-postgresql-operator:PR-1394-4866e9719

K8SPG-864: add sidecarPVCs and sidecarVolumes

d56fcaf

https://perconadev.atlassian.net/browse/K8SPG-864

pooknull force-pushed the K8SPG-864 branch from cae7770 to d56fcaf Compare January 8, 2026 10:15

pooknull added 2 commits January 9, 2026 13:39

revert kustomize and controller-gen updates

ca506c1

fix unit-test

c4be734

pooknull marked this pull request as ready for review January 13, 2026 09:50

pooknull requested review from egegunes, eleo007, gkech, hors, jvpasinatto, nmarukovich and valmiranogueira as code owners January 13, 2026 09:50

egegunes reviewed Jan 14, 2026

View reviewed changes

don't use volumeClaimTemplates

fb1cad2

pooknull requested review from bogdanjeler-ev, mayankshah1607 and oksana-grishchenko as code owners January 28, 2026 11:06

pooknull requested a review from egegunes January 28, 2026 11:09

pooknull added 2 commits January 28, 2026 13:22

Merge remote-tracking branch 'origin/main' into K8SPG-864

57a2553

make generate

2190767

egegunes requested changes Feb 3, 2026

View reviewed changes

pooknull added 2 commits February 10, 2026 13:32

make manifests

de3bcda

Merge branch 'main' into K8SPG-864

d26ddd8

pooknull requested a review from egegunes February 10, 2026 11:56

Merge remote-tracking branch 'origin/main' into K8SPG-864

93c1b32

egegunes requested changes Feb 11, 2026

View reviewed changes

gkech reviewed Feb 11, 2026

View reviewed changes

pooknull added 2 commits February 12, 2026 14:09

add labels

b10f5da

revert .gitignore

772b800

egegunes added this to the v2.9.0 milestone Feb 12, 2026

allow updating the pvc

cbc67f5

Copilot AI review requested due to automatic review settings February 13, 2026 12:23

Merge branch 'main' into K8SPG-864

608e287

Copilot started reviewing on behalf of pooknull February 13, 2026 12:23 View session

pooknull requested review from egegunes and gkech February 13, 2026 12:24

Copilot AI reviewed Feb 13, 2026

View reviewed changes

hors requested changes Feb 13, 2026

View reviewed changes

fix tests

e9e6a8d

pooknull requested a review from hors February 18, 2026 11:25

Merge branch 'main' into K8SPG-864

2e66a7e

Copilot AI review requested due to automatic review settings February 18, 2026 12:34

Copilot started reviewing on behalf of pooknull February 18, 2026 12:35 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

Merge branch 'main' into K8SPG-864

4866e97

Conversation

pooknull commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIPTION

CHECKLIST

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gkech commented Feb 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hors left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

JNKPercona commented Feb 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Comments

pooknull commented Jan 8, 2026 •

edited

Loading