From 294e6f9cec33f115417400341d4f9695e354442c Mon Sep 17 00:00:00 2001 From: Itay Grudev Date: Wed, 31 Jan 2024 21:24:51 +0200 Subject: [PATCH] Improved chart documentation Signed-off-by: Itay Grudev --- charts/cloudnative-pg/README.md | 2 +- charts/cluster/README.md | 249 +++++++++++++++++--------------- charts/cluster/README.md.gotmpl | 147 +++++++++++++++++++ charts/cluster/values.yaml | 85 ++++++----- 4 files changed, 327 insertions(+), 156 deletions(-) create mode 100644 charts/cluster/README.md.gotmpl diff --git a/charts/cloudnative-pg/README.md b/charts/cloudnative-pg/README.md index 21bf54d80..38afc5d73 100644 --- a/charts/cloudnative-pg/README.md +++ b/charts/cloudnative-pg/README.md @@ -2,7 +2,7 @@ ![Version: 0.19.1](https://img.shields.io/badge/Version-0.19.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 1.21.1](https://img.shields.io/badge/AppVersion-1.21.1-informational?style=flat-square) -CloudNativePG Helm Chart +CloudNativePG Operator Helm Chart **Homepage:** diff --git a/charts/cluster/README.md b/charts/cluster/README.md index b54c828de..d334c4389 100644 --- a/charts/cluster/README.md +++ b/charts/cluster/README.md @@ -1,18 +1,13 @@ -> **Warning** -> ### This chart is under active development. -> ### Do not use in production! +# cluster -## Features that require feedback +![Version: 0.0.1](https://img.shields.io/badge/Version-0.0.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) -Please raise a ticket tested any of the following features and they have worked. -Alternatively a ticket and a PR if you have found that something needs a change to work properly. +> **Warning** +> ### This chart is under active development. +> ### Advised caution when using in production! -- [ ] Azure Cloud Storage Backups -- [ ] Google Cloud Storage Backups -- [ ] Azure Cloud Storage Recovery -- [ ] Google Cloud Storage Recovery - -## A note on the chart's purpose +A note on the chart's purpose +----------------------------- This is an opinionated chart that is designed to provide a subset of simple, stable and safe configurations using the CloudNativePG operator. It is designed to provide a simple way to perform recovery operations to decrease your RTO. @@ -24,14 +19,15 @@ you either: * create your own chart * use Kustomize to modify the chart's resources -**_Note_** that the latter option carries it's own risks as the chart configuration may change, especially before it +**_Note_** that the latter option carries it's own risks as the chart configuration may change, especially before it reaches a stable release. That being said, we welcome PRs that improve the chart, but please keep in mind that we don't plan to support every single configuration that the operator provides and we may reject PRs that add too much complexity and maintenance difficulty to the chart. -## Getting Started +Getting Started +--------------- ### Installing the Operator Skip this step if the CNPG operator is already installed in your cluster. @@ -39,25 +35,26 @@ Skip this step if the CNPG operator is already installed in your cluster. ```console helm repo add cnpg https://cloudnative-pg.github.io/charts helm upgrade --install cnpg \ - --namespace cnpg-system \ - --create-namespace \ - cnpg/cloudnative-pg +--namespace cnpg-system \ +--create-namespace \ +cnpg/cloudnative-pg ``` -### Setting up a PostgreSQL Cluster +### Setting up a CNPG Cluster ```console helm repo add cnpg https://cloudnative-pg.github.io/charts helm upgrade --install cnpg \ - --namespace cnpg-database \ - --create-namespace \ - --values values.yaml \ - cnpg/cluster +--namespace cnpg-database \ +--create-namespace \ +--values values.yaml \ +cnpg/cluster ``` A more detailed guide can be found here: [Getting Started](docs/Getting Started.md) -## Cluster Configuration +Cluster Configuration +--------------------- ### Database types @@ -88,111 +85,129 @@ providers are supported: Additionally you can specify the following parameters: * `backups.retentionPolicy` - The retention policy for backups. Defaults to `30d`. * `backups.scheduledBackups` - An array of scheduled backups containing a name and a crontab schedule. Example: - ```yaml - backups: - scheduledBackups: - - name: daily-backup - schedule: "0 0 0 * * *" # Daily at midnight - backupOwnerReference: self - ``` +```yaml +backups: + scheduledBackups: + - name: daily-backup + schedule: "0 0 0 * * *" # Daily at midnight + backupOwnerReference: self +``` Each backup adapter takes it's own set of parameters, listed in the [Configuration options](#Configuration-options) section below. Refer to the table for the full list of parameters and place the configuration under the appropriate key: `backup.s3`, `backup.azure`, or `backup.google`. -## Recovery +Recovery +-------- There is a separate document outlining the recovery procedure here: **[Recovery](docs/recovery.md)** -## Examples +Examples +-------- There are several configuration examples in the [examples](examples) directory. Refer to them for a basic setup and refer to the [CloudNativePG Documentation](https://cloudnative-pg.io/documentation/current/) for more advanced configurations. -## TODO -* IAM Role for S3 Service Account -* Automatic provisioning of a Grafana Dashboard +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| backups.azure.connectionString | string | `""` | | +| backups.azure.containerName | string | `""` | | +| backups.azure.inheritFromAzureAD | bool | `false` | | +| backups.azure.path | string | `"/"` | | +| backups.azure.serviceName | string | `"blob"` | | +| backups.azure.storageAccount | string | `""` | | +| backups.azure.storageKey | string | `""` | | +| backups.azure.storageSasToken | string | `""` | | +| backups.destinationPath | string | `""` | Overrides the provider specific default path. Defaults to: S3: s3:// Azure: https://..core.windows.net/ Google: gs:// | +| backups.enabled | bool | `false` | You need to configure backups manually, so backups are disabled by default. | +| backups.endpointURL | string | `""` | Overrides the provider specific default endpoint. Defaults to: S3: https://s3..amazonaws.com" | +| backups.google.applicationCredentials | string | `""` | | +| backups.google.bucket | string | `""` | | +| backups.google.gkeEnvironment | bool | `false` | | +| backups.google.path | string | `"/"` | | +| backups.provider | string | `"s3"` | One of `s3`, `azure` or `google` | +| backups.retentionPolicy | string | `"30d"` | Retention policy for backups | +| backups.s3.accessKey | string | `""` | | +| backups.s3.bucket | string | `""` | | +| backups.s3.path | string | `"/"` | | +| backups.s3.region | string | `""` | | +| backups.s3.secretKey | string | `""` | | +| backups.scheduledBackups[0].backupOwnerReference | string | `"self"` | Backup owner reference | +| backups.scheduledBackups[0].name | string | `"daily-backup"` | Scheduled backup name | +| backups.scheduledBackups[0].schedule | string | `"0 0 0 * * *"` | Schedule in cron format | +| cluster.additionalLabels | object | `{}` | | +| cluster.affinity | object | `{"topologyKey":"topology.kubernetes.io/zone"}` | Affinity/Anti-affinity rules for Pods See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-AffinityConfiguration | +| cluster.annotations | object | `{}` | | +| cluster.certificates | string | `nil` | The configuration for the CA and related certificates See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-CertificatesConfiguration | +| cluster.enableSuperuserAccess | bool | `true` | When this option is enabled, the operator will use the SuperuserSecret to update the postgres user password. If the secret is not present, the operator will automatically create one. When this option is disabled, the operator will ignore the SuperuserSecret content, delete it when automatically created, and then blank the password of the postgres user by setting it to NULL. | +| cluster.imageName | string | `""` | Name of the container image, supporting both tags (:) and digests for deterministic and repeatable deployments: :@sha256: | +| cluster.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images | +| cluster.imagePullSecrets | list | `[]` | The list of pull secrets to be used to pull the images See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-LocalObjectReference | +| cluster.initdb | object | `{}` | BootstrapInitDB is the configuration of the bootstrap process when initdb is used See: https://cloudnative-pg.io/documentation/current/bootstrap/ See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-bootstrapinitdb | +| cluster.instances | int | `3` | Number of instances | +| cluster.logLevel | string | `"info"` | The instances' log level, one of the following values: error, warning, info (default), debug, trace | +| cluster.monitoring.customQueries | list | `[]` | | +| cluster.monitoring.enablePodMonitor | bool | `false` | | +| cluster.postgresql | string | `nil` | Configuration of the PostgreSQL server See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-PostgresConfiguration | +| cluster.primaryUpdateMethod | string | `"switchover"` | Method to follow to upgrade the primary server during a rolling update procedure, after all replicas have been successfully updated. It can be switchover (default) or in-place (restart). | +| cluster.primaryUpdateStrategy | string | `"unsupervised"` | Strategy to follow to upgrade the primary server during a rolling update procedure, after all replicas have been successfully updated: it can be automated (unsupervised - default) or manual (supervised) | +| cluster.priorityClassName | string | `""` | | +| cluster.resources | string | `nil` | Resources requirements of every generated Pod. Please refer to https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for more information. We strongly advise you use the same setting for limits and requests so that your cluster pods are given a Guaranteed QoS. See: https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/ | +| cluster.storage.size | string | `"8Gi"` | | +| cluster.storage.storageClass | string | `""` | | +| cluster.superuserSecret | string | `""` | | +| fullnameOverride | string | `""` | Override the full name of the chart | +| mode | string | `"standalone"` | Cluster mode of operation. Available modes: * `standalone` - default mode. Creates new or updates an existing CNPG cluster. * `replica` - Creates a replica cluster from an existing CNPG cluster. # TODO * `recovery` - Same as standalone but creates a cluster from a backup, object store or via pg_basebackup. | +| nameOverride | string | `""` | Override the name of the chart | +| pooler.enabled | bool | `false` | Whether to enable PgBouncer | +| pooler.instances | int | `3` | Number of PgBouncer instances | +| pooler.parameters | object | `{"default_pool_size":"25","max_client_conn":"1000"}` | PgBouncer configuration parameters | +| pooler.poolMode | string | `"transaction"` | PgBouncer pooling mode | +| recovery.azure.connectionString | string | `""` | | +| recovery.azure.containerName | string | `""` | | +| recovery.azure.inheritFromAzureAD | bool | `false` | | +| recovery.azure.path | string | `"/"` | | +| recovery.azure.serviceName | string | `"blob"` | | +| recovery.azure.storageAccount | string | `""` | | +| recovery.azure.storageKey | string | `""` | | +| recovery.azure.storageSasToken | string | `""` | | +| recovery.backupName | string | `""` | Backup Recovery Method | +| recovery.clusterName | string | `""` | Object Store Recovery Method | +| recovery.destinationPath | string | `""` | Overrides the provider specific default path. Defaults to: S3: s3:// Azure: https://..core.windows.net/ Google: gs:// | +| recovery.endpointURL | string | `""` | Overrides the provider specific default endpoint. Defaults to: S3: https://s3..amazonaws.com" Leave empty if using the default S3 endpoint | +| recovery.google.applicationCredentials | string | `""` | | +| recovery.google.bucket | string | `""` | | +| recovery.google.gkeEnvironment | bool | `false` | | +| recovery.google.path | string | `"/"` | | +| recovery.method | string | `"backup"` | Available recovery methods: * `backup` - Recovers a CNPG cluster from a CNPG backup (PITR supported) Needs to be on the same cluster in the same namespace. * `object_store` - Recovers a CNPG cluster from a barman object store (PITR supported). * `pg_basebackup` - Recovers a CNPG cluster viaa streaming replication protocol. Useful if you want to migrate databases to CloudNativePG, even from outside Kubernetes. # TODO | +| recovery.pitrTarget.time | string | `""` | Time in RFC3339 format | +| recovery.provider | string | `"s3"` | One of `s3`, `azure` or `google` | +| recovery.s3.accessKey | string | `""` | | +| recovery.s3.bucket | string | `""` | | +| recovery.s3.path | string | `"/"` | | +| recovery.s3.region | string | `""` | | +| recovery.s3.secretKey | string | `""` | | +| type | string | `"postgresql"` | Type of the CNPG database. Available types: * `postgresql` * `postgis` | + +## Maintainers + +| Name | Email | Url | +| ---- | ------ | --- | +| itay-grudev | | | + +Features that require feedback +------------------------------ + +Please raise a ticket tested any of the following features and they have worked. +Alternatively a ticket and a PR if you have found that something needs a change to work properly. + +- [ ] Google Cloud Storage Backups +- [ ] Google Cloud Storage Recovery + +TODO +---- +* IAM Role for S3 Service Account * Automatic provisioning of a Alert Manager configuration -## Configuration options - -| Parameter | Default | Description | -|-------------------------------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `nameOverride` | `""` | Override the name of the chart | -| `fullnameOverride` | `""` | Override the full name of the chart | -| `type` | `postgresql` | The type of the CNPG database. Can be on of: `postgresql`, `postgis` | -| `mode` | `standalone` | The mode of the CNPG database. Can be on of: `standalone`, `replica`, `recovery` | -| `recovery.method` | `"backup"` | The recovery method to use. Can be one of: `backup`, `object_store`, `pg_basebackup` | -| `recovery.pitrTarget.time` | `""` | Point in time recovery target time in RFC3339 format. | -| `recovery.backupName` | `""` | Backup Name when performing a recovery from a backup. | -| `recovery.clusterName` | `""` | Name of the original cluster when performing a recovery from a Barman Object Store. | -| `recovery.endpointURL` | `""` | Endpoint to be used to download data from the cloud, overriding the automatic endpoint discovery. | -| `recovery.destinationPath` | `""` | The path where to store the backup (i.e. s3://bucket/path/to/folder) this path, with different destination folders, will be used for WALs and for data. | -| `recovery.provider` | `""` | The cloud provider to use for the recovery. Can be one of: `s3`, `azure`, `google`. | -| `recovery.s3.region` | `""` | The S3 region to be used for recovery. | -| `recovery.s3.bucket` | `""` | The S3 bucket to be used for recovery. | -| `recovery.s3.path` | `"/"` | The S3 path to be used for recovery. | -| `recovery.s3.accessKey` | `""` | The S3 access key to be used for recovery. | -| `recovery.s3.secretKey` | `""` | The S3 secret key to be used for recovery. | -| `recovery.azure.path` | `"/"` | The Azure path to be used for recovery. | -| `recovery.azure.connectionString` | `""` | The Azure connection string to be used for recovery. | -| `recovery.azure.storageAccount` | `""` | The storage account where to upload data. | -| `recovery.azure.storageKey` | `""` | The storage account key to be used in conjunction with the storage account name. | -| `recovery.azure.storageSasToken` | `""` | A shared-access-signature to be used in conjunction with the storage account name. | -| `recovery.azure.containerName` | `""` | The Azure container name to use for recovery. | -| `recovery.azure.serviceName` | `blob` | The Azure service name to use for recovery. | -| `recovery.azure.inheritFromAzureAD` | `false` | Use the Azure AD based authentication without providing explicitly the keys. | -| `recovery.google.path` | `"/"` | The Google path to be used for recovery. | -| `recovery.google.bucket` | `""` | The Google bucket to be used for recovery. | -| `recovery.google.gkeEnvironment` | `false` | If set to true, will presume that it's running inside a GKE environment, default to false. | -| `recovery.google.applicationCredentials` | `""` | The secret containing the Google Cloud Storage JSON file with the credentials. | -| `cluster.instances` | `1` | The number of instances to deploy. | -| `cluster.imageName` | Depends on `type` | Name of the container image, supporting both tags and digests for deterministic and repeatable deployments: ` :@sha256:` | -| `cluster.imagePullPolicy` | `IfNotPresent` | The image pull policy to use. | -| `cluster.imagePullSecrets` | `[]` | The image pull secrets to use. | -| `cluster.storage.size` | `8Gi` | The size of the persistent volume to use. | -| `cluster.storage.storageClass` | `""` | The storage class to use for the persistent volume. | -| `cluster.resources` | `{}` | The resources to allocate for the container. **_Note:_** You are should use the same setting for Resources and Limits to ensure Guaranteed QoS. | -| `cluster.priorityClassName` | `""` | The priority class name to use for the container. | -| `cluster.primaryUpdateMethod` | `switchover` | It can be `switchover` (default) or `in-place` (restart). | -| `cluster.primaryUpdateStrategy` | `unsupervised` | Strategy for upgrading the primary server during a rolling update procedure, after replicas have been updated: it can be `unsupervised` (default) or `supervised` (manual). | -| `cluster.logLevel` | `info` | The log level to use. One of the following values: `error`, `warning`, `info` (default), `debug`, `trace`. | -| `cluster.affinity.topologyKey` | `topology.kubernetes.io/zone` | Affinity/Anti-affinity rules for Pods. See [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) for more details. | -| `cluster.certificates` | `{}` | The configuration for the CA and related certificates. See [CertificatesConfiguration](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-CertificatesConfiguration). | -| `cluster.enableSuperuserAccess` | `true` | Enable superuser access to the database. | -| `cluster.superuserSecret` | `""` | Superuser password. If not provided, a random password will be generated. | -| `cluster.monitoring.enablePodMonitor` | `true` | Pod monitoring configuration. See [Monitoring](https://cloudnative-pg.io/documentation/current/monitoring/). | -| `cluster.monitoring.customQueries` | `[]` | Custom monitoring metrics. See [Monitoring](https://cloudnative-pg.io/documentation/current/monitoring/). | -| `cluster.postgresql` | `{}` | Configuration of the PostgreSQL server. See [PostgreSQL Configuration](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-PostgresConfiguration). | -| `cluster.initSQL` | `[]` | SQL Queries run during the initialization of the cluster. | -| `cluster.additionalLabels` | `{}` | | -| `cluster.annotations` | `{}` | | -| `backups.enabled` | `false` | Whether to enable backups. | -| `backups.scheduledBackups[].name` | `` | Scheduled Backup Name. | -| `backups.scheduledBackups[].schedule` | `` | Cron Schedule syntax. | -| `backups.scheduledBackups[].backupOwnerReference` | `self` | Indicates which ownerReference should be put inside the created backup resources. See [ScheduledBackupSpec](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-ScheduledBackup). | -| `backups.retentionPolicy` | `"30d"` | Retention policy to be used for backups and WALs (i.e. '60d'). The retention policy is expressed in the form of XXu where XX is a positive integer and u is in [dwm] - days, weeks, months. | -| `backups.endpointURL` | `""` | Endpoint to be used to upload data to the cloud, overriding the automatic endpoint discovery. | -| `backups.destinationPath` | `""` | The path where to store the backup (i.e. s3://bucket/path/to/folder) this path, with different destination folders, will be used for WALs and for data. | -| `backups.provider` | `""` | The cloud provider to use for the recovery. Can be one of: `s3`, `azure`, `google`. | -| `backups.s3.region` | `""` | The S3 region to be used for backups. | -| `backups.s3.bucket` | `""` | The S3 bucket to be used for backups. | -| `backups.s3.path` | `"/"` | The S3 path to be used for backups. | -| `backups.s3.accessKey` | `""` | The S3 access key to be used for backups. | -| `backups.s3.secretKey` | `""` | The S3 secret key to be used for backups. | -| `backups.azure.path` | `"/"` | The Azure path to be used for backups. | -| `backups.azure.connectionString` | `""` | The Azure connection string to be used for backups. | -| `backups.azure.storageAccount` | `""` | The storage account where to upload data. | -| `backups.azure.storageKey` | `""` | The storage account key to be used in conjunction with the storage account name. | -| `backups.azure.storageSasToken` | `""` | A shared-access-signature to be used in conjunction with the storage account name. | -| `backups.azure.containerName` | `""` | The Azure container name to use for backups. | -| `backups.azure.serviceName` | `blob` | The Azure service name to use for backups. | -| `backups.azure.inheritFromAzureAD` | `false` | Use the Azure AD based authentication without providing explicitly the keys. | -| `backups.google.path` | `"/"` | The Google path to be used for backups. | -| `backups.google.bucket` | `""` | The Google bucket to be used for backups. | -| `backups.google.gkeEnvironment` | `false` | If set to true, will presume that it's running inside a GKE environment, default to false. | -| `backups.google.applicationCredentials` | `""` | The secret containing the Google Cloud Storage JSON file with the credentials | - -## LICENSE - -Apache License, Version 2.0 diff --git a/charts/cluster/README.md.gotmpl b/charts/cluster/README.md.gotmpl new file mode 100644 index 000000000..1fa8ac19c --- /dev/null +++ b/charts/cluster/README.md.gotmpl @@ -0,0 +1,147 @@ +{{ template "chart.header" . }} + + +{{ template "chart.deprecationWarning" . }} + + +{{ template "chart.badgesSection" . }} + + +> **Warning** +> ### This chart is under active development. +> ### Advised caution when using in production! + + +A note on the chart's purpose +----------------------------- + +This is an opinionated chart that is designed to provide a subset of simple, stable and safe configurations using the +CloudNativePG operator. It is designed to provide a simple way to perform recovery operations to decrease your RTO. + +It is not designed to be a one size fits all solution. If you need a more complicated setup we strongly recommend that +you either: + +* use the operator directly +* create your own chart +* use Kustomize to modify the chart's resources + +**_Note_** that the latter option carries it's own risks as the chart configuration may change, especially before it +reaches a stable release. + +That being said, we welcome PRs that improve the chart, but please keep in mind that we don't plan to support every +single configuration that the operator provides and we may reject PRs that add too much complexity and maintenance +difficulty to the chart. + + +Getting Started +--------------- + +### Installing the Operator +Skip this step if the CNPG operator is already installed in your cluster. + +```console +helm repo add cnpg https://cloudnative-pg.github.io/charts +helm upgrade --install cnpg \ +--namespace cnpg-system \ +--create-namespace \ +cnpg/cloudnative-pg +``` + +### Setting up a CNPG Cluster + +```console +helm repo add cnpg https://cloudnative-pg.github.io/charts +helm upgrade --install cnpg \ +--namespace cnpg-database \ +--create-namespace \ +--values values.yaml \ +cnpg/cluster +``` + +A more detailed guide can be found here: [Getting Started](docs/Getting Started.md) + + +Cluster Configuration +--------------------- + +### Database types + +Currently the chart supports two database types. These are configured via the `type` parameter. These are: +* `postgresql` - A standard PostgreSQL database. +* `postgis` - A PostgreSQL database with the PostGIS extension installed. + +Depending on the type the chart will use a different Docker image and fill in some initial setup, like extension installation. + +### Modes of operation + +The chart has three modes of operation. These are configured via the `mode` parameter: +* `standalone` - Creates new or updates an existing CNPG cluster. This is the default mode. +* `replica` - Creates a replica cluster from an existing CNPG cluster. **_Note_ that this mode is not yet supported.** +* `recovery` - Recovers a CNPG cluster from a backup, object store or via pg_basebackup. + +### Backup configuration + +CNPG implements disaster recovery via [Barman](https://pgbarman.org/). The following section configures the barman object +store where backups will be stored. Barman performs backups of the cluster filesystem base backup and WALs. Both are +stored in the specified location. The backup provider is configured via the `backups.provider` parameter. The following +providers are supported: + +* S3 or S3-compatible stores, like MinIO +* Microsoft Azure Blob Storage +* Google Cloud Storage + +Additionally you can specify the following parameters: +* `backups.retentionPolicy` - The retention policy for backups. Defaults to `30d`. +* `backups.scheduledBackups` - An array of scheduled backups containing a name and a crontab schedule. Example: +```yaml +backups: + scheduledBackups: + - name: daily-backup + schedule: "0 0 0 * * *" # Daily at midnight + backupOwnerReference: self +``` + +Each backup adapter takes it's own set of parameters, listed in the [Configuration options](#Configuration-options) section +below. Refer to the table for the full list of parameters and place the configuration under the appropriate key: `backup.s3`, +`backup.azure`, or `backup.google`. + + +Recovery +-------- + +There is a separate document outlining the recovery procedure here: **[Recovery](docs/recovery.md)** + + +Examples +-------- + +There are several configuration examples in the [examples](examples) directory. Refer to them for a basic setup and +refer to the [CloudNativePG Documentation](https://cloudnative-pg.io/documentation/current/) for more advanced configurations. + + +{{ template "chart.requirementsSection" . }} + + +{{ template "chart.valuesSection" . }} + + +{{ template "chart.maintainersSection" . }} + + +Features that require feedback +------------------------------ + +Please raise a ticket tested any of the following features and they have worked. +Alternatively a ticket and a PR if you have found that something needs a change to work properly. + +- [ ] Google Cloud Storage Backups +- [ ] Google Cloud Storage Recovery + + +TODO +---- +* IAM Role for S3 Service Account +* Automatic provisioning of a Alert Manager configuration + + +{{ template "helm-docs.versionFooter" . }} diff --git a/charts/cluster/values.yaml b/charts/cluster/values.yaml index 225513894..dec1fc9b4 100644 --- a/charts/cluster/values.yaml +++ b/charts/cluster/values.yaml @@ -1,50 +1,53 @@ +# -- Override the name of the chart nameOverride: "" +# -- Override the full name of the chart fullnameOverride: "" ### -# Type of the CNPG database. Available types: +# -- Type of the CNPG database. Available types: # * `postgresql` # * `postgis` type: postgresql ### -# Cluster mode of operation. Available modes: +# -- Cluster mode of operation. Available modes: # * `standalone` - default mode. Creates new or updates an existing CNPG cluster. # * `replica` - Creates a replica cluster from an existing CNPG cluster. # TODO # * `recovery` - Same as standalone but creates a cluster from a backup, object store or via pg_basebackup. mode: standalone -### -# Recovery settings if the chosen mode is `recovery`. recovery: ## - # Available recovery methods: + # -- Available recovery methods: # * `backup` - Recovers a CNPG cluster from a CNPG backup (PITR supported) Needs to be on the same cluster in the same namespace. # * `object_store` - Recovers a CNPG cluster from a barman object store (PITR supported). # * `pg_basebackup` - Recovers a CNPG cluster viaa streaming replication protocol. Useful if you want to # migrate databases to CloudNativePG, even from outside Kubernetes. # TODO method: backup - ## Point in time recovery target. Specify one of the following: + ## -- Point in time recovery target. Specify one of the following: pitrTarget: - time: "" # Time in RFC3339 format + # -- Time in RFC3339 format + time: "" ## - # Backup Recovery Method + # -- Backup Recovery Method backupName: "" # Name of the backup to recover from. Required if method is `backup`. ## - # Object Store Recovery Method + # -- Object Store Recovery Method clusterName: "" - # Overrides the provider specific default endpoint. Defaults to: + # -- Overrides the provider specific default endpoint. Defaults to: # S3: https://s3..amazonaws.com" - endpointURL: "" # Leave empty if using the default S3 endpoint - # Overrides the provider specific default path. Defaults to: + # Leave empty if using the default S3 endpoint + endpointURL: "" + # -- Overrides the provider specific default path. Defaults to: # S3: s3:// # Azure: https://..core.windows.net/ # Google: gs:// destinationPath: "" - provider: s3 # One of s3, azure, google + # -- One of `s3`, `azure` or `google` + provider: s3 s3: region: "" bucket: "" @@ -66,21 +69,20 @@ recovery: gkeEnvironment: false applicationCredentials: "" -### -# Database cluster configuration + cluster: - # Number of instances + # -- Number of instances instances: 3 - # Name of the container image, supporting both tags (:) and digests for deterministic and repeatable deployments: + # -- Name of the container image, supporting both tags (:) and digests for deterministic and repeatable deployments: # :@sha256: imageName: "" # Default value depends on type (postgresql/postgis/timescaledb) - # Image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Cannot be updated. + # -- Image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Cannot be updated. # More info: https://kubernetes.io/docs/concepts/containers/images#updating-images imagePullPolicy: IfNotPresent - # The list of pull secrets to be used to pull the images + # -- The list of pull secrets to be used to pull the images # See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-LocalObjectReference imagePullSecrets: [] @@ -88,7 +90,7 @@ cluster: size: 8Gi storageClass: "" - # Resources requirements of every generated Pod. + # -- Resources requirements of every generated Pod. # Please refer to https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for more information. # We strongly advise you use the same setting for limits and requests so that your cluster pods are given a Guaranteed QoS. # See: https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/ @@ -102,27 +104,27 @@ cluster: priorityClassName: "" - # Method to follow to upgrade the primary server during a rolling update procedure, after all replicas have been + # -- Method to follow to upgrade the primary server during a rolling update procedure, after all replicas have been # successfully updated. It can be switchover (default) or in-place (restart). primaryUpdateMethod: switchover - # Strategy to follow to upgrade the primary server during a rolling update procedure, after all replicas have been + # -- Strategy to follow to upgrade the primary server during a rolling update procedure, after all replicas have been # successfully updated: it can be automated (unsupervised - default) or manual (supervised) primaryUpdateStrategy: unsupervised - # The instances' log level, one of the following values: error, warning, info (default), debug, trace + # -- The instances' log level, one of the following values: error, warning, info (default), debug, trace logLevel: "info" - # Affinity/Anti-affinity rules for Pods + # -- Affinity/Anti-affinity rules for Pods # See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-AffinityConfiguration affinity: topologyKey: topology.kubernetes.io/zone - # The configuration for the CA and related certificates + # -- The configuration for the CA and related certificates # See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-CertificatesConfiguration certificates: - # When this option is enabled, the operator will use the SuperuserSecret to update the postgres user password. + # -- When this option is enabled, the operator will use the SuperuserSecret to update the postgres user password. # If the secret is not present, the operator will automatically create one. # When this option is disabled, the operator will ignore the SuperuserSecret content, delete it when automatically created, # and then blank the password of the postgres user by setting it to NULL. @@ -142,11 +144,11 @@ cluster: # usage: GAUGE # description: "Cache hit ratio" - # Configuration of the PostgreSQL server + # -- Configuration of the PostgreSQL server # See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-PostgresConfiguration postgresql: - # BootstrapInitDB is the configuration of the bootstrap process when initdb is used + # -- BootstrapInitDB is the configuration of the bootstrap process when initdb is used # See: https://cloudnative-pg.io/documentation/current/bootstrap/ # See: https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-bootstrapinitdb initdb: {} @@ -159,21 +161,21 @@ cluster: additionalLabels: {} annotations: {} -### -# Database cluster backup configuration + backups: - enabled: false # You need to configure backups manually, so backups are disabled by default. + # -- You need to configure backups manually, so backups are disabled by default. + enabled: false - # Overrides the provider specific default endpoint. Defaults to: + # -- Overrides the provider specific default endpoint. Defaults to: # S3: https://s3..amazonaws.com" endpointURL: "" # Leave empty if using the default S3 endpoint - # Overrides the provider specific default path. Defaults to: + # -- Overrides the provider specific default path. Defaults to: # S3: s3:// # Azure: https://..core.windows.net/ # Google: gs:// destinationPath: "" - + # -- One of `s3`, `azure` or `google` provider: s3 s3: region: "" @@ -197,18 +199,25 @@ backups: applicationCredentials: "" scheduledBackups: - - name: daily-backup # Daily at midnight - schedule: "0 0 0 * * *" # Daily at midnight + - + # -- Scheduled backup name + name: daily-backup + # -- Schedule in cron format + schedule: "0 0 0 * * *" + # -- Backup owner reference backupOwnerReference: self + # -- Retention policy for backups retentionPolicy: "30d" -### -# Database cluster PgBouncer configuration pooler: + # -- Whether to enable PgBouncer enabled: false + # -- PgBouncer pooling mode poolMode: transaction + # -- Number of PgBouncer instances instances: 3 + # -- PgBouncer configuration parameters parameters: max_client_conn: "1000" default_pool_size: "25"