Custom Resources Reference

Custom Resources Overview

Keldon defines six custom resources under the keldon.io/v1alpha1 API group. They split into three layers:

How the resources relate

The minimum required resources for your first MPP database cluster are a DatabaseImage and a DatabaseCluster. The DatabaseImage defines which database image to run, and the DatabaseCluster references it to create the actual coordinator, segments, mirrors, storage, and services. DatabaseClusterClass and DatabaseConfig are optional helpers for reusable topology and custom database configuration.

DatabaseImage, DatabaseClusterClass, and DatabaseConfig are cluster-scoped — define them once, reference them from any namespace. DatabaseCluster, DatabaseBackup, and DatabaseRestore are namespace-scoped and live next to your workload.

DatabaseImage

DatabaseImage registers a container image and database version that clusters can reference. It’s cluster-scoped, so one definition serves every namespace.

Example

apiVersion: keldon.io/v1alpha1
kind: DatabaseImage
metadata:
  name: cloudberry-2.1.0
spec:
  version: "2.1.0"
  image: ghcr.io/keldonio/cloudberry:2.1.0

Spec fields

Pinning vs floating tags

Always pin to a specific image tag in production (:2.1.0, not :latest). Floating tags will pull a different image on every pod restart, breaking reproducibility and making upgrades implicit. Use pinned tags as your declarative source of truth.

Multi-image setups

You can register multiple DatabaseImage resources to support different versions across clusters:

---
apiVersion: keldon.io/v1alpha1
kind: DatabaseImage
metadata:
  name: cloudberry-2.1.0
spec:
  version: "2.1.0"
  image: ghcr.io/keldonio/cloudberry:2.1.0
---
apiVersion: keldon.io/v1alpha1
kind: DatabaseImage
metadata:
  name: cloudberry-2.2.0
spec:
  version: "2.2.0"
  image: ghcr.io/keldonio/cloudberry:2.2.0

Each DatabaseCluster references one image. You can mix engines and versions across your cluster fleet without changing the operator.

DatabaseClusterClass

DatabaseClusterClass defines a reusable cluster topology and resource defaults. Multiple DatabaseCluster resources can reference one class, ensuring consistent shape across environments. It’s cluster-scoped.

Use a DatabaseClusterClass when you want to enforce a standard topology (segment counts, resources, kernel tuning) across many clusters — for example, dev-small, staging-medium, prod-large.

Example

apiVersion: keldon.io/v1alpha1
kind: DatabaseClusterClass
metadata:
  name: smoke-default
spec:
  segmentCount: 2
  kernelTuning: false
  coordinator:
    storage: 10Gi
    storageClassName: local-path
  segments:
    storage: 10Gi
    storageClassName: local-path
  mirror:
    enabled: true
    storage: 10Gi
    storageClassName: local-path
  standby:
    enabled: true
    storage: 10Gi
    storageClassName: local-path
  recovery:
    autoRecover: true
    autoRebalance: true
    rebalanceDelaySeconds: 30
  sshTrust: static

Spec fields

When to use a ClusterClass vs inline spec

Use a DatabaseClusterClass when:
  - You manage multiple clusters with the same shape
  - You want to enforce environment standards (dev/staging/prod)
  - Topology should be controlled by a platform team, not the cluster owner

Use inline DatabaseCluster spec when:
  - You have one or two clusters and don't need a template
  - Each cluster is genuinely unique
  - You're prototyping

Cluster-level fields always override class-level defaults. For example, if a DatabaseCluster references a DatabaseClusterClass where segmentCount: 4, but the cluster sets spec.segments.count: 8, the cluster gets 8 segments. This makes DatabaseClusterClass a default provider, not a hard constraint.

DatabaseConfig

DatabaseConfig provides declarative management of postgresql.conf and pg_hba.conf for clusters that reference it. It’s cluster-scoped — one named config (e.g. prod-tuned) can be shared across all namespaces.

Example

apiVersion: keldon.io/v1alpha1
kind: DatabaseConfig
metadata:
  name: standard-config
