Skip to content

Commit 803506e

Browse files
jmckulkjkatz
jmckulk
authored and
jkatz
committed
Document the configuration options for pgo-deployer
This ensures every single configuration parameter is record, which leads to the removal of the full_options file
1 parent d6be415 commit 803506e

File tree

2 files changed

+275
-244
lines changed

2 files changed

+275
-244
lines changed

‎docs/content/installation/configuration.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
---
2+
title: "Configuration Reference"
3+
date:
4+
draft: false
5+
weight: 40
6+
---
7+
8+
# PostgreSQL Operator Installer Configuration
9+
10+
The [`pgo-deployer` container]({{< relref "/installation/postgres-operator" >}})
11+
is launched by using a Kubernetes Job manifest and contains many configurable
12+
options.
13+
14+
This section lists the options that you can configure to deploy the PostgreSQL
15+
Operator in your environment. The following list of environmental variables can
16+
be used in the [`postgres-operator.yml`](https://github.com/CrunchyData/postgres-operator/blob/master/installers/kubectl/postgres-operator.yml)
17+
manifest.
18+
19+
## General Configuration
20+
21+
These environmental variables affect the general configuration of the PostgreSQL
22+
Operator.
23+
24+
| Name | Default | Required | Description |
25+
|------|---------|----------|-------------|
26+
| `ARCHIVE_MODE` | true | **Required** | Set to true enable archive logging on all newly created clusters. |
27+
| `ARCHIVE_TIMEOUT` | 60 | **Required** | Set to a value in seconds to configure the timeout threshold for archiving. |
28+
| `BACKREST` | true | **Required** | Set to true enable pgBackRest capabilities on all newly created cluster request. This can be disabled by the client. |
29+
| `BACKREST_AWS_S3_BUCKET` | | | Set to configure the *bucket* used by pgBackRest with Amazon Web Service S3 for backups and restoration in S3. |
30+
| `BACKREST_AWS_S3_ENDPOINT` | | | Set to configure the *endpoint* used by pgBackRest with Amazon Web Service S3 for backups and restoration in S3. |
31+
| `BACKREST_AWS_S3_KEY` | | | Set to configure the *key* used by pgBackRest with Amazon Web Service S3 for backups and restoration in S3. |
32+
| `BACKREST_AWS_S3_REGION` | | | Set to configure the *region* used by pgBackRest with Amazon Web Service S3 for backups and restoration in S3. |
33+
| `BACKREST_AWS_S3_SECRET` | | | Set to configure the *secret* used by pgBackRest with Amazon Web Service S3 for backups and restoration in S3. |
34+
| `BACKREST_PORT` | 2022 | **Required** | Defines the port where pgBackRest will run. |
35+
| `BADGER` | false | **Required** | Set to true enable pgBadger capabilities on all newly created clusters. This can be disabled by the client. |
36+
| `CCP_IMAGE_PREFIX` | crunchydata | **Required** | Configures the image prefix used when creating containers from Crunchy Container Suite. |
37+
| `CCP_IMAGE_PULL_SECRET` | | | Name of a Secret containing credentials for container image registries. |
38+
| `CCP_IMAGE_PULL_MANIFEST` | | | Provide a path to the Secret manifest to be installed in each namespace. (optional) |
39+
| `CCP_IMAGE_TAG` | | **Required** | Configures the image tag (version) used when creating containers from Crunchy Container Suite. |
40+
| `CREATE_RBAC` | true | **Required** | Set to true if the installer should create the RBAC resources required to run the PostgreSQL Operator. |
41+
| `CRUNCHY_DEBUG` | false | | Set to configure Operator to use debugging mode. Note: this can cause sensitive data such as passwords to appear in Operator logs. |
42+
| `DB_NAME` | | | Set to a value to configure the default database name on all newly created clusters. By default, the PostgreSQL Operator will set it to the name of the cluster that is being created. |
43+
| `DB_PASSWORD_AGE_DAYS` | 0 | | Set to a value in days to configure the expiration age on PostgreSQL role passwords on all newly created clusters. If set to "0", this is the same as saying the password never expires |
44+
| `DB_PASSWORD_LENGTH` | 24 | | Set to configure the size of passwords generated by the operator on all newly created roles. |
45+
| `DB_PORT` | 5432 | **Required** | Set to configure the default port used on all newly created clusters. |
46+
| `DB_REPLICAS` | 0 | **Required** | Set to configure the amount of replicas provisioned on all newly created clusters. |
47+
| `DB_USER` | testuser | **Required** | Set to configure the username of the dedicated user account on all newly created clusters. |
48+
| `DEFAULT_INSTANCE_MEMORY` | 128Mi | | Represents the memory request for a PostgreSQL instance. |
49+
| `DEFAULT_PGBACKREST_MEMORY` | 48Mi | | Represents the memory request for a pgBackRest repository. |
50+
| `DEFAULT_PGBOUNCER_MEMORY` | 24Mi | | Represents the memory request for a pgBouncer instance. |
51+
| `DELETE_METRICS_NAMESPACE` | false | | Set to configure whether or not the metrics namespace (defined using variable `metrics_namespace`) is deleted when uninstalling the metrics infrastructure. |
52+
| `DELETE_OPERATOR_NAMESPACE` | false | | Set to configure whether or not the PGO operator namespace (defined using variable `pgo_operator_namespace`) is deleted when uninstalling the PGO. |
53+
| `DELETE_WATCHED_NAMESPACES` | false | | Set to configure whether or not the PGO watched namespaces (defined using variable `namespace`) are deleted when uninstalling the PGO. |
54+
| `DISABLE_AUTO_FAILOVER` | false | | If set, will disable autofail capabilities by default in any newly created cluster |
55+
| `EXPORTERPORT` | 9187 | **Required** | Set to configure the default port used to connect to postgres exporter. |
56+
| `GRAFANA_ADMIN_PASSWORD` | | | Set to configure the login password for the Grafana administrator. |
57+
| `GRAFANA_ADMIN_USERNAME` | admin | | Set to configure the login username for the Grafana administrator. |
58+
| `GRAFANA_INSTALL` | false | | Set to true to install Crunchy Grafana to visualize metrics. |
59+
| `GRAFANA_STORAGE_ACCESS_MODE` | ReadWriteOnce | | Set to the access mode used by the configured storage class for Grafana persistent volumes. |
60+
| `GRAFANA_STORAGE_CLASS_NAME` | fast | | Set to the name of the storage class used when creating Grafana persistent volumes. |
61+
| `GRAFANA_SUPPLEMENTAL_GROUPS` | 65534 | | Set to configure any supplemental groups that should be added to security contexts for Grafana. |
62+
| `GRAFANA_VOLUME_SIZE` | 1G | | Set to the size of persistent volume to create for Grafana. |
63+
| `METRICS` | false | **Required** | Set to true enable performance metrics on all newly created clusters. This can be disabled by the client. |
64+
| `NAMESPACE` | | | Set to a comma delimited string of all the namespaces Operator will manage. |
65+
| `NAMESPACE_MODE` | dynamic | | When installing RBAC using 'create_rbac', the namespace mode determines what Cluster Roles are installed. Options: `dynamic`, `readonly`, and `disabled` |
66+
| `PGBADGERPORT` | 10000 | **Required** | Set to configure the default port used to connect to pgbadger. |
67+
| `PGO_ADD_OS_CA_STORE` | false | **Required** | When true, includes system default certificate authorities. |
68+
| `PGO_ADMIN_PASSWORD` | | **Required** | Configures the pgo administrator password. |
69+
| `PGO_ADMIN_PERMS` | * | **Required** | Sets the access control rules provided by the PostgreSQL Operator RBAC resources for the PostgreSQL Operator administrative account that is created by this installer. Defaults to allowing all of the permissions, which is represented with the * |
70+
| `PGO_ADMIN_ROLE_NAME` | pgoadmin | **Required** | Sets the name of the PostgreSQL Operator role that is utilized for administrative operations performed by the PostgreSQL Operator. |
71+
| `PGO_ADMIN_USERNAME` | admin | **Required** | Configures the pgo administrator username. |
72+
| `PGO_APISERVER_PORT` | 8443 | | Set to configure the port used by the Crunchy PostgreSQL Operator apiserver. |
73+
| `PGO_APISERVER_URL` | https://postgres-operator | | Sets the `pgo_apiserver_url` for the `pgo-client` deployment. |
74+
| `PGO_CLIENT_CERT_SECRET` | pgo.tls | | Sets the secret that the `pgo-client` will use when connecting to the PostgreSQL Operator. |
75+
| `PGO_CLIENT_CONTAINER_INSTALL` | false | | Run the `pgo-client` deployment with the PostgreSQL Operator. |
76+
| `PGO_CLUSTER_ADMIN` | false | **Required** | Determines whether or not the cluster-admin role is assigned to the PGO service account. Must be true to enable PGO namespace & role creation when installing in OpenShift. |
77+
| `PGO_DISABLE_EVENTING` | false | | Set to configure whether or not eventing should be enabled for the Crunchy PostgreSQL Operator installation. |
78+
| `PGO_DISABLE_TLS` | false | | Set to configure whether or not TLS should be enabled for the Crunchy PostgreSQL Operator apiserver. |
79+
| `PGO_IMAGE_PREFIX` | crunchydata | **Required** | Configures the image prefix used when creating containers for the Crunchy PostgreSQL Operator (apiserver, operator, scheduler..etc). |
80+
| `PGO_IMAGE_PULL_SECRET` | | | Name of a Secret containing credentials for container image registries. |
81+
| `PGO_IMAGE_PULL_MANIFEST` | | | Provide a path to the Secret manifest to be installed in each namespace. (optional) |
82+
| `PGO_IMAGE_TAG` | | **Required** | Configures the image tag used when creating containers for the Crunchy PostgreSQL Operator (apiserver, operator, scheduler..etc) |
83+
| `PGO_INSTALLATION_NAME` | devtest | **Required** | The name of the PGO installation. |
84+
| `PGO_NOAUTH_ROUTES` | | | Configures URL routes with mTLS and HTTP BasicAuth disabled. |
85+
| `PGO_OPERATOR_NAMESPACE` | pgo | **Required** | Set to configure the namespace where Operator will be deployed. |
86+
| `PGO_TLS_CA_STORE` | | | Set to add additional Certificate Authorities for Operator to trust (PEM-encoded file). |
87+
| `PGO_TLS_NO_VERIFY` | false | | Set to configure Operator to verify TLS certificates. |
88+
| `PROMETHEUS_INSTALL` | false | | Set to true to install Crunchy Grafana to visualize metrics. |
89+
| `PROMETHEUS_STORAGE_ACCESS_MODE` | ReadWriteOnce | | Set to the access mode used by the configured storage class for Prometheus persistent volumes. |
90+
| `PROMETHEUS_STORAGE_CLASS_NAME` | fast | | Set to the name of the storage class used when creating Prometheus persistent volumes. |
91+
| `PROMETHEUS_SUPPLEMENTAL_GROUPS` | 65534 | | Set to configure any supplemental groups that should be added to security contexts for Prometheus. |
92+
| `PROMETHEUS_VOLUME_SIZE` | 1G | | Set to the size of persistent volume to create for Prometheus. |
93+
| `SCHEDULER_TIMEOUT` | 3600 | **Required** | Set to a value in seconds to configure the `pgo-scheduler` timeout threshold when waiting for schedules to complete. |
94+
| `SERVICE_TYPE` | ClusterIP | | Set to configure the type of Kubernetes service provisioned on all newly created clusters. |
95+
| `SYNC_REPLICATION` | false | | If set to `true` will automatically enable synchronous replication in new PostgreSQL clusters. |
96+
97+
## Storage Settings
98+
99+
The store configuration options defined in this section can be used to specify
100+
the storage configurations that are used by the PostgreSQL Operator.
101+
102+
## Storage Configuration Options
103+
104+
Kubernetes and OpenShift offer support for a wide variety of different storage
105+
types and we provide suggested configurations for different environments. These
106+
storage types can be modified or removed as needed, while additional storage
107+
configurations can also be added to meet the specific storage requirements for
108+
your PostgreSQL clusters.
109+
110+
The following storage variables are utilized to add or modify operator storage
111+
configurations in the with the installer:
112+
113+
| Name | Required | Description |
114+
|------|----------|-------------|
115+
| `storage<ID>_name` | Yes | Set to specify a name for the storage configuration. |
116+
| `storage<ID>_access_mode` | Yes | Set to configure the access mode of the volumes created when using this storage definition. |
117+
| `storage<ID>_size` | Yes | Set to configure the size of the volumes created when using this storage definition. |
118+
| `storage<ID>_class` | Required when using the `dynamic` storage type | Set to configure the storage class name used when creating dynamic volumes. |
119+
| `storage<ID>_supplemental_groups` | Required when using NFS storage | Set to configure any supplemental groups that should be added to security contexts on newly created clusters. |
120+
| `storage<ID>_type` | Yes | Set to either `create` or `dynamic` to configure the operator to create persistent volumes or have them created dynamically by a storage class. |
121+
122+
The ID portion of storage prefix for each variable name above should be an
123+
integer that is used to group the various storage variables into a single
124+
storage configuration.
125+
126+
### Example Storage Configuration
127+
128+
| Name | Value |
129+
|------|-------|
130+
| STORAGE3_NAME | nfsstorage |
131+
| STORAGE3_ACCESS_MODE | ReadWriteMany |
132+
| STORAGE3_SIZE | 1G |
133+
| STORAGE3_TYPE | create |
134+
| STORAGE3_SUPPLEMENTAL_GROUPS | 65534 |
135+
136+
As this example storage configuration shows, integer `3` is used as the ID for
137+
each of the `storage` variables, which together form a single storage
138+
configuration called `nfsstorage`. This approach allows different storage
139+
configurations to be created by defining the proper `storage` variables with a
140+
unique ID for each required storage configuration.
141+
142+
### PostgreSQL Cluster Storage Defaults
143+
144+
You can specify the default storage to use for PostgreSQL, pgBackRest, and other
145+
elements that require storage that can outlast the lifetime of a Pod. While the
146+
PostgreSQL Operator defaults to using `hostpathstorage` to work with
147+
environments that are typically used to test, we recommend using one of the
148+
other storage classes in production deployments.
149+
150+
| Name | Default | Required | Description |
151+
|------|---------|----------|-------------|
152+
| `BACKREST_STORAGE` | hostpathstorage | **Required** | Set the value of the storage configuration to use for the pgbackrest shared repository deployment created when a user specifies pgbackrest to be enabled on a cluster. |
153+
| `BACKUP_STORAGE` | hostpathstorage | **Required** | Set the value of the storage configuration to use for backups, including the storage for pgbackrest repo volumes. |
154+
| `PRIMARY_STORAGE` | hostpathstorage | **Required** | Set to configure which storage definition to use when creating volumes used by PostgreSQL primaries on all newly created clusters. |
155+
| `REPLICA_STORAGE` | hostpathstorage | **Required** | Set to configure which storage definition to use when creating volumes used by PostgreSQL replicas on all newly created clusters. |
156+
| `WAL_STORAGE` | | | Set to configure which storage definition to use when creating volumes used for PostgreSQL Write-Ahead Log |
157+
158+
### Storage Configuration Types
159+
160+
#### Host Path Storage
161+
162+
| Name | Value |
163+
|------|-------|
164+
| STORAGE1_NAME | hostpathstorage |
165+
| STORAGE1_ACCESS_MODE | ReadWriteMany |
166+
| STORAGE1_SIZE | 1G |
167+
| STORAGE1_TYPE | create |
168+
169+
#### Replica Storage
170+
171+
| Name | Value |
172+
|------|-------|
173+
| STORAGE2_NAME | replicastorage |
174+
| STORAGE2_ACCESS_MODE | ReadWriteMany |
175+
| STORAGE2_SIZE | 1G |
176+
| STORAGE2_TYPE | create |
177+
178+
#### NFS Storage
179+
180+
| Name | Value |
181+
|------|-------|
182+
| STORAGE3_NAME | nfsstorage |
183+
| STORAGE3_ACCESS_MODE | ReadWriteMany |
184+
| STORAGE3_SIZE | 1G |
185+
| STORAGE3_TYPE | create |
186+
| STORAGE3_SUPPLEMENTAL_GROUPS | 65534 |
187+
188+
#### NFS Storage Red
189+
190+
| Name | Value |
191+
|------|-------|
192+
| STORAGE4_NAME | nfsstoragered |
193+
| STORAGE4_ACCESS_MODE | ReadWriteMany |
194+
| STORAGE4_SIZE | 1G |
195+
| STORAGE4_MATCH_LABELS | crunchyzone=red |
196+
| STORAGE4_TYPE | create |
197+
| STORAGE4_SUPPLEMENTAL_GROUPS | 65534 |
198+
199+
#### StorageOS
200+
201+
| Name | Value |
202+
|------|-------|
203+
| STORAGE5_NAME | storageos |
204+
| STORAGE5_ACCESS_MODE | ReadWriteOnce |
205+
| STORAGE5_SIZE | 5Gi |
206+
| STORAGE5_TYPE | dynamic |
207+
| STORAGE5_CLASS | fast |
208+
209+
#### Primary Site
210+
211+
| Name | Value |
212+
|------|-------|
213+
| STORAGE6_NAME | primarysite |
214+
| STORAGE6_ACCESS_MODE | ReadWriteOnce |
215+
| STORAGE6_SIZE | 4G |
216+
| STORAGE6_TYPE | dynamic |
217+
| STORAGE6_CLASS | primarysite |
218+
219+
#### Alternate Site
220+
221+
| Name | Value |
222+
|------|-------|
223+
| STORAGE7_NAME | alternatesite |
224+
| STORAGE6_ACCESS_MODE | ReadWriteOnce |
225+
| STORAGE7_SIZE | 4G |
226+
| STORAGE7_TYPE | dynamic |
227+
| STORAGE6_CLASS | alternatesite |
228+
229+
#### GCE
230+
231+
| Name | Value |
232+
|------|-------|
233+
| STORAGE8_NAME | gce |
234+
| STORAGE8_ACCESS_MODE | ReadWriteOnce |
235+
| STORAGE8_SIZE | 300M |
236+
| STORAGE8_TYPE | dynamic |
237+
| STORAGE8_CLASS | standard |
238+
239+
#### Rook
240+
241+
| Name | Value |
242+
|------|-------|
243+
| STORAGE9_NAME | rook |
244+
| STORAGE9_ACCESS_MODE | ReadWriteOnce |
245+
| STORAGE9_SIZE | 1Gi |
246+
| STORAGE9_TYPE | dynamic |
247+
| STORAGE9_CLASS | rook-ceph-block |
248+
249+
250+
## Pod Anti-affinity Settings
251+
This will set the default pod anti-affinity for the deployed PostgreSQL
252+
clusters. Pod Anti-Affinity is set to determine where the PostgreSQL Pods are
253+
deployed relative to each other There are three levels:
254+
255+
- required: Pods *must* be scheduled to different Nodes. If a Pod cannot be
256+
scheduled to a different Node from the other Pods in the anti-affinity
257+
group, then it will not be scheduled.
258+
- preferred (default): Pods *should* be scheduled to different Nodes. There is
259+
a chance that two Pods in the same anti-affinity group could be scheduled to
260+
the same node
261+
- disabled: Pods do not have any anti-affinity rules
262+
263+
The `POD_ANTI_AFFINITY` label sets the Pod anti-affinity for all of the Pods
264+
that are managed by the Operator in a PostgreSQL cluster. In addition to the
265+
PostgreSQL Pods, this also includes the pgBackRest repository and any
266+
pgBouncer pods. By default, the pgBackRest and pgBouncer pods inherit the
267+
value of `POD_ANTI_AFFINITY`, but one can override the default by setting
268+
the `POD_ANTI_AFFINITY_PGBACKREST` and `POD_ANTI_AFFINITY_PGBOUNCER` variables
269+
for pgBackRest and pgBouncer respectively
270+
271+
| Name | Default | Required | Description |
272+
|------|---------|----------|-------------|
273+
| `POD_ANTI_AFFINITY` | preferred | | This will set the default pod anti-affinity for the deployed PostgreSQL clusters. |
274+
| `POD_ANTI_AFFINITY_PGBACKREST` | | | This will set the default pod anti-affinity for the pgBackRest pods. |
275+
| `POD_ANTI_AFFINITY_PGBOUNCER` | | | This will set the default pod anti-affinity for the pgBouncer pods. |

0 commit comments

Comments
 (0)