postgres database controllers

[mploski]

Description

Introduces the MVP PostgreSQL contoller stack to the Splunk Operator. Rather than
implementing PostgreSQL cluster management from scratch, this PR builds a Kubernetes-native
wrapper on top of CloudNativePG (CNPG) — a production-grade
PostgreSQL operator. The Splunk Operator layer adds three new CRDs and two new controllers
that translate high-level declarative intent (cluster classes, logical databases, managed
roles) into CNPG primitives, while handling the Splunk-specific lifecycle concerns:
credential provisioning, connection metadata publishing, and multi-phase status tracking.

---

Key Changes

api/v4/postgresclusterclass_types.go (new)

Defines the Go API schema for PostgresClusterClass — a cluster-scoped CRD that
standardises PostgreSQL cluster configuration (instance count, storage, Postgres version,
resource limits, pg_hba rules, connection pooler) across environments. Operators define
dev and prod classes; teams reference them by name.

api/v4/postgrescluster_types.go (new)

Defines the Go API schema for PostgresCluster — the namespaced CRD teams use to request
a PostgreSQL cluster. Declares spec fields for merging class defaults with per-cluster
overrides, and status fields for provisioner reference, connection pooler state, and
managed role tracking.

api/v4/postgresdatabase_types.go (new)

Defines the Go API schema for PostgresDatabase — the CRD that declares one or more
logical databases on a PostgresCluster, including reclaim policy and the list of
database definitions. Status tracks per-database secret and ConfigMap references.

internal/controller/postgresoperator_common_types.go (new)

Shared constants, phase enums, condition types, and condition reasons used across both
controllers. Single source of truth for retry delays, finalizer names, endpoint suffixes,
and all status strings.

internal/controller/postgrescluster_controller.go (new)

Reconciles PostgresCluster CRs against CNPG:

• Provisions a PostgreSQL cluster by translating the PostgresCluster spec into a CNPG
  cluster, merging any defaults inherited from the referenced PostgresClusterClass with
  per-cluster overrides
• Manages the optional connection pooler (PgBouncer) lifecycle alongside the cluster,
  enabling high-throughput workloads to share a bounded pool of database connections
• Handles safe deletion by cleaning up all dependent CNPG resources before removing the CR,
  preventing orphaned infrastructure
• Exposes observable status conditions (ClusterReady, PoolerReady) so the
  PostgresDatabase controller and operators can wait on a confirmed healthy cluster before
  proceeding

internal/controller/postgresdatabase_controller.go (new)

Reconciles PostgresDatabase CRs against CNPG:

• Ensures the target PostgresCluster is healthy before creating any database resources,
  so partial provisioning is never left in an inconsistent state
• Provisions database roles (admin and read-write) by configuring them on the cluster —
  each role is scoped to its own database to enforce least-privilege access
• Generates secure credentials for each role and stores them as Kubernetes Secrets,
  ready to be mounted by workloads that need database access
• Publishes connection details (host, port, database name, usernames, and pooler endpoints
  when available) into a ConfigMap per database, giving consuming services a stable
  reference without hardcoding hostnames
• Provisions the logical databases on the PostgreSQL cluster and respects a configurable
  deletion policy that controls whether the database is physically dropped when the CR is
  deleted
• Exposes observable status conditions (ClusterReady, SecretsReady, ConfigMapsReady,
  UsersReady, DatabasesReady) so operators can track exactly which phase reconciliation
  is in at any point

cmd/main.go

Both new controllers registered with the manager.

config/rbac/

Nine new RBAC files: admin, editor, and viewer roles for PostgresCluster,
PostgresClusterClass, and PostgresDatabase.

config/samples/

Five sample CRs: dev and prod cluster classes, default and override cluster
instances, and a PostgresDatabase example.

---

Testing and Verification

Manual Testing

End-to-end flow verified by applying the full CR chain in order:

# Deploy Class
kubectl apply -f config/samples/enterprise_v4_postgresclusterclass_dev.yaml
# Deploy Postgres Cluster
kubectl apply -f config/samples/enterprise_v4_postgrescluster_default.yaml
# Deploy Postgres Databases
kubectl apply -f config/samples/enterprise_v4_postgresdatabase.yaml

1. Verify the PostgresCluster is ready

kubectl get postgrescluster postgresql-cluster-dev -n default

2. Verify CNPG provisioned the underlying cluster

kubectl get clusters.postgresql.cnpg.io postgresql-cluster-dev -n default

3. Verify the PostgresDatabase status and conditions

kubectl get postgresdatabase splunk-databases -n default
kubectl get postgresdatabase splunk-databases -n default \
  -o jsonpath='{.status.conditions}' | jq

4. Verify CNPG Database CRs were created for each declared database

kubectl get databases.postgresql.cnpg.io -n default

5. Inspect Secrets and ConfigMaps created per database

# Secrets: {postgresdatabase-name}-{db-name}-{role}
kubectl get secret splunk-databases-kvstore-admin -n default -o jsonpath='{.data}' | jq
kubectl get secret splunk-databases-kvstore-rw -n default -o jsonpath='{.data}' | jq

