mirror of
https://github.com/cozystack/cozystack.git
synced 2026-11-03 10:37:21 +09:00
Andrey KolkovandClaude Fable 5
67db8f7da7
Two defects of the same class — the WAL-archive S3 prefix (serverName) changing or defaulting differently between components: Recovery default regression (review blocker): native CNPG defaulted an absent externalClusters serverName to the entry name (= bootstrap.oldName), but the barman-cloud plugin defaults it to the NEW cluster's name, so a legacy-flow restore with bootstrap.serverName unset would read the wrong S3 prefix (hard failure, or silently restoring another cluster's data). The chart now always emits serverName, defaulting to bootstrap.oldName. Live-cluster serverName flip (found by the gated postgres backup e2e on a real cluster): the chart renders spec.plugins without serverName (effective prefix = cluster name) while a strategy template may name a different one; the driver's ForceOwnership patch then flipped the prefix mid-stream, splitting the WAL archive across two prefixes — the WAL holding the backup's start was lost between them and the restore failed with "WAL not found". The driver now preserves the live Cluster's effective serverName (explicit parameter, or the cluster name when the plugin is attached without one) and only applies the strategy's value to a Cluster with no plugin attached; both charts pin serverName explicitly, and the example strategy no longer sets one. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Andrey Kolkov <androndo@gmail.com>
277 lines
14 KiB
YAML
277 lines
14 KiB
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
|
|
|
|
##
|
|
## @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.
|
|
|
|
## @param {Bootstrap} bootstrap - Bootstrap configuration.
|
|
bootstrap:
|
|
enabled: false
|
|
# example: 2020-11-26 15:22:00.00000+00
|
|
recoveryTime: ""
|
|
oldName: ""
|
|
serverName: ""
|