mirror of
https://github.com/cloudnative-pg/plugin-barman-cloud.git
synced 2026-01-11 13:23:09 +01:00
docs: provide usage instructions (#89)
Update the `README` file with usage instructions. Signed-off-by: Leonardo Cecchi <leonardo.cecchi@enterprisedb.com> Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com> Co-authored-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
This commit is contained in:
Leonardo Cecchi
GitHub
parent
2a413c7b6b
commit
b7daaac075
@ -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
|
||||
|
||||
328
README.md
328
README.md
@ -1,6 +1,330 @@
|
||||
[](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
|
||||
```
|
||||
|
||||
@ -9,7 +9,8 @@ spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: barman-cloud
|
||||
strategy: {}
|
||||
strategy:
|
||||
type: Recreate
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user