# ConfigMaps: {postgresdatabase-name}-{db-name}
kubectl get configmap splunk-databases-kvstore -n default -o jsonpath='{.data}' | jq
kubectl get configmap splunk-databases-analytics -n default -o jsonpath='{.data}' | jq

6. Connect to the database using credentials and endpoints from the ConfigMap and Secret

HOST=$(kubectl get configmap splunk-databases-kvstore -n default \
  -o jsonpath='{.data.rw-host}')
DB=$(kubectl get configmap splunk-databases-kvstore -n default \
  -o jsonpath='{.data.dbname}')
USER=$(kubectl get configmap splunk-databases-kvstore -n default \
  -o jsonpath='{.data.rw-user}')
PASS=$(kubectl get secret splunk-databases-kvstore-rw -n default \
  -o jsonpath='{.data.password}' | base64 -d)

psql "postgresql://$USER:$PASS@$HOST/$DB"

Additional scenarios verified:

• pooler-rw-host and pooler-ro-host keys appear in ConfigMap only when the cluster
  has connection pooling enabled
• Controller fully reconciles on first apply with no hang after finalizer write
• Deleting a PostgresDatabase CR triggers clean-up respecting the deletionPolicy
  declared per database (Retain preserves data, Delete drops the database)

Automated Tests — Planned Next

Unit and integration tests covering the full reconciliation lifecycle, error paths, and
status condition transitions are scheduled as the next deliverable for this feature branch.

Related Issues

Jira tickets, GitHub issues, Support tickets...

PR Checklist

• Code changes adhere to the project's coding standards.
• Relevant unit and integration tests are included.
• Documentation has been updated accordingly.
• All tests pass locally.
• The PR description follows the project's guidelines.

[github-actions]

CLA Assistant Lite bot:
Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contribution License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment with the exact sentence copied from below.

---

I have read the CLA Document and I hereby sign the CLA

---

1 out of 4 committers have signed the CLA.
✅ @DmytroPI-dev
❌ @mploski
❌ @limak9182
❌ @M4KIF
_{You can retrigger this bot by commenting recheck in this Pull Request}

[vivekr-splunk]

Please move the logic to pkg/postgresql or pkg/splunk/postgresql . we tried to avoid doing changes in controller code as this code is mostly auto-generated. upgrade becomes hard as and when we might have to auto-generate the code

[mploski]

logic moved, followed the pattern already used with other controllers

[vivekr-splunk]

add Recorder record.EventRecorder helps you generating events

[mploski]

we will add it

[vivekr-splunk]

missing how many concurrent reconciliation you want to do.
MaxConcurrentReconciles: enterpriseApi.TotalWorker

[mploski]

added

[vivekr-splunk]

I am unsure if you contorller owns secret here. check the other controllers for reference

Watches(&corev1.Secret{},
			handler.EnqueueRequestForOwner(
				mgr.GetScheme(),
				mgr.GetRESTMapper(),
				&enterpriseApi.ClusterManager{},
			)).

also look into predicates

[mploski]

we levarage predicates now for filtering event's out

[vivekr-splunk]

missing metric data collection, check other controllers. we might have to improve that code, but that explains what we are trying to do

[mploski]

Will be working on this in the next sprint

[vivekr-splunk]

I am unsure if PostgresCluster owns Pooler, configmap and secret here for all the Poolers/configmaps/secret. check example Watches in other contorller

[mploski]

Yes, postgrescluster is owner of pooler, configmap and secrets. If I understand correctly, you use this pattern to control what we trigger:

		Watches(&corev1.Pod{},
			handler.EnqueueRequestForOwner(
				mgr.GetScheme(),
				mgr.GetRESTMapper(),
				&enterpriseApiV3.LicenseMaster{},
			)).

and this is an equivalent to Owns we used. Isnt it?

[vivekr-splunk]

Add a test case where you do not own the postgresql database but they also use postgresql operator to create and manage database. how will this controller respond to it.

[mploski]

@M4KIF worth adding to tests you work on

[vivekr-splunk]

add annotations for maintenance mode support, where we do not want operator to do anything when customer /support is debugging postgresql database/cluster

[kubabuczak]

Do you mean <kind>.enterprise.splunk.com/paused annotations or maintenance_mode field in IDX/SHC spec?

[mploski]

Could you please share the reference doc for me to understand this pattern and what and how we should use this mechanism?

[vivekr-splunk]

add support for maintenance mode where if user has set annotations you will return without running any logic in reconciliation loop

[mploski]

any reference, how to achieve this?

[kasiakoziol]

Could there be a validation for that?

[mploski]

It can, but it will require k8s admission webhooks - we decided to postpone it for now, but we have a ticket for it. Do we have already standard how to use the admission webhooks with SOK?

[kasiakoziol]

Yes, we have a standard for validating webhooks. https://github.com/splunk/splunk-operator/blob/develop/docs/ValidationWebhook.md

[kasiakoziol]

Could there be a validation for that?

[mploski]

yes, in admission webhook. Work postponed for now, but we have a ticket for in in our board