From b7daaac075844ad290b385d15eccbbdbefbd5a67 Mon Sep 17 00:00:00 2001 From: Leonardo Cecchi Date: Tue, 10 Dec 2024 17:00:02 +0100 Subject: [PATCH] docs: provide usage instructions (#89) Update the `README` file with usage instructions. Signed-off-by: Leonardo Cecchi Signed-off-by: Gabriele Bartolini Co-authored-by: Gabriele Bartolini --- .wordlist.txt | 58 +++++- README.md | 328 +++++++++++++++++++++++++++++++++- kubernetes/deployment.yaml | 3 +- kubernetes/kustomization.yaml | 6 +- 4 files changed, 388 insertions(+), 7 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 7179089..5ae0fae 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,3 +1,59 @@ -cnpg +Azurite +BarmanObjectStore +BarmanObjectStores CloudNativePG +Gi +IfNotPresent +MinIO +PITR TODO +TLS +WAL +WALs +api +apiVersion +apiextensions +auth +backends +barmanObjectName +barmancloud +cd +cloudnative +clusterrole +clusterrolebinding +cmctl +cnpg +codebase +csi +customresourcedefinition +externalClusters +gcs +gf +github +hostpath +https +imagePullPolicy +io +kubectl +kubernetes +minio +namespace +namespaces +objectstore +objectstores +pluginConfiguration +postgresql +primaryUpdateStrategy +rbac +rc +repos +rolebinding +sc +selfsigned +serverName +serviceaccount +storageClass +tfddg +tgz +xvzf +yaml diff --git a/README.md b/README.md index 33a2a4f..5757cb5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,330 @@ [![CloudNativePG](./logo/cloudnativepg.png)](https://cloudnative-pg.io/) -# New Component for CloudNativePG +# Barman Cloud CNPG-I plugin -TODO +Welcome to the codebase of the [barman-cloud](https://pgbarman.org/) CNPG-I +plugin for [CloudNativePG](https://cloudnative-pg.io/). +## Table of contents + +- [Features](#features) +- [Prerequisites](#prerequisites) +- [Installation](#installation) +- [Usage](#usage) + - [WAL Archiving](#wal-archiving) + - [Backup](#backup) + - [Restore](#restore) + - [Replica clusters](#replica-clusters) + +## Features + +This plugin enables continuous backup to object storage for a PostgreSQL +cluster using the [barman-cloud](https://pgbarman.org/) tool suite. + +The features provided by this plugin are: + +- Data Directory Backup +- Data Directory Restore +- WAL Archiving +- WAL Restoring +- Point-in-Time Recovery (PITR) +- Replica Clusters + +This plugin is compatible with all object storage services supported by +barman-cloud, including: + +- Amazon AWS S3 +- Google Cloud Storage +- Microsoft Azure Blob Storage + +The following storage solutions have been tested and confirmed to work with +this implementation: + +- [MinIO](https://min.io/) – An S3-compatible object storage solution. +- [Azurite](https://github.com/Azure/Azurite) – A simulator for Microsoft Azure Blob Storage. +- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage. + +Backups created with in-tree object store support can be restored using this +plugin, ensuring compatibility and reliability across environments. + +## Prerequisites + +To use this plugin, ensure the following prerequisites are met: + +- [**CloudNativePG**](https://cloudnative-pg.io) version **1.25** or newer. +- [**cert-manager**](https://cert-manager.io/) for enabling **TLS communication** between the plugin and the operator. + +## Installation + +**IMPORTANT NOTES:** + +1. The plugin **must** be installed in the same namespace where the operator is + installed (typically `cnpg-system`). + +2. Be aware that the operator's **listening namespaces** may differ from its + installation namespace. Ensure you verify this distinction to avoid + configuration issues. + +Here’s an enhanced version of your instructions for verifying the prerequisites: + +### Step 1 - Verify the Prerequisites + +If CloudNativePG is installed in the default `cnpg-system` namespace, verify its version using the following command: + +```sh +kubectl get deployment -n cnpg-system cnpg-controller-manager \ + | grep ghcr.io/cloudnative-pg/cloudnative-pg +``` + +Example output: + +```output +image: ghcr.io/cloudnative-pg/cloudnative-pg:1.25.0-rc1 +``` + +Ensure that the version displayed is **1.25** or newer. + +Then, use the [cmctl](https://cert-manager.io/v1.6-docs/usage/cmctl/#installation) +tool to confirm that `cert-manager` is correctly installed: + +```sh +cmctl check api +``` + +Example output: + +```output +The cert-manager API is ready +``` + +Both checks are necessary to proceed with the installation. + +### Step 2 - Install the barman-cloud Plugin + +Use `kubectl` to apply the manifest for the latest commit in the `main` branch: + +```sh +kubectl apply -f \ + https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml +``` + +Example output: + +```output +customresourcedefinition.apiextensions.k8s.io/objectstores.barmancloud.cnpg.io created +serviceaccount/plugin-barman-cloud created +role.rbac.authorization.k8s.io/leader-election-role created +clusterrole.rbac.authorization.k8s.io/metrics-auth-role created +clusterrole.rbac.authorization.k8s.io/metrics-reader created +clusterrole.rbac.authorization.k8s.io/objectstore-editor-role created +clusterrole.rbac.authorization.k8s.io/objectstore-viewer-role created +clusterrole.rbac.authorization.k8s.io/plugin-barman-cloud created +rolebinding.rbac.authorization.k8s.io/leader-election-rolebinding created +clusterrolebinding.rbac.authorization.k8s.io/metrics-auth-rolebinding created +clusterrolebinding.rbac.authorization.k8s.io/plugin-barman-cloud-binding created +secret/plugin-barman-cloud-8tfddg42gf created +service/barman-cloud created +deployment.apps/barman-cloud configured +certificate.cert-manager.io/barman-cloud-client created +certificate.cert-manager.io/barman-cloud-server created +issuer.cert-manager.io/selfsigned-issuer created +``` + +After these steps, the plugin will be successfully installed. Make sure it is +ready to use by checking the deployment status as follows: + +```sh +kubectl rollout status deployment \ + -n cnpg-system barman-cloud +``` + +Example output: + +```output +deployment "barman-cloud" successfully rolled out +``` + +This confirms that the plugin is deployed and operational. + +## Usage + +### Defining the `BarmanObjectStore` + +A `BarmanObjectStore` object should be created for each object store used in +your PostgreSQL architecture. Below is an example configuration for using +MinIO: + +```yaml +apiVersion: barmancloud.cnpg.io/v1 +kind: ObjectStore +metadata: + name: minio-store +spec: + configuration: + destinationPath: s3://backups/ + endpointURL: http://minio:9000 + s3Credentials: + accessKeyId: + name: minio + key: ACCESS_KEY_ID + secretAccessKey: + name: minio + key: ACCESS_SECRET_KEY + wal: + compression: gzip +``` + +The `.spec.configuration` API follows the same schema as the +[in-tree barman-cloud support](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration). +Refer to [the CloudNativePG documentation](https://cloudnative-pg.io/documentation/preview/backup_barmanobjectstore/) +for detailed usage. + +### Configuring WAL Archiving + +Once the `BarmanObjectStore` is defined, you can configure a PostgreSQL cluster +to archive WALs by referencing the store in the `.spec.plugins` section, as +shown below: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-example +spec: + instances: 3 + imagePullPolicy: Always + plugins: + - name: barman-cloud.cloudnative-pg.io + parameters: + barmanObjectName: minio-store + storage: + size: 1Gi +``` + +This configuration enables both WAL archiving and data directory backups. + +### Performing a Base Backup + +Once WAL archiving is enabled, the cluster is ready for backups. To create a +backup, configure the `backup.spec.pluginConfiguration` section to specify this +plugin: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Backup +metadata: + name: backup-example +spec: + method: plugin + cluster: + name: cluster-example + pluginConfiguration: + name: barman-cloud.cloudnative-pg.io +``` + +### Restoring a Cluster + +To restore a cluster from an object store, create a new `Cluster` resource that +references the store containing the backup. Below is an example configuration: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-restore +spec: + instances: 3 + imagePullPolicy: IfNotPresent + bootstrap: + recovery: + source: source + externalClusters: + - name: source + plugin: + name: barman-cloud.cloudnative-pg.io + parameters: + barmanObjectName: minio-store + serverName: cluster-example + storage: + size: 1Gi +``` + +**NOTE:** The above configuration does **not** enable WAL archiving for the +restored cluster. + +To enable WAL archiving for the restored cluster, include the `.spec.plugins` +section alongside the `externalClusters.plugin` section, as shown below: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-restore +spec: + instances: 3 + imagePullPolicy: IfNotPresent + bootstrap: + recovery: + source: source + plugins: + - name: barman-cloud.cloudnative-pg.io + parameters: + # Backup Object Store (push, read-write) + barmanObjectName: minio-store-bis + externalClusters: + - name: source + plugin: + name: barman-cloud.cloudnative-pg.io + parameters: + # Recovery Object Store (pull, read-only) + barmanObjectName: minio-store + serverName: cluster-example + storage: + size: 1Gi +``` + +The same object store may be used for both transaction log archiving and +restoring a cluster, or you can configure separate stores for these purposes. + +### Configuring Replica Clusters + +You can set up a distributed topology by combining the previously defined +configurations with the `.spec.replica` section. Below is an example of how to +define a replica cluster: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-dc-a +spec: + instances: 3 + primaryUpdateStrategy: unsupervised + + storage: + storageClass: csi-hostpath-sc + size: 1Gi + + plugins: + - name: barman-cloud.cloudnative-pg.io + parameters: + barmanObjectName: minio-store-a + + replica: + self: cluster-dc-a + primary: cluster-dc-a + source: cluster-dc-b + + externalClusters: + - name: cluster-dc-a + plugin: + name: barman-cloud.cloudnative-pg.io + parameters: + barmanObjectName: minio-store-a + + - name: cluster-dc-b + plugin: + name: barman-cloud.cloudnative-pg.io + parameters: + barmanObjectName: minio-store-b +``` diff --git a/kubernetes/deployment.yaml b/kubernetes/deployment.yaml index dd8df11..acc0ab4 100644 --- a/kubernetes/deployment.yaml +++ b/kubernetes/deployment.yaml @@ -9,7 +9,8 @@ spec: selector: matchLabels: app: barman-cloud - strategy: {} + strategy: + type: Recreate template: metadata: labels: diff --git a/kubernetes/kustomization.yaml b/kubernetes/kustomization.yaml index 3e95607..b4ebc9e 100644 --- a/kubernetes/kustomization.yaml +++ b/kubernetes/kustomization.yaml @@ -11,9 +11,9 @@ resources: - ../config/rbac images: - name: plugin-barman-cloud - # result of kind load docker-image - newName: docker.io/library/plugin-barman-cloud + newName: ghcr.io/cloudnative-pg/plugin-barman-cloud-testing + newTag: main secretGenerator: - literals: - - SIDECAR_IMAGE=docker.io/library/plugin-barman-cloud + - SIDECAR_IMAGE=ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar-testing:main name: plugin-barman-cloud