mirror of
https://github.com/cloudnative-pg/plugin-barman-cloud.git
synced 2026-01-11 21:23:12 +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
|
CloudNativePG
|
||||||
|
Gi
|
||||||
|
IfNotPresent
|
||||||
|
MinIO
|
||||||
|
PITR
|
||||||
TODO
|
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/)
|
[](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:
|
selector:
|
||||||
matchLabels:
|
matchLabels:
|
||||||
app: barman-cloud
|
app: barman-cloud
|
||||||
strategy: {}
|
strategy:
|
||||||
|
type: Recreate
|
||||||
template:
|
template:
|
||||||
metadata:
|
metadata:
|
||||||
labels:
|
labels:
|
||||||
|
|||||||
@ -11,9 +11,9 @@ resources:
|
|||||||
- ../config/rbac
|
- ../config/rbac
|
||||||
images:
|
images:
|
||||||
- name: plugin-barman-cloud
|
- name: plugin-barman-cloud
|
||||||
# result of kind load docker-image
|
newName: ghcr.io/cloudnative-pg/plugin-barman-cloud-testing
|
||||||
newName: docker.io/library/plugin-barman-cloud
|
newTag: main
|
||||||
secretGenerator:
|
secretGenerator:
|
||||||
- literals:
|
- 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
|
name: plugin-barman-cloud
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user