Inputs
The following input variables are supported:
arm_nodes_enabled
Description: Whether the database pods can be scheduled on arm64 nodes
Type: bool
Default: true
aws_iam_ip_allow_list
Description: A list of IPs that can use the service account token to authenticate with AWS API
Type: list(string)
Default: n/a
backups_cron_schedule
Description: The cron schedule on which to create CNPG Backup resources
Type: string
Default: "0 0 0 * * *"
backups_force_delete
Description: Whether to delete backups on destroy
Type: bool
Default: false
backups_retention_days
Description: The number of days that backups will be retained
Type: number
Default: 3
burstable_nodes_enabled
Description: Whether the database pods can be scheduled on burstable nodes
Type: bool
Default: true
controller_nodes_enabled
Description: Whether the database pods can be scheduled on controller nodes
Type: bool
Default: false
create_timeout_minutes
Description: The number of minutes to wait for a new database to be created
Type: number
Default: 60
extra_schemas
Description: Extra schemas that were created in the app database
Type: list(string)
Default: []
gc_failed_backups
Description: Whether to delete failed backups after backups_retention_days. By default, CNPG does not delete failed backups.
Type: bool
Default: true
instance_type_anti_affinity_required
Description: Whether to enable anti-affinity to prevent pods from being scheduled on the same instance type
Type: bool
Default: true
monitoring_enabled
Description: Whether to add active monitoring to the deployed systems
Type: bool
Default: false
panfactum_scheduler_enabled
Description: Whether to use the Panfactum pod scheduler with enhanced bin-packing
Type: bool
Default: true
pg_backup_directory
Description: The name of the directory in the backup bucket containing the backups files.
Type: string
Default: "initial"
pg_cluster_namespace
Description: The namespace to deploy to the cluster into
Type: string
Default: n/a
pg_custom_image
Description: Custom PostgreSQL container image to use instead of the default CloudNativePG image.
This allows you to use:
- Pre-built CNPG images with extensions (e.g.,
ghcr.io/cloudnative-pg/postgis:17) - Custom-built images with your own extensions (e.g.,
myregistry.io/postgres:16.9-custom)
When set, this overrides the pg_version variable for image selection.
The image must be compatible with CloudNativePG requirements.
Note: Custom images bypass the ECR pull through cache. Ensure your cluster
has appropriate image pull secrets and registry access configured.
Example building custom image with pgvector:
See https://cloudnative-pg.io/blog/building-images-bake/
Type: string
Default: null
pg_initial_storage_gb
Description: The initial number of gigabytes of storage to provision for the postgres cluster
Type: number
Default: 10
pg_instances
Description: The number of instances to deploy in the postgres cluster
Type: number
Default: 2
pg_maintenance_work_mem_percent
Description: The percent of the overall memory allocation available for database maintenance operations
Type: number
Default: 5
pg_max_connections
Description: The maximum number of connections to each postgres database
Type: number
Default: 100
pg_max_slot_wal_keep_size_gb
Description: Maximum size in gigabytes of WAL files that replication slots can retain before old segments are removed.
Type: number
Default: 10
pg_maximum_cpu_millicores
Description: The maximum amount of cpu to allocate to the postgres pods (in millicores)
Type: number
Default: 10000
pg_maximum_memory_mb
Description: The maximum amount of memory to allocate to the postgres pods (in Mi)
Type: number
Default: 128000
pg_minimum_cpu_millicores
Description: The minimum amount of cpu to allocate to the postgres pods (in millicores)
Type: number
Default: 50
pg_minimum_cpu_update_millicores
Description: The CPU settings for the Postgres won’t be updated until the recommendations from the VPA (if enabled) differ from the current settings by at least this many millicores. This prevents autoscaling thrash.
Type: number
Default: 250
pg_minimum_memory_mb
Description: The minimum amount of memory to allocate to the postgres pods (in Mi)
Type: number
Default: 500
pg_parameters
Description: A map of postgres parameters. See https://cloudnative-pg.io/documentation/1.23/postgresql_conf.
Type: map(string)
Default: {}
pg_recovery_bucket
Description: The name of the S3 bucket containing the backup files which the database will bootstrap from. If not provided, will default to the randomly generated backup bucket.
Type: string
Default: null
pg_recovery_directory
Description: The name of the directory in the backup bucket containing the backup files which the database will bootstrap from.
Type: string
Default: null
pg_recovery_mode_enabled
Description: If true, will attempt to recover the cluster
Type: bool
Default: false
pg_recovery_target_immediate
Description: The backup ID (timestamp) to recover to. Sets CloudNativePG’s recoveryTarget.backupID
and recoveryTarget.targetImmediate=true to stop recovery at the end of the specified backup
without replaying additional WAL files.
Format: YYYYMMDDTHHmmss (e.g., 20251015T121455)
Requires pg_recovery_mode_enabled=true and pg_recovery_directory to be set.
This is mutually exclusive with pg_recovery_target_time.
Type: string
Default: null
pg_recovery_target_time
Description: If provided, will recover the database to the indicated target time in RFC 3339 format rather than to the latest data.
Type: string
Default: null
pg_shared_buffers_percent
Description: The percent of the overall memory allocation dedicated for caching data (avoiding reads to disk)
Type: number
Default: 25
pg_smart_shutdown_timeout
Description: The number of seconds to wait for open connections to close before shutting down postgres nodes
Type: number
Default: 1
pg_storage_increase_gb
Description: The number of GB to increase storage by if free space drops below the threshold
Type: number
Default: 10
pg_storage_increase_threshold_percent
Description: Dropping below this percent of free storage will trigger an automatic increase in storage size
Type: number
Default: 20
pg_storage_limit_gb
Description: The maximum number of gigabytes of storage to provision for the postgres cluster
Type: number
Default: null
pg_switchover_delay
Description: Controls max amount of time that CNPG will wait for data to be synced from primary to replica before forcing the switchover
Type: number
Default: 30
pg_sync_replication_enabled
Description: Whether to use synchronous replication for the streaming replicas (vs async)
Type: bool
Default: false
pg_version
Description: The version of postgres to deploy
Type: string
Default: "16.6-13"
pg_wal_keep_size_gb
Description: The number of gigabytes of WAL files to keep for the cluster
Type: number
Default: 2
pg_work_mem_percent
Description: The percent of the overall memory allocation available to queries for sort and hash operations (intermediate calculations during queries)
Type: number
Default: 25
pgbouncer_application_name_add_host
Description: Add the client host address and port to the application name setting set on connection start.
Type: bool
Default: false
pgbouncer_autodb_idle_timeout
Description: If the automatically created (via “*”) database pools have been unused this many seconds, they are freed.
Type: number
Default: 3600
pgbouncer_client_idle_timeout
Description: Client connections idling longer than this many seconds are closed. This should be larger than the client-side connection lifetime settings, and only used for network problems.
Type: number
Default: 0
pgbouncer_client_login_timeout
Description: If a client connects but does not manage to log in in this amount of time, it will be disconnected. Mainly needed to avoid dead connections stalling SUSPEND and thus online restart.
Type: number
Default: 60
pgbouncer_default_pool_size
Description: How many server connections to allow per user/database pair.
Type: number
Default: 20
pgbouncer_disable_pqexec
Description: Disable the Simple Query protocol (PQexec). Unlike the Extended Query protocol, Simple Query allows multiple queries in one packet, which allows some classes of SQL-injection attacks.
Type: bool
Default: false
pgbouncer_ignore_startup_parameters
Description: A list of startup parameters that PgBouncer should ignore when sent by clients. Useful when clients (e.g., JDBC drivers) send parameters like search_path that PgBouncer does not support.
Type: list(string)
Default:
[ "search_path"]pgbouncer_log_connections
Description: Whether to log each connection.
Type: bool
Default: false
pgbouncer_log_disconnections
Description: Whether to log each disconnection.
Type: bool
Default: false
pgbouncer_log_pooler_errors
Description: Whether to log errors the pooler sends to clients.
Type: bool
Default: true
pgbouncer_max_client_conn
Description: The maximum client connections allowed by pgbouncer
Type: number
Default: 10000
pgbouncer_max_db_connections
Description: Do not allow more than this many server connections per database (regardless of user). This considers the PgBouncer database that the client has connected to, not the PostgreSQL database of the outgoing connection.
Type: number
Default: 0
pgbouncer_max_prepared_statements
Description: When this is set to a non-zero value PgBouncer tracks protocol-level named prepared statements related commands sent by the client in transaction and statement pooling mode. PgBouncer makes sure that any statement prepared by a client is available on the backing server connection. Even when the statement was originally prepared on another server connection.
Type: number
Default: 0
pgbouncer_max_user_connections
Description: Do not allow more than this many server connections per user (regardless of database).
Type: number
Default: 0
pgbouncer_maximum_cpu_millicores
Description: The maximum amount of cpu to allocate to the pgbouncer pods (in millicores)
Type: number
Default: 10000
pgbouncer_maximum_memory_mb
Description: The maximum amount of memory to allocate to the pgbouncer pods (in Mi)
Type: number
Default: 32000
pgbouncer_min_pool_size
Description: Add more server connections to pool if below this number. Improves behavior when the normal load suddenly comes back after a period of total inactivity. The value is effectively capped at the pool size.
Type: number
Default: 0
pgbouncer_minimum_cpu_millicores
Description: The minimum amount of cpu to allocate to the pgbouncer pods (in millicores)
Type: number
Default: 15
pgbouncer_minimum_memory_mb
Description: The minimum amount of memory to allocate to the pgbouncer pods (in Mi)
Type: number
Default: 25
pgbouncer_pool_mode
Description: What pool_mode to run pgbouncer in
Type: string
Default: "session"
pgbouncer_query_timeout
Description: Queries running longer than this amount of seconds are canceled. This should be used only with a slightly smaller server-side statement_timeout, to apply only for network problems.
Type: number
Default: 0
pgbouncer_query_wait_timeout
Description: Maximum time queries are allowed to spend waiting for execution. If the query is not assigned to a server during that time, the client is disconnected. 0 disables. If this is disabled, clients will be queued indefinitely.
Type: number
Default: 120
pgbouncer_read_only_enabled
Description: Whether to enable a pgbouncer deployment in read-only mode
Type: bool
Default: false
pgbouncer_read_write_enabled
Description: Whether to enable a pgbouncer deployment in read-write mode
Type: bool
Default: true
pgbouncer_reserve_pool_size
Description: How many additional connections to allow to a pool (see reserve_pool_timeout). 0 disables.
Type: number
Default: 0
pgbouncer_reserve_pool_timeout
Description: If a client has not been serviced in this amount of seconds, use additional connections from the reserve pool. 0 disables.
Type: number
Default: 5
pgbouncer_server_check_delay
Description: How long to keep released connections available for immediate re-use.
Type: number
Default: 30
pgbouncer_server_connect_timeout
Description: If connection and login don’t finish in this amount of seconds, the connection will be closed.
Type: number
Default: 15
pgbouncer_server_fast_close
Description: Disconnect a server in session pooling mode immediately or after the end of the current transaction if it is in “close_needed” mode (set by RECONNECT, RELOAD that changes connection settings, or DNS change), rather than waiting for the session end. In statement or transaction pooling mode, this has no effect since that is the default behavior there.
Type: bool
Default: false
pgbouncer_server_idle_timeout
Description: If a server connection has been idle more than this many seconds it will be closed. If 0 then this timeout is disabled.
Type: number
Default: 600
pgbouncer_server_lifetime
Description: The pooler will close an unused (not currently linked to any client connection) server connection that has been connected longer than this. Setting it to 0 means the connection is to be used only once, then closed.
Type: number
Default: 3600
pgbouncer_server_login_retry
Description: If login to the server failed, because of failure to connect or from authentication, the pooler waits this many seconds before retrying to connect. During the waiting interval, new clients trying to connect to the failing server will get an error immediately without another connection attempt.
Type: number
Default: 15
pgbouncer_stats_period
Description: Sets how often the averages shown in various SHOW commands are updated and how often aggregated statistics are written to the log.
Type: number
Default: 60
pgbouncer_tcp_keepalive
Description: Turns on basic keepalive with OS defaults.
Type: bool
Default: true
pgbouncer_tcp_keepcnt
Description: Sets tcp_keepcnt
Type: number
Default: null
pgbouncer_tcp_keepidle
Description: Sets tcp_keepidle
Type: number
Default: null
pgbouncer_tcp_keepintvl
Description: Sets tcp_keepintvl
Type: number
Default: null
pgbouncer_tcp_user_timeout
Description: Sets the TCP_USER_TIMEOUT socket option. This specifies the maximum amount of time in milliseconds that transmitted data may remain unacknowledged before the TCP connection is forcibly closed. If set to 0, then operating system’s default is used.
Type: bool
Default: false
pgbouncer_verbose
Description: Increase verbosity. Mirrors the “-v” switch on the command line. For example, using “-v -v” on the command line is the same as verbose=2.
Type: number
Default: 0
pgbouncer_version
Description: The version of the cloudnative-pg/pgbouncer image to use
Type: string
Default: "1.22.1"
pull_through_cache_enabled
Description: Whether to use the ECR pull through cache for the deployed images
Type: bool
Default: true
s3_bucket_access_policy
Description: Additional AWS access policy for the backup S3 bucket. https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document#argument-reference
Type: string
Default: null
spot_nodes_enabled
Description: Whether the database pods can be scheduled on spot nodes
Type: bool
Default: true
vault_credential_lifetime_hours
Description: The lifetime of database credentials generated by Vault
Type: number
Default: 16
voluntary_disruption_window_cron_schedule
Description: The times when disruption windows should start
Type: string
Default: "0 4 * * *"
voluntary_disruption_window_enabled
Description: Whether to confine voluntary disruptions of pods in this module to specific time windows
Type: bool
Default: false
voluntary_disruption_window_seconds
Description: The length of the disruption window in seconds
Type: number
Default: 3600
voluntary_disruptions_enabled
Description: Whether to enable voluntary disruptions of pods in this module.
Type: bool
Default: true
vpa_enabled
Description: Whether to enable the vertical pod autoscaler
Type: bool
Default: true
Outputs
The following outputs are exported:
admin_creds_secret
Description: The name of the Kubernetes Secret holding credentials for the admin role in the PostgreSQL database
backup_bucket_name
Description: The name of the backup bucket
backup_directory
Description: The name of the directory in the backup bucket that contains the PostgreSQL backups and WAL archives
cluster_match_labels
Description: Label selector that matches all PostgreSQL pods
cluster_ro_match_labels
Description: Label selector that matches all read-only replica PostgreSQL pods
cluster_rw_match_labels
Description: Label selector that matches the primary PostgreSQL pod (the read-write node)
database
Description: The database to use for application data
db_admin_role
Description: The Vault role used to get admin credentials for the created PostgreSQL cluster
db_reader_role
Description: The Vault role used to get read-only credentials for the created PostgreSQL cluster
db_schema_admin_roles
Description: Map of schema name to Vault role name for per-schema admin credentials
db_schema_reader_roles
Description: Map of schema name to Vault role name for per-schema read-only credentials
db_schema_superuser_roles
Description: Map of schema name to Vault role name for per-schema superuser credentials
db_superuser_role
Description: The Vault role used to get superuser credentials for the created PostgreSQL cluster
namespace
Description: The Kubernetes namespace for the created resources
pooler_r_match_labels
Description: Label selector that matches all PgBouncer pods that allows read-only access to the PostgreSQL cluster
pooler_r_service_name
Description: The service name of the PgBouncer connection pooler that allows read-only access
pooler_r_service_port
Description: The PostgreSQL port for this service
pooler_rw_match_labels
Description: Label selector that matches all PgBouncer pods that allows read-write access to the PostgreSQL cluster
pooler_rw_service_name
Description: The service name of the PgBouncer connection pooler that allows read-write access
pooler_rw_service_port
Description: The PostgreSQL port for this service
r_service_name
Description: The service name for all db instances that allows read access (includes read-write instances as well)
r_service_port
Description: The PostgreSQL port for this service
reader_creds_secret
Description: The name of the Kubernetes Secret holding credentials for the reader role in the PostgreSQL database
ro_service_name
Description: The service name for the db instances that allows read-only access
ro_service_port
Description: The PostgreSQL port for this service
root_password
Description: The password for root user of the database
root_username
Description: The root user of the database
rw_service_name
Description: The service name of the db node that allows read-write access
rw_service_port
Description: The PostgreSQL port for this service
schema_admin_creds_secrets
Description: Map of schema name to the Kubernetes Secret name holding per-schema admin credentials
schema_reader_creds_secrets
Description: Map of schema name to the Kubernetes Secret name holding per-schema reader credentials
schema_superuser_creds_secrets
Description: Map of schema name to the Kubernetes Secret name holding per-schema superuser credentials
server_certs_secret
Description: The secret containing the server certificates for the database
superuser_creds_secret
Description: The name of the Kubernetes Secret holding credentials for the superuser role in the PostgreSQL database
Providers
The following providers are needed by this module: