Container Specifications

Latest Release: 2.1.0 2018-08-13

Introduction

Each of the containers found within the Crunchy Container Suite for PostgreSQL are described in further detail within their respective pages.

The containers and their relationships to the overall architecture are depicted below:

containers

Containers

The following container images are provided with further information:

crunchy-postgres

The crunchy-postgres container executes the Postgres database.

Packages

The container image is built using either the Crunchy Postgres release or the community version based upon a flag in the Makefile.

The crunchy-postgres RPMs are available to Crunchy customers only. The Crunchy release is meant for customers that require enterprise level support.

The PGDG community RPMs can be used as well by simply commenting out the Crunchy yum repo within the Dockerfiles and uncommenting the PGDG yum repo.

setup.sql

The setup.sql script is used to define startup SQL commands that are executed when the database is first created.

Environment Variables

  • PG_MODE - either primary, replica or set, this value determines whether the database is set up as a primary or replica instance. In the case of set, it means the container is started within a StatefulSet in a Kubernetes cluster.

  • PG_PRIMARY_USER - the value to use for the user ID created as primaryuser. The primaryuser has super user privileges.

  • PG_PRIMARY_PASSWORD - the password for the PG_PRIMARY_USER database user

  • PG_USER - the value to use for the user ID created as a normal user. This user is created as part of the setup.sql script upon database creation and allows users to predefine an application user.

  • PG_PASSWORD - the password for the PG_USER database user that is created

  • PG_DATABASE - a database that is created upon database initialization

  • PG_ROOT_PASSWORD - the PostgreSQL user password set up upon database initialization

  • PG_LOCALE - if set, the locale you want to create the database with, if not set, the default locale is used

  • SYNC_REPLICA - if set, this value is used to specify the application_name of a replica that will be used for a synchronous replication

  • CHECKSUMS - if set, this value is used to enable the --data-checksums option when initdb is executed at initialization, if not set, the default is to not enable data checksums

  • ARCHIVE_MODE - if set to on, will enable continuous WAL archiving by setting the value within the postgresql.conf file archive_mode setting, if not set, the default is off

  • ARCHIVE_TIMEOUT - if set to a number (in seconds) , will specify the postgresql.conf archive_timeout setting, if not set, the default value of 60 is used.

  • PGAUDIT_ANALYZE - if set, will cause the container to also start the pgaudit_analyze program in the background

  • PG_PRIMARY_HOST - for when PG_MODE is set, specifies the primary host for setting the primary label

  • PG_REPLICA_HOST - for when PG_MODE is set, specifies the replica host for setting the replica label

  • PGDATA_PATH_OVERRIDE - if set, will cause the container to use a /pgdata path name of your choosing rather than the hostname of the container which is the default. This is useful for a primary in a deployment.

  • XLOGDIR - if set to true, will cause initdb to include --xlogdir=$PGWAL, this will cause a symlink to be created from /pgdata/containername/pg_wal (or pg_xlog if you’re running PG 9.5 or 9.6) to /pgwal/containername-wal

  • TEMP_BUFFERS - default is 8MB, set this value to override this PostgreSQL configuration setting

  • MAX_CONNECTIONS - default is 100, set this value to override this PostgreSQL configuration setting

  • SHARED_BUFFERS - default is 128MB, set this value to override this PostgreSQL configuration setting

  • WORK_MEM - default is 4MB, set this value to override this PostgreSQL configuration setting

  • MAX_WAL_SENDERS - default is 6, set this value to override this PostgreSQL configuration setting

  • ENABLE_SSHD- default is false, set this value to true to enable SSHD

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Features

The following features are supported by the crunchy-postgres container:

  • use of OpenShift secrets

  • ability to restore from a database backup

  • use of custom pg_hba.conf and postgresql.conf files

  • ability to override postgresql.conf configuration parameters

  • ability to override the default setup.sql script

  • ability to set the database locale

  • ability to specify a synchronous replica application_name

  • ability to specify a recovery using PITR and WAL files

  • ability to enable SSHD

Locale Support

Adding locale support to the container is accomplished by running 'yum reinstall glibc_common' within the container, this increases the size of the container image and can be removed if you do not require specific locale support.

You can specify the PG_LOCALE env var which is passed to the initdb command when the initial data files are created, for example:

"name": "PG_LOCALE",
"value": "fr_BE.UTF-8"

By default, no locale is specified when the initdb command is executed.

crunchy-postgres-gis

This container is the same as the crunchy-postgres container except that it includes the following PostgreSQL extensions:

  • postgis

  • pl/r

You can test the pl/r extension by running the following commands for example:

create extension plr;
SELECT * FROM plr_environ();
SELECT load_r_typenames();
SELECT * FROM r_typenames();
SELECT plr_array_accum('{23,35}', 42);
CREATE OR REPLACE FUNCTION plr_array (text, text)
RETURNS text[]
AS '$libdir/plr','plr_array'
LANGUAGE 'c' WITH (isstrict);
select plr_array('hello','world');

crunchy-backup

The crunchy-backup container executes a pg_basebackup against another database container. The backup is a full backup using the standard utility included with PostgreSQL, pg_basebackup.

Backup Location

Backups are stored in a mounted backup volume location, using the database host name plus -backups as a sub-directory, then followed by a unique backup directory based upon a date/timestamp. It is left to the user to perform database backup archives in this current version of the container. This backup location is referenced when performing a database restore.

Dependencies

The container is meant to be using NFS or a similar network file system to persist database backups.

Environment Variables

  • BACKUP_LABEL - when set, will set the label of the backup, if not set the default label used is crunchy-backup

  • BACKUP_HOST - required, this is the database we will be doing the backup for

  • BACKUP_USER - required, this is the database user we will be doing the backup with

  • BACKUP_PASS - required, this is the database password we will be doing the backup with

  • BACKUP_PORT - required, this is the database port we will be doing the backup with

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

crunchy-pgdump

The crunchy-pgdump container executes either a pg_dump or pg_dumpall against another Postgres database.

Dump Location

Dumps are stored in a mounted backup volume location, using the database host name plus -backups as a sub-directory, then followed by a unique backup directory based upon a date/timestamp. It is left to the user to perform database dump archives in this current version of the container.

Dependencies

The container is meant to be using NFS or a similar network file system to persist database dumps.

Environment Variables

REQUIRED ARGS

  • PGDUMP_DB - Database to connect to

  • PGDUMP_HOST - Hostname of the PostgreSQL database to connect to

  • PGDUMP_PASS - Password of the PostgreSQL role used by the pgdump container

  • PGDUMP_USER - PostgreSQL Role used by the pgdump container

OPTIONAL/EXTENDED ARGS

  • PGDUMP_ALL - Run pg_dump instead of pg_dumpall. Default is true, set to false to use pg_dump

  • PGDUMP_CUSTOM_OPTS - Advanced options to pass into pg_dump or pg_dumpall. Default is empty

  • PGDUMP_FILENAME - Name of the file created by the pgdump container. Default is dump

  • PGDUMP_PORT - Port of the PostgreSQL database to connect to. Default is 5432

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs Note: this mode can reveal secrets in logs.

Note: For a list of advanced options for configuring the PGDUMP_CUSTOM_OPTS variable, see the official documentation:

crunchy-collect

Description

Crunchy Collect container provides real time metrics about the PostgreSQL database via an API. These metrics are scrapped and stored by Crunchy Prometheus time-series database and visualized by Crunchy Grafana.

Requirements

This container requires TCP access to the PostgreSQL database to run queries for collecting metrics. The PostgreSQL database to be scrapped is specified by the DATA_SOURCE_NAME environment variable.

Additionally, custom queries to collect metrics can be specified by the user. By mounting a queries.yml file to /conf on the container, additionally metrics can be specified for the API to collect. For an example of a queries.yml file, see here.

Environment Variables

Required:

  • DATA_SOURCE_NAME - The URL for the PostgreSQL server’s data source name. This is required to be in the form of postgresql://.

Optional: * CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

crunchy-prometheus

Description

Prometheus is a multi-dimensional time series data model with an elastic query language. It is used in collaboration with Grafana in this metrics suite. Overall, it’s reliable, manageable, and operationally simple for efficiently storing and analyzing data for large-scale environments. It scraps metrics from exporters such as Crunchy Collect.

The following port is exposed by the crunchy-prometheus container:

  • crunchy-prometheus:9090 - the Prometheus web user interface

Requirements

The Crunchy Prometheus container must be able to reach the Crunchy Collect container to scrape metrics.

By default, Crunchy Prometheus detects which environment its running on (Docker, Kube or OCP) and applies a default configuration. If this container is running on Kube or OCP, it will use the Kubernetes API to discover pods with the label "crunchy-collect": "true". Crunchy Collect container must have this label to be discovered.

For Docker environments the Crunchy Collect hostname must be specified as an environment variable.

A user may define a custom prometheus.yml file and mount to /conf for custom configuration. For a configuration examples, see here.

Environment Variables

Required:

  • COLLECT_HOST - Hostname of Crunchy Collect container. Only required in Docker environments.

Optional:

  • SCRAPE_INTERVAL - default is "5s", set this value to the number of seconds to scrape metrics from exporters.

  • SCRAPE_TIMEOUT - default is "5s", set this value to the number of seconds to timeout when scraping metrics from exporters.

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

crunchy-grafana

Description

Visual dashboards are created from the collected and stored data that crunchy-collect and crunchy-prometheus provides with the crunchy-grafana container, which hosts a web-based graphing dashboard called Grafana.

Grafana is an open-source platform which can then apply the defined metrics and visualize information through various tools. It is extremely flexible with a powerful query and transformation language, producing beautiful and easily understandable graphics to analyze and monitor your data.

By default, Crunchy Grafana will register the Crunchy Prometheus datasource within Grafana and import a premade dashboard for PostgreSQL monitoring.

The following port is exposed by the crunchy-grafana container:

  • crunchy-grafana:3000 - the Grafana web user interface

Requirements

The Crunchy Grafana container must be able to reach the Crunchy Prometheus container.

Users must specify an administrator user and password to provide basic authentication for the web frontend.

Additionally the Prometheus Host and Port are required. If Prometheus uses basic authentication, users must specify the username and password to access Prometheus via environment variables.

Users may define a custom defaults.ini file and mount to /conf for custom configuration. For a configuration examples, see here.

Environment Variables

Required:

  • ADMIN_USER - specifies the administrator user to be used when logging into the web frontend.

  • ADMIN_PASS - specifies the administrator password to be used when logging into the web frontend.

  • PROM_HOST - specifies the Prometheus container hostname for auto registering the prometheus datasource.

  • PROM_PORT - specifies the Prometheus container port for auto registering the prometheus datasource.

Optional:

  • PROM_USER - specifies the Prometheus username, if one is required.

  • PROM_PASS - specifies the Prometheus password, if one is required.

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

crunchy-pgbadger

The crunchy-pgbadger container executes the pgbadger utility. A small http server is running on the container, when a request is made to:

http://<<ip address>>:10000/api/badgergenerate

Environment Variables

Optional:

  • BADGER_TARGET - only used in standalone mode to specify the name of the container, also used to find the location of the database log files in /pgdata/$BADGER_TARGET/pg_log/*.log

  • BADGER_CUSTOM_OPTS - no default, set this value to provide custom flags to pgbadger. For a list of optional flags, see the official pgBadger documentation.

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Features

The following features are supported by the crunchy-pgbadger container:

  • Generate a full report by default

  • Optional custom options for more advanced use cases (such as incremental reports)

  • Report persistence on a volume

crunchy-pgpool

The crunchy-pgpool container executes the pgpool utility. Pgpool can be used to provide a smart PostgreSQL-aware proxy to a PostgreSQL cluster, both primary and replica, so that applications can only have to work with a single database connection.

Postgres replicas are read-only whereas a primary is both read and write capable.

The default pgpool examples use a Secret to hold the set of pgpool configuration files used by the examples. The Secret is mounted into the pgconf volume mount where the container will look to find configuration files. If you do not specify your own configuration files via a Secret then you can specify environment variables to the container that it will attempt to use to configure pgpool, this is not recommended however for a real pgpool deployment.

Environment Variables

  • PG_USERNAME - user to connect to PostgreSQL

  • PG_PASSWORD - user password to connect to PostgreSQL

  • PG_PRIMARY_SERVICE_NAME - database host to connect to for the primary node

  • PG_REPLICA_SERVICE_NAME - database host to connect to for the replica node

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Features

The following features are supported by the crunchy-pgpool container:

  • basic invocation of pgpool

crunchy-watch

crunchy-watch runs as a pod unto itself typically. The watch container essentially does a health check on a primary database container and performs a failover sequence if the primary is not reached.

The watch container has access to a service account that is used inside the container to issue commands to OpenShift.

In Kube 1.5, if a policy file is being used for securing down the Kube cluster, you could possibly need to add a policy to allow the pg-watcher service account access to the Kube API as mentioned here: https://kubernetes.io/docs/admin/authorization/abac/#a-quick-note-on-service-accounts

In Kube 1.6, an equivalent RBAC policy is also possibly required depending on your authorization/authentication configuration. See this link for details on the new RBAC policy mechanism: https://kubernetes.io/docs/admin/authorization/rbac/

For example, you can grant cluster-admin permissions on the pg-watcher service account, in the my-namespace namespace as follows:

kubectl create clusterrolebinding pgwatcher-view-binding --clusterrole=cluster-admin --serviceaccount=my-namespace:pg-watcher

A less wide open policy would be applied like this on Kube 1.6 rbac:

kubectl create rolebinding my-sa-binding --clusterrole=admin --serviceaccount=demo:pg-watcher --namespace=demo
Note
 this kubectl command is only available in Kube 1.6, for prior Kube release such as 1.5 and the alpha RBAC, you will need to specify the role binding in a JSON/YAML file instead of using this command syntax above.

You then reference the SA within the POD spec.

The oc/docker/kubectl commands are included into the container from the host when the container image is built. These commands are used by the watch logic to interact with the replica containers.

Starting with release 1.7.1 crunchy-watch source code is relocated to https://github.com/crunchydata/crunchy-watch

Environment Variables

  • CRUNCHY_WATCH_HEALTHCHECK_INTERVAL - the time to sleep in seconds between checking on the primary

  • CRUNCHY_WATCH_FAILOVER_WAIT - the time to sleep in seconds between triggering the failover and updating its label (default is 40 secs)

  • PG_CONTAINER_NAME - if set, the name of the container to refer to when doing an exec, this is required if you have more than 1 container in your database pod

  • CRUNCHY_WATCH_PRIMARY - the primary service name

  • CRUNCHY_WATCH_REPLICA - the replica service name

  • PG_PRIMARY_PORT - database port to use when checking the database

  • CRUNCHY_WATCH_USERNAME - database user account to use when checking the database using pg_isready utility

  • CRUNCHY_WATCH_DATABASE - database to use when checking the database using pg_isready

  • REPLICA_TO_TRIGGER_LABEL - the pod name of a replica that you want to choose as the new primary in a failover; this will override the normal replica selection

  • CRUNCHY_WATCH_PRE_HOOK - path to an executable file to run before failover is processed.

  • CRUNCHY_WATCH_POST_HOOK - path to an executable file to run after failover is processed.

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Logic

The watch container will watch the primary, if the primary dies, then the watcher will:

  • create the trigger file on the replica that will become the new primary

  • change the labels on the replica to be those of the primary

  • start watching the new primary in case that falls over next

  • look for replicas that have the metadata label value of replicatype=trigger to prefer the failover to. If found, it will use the first replica with that label; if not found, it will use the first replica it finds.

Example of looking for the failover replica:

oc get pod -l name=pg-replica-rc-dc
NAME                     READY     STATUS    RESTARTS   AGE
pg-replica-rc-dc           1/1       Running   2          16m
pg-replica-rc-dc-1-96qs8   1/1       Running   1          16m

oc get pod -l replicatype=trigger
NAME             READY     STATUS    RESTARTS   AGE
pg-replica-rc-dc   1/1       Running   2          16m

crunchy-vacuum

Description

The crunchy-vacuum container allows you to perform a SQL VACUUM job against a PostgreSQL database container. You specify a database to vacuum using various environment variables which are listed below. It is possible to run different vacuum operations either manually or automatically through scheduling.

The crunchy-vacuum image is executed, passed in the Postgres connection parameters to the single-primary PostgreSQL container. The type of vacuum performed is dictated by the environment variables passed into the job.

Environment Variables

The complete set of environment variables read by the crunchy-vacuum job include:

  • VAC_FULL - when set to true adds the FULL parameter to the VACUUM command

  • VAC_TABLE - when set, allows you to specify a single table to vacuum, when not specified, the entire database tables are vacuumed

  • JOB_HOST - required variable is the postgres host we connect to

  • PG_USER - required variable is the postgres user we connect with

  • PG_DATABASE - required variable is the postgres database we connect to

  • PG_PASSWORD - required variable is the postgres user password we connect with

  • PG_PORT - allows you to override the default value of 5432

  • VAC_ANALYZE - when set to true adds the ANALYZE parameter to the VACUUM command

  • VAC_VERBOSE - when set to true adds the VERBOSE parameter to the VACUUM command

  • VAC_FREEZE - when set to true adds the FREEZE parameter to the VACUUM command

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

crunchy-dba

The crunchy-dba container implements a cron scheduler. The purpose of the crunchy-dba container is to offer a way to perform simple DBA tasks that occur on some form of schedule such as backup jobs or running a vacuum on a single Postgres database container.

You can either run the crunchy-dba container as a single pod or include the container within a database pod.

The crunchy-dba container makes use of a Service Account to perform the startup of scheduled jobs. The Kube Job type is used to execute the scheduled jobs with a Restart policy of Never.

Environment Variables

The following environment variables control the actions of crunchy-dba:

  • OSE_PROJECT - required, the OSE project name to log into

  • JOB_HOST - required, the PostgreSQL container name the action will be taken against

  • VAC_SCHEDULE - if set, this will start a vacuum job container. The setting value must be a valid cron expression as described below.

  • BACKUP_SCHEDULE - if set, this will start a backup job container. The setting value must be a valid cron expression as described below.

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

For a vacuum job, you are required to supply the following environment variables:

  • JOB_HOST

  • PG_USER

  • PG_PASSWORD

  • PG_DATABASE - defaults to postgres when not specified

  • PG_PORT - defaults to 5432 when not specified

  • VAC_ANALYZE(optional) - defaults to true when not specified

  • VAC_FULL(optional) - defaults to true when not specified

  • VAC_VERBOSE(optional) - defaults to true when not specified

  • VAC_FREEZE(optional) - defaults to false when not specified

  • VAC_TABLE(optional) - defaults to all tables when not specified, or you can set this value to indicate a single table to vacuum

For a backup job, you are required to supply the following environment variables:

  • JOB_HOST

  • PG_USER - database user used to perform the backup

  • PG_PASSWORD - database user password used to perform the backup

  • PG_PORT - port value used when connecting for a backup to the database

  • BACKUP_PV_CAPACITY - a value like 1Gi is used to define the PV storage capacity

  • BACKUP_PV_PATH - the storage path used to build the PV

  • BACKUP_PV_HOST - the storage host used to build the PV

  • BACKUP_PVC_STORAGE - a value like 75M means to allow 75 megabytes for the PVC used in performing the backup

CRON Expression Format

A cron expression represents a set of times, using 6 space-separated fields.

Table 1. Table Fields
Field name Mandatory? Allowed values Allowed special characters

Seconds

Yes

0-59

* / , -

Minutes

Yes

0-59

* / , -

Hours

Yes

0-23

* / , -

Day of month

Yes

1-31

* / , - ?

Month

Yes

1-12 or JAN-DEC

* / , -

Day of week

Yes

0-6 or SUN-SAT

* / , - ?
Note
 Month and Day-of-week field values are case insensitive. SUN'', Sun'', and ``sun'' are equally accepted.

Special Characters

Asterisk ( * )

The asterisk indicates that the cron expression will match for all values of the field; e.g., using an asterisk in the 5th field (month) would indicate every month.

Slash ( / )

Slashes are used to describe increments of ranges. For example 3-59/15 in the 1st field (minutes) would indicate the 3rd minute of the hour and every 15 minutes thereafter. The form *\/…​'' is equivalent to the form first-last/…​'', that is, an increment over the largest possible range of the field. The form N/…​'' is accepted as meaning N-MAX/…​'', that is, starting at N, use the increment until the end of that specific range. It does not wrap around.

Comma ( , )

Commas are used to separate items of a list. For example, using ``MON,WED,FRI'' in the 5th field (day of week) would mean Mondays, Wednesdays and Fridays.

Hyphen ( - )

Hyphens are used to define ranges. For example, 9-17 would indicate every hour between 9am and 5pm inclusive.

Question mark ( ? )

Question mark may be used instead of '*' for leaving either day-of-month or day-of-week blank.

Predefined schedules

You may use one of several pre-defined schedules in place of a cron expression.

Table 2. Table Predefined Schedules
Entry Description Equivalent To

@yearly (or @annually)

Run once a year, midnight, Jan. 1st

0 0 0 1 1 *

@monthly

Run once a month, midnight, first of month

0 0 0 1 * *

@weekly

Run once a week, midnight on Sunday

0 0 0 * * 0

@daily (or @midnight)

Run once a day, midnight

0 0 0 * * *

@hourly

Run once an hour, beginning of hour

0 0 * * * *

Intervals

You may also schedule a job to execute at fixed intervals. This is supported by formatting the cron spec like this:

@every <duration>

where ``duration'' is a string accepted by time.ParseDuration (http://golang.org/pkg/time/#ParseDuration).

For example, ``@every 1h30m10s'' would indicate a schedule that activates every 1 hour, 30 minutes, 10 seconds.

Note
 The interval does not take the job runtime into account. For example, if a job takes 3 minutes to run, and it is scheduled to run every 5 minutes, it will have only 2 minutes of idle time between each run.

Time zones

All interpretation and scheduling is done in the machines local time zone (as provided by the Go time package (http://www.golang.org/pkg/time). Be aware that jobs scheduled during daylight-savings leap-ahead transitions will not be run!

crunchy-pgbouncer

Crunchy pgBouncer is a lightweight connection pooler for PostgreSQL databases.

Environment Variables

REQUIRED ARGS

  • PGBOUNCER_PASSWORD - the password of the pgbouncer role in PostgreSQL. Must be also set on the primary database.

  • PG_SERVICE - the hostname of the database service

OPTIONAL/EXTENDED ARGS

  • DEFAULT_POOL_SIZE - default 20, how many server connections to allow per user/database pair.

  • MAX_CLIENT_CONN - default 100, maximum number of client connections allowed.

  • MAX_DB_CONNECTIONS - default unlimited, do not allow more than this many connections per-database.

  • MIN_POOL_SIZE - default 0 (disabled), adds more server connections to pool if below this number.

  • POOL_MODE - default session, specifies when a server connection can be reused by other clients. Possible values: session, transaction and statement.

  • RESERVE_POOL_SIZE - default 0 (disabled), how many additional connections to allow to a pool.

  • RESERVE_POOL_TIMEOUT - default 5, if a client has not been serviced in this many seconds, pgbouncer enables use of additional connections from reserve pool. 0 disables.

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Features

The following features are supported by the crunchy-pgbouncer container:

  • Crunchy pgBouncer uses auth_query to authenticate users. This requires only the pgbouncer username and password in users.txt. Automatically generated from environment variables.

  • Mount a custom users.txt and pgbouncer.ini configurations for advanced usage.

  • Tune pooling parameters via environment variables.

  • Connect to the administration database in pgBouncer to view statistics of the target databases.

Restrictions

  • OpenShift: If custom configurations aren’t being mounted, an emptydir volume is required to be mounted at /pgconf.

  • Superusers cannot connect through the connection pooler.

crunchy-backrest-restore

The crunchy-backrest-restore container executes the pgbackrest utility, allowing FULL and DELTA restore capability. See the pgbackrest guide for more details. https://github.com/pgbackrest/pgbackrest

Environment Variables

Required: * STANZA - desired stanza to restore from. For most cases this should be set to db.

Optional: * DELTA - when set to true, this will configure pgBackRest to do a delta restore. Delta restores do not require pgdata directoy to be empty. This will only pull in differences between pgdata and the backup. * BACKREST_CUSTOM_OPTS - pass in custom parameters to pgBackRest for advanced use cases (such as point in time recovery). * CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Features

The following features are supported by the crunchy-backrest-restore container:

  • mount pgbackrest.conf config file via /pgconf volume

  • mount the /backrestrepo for access to pgbackrest archives

Restrictions

  • for configuration, has to have pgbackrest.conf files mounted in /pgconf

  • must have valid pgbackrest archive directory mounted in /backrestrepo

crunchy-pgadmin4

The crunchy-ppgadmin4 container executes the pgadmin4 web application.

The pgadmin4 project is found at the following location: https://www.pgadmin.org/

pgadmin4 provides a web user interface to PostgreSQL databases. A sample screenshot is below:

pgadmin screenshot

Environment Variables

  • PGADMIN_SETUP_EMAIL - required, set this value to the email address used for pgAdmin4 login.

  • PGADMIN_SETUP_PASSWORD - required, set this value to a password used for pgAdmin4 login. This should be a strong password.

  • SERVER_PORT - default is 5050, set this value to a change the port pgAdmin4 listens on.

  • ENABLE_TLS - default is false, set this value to true to enable HTTPS on the pgAdmin4 container. This requires a server.key and server.crt to be mounted on the /certs directory.

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Features

The following features are supported by the crunchy-pgadmin4 container:

  • expose port (5050 by default) which is the web server port

  • mount a certificate and key to the /certs directory and set ENABLE_TLS to true to activate HTTPS mode.

  • Set username and password for login via environment variables.

Restrictions

  • An emptyDir, with write access, must be mounted to the /run/httpd directory in OpenShift.

crunchy-pgrestore

The restore image provides a means of performing a restore of a dump from pg_dump or pg_dumpall via psql or pg_restore to a Postgres container database.

Dump-file Input Location

As the input files for crunchy-pgrestore, files generated by crunchy-pgdump are retrieved in a mounted backup volume location, using the database host name plus -backups as a sub-directory, then followed by a unique backup directory based upon a date/timestamp. It is left to the user to restore database dump archives in this current version of the container.

Dependencies

The container is meant to be using NFS or a similar network file system to retrieve database dumps to be restored via psql or pg_restore.

Environment Variables

REQUIRED ARGS

  • PGRESTORE_DB - Database to connect to

  • PGRESTORE_HOST - Hostname of the PostgreSQL database to connect to

  • PGRESTORE_PASS - Password of the PostgreSQL role used by the pgdump container

  • PGRESTORE_USER - PostgreSQL Role used by the pgdump container

OPTIONAL/EXTENDED ARGS

  • PGDUMP_BACKUP_HOST - Hostname of the PostgreSQL server that was backed up by pgdump container. Used when restoring a backup to a new host.

  • PGRESTORE_BACKUP_TIMESTAMP - Timestamp of the backup to restore from. Default is empty (restores from latest backup)

  • PGRESTORE_CUSTOM_OPTS - Advanced options to pass into pg_restore. Default is empty

  • PGRESTORE_PORT - Port of the PostgreSQL database to connect to. Default is 5432

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs Note: this mode can reveal secrets in logs.

Note: For a list of advanced options for configuring the PGRESTORE_CUSTOM_OPTS variable, see the official documentation:

crunchy-upgrade

The crunchy-upgrade container contains both the 9.5/9.6 and 9.6/10 Postgres packages in order to perform a pg_upgrade from 9.5 to 9.6 or 9.6 to 10 versions.

Environment Variables

  • OLD_DATABASE_NAME - required, refers to the database (pod) name that we want to convert

  • NEW_DATABASE_NAME - required, refers to the database (pod) name that we give to the upgraded database

  • OLD_VERSION - required, the Postgres version of the old database

  • NEW_VERSION - required, the Postgres version of the new database

  • PG_LOCALE - if set, the locale you want to create the database with, if not set, the default locale is used

  • CHECKSUMS - if set, this value is used to enable the --data-checksums option when initdb is executed at initialization, if not set, the default is to not enable data checksums

  • XLOGDIR - if set, initdb will use the specified directory for WAL

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Features

The following features are supported by the crunchy-upgrade container:

  • supports only a pg_upgrade of the Postgres database

  • doesn’t alter the old database files

  • creates the new database directory

Restrictions

  • does NOT support a postgis upgrade currently

  • all environment variables are required

  • supports upgrades from 9.5/9.6 to 10

crunchy-sim

The crunchy-sim container is a simple traffic simulator for PostgreSQL.

Environment Variables

  • PGSIM_HOST - required, the PostgreSQL host address

  • PGSIM_PORT - required, the PostgreSQL host port

  • PGSIM_USERNAME - required, the PostgreSQL username

  • PGSIM_PASSWORD - required, the PostgreSQL password

  • PGSIM_DATABASE - required, the database to connect

  • PGSIM_INTERVAL - required, The units of the simulation interval

  • PGSIM_MININTERVAL - required, the minimum interval value

  • PGSIM_MAXINTERVAL - requited, the maximum interval value

  • CRUNCHY_DEBUG - default is false, set this value to true to debugging in logs. Note: this mode can reveal secrets in logs.

Valid values for PGSIM_INTERVAL are as follows:

  • millisecond

  • second

  • minute

Features

  • Creates a single connection to PostgreSQL and will execute queries over a specified interval range.

  • Queries are specified through a simple YAML file. Each query is a name-value pair and can span multiple lines by utilizing scalar notation (|'' or >'') as defined by the YAML spec.

  • Queries are randomly chosen for execution.

Restrictions

  • Only one connection is created for all queries. >>>>>>> aae224745f5caf481c142b4ccbf3332ab4f45f8e