cozystack/packages/apps/postgres/values.yaml

##
## @section Common parameters
##

## @typedef {struct} Resources - Explicit CPU and memory configuration for each PostgreSQL replica.
## @field {quantity} [cpu] - CPU available to each replica.
## @field {quantity} [memory] - Memory (RAM) available to each replica.

## @enum {string} ResourcesPreset - Default sizing preset.
## @value t1.nano
## @value t1.micro
## @value t1.small
## @value t1.medium
## @value t1.large
## @value t1.xlarge
## @value t1.2xlarge
## @value t1.4xlarge
## @value c1.nano
## @value c1.micro
## @value c1.small
## @value c1.medium
## @value c1.large
## @value c1.xlarge
## @value c1.2xlarge
## @value c1.4xlarge
## @value s1.nano
## @value s1.micro
## @value s1.small
## @value s1.medium
## @value s1.large
## @value s1.xlarge
## @value s1.2xlarge
## @value s1.4xlarge
## @value u1.nano
## @value u1.micro
## @value u1.small
## @value u1.medium
## @value u1.large
## @value u1.xlarge
## @value u1.2xlarge
## @value u1.4xlarge
## @value m1.nano
## @value m1.micro
## @value m1.small
## @value m1.medium
## @value m1.large
## @value m1.xlarge
## @value m1.2xlarge
## @value m1.4xlarge
## @value nano
## @value micro
## @value small
## @value medium
## @value large
## @value xlarge
## @value 2xlarge

## @param {int} replicas - Number of Postgres replicas.
replicas: 2

## @param {Resources} [resources] - Explicit CPU and memory configuration for each PostgreSQL replica. When omitted, the preset defined in `resourcesPreset` is applied.
resources: {}

## @param {ResourcesPreset} resourcesPreset="t1.micro" - Default sizing preset used when `resources` is omitted.
resourcesPreset: "t1.micro"

## @param {quantity} size - Persistent Volume Claim size available for application data.
size: 10Gi

## @param {string} storageClass - StorageClass used to store the data.
## @immutable
## @x-cozystack-options {source: storageclass}
storageClass: ""

## @param {bool} external - Enable external access from outside the cluster.
external: false

##
## @enum {string} Version
## @value v18
## @value v17
## @value v16
## @value v15
## @value v14
## @value v13

## @param {Version} version - PostgreSQL major version to deploy
version: v18

##
## @section TLS configuration
##

## @typedef {struct} TLS - TLS configuration for PostgreSQL server connections.
## @field {*bool} enabled - Tri-state switch controlling whether the chart injects the external hostname into the operator-managed CNPG cert via spec.certificates.serverAltDNSNames. When omitted, the chart injects the SAN if `external: true` and skips it otherwise. Set explicitly to `true` to inject regardless of `external` (no-op when `external: false` since there is no external hostname to add). Set to `false` to skip injection. Note that CNPG keeps its built-in TLS on the wire regardless of this flag — this toggle only controls the chart-side SAN injection; to disable PostgreSQL TLS entirely set `postgresql.parameters.ssl = "off"` at the CNPG layer.

## @param {TLS} tls - TLS configuration for server connections.
tls: {}

## @section Application-specific parameters
##

## @typedef {struct} PostgreSQL - PostgreSQL server configuration.
## @field {map[string]intOrString} [parameters] - PostgreSQL server parameters. Values may be strings or integers; integers are coerced to strings by the template (e.g. both `max_connections: 100` and `max_connections: "100"` are accepted). BLOCKED (enable arbitrary code execution): archive_command, restore_command, ssl_passphrase_command, archive_cleanup_command, recovery_end_command, dynamic_library_path, local_preload_libraries, session_preload_libraries, shared_preload_libraries. Do NOT override CloudNativePG-managed parameters: archive_mode, primary_conninfo, wal_level, max_replication_slots.

## @param {PostgreSQL} postgresql - PostgreSQL server configuration.
postgresql:
  parameters:
    max_connections: "100"
## Additional parameters examples:
##   shared_buffers: "1GB"
##   effective_cache_size: "4GB"
##   bgwriter_delay: "200ms"
##   commit_delay: "100"
##   commit_siblings: "5"
##   work_mem: "256MB"
##
## SECURITY: The following parameters are BLOCKED (enable arbitrary code execution):
##   archive_command, restore_command, ssl_passphrase_command, archive_cleanup_command, recovery_end_command (shell commands),
##   dynamic_library_path, local_preload_libraries, session_preload_libraries,
##   shared_preload_libraries (arbitrary .so loading)
##
## IMPORTANT: Do NOT override CloudNativePG-managed parameters:
##   archive_mode, primary_conninfo, wal_level, max_replication_slots
##
## NOTE: Some parameters require pod restart (not just reload):
##   shared_buffers, max_connections, max_prepared_transactions,
##   wal_buffers, max_wal_senders
##
## When shared_buffers is not set and the memory limit is below 512Mi, the
## chart sets it to a quarter of the limit with a 16MB floor, capped at the
## memory request rounded down to whole MiB. Larger limits keep the
## PostgreSQL default of 128MB.

##
## @section Quorum-based synchronous replication
##

## @typedef {struct} Quorum - Quorum configuration for synchronous replication.
## @field {int} minSyncReplicas - Minimum number of synchronous replicas required for commit.
## @field {int} maxSyncReplicas - Maximum number of synchronous replicas allowed (must be less than total replicas).

## @param {Quorum} quorum - Quorum configuration for synchronous replication.
quorum:
  minSyncReplicas: 0
  maxSyncReplicas: 0

##
## @section Users configuration
##

## @typedef {struct} User - User configuration.
## @field {string} [password] - Password for the user.
## @field {bool} [replication] - Whether the user has replication privileges.

## @param {map[string]User} users - Users configuration map.
users: {}
## Example:
## users:
##   user1:
##     password: strongpassword
##   user2:
##     password: hackme
##   airflow:
##     password: qwerty123
##   debezium:
##     replication: true

##
## @section Databases configuration
##

## @typedef {struct} DatabaseRoles - Role assignments for a database.
## @field {[]string} [admin] - List of users with admin privileges.
## @field {[]string} [readonly] - List of users with read-only privileges.

## @typedef {struct} Database - Database configuration.
## @field {DatabaseRoles} [roles] - Roles assigned to users.
## @field {[]string} [extensions] - List of enabled PostgreSQL extensions.

## @param {map[string]Database} databases - Databases configuration map.
databases: {}
## Example:
## databases:
##   myapp:
##     roles:
##       admin:
##       - user1
##       - debezium
##       readonly:
##       - user2
##   airflow:
##     roles:
##       admin:
##       - airflow
##     extensions:
##     - hstore

##
## @section Backup parameters
##

## @typedef {struct} S3CredentialsSecret - Reference to a pre-existing Secret with S3 credentials. Setting `name` makes the chart bind the barman-cloud ObjectStore's `spec.configuration.s3Credentials` directly to that Secret instead of materialising `<release>-s3-creds` from `s3AccessKey`/`s3SecretKey`. Use this to keep credentials out of the Postgres CR's `.spec`.
## @field {string} [name] - Name of the Secret in the application namespace. Empty means the chart materialises `<release>-s3-creds` from `s3AccessKey`/`s3SecretKey`.
## @field {string} [accessKeyIDKey] - Key in the Secret holding the access key ID. Defaults to `AWS_ACCESS_KEY_ID`.
## @field {string} [secretAccessKeyKey] - Key in the Secret holding the secret access key. Defaults to `AWS_SECRET_ACCESS_KEY`.

## @typedef {struct} EndpointCA - Reference to a Secret holding a PEM-encoded CA bundle the barman-cloud plugin should trust when reaching a self-signed S3 endpoint. Required when the cluster's S3 (e.g. cozystack's seaweedfs-s3) presents a certificate not signed by a publicly-trusted CA. Used by both the backup ObjectStore's spec.configuration.endpointCA and the recovery ObjectStore's spec.configuration.endpointCA (referenced from externalClusters[].plugin) so backup *and* recovery can verify TLS.
## @field {string} [name] - Name of the Secret in the application namespace. Empty means no endpointCA is emitted (the plugin uses the system trust store).
## @field {string} [key] - Key within the Secret containing the CA bundle. Defaults to `ca.crt`.

## @typedef {struct} Backup - Backup configuration.
## @field {bool} enabled - Enable regular backups.
## @field {bool} [useSystemBucket] - Opt-in: when true, the chart-emitted `<release>-s3-creds` Secret is skipped AND `spec.plugins` (plus the barman-cloud ObjectStore) is left UNSET in the chart-rendered Cluster — the cozy-default BackupClass driver SSA-applies an ObjectStore (carrying destinationPath/endpointURL/credentials) and patches `spec.plugins` on the live Cluster when the first BackupJob runs. Consequence: plugin WAL archiving is NOT active until that first BackupJob fires; WAL accumulates on the PVC in the meantime, so fire an ad-hoc BackupJob immediately after enabling the flag on existing releases. Use together with the platform `cozy-default` BackupClass — tenants do not need to fill `s3AccessKey`/`s3SecretKey` or `destinationPath`/`endpointURL`. The destination path automatically scopes to `s3://cozy-backups/<namespace>/<release>/`.
## @field {string} [schedule] - Legacy. Cron schedule (CNPG 6-field format) for the chart-emitted ScheduledBackup. Empty means no chart-managed schedule, which is the recommended setup when a `BackupClass` from `backups.cozystack.io` already drives backup orchestration. In the legacy chart-managed flow `spec.plugins` plus the barman-cloud ObjectStore is rendered when `backup.enabled=true` AND `useSystemBucket=false` AND `destinationPath` is non-empty AND inline-or-external creds are supplied; in the platform `useSystemBucket=true` flow the chart skips emitting `spec.plugins` and the CNPG driver SSA-applies the ObjectStore and patches `spec.plugins` onto the live Cluster at first BackupJob time.
## @field {string} [retentionPolicy] - Retention policy (e.g. "30d").
## @field {string} [destinationPath] - DEPRECATED. Per-tenant S3 configuration is superseded by the platform-managed `cozy-default` BackupClass and the `cozy-backups` system bucket. Leave empty for new installations; the BackupClass driver picks up the system-managed coordinates. Kept for in-place upgrade compatibility.
## @field {string} [endpointURL] - DEPRECATED. See `destinationPath`.
## @field {string} [s3AccessKey] - DEPRECATED. Tenants no longer supply S3 keys; the system Bucket Secret is projected into the tenant namespace by the backup controller. Ignored when `s3CredentialsSecret.name` is set or `useSystemBucket` is true. The chart skips materialising `<release>-s3-creds` whenever this field is empty so a default install does not leak placeholder credentials into the tenant namespace.
## @field {string} [s3SecretKey] - DEPRECATED. See `s3AccessKey`.
## @field {S3CredentialsSecret} [s3CredentialsSecret] - DEPRECATED. Pre-existing Secret with S3 credentials. Use the platform-managed `cozy-default` BackupClass instead. When set, the chart references this Secret directly (legacy chart-managed flow). The CNPG backup driver writes this field on restore so credentials never land in the CR `.spec`.
## @field {EndpointCA} [endpointCA] - DEPRECATED. Pre-existing Secret with the CA bundle the barman-cloud plugin should trust when reaching a self-signed S3 endpoint. Used for both backup and bootstrap recovery in the legacy chart-managed flow.

## @param {Backup} backup - Backup configuration.
##
## Note on defaults: destinationPath/endpointURL keep their pre-PR
## placeholder values so existing tenants on the legacy chart-managed
## flow continue to render spec.plugins + a barman-cloud ObjectStore on
## upgrade (the placeholder coordinates never produced working plugin
## WAL archiving, but the CR shape stays compatible with what Flux
## already applied).
##
## BEHAVIOUR CHANGE on upgrade for tenants with backup.enabled=true and
## empty s3AccessKey / s3SecretKey: the pre-PR defaults were the literal
## "<your-access-key>" / "<your-secret-key>" placeholders, so the chart
## still wired the plugin (with junk creds, plugin WAL archiving failing
## at runtime). After this PR the defaults are empty strings,
## $hasInlineCreds is false, and the chart NO LONGER renders the backup
## block at all. Such tenants stop seeing chart-emitted spec.plugins and
## the ObjectStore on the cnpg.io Cluster. Action: either set real
## s3AccessKey/s3SecretKey (legacy flow), set useSystemBucket=true
## (platform flow), or supply s3CredentialsSecret.name (external Secret).
##
## New tenants should set useSystemBucket=true and leave the placeholders
## alone — the chart skips rendering spec.plugins and the ObjectStore
## entirely in that mode and the CNPG driver SSA-applies the ObjectStore
## and patches spec.plugins onto the live Cluster at first BackupJob time.
backup:
  enabled: false
  useSystemBucket: false
  retentionPolicy: 30d
  destinationPath: "s3://bucket/path/to/folder/"
  endpointURL: "http://minio-gateway-service:9000"
  schedule: ""
  s3AccessKey: ""
  s3SecretKey: ""
  s3CredentialsSecret:
    name: ""
    accessKeyIDKey: ""
    secretAccessKeyKey: ""
  endpointCA:
    name: ""
    key: ""

##
## @section Bootstrap (recovery) parameters
##

## @typedef {struct} Bootstrap - Bootstrap configuration for restoring a database cluster from a backup.
## @field {bool} enabled - Whether to restore from a backup.
## @field {string} [recoveryTime] - Timestamp (RFC3339) for point-in-time recovery; empty means latest.
## @field {string} oldName - Previous cluster name before deletion.
## @field {string} [serverName] - Server name (S3 path prefix) used by the original cluster when writing backups; passed to the barman-cloud plugin via `externalClusters[].plugin.parameters.serverName`. Defaults to `bootstrap.oldName`. Set this only when the original cluster wrote backups under an explicit server name that differed from its Kubernetes resource name.
## @field {string} [newServerName] - WAL-archive server name (S3 path prefix) the RESTORED cluster writes to. Must differ from `serverName` (the recovery source) so a restored cluster archives to a fresh, empty prefix and barman-cloud-check-wal-archive passes while it recovers from the source's prefix. The CNPG backup driver sets this on restore; empty means the cluster archives under its own name.

## @param {Bootstrap} bootstrap - Bootstrap configuration.
bootstrap:
  enabled: false
  # example: 2020-11-26 15:22:00.00000+00
  recoveryTime: ""
  oldName: ""
  serverName: ""
  newServerName: ""