spec:
  postgresqlConf:
    max_connections: "500"
    shared_buffers: "2GB"
    work_mem: "64MB"
    log_min_duration_statement: "1000"
  pgHbaRules:
    - type: host
      database: all
      user: all
      address: "10.0.0.0/8"
      method: md5
    - type: host
      database: all
      user: all
      address: "0.0.0.0/0"
      method: scram-sha-256

Spec fields

pgHbaRules entry fields

The operator’s built-in pg_hba rules — host all <adminUser> <podCIDR> trust and host replication ... — are always present and cannot be removed. They’re required for the operator to talk to the cluster from any pod. Your pgHbaRules are appended after them.

Reload vs restart

Most postgresql.conf parameters can be applied via a configuration reload (pg_ctl reload), which is non-disruptive. Some require a full cluster restart.

Parameters like shared_buffers, max_connections, and max_wal_senders require a full database restart to take effect. The cluster’s status surfaces a warning message when a changed setting needs restart, but the operator does not restart automatically. Plan restart-requiring config changes for maintenance windows.

Common configuration recipes

Connection pooling-friendly:

spec:
  postgresqlConf:
    max_connections: "1000"
    superuser_reserved_connections: "10"

Aggressive query logging for debugging:

spec:
  postgresqlConf:
    log_min_duration_statement: "0"      # log all queries
    log_statement: "all"
    log_duration: "on"

Memory-tuned for OLAP:

spec:
  postgresqlConf:
    shared_buffers: "8GB"
    work_mem: "256MB"
    maintenance_work_mem: "2GB"
    effective_cache_size: "32GB"

DatabaseCluster

The main resource — the cluster itself. Defines coordinator, standby, segments, mirrors, and operational behavior. Namespace-scoped.

Minimal example

apiVersion: keldon.io/v1alpha1
kind: DatabaseCluster
metadata:
  name: cluster-demo
  namespace: default
spec:
  databaseImage: cloudberry-2.1.0
  coordinator:
    storage: 10Gi
    storageClassName: local-path
  segments:
    count: 2
    storage: 10Gi
    storageClassName: local-path

DatabaseCluster using DatabaseClusterClass and DatabaseConfig

apiVersion: keldon.io/v1alpha1
kind: DatabaseCluster
metadata:
  name: cluster-demo
  namespace: default
spec:
  databaseImage: cloudberry-2.1.0
  databaseClusterClass: prod-medium
  databaseConfig: standard-config

DatabaseCluster overrides values of DatabaseClusterClass and DatabaseConfig

apiVersion: keldon.io/v1alpha1
kind: DatabaseCluster
metadata:
  name: cluster-demo
  namespace: default
spec:
  databaseImage: cloudberry-2.1.0
  databaseClusterClass: prod-medium
  databaseConfig: standard-config
  mirroring: true
  kernelTuning: true
  sshTrust: certificate
  standby:
    enabled: true
    storage: 10Gi
    storageClassName: local-path
  coordinator:
    storage: 10Gi
    storageClassName: local-path
  segments:
    count: 2
    storage: 10Gi
    storageClassName: local-path
  recovery:
    autoRecover: true
    autoRebalance: true
    rebalanceDelaySeconds: 30

The cluster name (metadata.name) must be 18 characters or fewer. This limit comes from Cloudberry’s MAXHOSTNAMELEN=64 constraint. The admission webhook rejects longer names. See Limits and Known Issues.

Top-level spec fields

spec.coordinator

coordinator:
  storage: 10Gi
  storageClassName: local-path
  resources:                       # optional, overrides class defaults
    requests:
      cpu: "2"
      memory: 4Gi

spec.standby

standby:
  enabled: true
  storage: 10Gi
  storageClassName: local-path

When enabled: true, the operator provisions a standby coordinator that streams WAL from the primary. On primary failure, the operator promotes the standby and updates the Service selector.

spec.segments

segments:
  count: 4
  storage: 50Gi
  storageClassName: local-path
  resources:
    requests:
      cpu: "4"
      memory: 16Gi

count is the number of primary segments. If mirroring: true, one mirror is provisioned per primary, so a count: 4 cluster with mirroring has 8 segment pods total.

Scaling DOWN segments is not supported. Decreasing spec.segments.count will be rejected by the admission webhook. To shrink a cluster, back it up and restore into a new smaller cluster.

spec.recovery

recovery:
  autoRecover: true              # auto-recover failed segments
  autoRebalance: true            # rebalance data after recovery
  rebalanceDelaySeconds: 30      # wait before triggering rebalance

When autoRecover: true, the operator detects failed segments and runs gprecoverseg automatically. With autoRebalance: true, data is redistributed across the recovered cluster after a grace period.

Tri-state booleans

mirroring and kernelTuning are tri-state pointer booleans:

This lets a single class serve both clusters that want a feature and clusters that don’t, with the cluster always able to override.

Override semantics

When a cluster references a DatabaseClusterClass, fields are merged as follows:

Cluster spec field set?
  → Cluster value wins.

Cluster spec field not set, but class has it?
  → Class value applies.

Neither sets the field?
  → Operator default applies (usually safe minimum).

Override happens at the leaf level. If your cluster sets spec.segments.count: 8 but doesn’t set spec.segments.storage, the storage comes from the class — the count override doesn’t blank out the rest of the segments object.

Status fields

The operator continuously updates status with cluster state:

Phases at a glance

Full phase transition diagram: Phases and Conditions.

DatabaseBackup

DatabaseBackup represents an on-demand backup to S3-compatible storage. Namespace-scoped.

Minimal example — full cluster backup

apiVersion: keldon.io/v1alpha1
kind: DatabaseBackup
metadata:
  name: my-backup-20260528
spec:
  cluster: cluster-demo
  type: full
  storage:
    type: s3
    bucket: s3-test-keldon
    prefix: cloudberry/cluster-demo/
    region: eu-west-3
    secret: my-s3-credentials
  database: "postgres"

Spec fields

Spec fields

Only full database backups are supported in the current release. The schema and table fields exist on the CRD but are not yet wired through to the operator. Schema-level and table-level backups, as well as filtered restores, are planned for a future release. Use type: full with the database field to scope the backup to one database on the cluster.

spec.storage

S3 credentials secret

The referenced Secret must contain the AWS credential keys:

kubectl create secret generic my-s3-credentials \
  --from-literal=AWS_ACCESS_KEY_ID=<your-key> \
  --from-literal=AWS_SECRET_ACCESS_KEY=<your-secret>

For S3-compatible storage (MinIO, Cloudflare R2, Backblaze B2, etc.), set the endpoint field and use the provider’s access key + secret. The protocol is the same; the operator passes them through to gpbackup_s3_plugin.

DatabaseRestore

DatabaseRestore restores from a DatabaseBackup into a cluster. Namespace-scoped.

Minimal example

apiVersion: keldon.io/v1alpha1
kind: DatabaseRestore
metadata:
  name: restore-from-2026-06-26
  namespace: default
spec:
  cluster: cluster-demo
  backup: cluster-demo-2026-06-26

Cross-cluster restore

You can restore a backup taken from one cluster into a different cluster:

spec:
  cluster: cluster-demo-recovered      # different cluster
  backup: cluster-demo-2026-06-26      # backup originally taken from cluster-demo

This is useful for cloning a production cluster into staging, or recovering into a fresh cluster after a destructive incident.

Restore into a different database name

spec:
  cluster: cluster-demo
  backup: cluster-demo-full-2026-06-26
  database: cluster-demo-restored      # restore INTO this DB name

The target database must already exist on the cluster — DatabaseRestore does not create it. To restore into a fresh database name, create it first before applying the DatabaseRestore.

Spec fields

The target cluster must exist and be in phase: Running before a restore is attempted. The operator validates this and waits for the cluster to be ready, but will fail the restore if the cluster is in an error state.

That covers every resource Keldon manages. Next: Operations for day-two topics like scaling, upgrades, and HA management.