marco/plugin-barman-cloud
1
0
Fork 0
mirror of https://github.com/cloudnative-pg/plugin-barman-cloud.git synced 2026-09-05 14:42:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: marco:3b22cd68f2961d056c6b4ecfcde27725bceff464
Branches Tags
marco:main
marco:renovate/sigs.k8s.io-controller-runtime-0.x
marco:renovate/controller-runtime-0.x
marco:renovate/amazon-aws-cli-2.x
marco:dev/cnp-6102
marco:dev/dump-diagnostics-for-ci-test
marco:dev/reduce-e2e-test-verbosity
marco:dev/385
marco:snyk-fix-6f890911d063843b8cacf57cf3c8ee75
marco:dev/pprof_server
marco:dev/389
marco:v0.15.0
marco:v0.14.0
marco:v0.13.0
marco:v0.12.0
marco:v0.11.0
marco:v0.10.0
marco:v0.9.0
marco:v0.8.0
marco:v0.7.0
marco:v0.6.0
marco:v0.5.0
marco:v0.4.1
marco:v0.4.0
marco:v0.3.0
marco:v0.2.0
marco:v0.1.0
...
compare: marco:1c53989b49a21d32be856b44784e64d01bda2175
Branches Tags
marco:main
marco:renovate/sigs.k8s.io-controller-runtime-0.x
marco:renovate/controller-runtime-0.x
marco:renovate/amazon-aws-cli-2.x
marco:dev/cnp-6102
marco:dev/dump-diagnostics-for-ci-test
marco:dev/reduce-e2e-test-verbosity
marco:dev/385
marco:snyk-fix-6f890911d063843b8cacf57cf3c8ee75
marco:dev/pprof_server
marco:dev/389
marco:v0.15.0
marco:v0.14.0
marco:v0.13.0
marco:v0.12.0
marco:v0.11.0
marco:v0.10.0
marco:v0.9.0
marco:v0.8.0
marco:v0.7.0
marco:v0.6.0
marco:v0.5.0
marco:v0.4.1
marco:v0.4.0
marco:v0.3.0
marco:v0.2.0
marco:v0.1.0

13 Commits
3b22cd68f2 ... 1c53989b49

Author SHA1 Message Date
Max Eisner
1c53989b49
Merge 78d02d6803 into 77118ed413 2026-08-20 07:05:09 +00:00
renovate[bot]
77118ed413
chore(deps): update all cloudnative-pg daggerverse dependencies to 26cd57f (#1072) 
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 2026-08-19 13:01:46 +02:00
Danish
697c2faafb
docs: remove old unmaintained docs from web (#1063) 
Closes #1062 
Related to #351 

Signed-off-by: danishedb <danish.khan@enterprisedb.com>
 2026-08-18 12:35:34 +02:00
Marco Nenciarini
561289e434
chore(deps): bump dagger module deps (#1067) 
Bump dagger engine version to v0.21.8 and module google.golang.org/grpc to v1.82.1

Signed-off-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
 2026-08-17 11:52:05 +02:00
renovate[bot]
5c07b3e809
chore(deps): update all cloudnative-pg daggerverse dependencies to 7174b66 (#1065) 
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 2026-08-15 14:55:06 +02:00
renovate[bot]
e8b4f74c53
chore(deps): update amazon/aws-cli docker tag to v2.36.24 (#1038) 
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 2026-08-15 14:36:24 +02:00
renovate[bot]
d75ebb5687
chore(deps): update dependency cert-manager/cert-manager to v1.21.1 (#1042) 
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 2026-08-15 12:05:35 +02:00
renovate[bot]
9a3cc0d354
fix(deps): update all non-major go dependencies (#1041) 
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 2026-08-15 11:37:46 +02:00
renovate[bot]
d356d7b4df
chore(deps): update dependency dagger/dagger to v0.21.8 (#1043) 
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 2026-08-15 11:20:22 +02:00
dependabot[bot]
4f178c590e
chore(deps): bump cryptography from 49.0.0 to 50.0.0 in /containers (#1052) 
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-08-14 17:31:56 +02:00
renovate[bot]
b825c1c36b
chore(deps): lock file maintenance (#1064) 
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
 2026-08-14 17:05:08 +02:00
dependabot[bot]
0e29da1149
chore(deps): bump js-yaml from 4.3.0 to 4.3.1 in /web (#1058) 
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
 2026-08-14 16:47:44 +02:00
Max Eisner
78d02d6803
docs: add IRSA instructions 
Signed-off-by: Max Eisner <4730112+max-ae@users.noreply.github.com>
 2025-08-18 13:36:01 +02:00
175 changed files with 408 additions and 22328 deletions
Show Stats Expand all files Collapse all files

4
.github/workflows/ci.yml vendored
View File

@ -47,7 +47,7 @@ jobs:
- name: Install Dagger
env:
# renovate: datasource=github-tags depName=dagger/dagger versioning=semver
DAGGER_VERSION: 0.21.7
DAGGER_VERSION: 0.21.8
run: |
curl -L https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh
- name: Run CI task
@ -71,7 +71,7 @@ jobs:
- name: Install Dagger
env:
# renovate: datasource=github-tags depName=dagger/dagger versioning=semver
DAGGER_VERSION: 0.21.7
DAGGER_VERSION: 0.21.8
run: |
curl -L https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh
- name: Write manifest

2
.github/workflows/release-please.yml vendored
View File

@ -31,7 +31,7 @@ jobs:
- name: Install Dagger
env:
# renovate: datasource=github-tags depName=dagger/dagger versioning=semver
DAGGER_VERSION: 0.21.7
DAGGER_VERSION: 0.21.8
run: |
curl -L https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh
- name: Create image and manifest

2
.github/workflows/release-publish.yml vendored
View File

@ -21,7 +21,7 @@ jobs:
- name: Install Dagger
env:
# renovate: datasource=github-tags depName=dagger/dagger versioning=semver
DAGGER_VERSION: 0.21.7
DAGGER_VERSION: 0.21.8
run: |
curl -L https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh
- name: Create image and manifest

12
Taskfile.yml
View File

@ -46,7 +46,7 @@ tasks:
- wordlist-ordered
env:
# renovate: datasource=git-refs depName=spellcheck lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
DAGGER_SPELLCHECK_SHA: f7187c307f2ba79290efbfff5ce436b956162c53
DAGGER_SPELLCHECK_SHA: 26cd57fb6ad66e88c036b675b0478d38df93962d
cmds:
- >
GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/spellcheck@${DAGGER_SPELLCHECK_SHA}
@ -60,7 +60,7 @@ tasks:
desc: Check for conventional commits
env:
# renovate: datasource=git-refs depName=commitlint lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
DAGGER_COMMITLINT_SHA: f7187c307f2ba79290efbfff5ce436b956162c53
DAGGER_COMMITLINT_SHA: 26cd57fb6ad66e88c036b675b0478d38df93962d
cmds:
- >
GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/commitlint@${DAGGER_COMMITLINT_SHA}
@ -74,7 +74,7 @@ tasks:
- wordlist-ordered
env:
# renovate: datasource=git-refs depName=uncommitted lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
DAGGER_UNCOMMITTED_SHA: f7187c307f2ba79290efbfff5ce436b956162c53
DAGGER_UNCOMMITTED_SHA: 26cd57fb6ad66e88c036b675b0478d38df93962d
cmds:
- GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/uncommitted@${DAGGER_UNCOMMITTED_SHA} check-uncommitted --source . stdout
sources:
@ -86,7 +86,7 @@ tasks:
- controller-gen
env:
# renovate: datasource=git-refs depName=crd-gen-refs lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
DAGGER_CRDGENREF_SHA: f7187c307f2ba79290efbfff5ce436b956162c53
DAGGER_CRDGENREF_SHA: 26cd57fb6ad66e88c036b675b0478d38df93962d
# renovate: datasource=go depName=github.com/elastic/crd-ref-docs
CRDREFDOCS_VERSION: v0.3.0
cmds:
@ -206,7 +206,7 @@ tasks:
- start-build-network
vars:
# renovate: datasource=github-tags depName=dagger/dagger versioning=semver
DAGGER_VERSION: 0.21.7
DAGGER_VERSION: 0.21.8
DAGGER_ENGINE_IMAGE: registry.dagger.io/engine:v{{ .DAGGER_VERSION }}
cmds:
- >
@ -383,7 +383,7 @@ tasks:
run: once
env:
# renovate: datasource=git-refs depName=controller-gen lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main
DAGGER_CONTROLLER_GEN_SHA: f7187c307f2ba79290efbfff5ce436b956162c53
DAGGER_CONTROLLER_GEN_SHA: 26cd57fb6ad66e88c036b675b0478d38df93962d
cmds:
- >
GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/controller-gen@${DAGGER_CONTROLLER_GEN_SHA}

94
containers/sidecar-requirements.txt
View File

@ -370,53 +370,53 @@ cramjam==2.11.0 \
# via
# barman
# python-snappy
cryptography==49.0.0 \
--hash=sha256:026ac7423e6fa66872d3bf889be5974507da3944f866f704fa200eadacd00001 \
--hash=sha256:07cab27cc7b7e0fd28e5e26bb9eeedde5c135c868b46de4a27845abe94af6122 \
--hash=sha256:084ef1af862eb07ec46d25f68689f2102a9fc0e05ce7b80f14f5fe51e4eef0f6 \
--hash=sha256:0b82e28ee398a386f0807bba7884d30f25218855690f45115831bcce5d90822c \
--hash=sha256:0e959b578856a3924bc0cbb710fc12c387b9412a951389f3ca61704a9e25f325 \
--hash=sha256:0f21641cf4b30fca7aee061ced0ec7ad7b073518088b7c9969a297c0ae796c69 \
--hash=sha256:196ecd6a36e4e9aa10270393bb98d8df88fccee0bf1e5128b91ae4eb4375896d \
--hash=sha256:2400ef9c9e2299a25614eb1dea3db54a69b1349efd043bfac9c67630d136df36 \
--hash=sha256:28d8b15e6275f12c8a207dc309dfa957903c927d08d0cc937ee3f63f200693cc \
--hash=sha256:2afe9051da7ae7bd5905da5a949280c7d2bb75682e188f650a9d0f2756b834c6 \
--hash=sha256:2eda353d8a27bcbcaa4cbed18994a74ab4d19a2ca897db188ea269ab9b71419b \
--hash=sha256:32703d93296f5c1f4b53349ad3a250c2cae0fdecd3a3dd5d47e616d8d616af27 \
--hash=sha256:33cd0565932807baddb67b96dbee92f2c374b5c89dee09fd74079aeb8c8dba61 \
--hash=sha256:35b151772baff2c74cba7fa290ceaff4c3b11c0c881eb93eb5dbc05a7cfbba18 \
--hash=sha256:36d1709f992593689b45bda411498d62c6e365f2ca00b84657d4dadd24de16db \
--hash=sha256:42b0684e0e40cf26122427802486f6d93aea593612603a94fbf260c7eb1e9c1b \
--hash=sha256:4ae387c9cb68ea569ca17e490d66d8142b81c3cc814bf179974b7d146e490bbb \
--hash=sha256:53ecee2e23f7169b6117e99fc8a944e5e50f79e69758a83b52a00cb98ab2b2d2 \
--hash=sha256:66ec79c3904820572d7e987abdf304281f141d37ad9a489b8e97066e7b9b6459 \
--hash=sha256:67e1d20ad9ef3a563c59ef22e7a8a0b8210bd26604369ea4a30a7c66aefe504e \
--hash=sha256:6f2debedf9ca60cf1d5bd466475638af5130f89965605cd818484d19987d3a21 \
--hash=sha256:6fc361c34fb6aac015ce19435876635e5c6d21db31998b0920f675f131e043b8 \
--hash=sha256:73a205dce83953d131a4aa1e0fd917a2fd1c5b1eef251e9d7152efefcbf5caf7 \
--hash=sha256:7abcee80084cda3f7691f3eb1ce480d8df49cec637b429aa35986c1de71738aa \
--hash=sha256:8c25ceb16df5b9435f3f6a9829204985b0e0cbee3b48aacd432c7d2c850b44d9 \
--hash=sha256:966fe0e9c67490071f14c0d2b1cb2dfb3023c5ce39457343931415f08382f2db \
--hash=sha256:9e82dcc8e56052715fb18b2429e3bca4823b1629136a2084fc45a9a5cecb9b64 \
--hash=sha256:b20133d204d2bb56ba047642199603876c872026ca53e79c35b83772ab2cc505 \
--hash=sha256:b39efa323140595abd3ecca8529d321ae50f55f3aa3ba9cc81ea56a6011953d5 \
--hash=sha256:b47db11c2c3525083296069b98ac5221907455e989ae0c2e3008bde851921615 \
--hash=sha256:b87e65d263b3e5d3bb92a57e2a6638e2f31110fa7aa890c7b2dbba42248d0a3f \
--hash=sha256:b970c6da94d5bb18629db453d14f2a1300f6bf59b61e9b82377931ef95504866 \
--hash=sha256:be9fcb48a55f023493482827d4f459bd263cc20efde64f204b97c123201850c6 \
--hash=sha256:c2bc30226390d60ea19d9f82b19db005fe0452154a23c1c410c12ea801e43561 \
--hash=sha256:c83782480a4a9da4d0feb51950131ba32e12e70813848b3343f6e18c28a66838 \
--hash=sha256:cbc77da8c523d5abd028635ba850a6966fcee2c82e2bf65a41d1d8afe0f98be9 \
--hash=sha256:ccac2bfebc306b862133e3bb71f3f6ee8bb525240089b2d952e4144b3a6d5da7 \
--hash=sha256:d0527ce944105f257f605a827d6ebead966c752038b6e8656abb9c5edee6fc68 \
--hash=sha256:d8ecde755e2e91bf773fc94e8c9d730cd7f2007004cb492263a794ec3899a1c8 \
--hash=sha256:e3fb64c420688e5319ae25113a354015abbd8dffbfbc41781a1ea66fc7622ac3 \
--hash=sha256:e5dfc1e64de5677cec922ffa8da89c546d0415bf6efdf081842e5d44c84e1f0e \
--hash=sha256:ec5e529fb80935c94fe7b729f9972b50e351a0e6b50aa294fd5cabb109fcc29a \
--hash=sha256:f37d847238971164fdbc68ade6f6574aecc9c0af714190e2083429ff68f4ce9d \
--hash=sha256:f78ff2c9ed8dc2d036b0f4d640e22522213d047c1b14e61205a7e55c80a494d4 \
--hash=sha256:f89660a348f4f78a92366240a61404e337586ef7f5909a2fef59ca88ef505493 \
--hash=sha256:fc1e275c2f1d97b1a6450b8b0ea3ebfa6e087a611c2b26cb2404d48588abab7b
cryptography==50.0.0 \
--hash=sha256:031e2d5dd4bb9caa3ca9c82e5a197fd8ae680232cee62603d1a813f3f07e3d03 \
--hash=sha256:06a32a980526a6ab9a4b9bf8f7385800791e2bb960903cb6b530e4817509a3b7 \
--hash=sha256:07479a1cb08219ab719147e742e76090c9c773321959bb94946fffdd397a6437 \
--hash=sha256:07949c449a1abcf60d1ee6e88956d89404c7df3c8258f46589e912988e551987 \
--hash=sha256:105110f43a471dbd0060b9c9516cb8a6a79233631a04cc2ba16f28323ac6e025 \
--hash=sha256:11b74db56cdbe3cdee6e3f6982ecb70334fa10dce99ed58bf7894aaaa3b2a037 \
--hash=sha256:12b9c6996425c76ea6c457ace4f3073e715b8c545add07cd1a8f3a4f90691269 \
--hash=sha256:1489e263a8048bb8b6a8bac662eb2d402ea5d2b7b4699b72f385f1e2772db105 \
--hash=sha256:19736989797678c6af1e55cd49055cdbcb55d8f6b5583ac5335f933aba9101dc \
--hash=sha256:1b4a266766514614f8aa60416e71f2fc6e575d36e7bdc90f644fadb2f4b75b95 \
--hash=sha256:2a8183b489dc1f7f80f135780fadc1108f14b31b8a40411c7a5b17425f65f28b \
--hash=sha256:37fdb0d0111f1e2ff07139dfb79f1b49531f8e213c46f1163dd7642979b58c47 \
--hash=sha256:3f5735ffe4996d28b809371756219f5354864902a3b9e7c0b9ee87041209fc9c \
--hash=sha256:49e7d93abdbd2990caced757e5fade25302f719c3c8fb6e6fff2dde98999fc41 \
--hash=sha256:5e34edd123674534acd70147f0ca331eaa2c74e6325fb2028c886aa26ba0b68c \
--hash=sha256:62598a8a57f815db4c6259a4e97d857dab56697e7de8e8ab02352ab74da1995d \
--hash=sha256:65c2c3add92b45fd0709db8594536aea39c2a67af0e27ffcf049c498501140b7 \
--hash=sha256:6ba6a53445bd3cfa809ef3ef5f1589aa6ba08784a1d962bf47d0940e871dab1c \
--hash=sha256:6e7d61120573a7f2cd94cc095f9e81f6967c61ccdf194285aa143ecec8e0b708 \
--hash=sha256:7cec5b856506da6defb290f30c9ee687d5f5e8cb0bd3f6459dde43b0b4fa40ef \
--hash=sha256:80b63928fa35083b33966ce1efb70e5b9607181e49dcd1c22c8c005e319f667f \
--hash=sha256:82148ec5bddac30b51a5b3c1945075f896fa022cb93f8e4a01e9f6ee95292c5f \
--hash=sha256:828743d939e9629bc267b8e2d08d8bb67cd4319c771a33d4b18b22dd8fb7440a \
--hash=sha256:8d89f3976b10b4ce31118de72329025f70d2c6ead14a8217c5514dd2c6d5a78f \
--hash=sha256:8eb5e1172eb569ea8a872796576e6a67c276351728b6455d5beb01242b027c6a \
--hash=sha256:900131fafd8aead39ac7dd3a7e833be754c17a95cfd91221636949fe4eb0aa8a \
--hash=sha256:910d11e1a385c654bf738bf3e6b8e6ed5de0f5610fcae2be9e5b398d8081d20e \
--hash=sha256:910e1d2668e7de9648f2bcee30e180db2a6b15c30f887d7c4c93ddf96e3992e3 \
--hash=sha256:9aa87839c383bdbab6ef865787a1fb877af8dd03464c4400322726feaaadfc6d \
--hash=sha256:a1b30560f2acc95aa8b2e06e716a13dbfc97314747b80d9707e307f77b40d6b3 \
--hash=sha256:a91296cb61e8df6f86d0c19cc4068228da256bf59bf86049fbd821084565327f \
--hash=sha256:b42a28c1844fd9de8f3f7d540e36b66f3a9c83fceac7170ebc7a6a19edd9dcae \
--hash=sha256:bd1c592e4d5974f0d08d4888e432157adba757c66da0246918e43677fafa2d30 \
--hash=sha256:c87f62a3d3b9888ed0fdde100ec06aa61ca9cd44bad9057d1dff9a516b5f5bb9 \
--hash=sha256:c99c003e088647b8a5b7c145d6f78c335f6348332b62e142d411c4b63d1460b9 \
--hash=sha256:ccdc4a71a4dabae05de219404f9f4abc38e3b58422177ff93d0da05967dafa07 \
--hash=sha256:d24fead1d4d076e1bfb006dcec392074a3cd8d7b4fc8a595aa64073b2b7a96ba \
--hash=sha256:d58c3db7cd6eed54e6c06744db55456b65ebd7492ddeae9c1e93cfca7aa857d3 \
--hash=sha256:d764dcf130c428ef66786f866dd750f53182bc608813489915e9fc106bb0c82f \
--hash=sha256:df2a58a472f332225671c35b0a830208b86d004f82baa8530fa3782c85646533 \
--hash=sha256:e722f16708d854fe924790e051061f6704a472c3bac347b6fd88033ea8dd0dc5 \
--hash=sha256:ecfed7367f965a0328cfbdd70da860f15441f002f613185668c6e6ebf5a0ac11 \
--hash=sha256:eeac2acb5a20ed25e0ad6d1df9891a520b78b404266b6d11778f25d5d691a6c9 \
--hash=sha256:f59e38625469987d7ef6d495323c55e7db6c212eaf6112267e0d3b565a2e9c9f \
--hash=sha256:f89831ef99dd7dd169ab06d63a831adb9e20a87aac6d380266bbda5823349169 \
--hash=sha256:fd9192b7b70c573d7f214eb1ae35e00d359f6f5e4b27c7e21e30de1fc6204645
# via
# azure-identity
# azure-storage-blob

2
dagger/check-doc-version/dagger.json
View File

@ -1,6 +1,6 @@
{
"name": "check-doc-version",
"engineVersion": "v0.21.7",
"engineVersion": "v0.21.8",
"sdk": {
"source": "go"
},

2
dagger/check-doc-version/go.mod
View File

@ -26,7 +26,7 @@ require (
go.opentelemetry.io/otel/sdk/metric v1.43.0 // indirect
go.opentelemetry.io/proto/otlp v1.10.0 // indirect
golang.org/x/sync v0.20.0 // indirect
google.golang.org/grpc v1.80.0 // indirect
google.golang.org/grpc v1.82.1 // indirect
)
require (

4
dagger/check-doc-version/go.sum
View File

@ -89,8 +89,8 @@ google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478 h1:
google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478/go.mod h1:C6ADNqOxbgdUUeRTU+LCHDPB9ttAMCTff6auwCVa4uc=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 h1:RmoJA1ujG+/lRGNfUnOMfhCy5EipVMyvUE+KNbPbTlw=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
google.golang.org/grpc v1.82.1 h1:NnAxzGRA0677vCa4BUkOAnO5+FfQqVl9iUXeD0IqcGE=
google.golang.org/grpc v1.82.1/go.mod h1:yzTZ1TB1Z3SG+LIYaI+WiE8D5+PZ3ArnrSp8zF3+/ZA=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

2
dagger/e2e/dagger.json
View File

@ -1,6 +1,6 @@
{
"name": "e2e",
"engineVersion": "v0.21.7",
"engineVersion": "v0.21.8",
"sdk": {
"source": "go"
},

2
dagger/e2e/go.mod
View File

@ -22,7 +22,7 @@ require (
go.opentelemetry.io/otel/trace v1.43.0
go.opentelemetry.io/proto/otlp v1.10.0
golang.org/x/sync v0.20.0
google.golang.org/grpc v1.80.0
google.golang.org/grpc v1.82.1
)
require github.com/cenkalti/backoff/v5 v5.0.3 // indirect

4
dagger/e2e/go.sum
View File

@ -89,8 +89,8 @@ google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478 h1:
google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478/go.mod h1:C6ADNqOxbgdUUeRTU+LCHDPB9ttAMCTff6auwCVa4uc=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 h1:RmoJA1ujG+/lRGNfUnOMfhCy5EipVMyvUE+KNbPbTlw=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
google.golang.org/grpc v1.82.1 h1:NnAxzGRA0677vCa4BUkOAnO5+FfQqVl9iUXeD0IqcGE=
google.golang.org/grpc v1.82.1/go.mod h1:yzTZ1TB1Z3SG+LIYaI+WiE8D5+PZ3ArnrSp8zF3+/ZA=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

2
dagger/gotest/dagger.json
View File

@ -1,6 +1,6 @@
{
"name": "gotest",
"engineVersion": "v0.21.7",
"engineVersion": "v0.21.8",
"sdk": {
"source": "go"
},

2
dagger/gotest/go.mod
View File

@ -22,7 +22,7 @@ require (
go.opentelemetry.io/otel/sdk/log v0.19.0 // indirect
go.opentelemetry.io/proto/otlp v1.10.0 // indirect
golang.org/x/sync v0.20.0 // indirect
google.golang.org/grpc v1.80.0 // indirect
google.golang.org/grpc v1.82.1 // indirect
)
require (

4
dagger/gotest/go.sum
View File

@ -89,8 +89,8 @@ google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478 h1:
google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478/go.mod h1:C6ADNqOxbgdUUeRTU+LCHDPB9ttAMCTff6auwCVa4uc=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 h1:RmoJA1ujG+/lRGNfUnOMfhCy5EipVMyvUE+KNbPbTlw=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
google.golang.org/grpc v1.82.1 h1:NnAxzGRA0677vCa4BUkOAnO5+FfQqVl9iUXeD0IqcGE=
google.golang.org/grpc v1.82.1/go.mod h1:yzTZ1TB1Z3SG+LIYaI+WiE8D5+PZ3ArnrSp8zF3+/ZA=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

31
go.mod
View File

@ -3,18 +3,18 @@ module github.com/cloudnative-pg/plugin-barman-cloud
go 1.26.4
require (
github.com/cert-manager/cert-manager v1.21.0
github.com/cert-manager/cert-manager v1.21.1
github.com/cloudnative-pg/api v1.30.0
github.com/cloudnative-pg/barman-cloud v0.5.2-0.20260720143032-950b0f57e122
github.com/cloudnative-pg/barman-cloud v0.5.2-0.20260806065336-5aa56cd49543
github.com/cloudnative-pg/cloudnative-pg v1.30.0
github.com/cloudnative-pg/cnpg-i v0.6.0
github.com/cloudnative-pg/cnpg-i-machinery v0.4.2
github.com/cloudnative-pg/machinery v0.5.0
github.com/onsi/ginkgo/v2 v2.32.0
github.com/onsi/ginkgo/v2 v2.32.1
github.com/onsi/gomega v1.42.1
github.com/spf13/cobra v1.10.2
github.com/spf13/viper v1.21.0
google.golang.org/grpc v1.82.1
google.golang.org/grpc v1.83.0
gopkg.in/yaml.v3 v3.0.1
k8s.io/api v0.36.3
k8s.io/apiextensions-apiserver v0.36.3
@ -27,7 +27,7 @@ require (
)
require (
cel.dev/expr v0.25.1 // indirect
cel.dev/expr v0.25.2 // indirect
github.com/Masterminds/semver/v3 v3.5.0 // indirect
github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
github.com/avast/retry-go/v5 v5.0.0 // indirect
@ -61,7 +61,7 @@ require (
github.com/go-openapi/swag/yamlutils v0.26.0 // indirect
github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
github.com/google/cel-go v0.26.0 // indirect
github.com/google/cel-go v0.29.0 // indirect
github.com/google/gnostic-models v0.7.1 // indirect
github.com/google/go-cmp v0.7.0 // indirect
github.com/google/pprof v0.0.0-20260402051712-545e8a4df936 // indirect
@ -91,36 +91,35 @@ require (
github.com/spf13/afero v1.15.0 // indirect
github.com/spf13/cast v1.10.0 // indirect
github.com/spf13/pflag v1.0.10 // indirect
github.com/stoewer/go-strcase v1.3.1 // indirect
github.com/subosito/gotenv v1.6.0 // indirect
github.com/thoas/go-funk v0.9.3 // indirect
github.com/x448/float16 v0.8.4 // indirect
github.com/xlab/treeprint v1.2.0 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 // indirect
go.opentelemetry.io/otel v1.43.0 // indirect
go.opentelemetry.io/otel v1.44.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.40.0 // indirect
go.opentelemetry.io/otel/metric v1.43.0 // indirect
go.opentelemetry.io/otel/sdk v1.43.0 // indirect
go.opentelemetry.io/otel/trace v1.43.0 // indirect
go.opentelemetry.io/otel/metric v1.44.0 // indirect
go.opentelemetry.io/otel/sdk v1.44.0 // indirect
go.opentelemetry.io/otel/trace v1.44.0 // indirect
go.opentelemetry.io/proto/otlp v1.9.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
go.uber.org/zap v1.28.0 // indirect
go.yaml.in/yaml/v2 v2.4.4 // indirect
go.yaml.in/yaml/v3 v3.0.4 // indirect
golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93 // indirect
golang.org/x/mod v0.36.0 // indirect
golang.org/x/mod v0.37.0 // indirect
golang.org/x/net v0.56.0 // indirect
golang.org/x/oauth2 v0.36.0 // indirect
golang.org/x/sync v0.21.0 // indirect
golang.org/x/sync v0.22.0 // indirect
golang.org/x/sys v0.47.0 // indirect
golang.org/x/term v0.44.0 // indirect
golang.org/x/text v0.38.0 // indirect
golang.org/x/text v0.40.0 // indirect
golang.org/x/time v0.15.0 // indirect
golang.org/x/tools v0.45.0 // indirect
golang.org/x/tools v0.47.0 // indirect
gomodules.xyz/jsonpatch/v2 v2.5.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad // indirect
google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af // indirect
gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect

71
go.sum
View File

@ -1,5 +1,5 @@
cel.dev/expr v0.25.1 h1:1KrZg61W6TWSxuNZ37Xy49ps13NUovb66QLprthtwi4=
cel.dev/expr v0.25.1/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4=
cel.dev/expr v0.25.2 h1:K6j46C81hXtZQfuX60cVWQFBJahKSE2gfRbNuvr5bFs=
cel.dev/expr v0.25.2/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4=
github.com/Masterminds/semver/v3 v3.5.0 h1:kQceYJfbupGfZOKZQg0kou0DgAKhzDg2NZPAwZ/2OOE=
github.com/Masterminds/semver/v3 v3.5.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYWrPrQ=
@ -14,14 +14,14 @@ github.com/blang/semver/v4 v4.0.0 h1:1PFHFE6yCCTv8C1TeyNNarDzntLi7wMI5i/pzqYIsAM
github.com/blang/semver/v4 v4.0.0/go.mod h1:IbckMUScFkM3pff0VJDNKRiT6TG/YpiHIM2yvyW5YoQ=
github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=
github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
github.com/cert-manager/cert-manager v1.21.0 h1:BCoB2BxA1lbqPusZCqPLPn8Q9MhraL7RbZGHbBcm3W8=
github.com/cert-manager/cert-manager v1.21.0/go.mod h1:V8iALETs2W428CjBZ4Ez3DftDeyu0f8PZnHDTcliS4I=
github.com/cert-manager/cert-manager v1.21.1 h1:0LttV37Q5c2CBNoHkjuI8sLKTXWZDC2SwQkxrBMKV9w=
github.com/cert-manager/cert-manager v1.21.1/go.mod h1:sVwmLBWoiB1BRd0rJElBGQuiu94z4k7p3Kd0FRQyfgw=
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/cloudnative-pg/api v1.30.0 h1:L8hnvV/tPEQA1xYEi41FUBFA7FUNVGju8+SlgFlDDjI=
github.com/cloudnative-pg/api v1.30.0/go.mod h1:XrKBbOWObL33si0FNuwX4uHNf5JShiZyOUqd6LxbJQo=
github.com/cloudnative-pg/barman-cloud v0.5.2-0.20260720143032-950b0f57e122 h1:NuOztBdp+bUr/xYtaAw8o/x880hvWDRhJGl+R1YsZNw=
github.com/cloudnative-pg/barman-cloud v0.5.2-0.20260720143032-950b0f57e122/go.mod h1:ZQLkdpk44FW5/BGWzABTOEcV9qPbwC+rbdscg2I8mBI=
github.com/cloudnative-pg/barman-cloud v0.5.2-0.20260806065336-5aa56cd49543 h1:QNddaYyvyw14Ky/oxeI3cBiMMg7h6J0LI8VLCaxTUCY=
github.com/cloudnative-pg/barman-cloud v0.5.2-0.20260806065336-5aa56cd49543/go.mod h1:ZQLkdpk44FW5/BGWzABTOEcV9qPbwC+rbdscg2I8mBI=
github.com/cloudnative-pg/cloudnative-pg v1.30.0 h1:fnhVq44xXx97MNiuvJsPrX1vSjYbgdyBK5MSGfdHdp0=
github.com/cloudnative-pg/cloudnative-pg v1.30.0/go.mod h1:QkolwBOWZ+GvAiJt6KpDSymwkpf0K19/p4Q6MQlTM8U=
github.com/cloudnative-pg/cnpg-i v0.6.0 h1:LA//DLkFOLIjU0ASOpFkydZhGir9IAIDfgSsTTX9IpU=
@ -108,8 +108,8 @@ github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw=
github.com/goccy/go-yaml v1.18.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
github.com/google/cel-go v0.26.0 h1:DPGjXackMpJWH680oGY4lZhYjIameYmR+/6RBdDGmaI=
github.com/google/cel-go v0.26.0/go.mod h1:A9O8OU9rdvrK5MQyrqfIxo1a0u4g3sF8KB6PUIaryMM=
github.com/google/cel-go v0.29.0 h1:fEG+Ja3YRwNOqnQxTyJwoByAUAvTuxUGiro/jhrm4F4=
github.com/google/cel-go v0.29.0/go.mod h1:X0bD6iVNR8pkROSOoHVdgTkzmRcosof7WQqCD6wcMc8=
github.com/google/gnostic-models v0.7.1 h1:SisTfuFKJSKM5CPZkffwi6coztzzeYUhc3v4yxLWH8c=
github.com/google/gnostic-models v0.7.1/go.mod h1:whL5G0m6dmc5cPxKc5bdKdEN3UjI7OUGxBlw57miDrQ=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
@ -161,8 +161,8 @@ github.com/monochromegane/go-gitignore v0.0.0-20200626010858-205db1a8cc00 h1:n6/
github.com/monochromegane/go-gitignore v0.0.0-20200626010858-205db1a8cc00/go.mod h1:Pm3mSP3c5uWn86xMLZ5Sa7JB9GsEZySvHYXCTK4E9q4=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
github.com/onsi/ginkgo/v2 v2.32.0 h1:Hw7s2pVrQo/8Yz5N77qdnpHaoc+c6cC9WIV1Jce+J6E=
github.com/onsi/ginkgo/v2 v2.32.0/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
github.com/onsi/ginkgo/v2 v2.32.1 h1:6tlvcDm/3sE8lGJbZ4+d4mO3RLy24/tQWOFzVSQNIfw=
github.com/onsi/ginkgo/v2 v2.32.1/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
github.com/onsi/gomega v1.42.1 h1:iN1rCUX+44NZ1Dc97MPoeFYbFR0vh8zxoxMFwKdyZ6I=
github.com/onsi/gomega v1.42.1/go.mod h1:REff/hsDsodHoKlWsP2mAPhu1+5/6hVYNf9rIEBpeSg=
github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
@ -204,19 +204,12 @@ github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
github.com/stoewer/go-strcase v1.3.1 h1:iS0MdW+kVTxgMoE1LAZyMiYJFKlOzLooE4MxjirtkAs=
github.com/stoewer/go-strcase v1.3.1/go.mod h1:fAH5hQ5pehh+j3nZfvwdk2RgEgQjAoM8wodgtPmh1xo=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
@ -239,20 +232,20 @@ go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o=
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg=
go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 h1:QKdN8ly8zEMrByybbQgv8cWBcdAarwmIPZ6FThrWXJs=
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0/go.mod h1:bTdK1nhqF76qiPoCCdyFIV+N/sRHYXYCTQc+3VCi3MI=
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.40.0 h1:DvJDOPmSWQHWywQS6lKL+pb8s3gBLOZUtw4N+mavW1I=
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.40.0/go.mod h1:EtekO9DEJb4/jRyN4v4Qjc2yA7AtfCBuz2FynRUWTXs=
go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=
go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
@ -267,34 +260,34 @@ go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93 h1:fQsdNF2N+/YewlRZiricy4P1iimyPKZ/xwniHj8Q2a0=
golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93/go.mod h1:EPRbTFwzwjXj9NpYyyrvenVh9Y+GFeEvMNh7Xuz7xgU=
golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/term v0.44.0 h1:0rLvDRCtNj0gZkyIXhCyOb2OAzEhLVqc4B+hrsBhrmc=
golang.org/x/term v0.44.0/go.mod h1:7ze4MdzUzLXpSAoFP1H0bOI9aXDqveSvatT5vKcFh2Y=
golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
gomodules.xyz/jsonpatch/v2 v2.5.0 h1:JELs8RLM12qJGXU4u/TO3V25KW8GreMKl9pdkk14RM0=
gomodules.xyz/jsonpatch/v2 v2.5.0/go.mod h1:AH3dM2RI6uoBZxn3LVrfvJ3E0/9dG4cSrbuBJT4moAY=
gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478 h1:yQugLulqltosq0B/f8l4w9VryjV+N/5gcW0jQ3N8Qec=
google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478/go.mod h1:C6ADNqOxbgdUUeRTU+LCHDPB9ttAMCTff6auwCVa4uc=
google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa h1:Kjn0N0tCrDgiAFW+lGO4JZ3ck44CehvJQMAwj9QF0G8=
google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:q4lMZS6kskjT5HvCPrnnypcDPVJqT/f4nfxmkE7gryY=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad h1:45WmJvIV6C2+O/jjLkPUH+F3aOj/1miDoU2DD0+NWbg=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260610212136-7ab31c22f7ad/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.82.1 h1:NnAxzGRA0677vCa4BUkOAnO5+FfQqVl9iUXeD0IqcGE=
google.golang.org/grpc v1.82.1/go.mod h1:yzTZ1TB1Z3SG+LIYaI+WiE8D5+PZ3ArnrSp8zF3+/ZA=
google.golang.org/grpc v1.83.0 h1:JeNZEKJFbQxArAMl+hiytHauacDNqJUllNfmIMmpqnQ=
google.golang.org/grpc v1.83.0/go.mod h1:kDyl6SKsiHKt0uylY5gtn5cEjkrIOhQOGDgIc4JGwzQ=
google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af h1:+5/Sw3GsDNlEmu7TfklWKPdQ0Ykja5VEmq2i817+jbI=
google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

2
test/e2e/internal/certmanager/certmanager.go
View File

@ -58,7 +58,7 @@ func WithIgnoreExistingResources(ignore bool) InstallOption {
// DefaultVersion is the default version of cert-manager to install.
//
// renovate: datasource=github-releases depName=cert-manager/cert-manager
const DefaultVersion = "v1.21.0"
const DefaultVersion = "v1.21.1"
// Install installs cert-manager using kubectl.
func Install(ctx context.Context, cl client.Client, opts ...InstallOption) error {

4
test/e2e/internal/tests/walrestore/fixtures.go
View File

@ -121,8 +121,8 @@ func newS3ClientDeployment(namespace string) *appsv1.Deployment {
{
Name: s3ClientName,
// renovate: datasource=docker depName=amazon/aws-cli versioning=docker
// Version: 2.36.9
Image: "docker.io/amazon/aws-cli@sha256:00dee8ccaf669721f8163944ea9e6ac13183851b23d5b7a9868a608bc932cfdb",
// Version: 2.36.24
Image: "docker.io/amazon/aws-cli@sha256:cd11f6e909d42f066a03e15f072853fcc19f033e343cb83b2d553e2082cbb5a7",
Command: []string{"sleep", "infinity"},
Env: []corev1.EnvVar{
{

4
web/docs/migration.md
View File

@ -103,6 +103,10 @@ As you can see, the contents of `barmanObjectStore` have been copied directly
under the `configuration` field of the `ObjectStore` resource, using the same
secret references.
### IAM Role for Service Account (IRSA)
If you use IRSA, you need to configure the `ObjectStore` to utilize the correct role as described in the [`Object Store Reference`](object_stores.md#iam-role-for-service-account-irsa).
## Step 2: Update the `Cluster` for plugin WAL archiving
Once the `ObjectStore` resource is in place, update the `Cluster` resource as

13
web/docs/object_stores.md
View File

@ -111,6 +111,19 @@ spec:
[...]
```
In addition, configure the `ObjectStore` to inherit permissions from the IAM role referenced in the service account:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
[...]
spec:
configuration:
s3Credentials:
inheritFromIAMRole: true
```
### S3 Lifecycle Policy
Barman Cloud uploads backup files to S3 but does not modify them afterward.

43
web/versioned_docs/version-0.10.0/compression.md
View File

@ -1,43 +0,0 @@
---
sidebar_position: 80
---
# Compression
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
By default, backups and WAL files are archived **uncompressed**. However, the
Barman Cloud Plugin supports multiple compression algorithms via
`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
for space, speed, or a balance of both.
### Supported Compression Algorithms
- `bzip2`
- `gzip`
- `lz4` (WAL only)
- `snappy`
- `xz` (WAL only)
- `zstd` (WAL only)
Compression settings for base backups and WAL archives are configured
independently. For implementation details, refer to the corresponding API
definitions:
- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
:::important
Compression impacts both performance and storage efficiency. Choose the right
algorithm based on your recovery time objectives (RTO), storage capacity, and
network throughput.
:::
## Compression Benchmark (on MinIO)
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |

177
web/versioned_docs/version-0.10.0/concepts.md
View File

@ -1,177 +0,0 @@
---
sidebar_position: 10
---
# Main Concepts
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::important
Before proceeding, make sure to review the following sections of the
CloudNativePG documentation:
- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
:::
The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
supporting continuous physical backups and WAL archiving to an **object
store**—without interrupting write operations.
It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
of a PostgreSQL cluster.
## The Object Store
At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
which acts as the interface between the PostgreSQL cluster and the target
object storage system. It allows you to configure:
- **Authentication and bucket location** via the `.spec.configuration` section
- **WAL archiving** settings—such as compression type, parallelism, and
server-side encryption—under `.spec.configuration.wal`
- **Base backup options**—with similar settings for compression, concurrency,
and encryption—under `.spec.configuration.data`
- **Retention policies** to manage the life-cycle of archived WALs and backups
via `.spec.configuration.retentionPolicy`
WAL files are archived in the `wals` directory, while base backups are stored
as **tarballs** in the `base` directory, following the
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
The plugin also offers advanced capabilities, including
[backup tagging](misc.md#backup-object-tagging) and
[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving).
:::tip
For details, refer to the
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).
:::
## Integration with a CloudNativePG Cluster
CloudNativePG can delegate continuous backup and recovery responsibilities to
the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
to be defined.
:::important
While it is technically possible to reuse the same `ObjectStore` for multiple
`Cluster` resources within the same namespace, it is strongly recommended to
dedicate one object store per PostgreSQL cluster to ensure data isolation and
operational clarity.
:::
The following example demonstrates how to configure a CloudNativePG cluster
named `cluster-example` to use a previously defined `ObjectStore` (also named
`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
WAL archiving through the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
# Other cluster settings...
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: cluster-example
```
## Backup of a Postgres Cluster
Once the object store is defined and the `Cluster` is configured to use the
Barman Cloud Plugin, **WAL archiving is activated immediately** on the
PostgreSQL primary.
Physical base backups are seamlessly managed by CloudNativePG using the
`Backup` and `ScheduledBackup` resources, respectively for
[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
and
[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
backups.
To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
configure the `pluginConfiguration` section as shown:
```yaml
[...]
spec:
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
[...]
```
With this configuration, CloudNativePG supports:
- Backups from both **primary** and **standby** instances
- Backups from **designated primaries** in a distributed topology using
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
:::tip
For details on how to back up from a standby, refer to the official documentation:
[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
:::
:::important
Both backup and WAL archiving operations are executed by sidecar containers
running in the same pod as the PostgreSQL `Cluster` primary instance—except
when backups are taken from a standby, in which case the sidecar runs alongside
the standby pod.
The sidecar containers use a [dedicated container image](images.md) that
includes only the supported version of Barman Cloud.
:::
## Recovery of a Postgres Cluster
In PostgreSQL, *recovery* refers to the process of starting a database instance
from an existing backup. The Barman Cloud Plugin integrates with CloudNativePG
to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
object store.
Recovery in this context is *not in-place*: it bootstraps a brand-new
PostgreSQL cluster from a backup and replays the necessary WAL files to reach
the desired recovery target.
To perform a recovery, define an *external cluster* that references the
appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
of the target cluster:
```yaml
[...]
spec:
[...]
bootstrap:
recovery:
source: source
externalClusters:
- name: source
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: cluster-example
serverName: cluster-example
[...]
```
The critical element here is the `externalClusters` section of the `Cluster`
resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
Cloud Plugin to access the object store for recovery.
This same mechanism can be used for a variety of scenarios enabled by the
CloudNativePG API, including:
* **Full cluster recovery** from the latest backup
* **Point-in-Time Recovery (PITR)**
* Bootstrapping **replica clusters** in a distributed topology
:::tip
For complete instructions and advanced use cases, refer to the official
[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
:::

37
web/versioned_docs/version-0.10.0/images.md
View File

@ -1,37 +0,0 @@
---
sidebar_position: 99
---
# Container Images
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin is distributed using two container images:
- One for deploying the plugin components
- One for the sidecar that runs alongside each PostgreSQL instance in a
CloudNativePG `Cluster` using the plugin
## Plugin Container Image
The plugin image contains the logic required to operate the Barman Cloud Plugin
within your Kubernetes environment with CloudNativePG. It is published on the
GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
This image is built from the
[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
in the plugin repository.
## Sidecar Container Image
The sidecar image is used within each PostgreSQL pod in the cluster. It
includes the latest supported version of Barman Cloud and is responsible for
performing WAL archiving and backups on behalf of CloudNativePG.
It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
built from the
[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
These sidecar images are designed to work seamlessly with the
[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
maintained by the CloudNativePG Community.

109
web/versioned_docs/version-0.10.0/installation.mdx
View File

@ -1,109 +0,0 @@
---
sidebar_position: 20
---
# Installation
:::important
1. The plugin **must** be installed in the same namespace as the CloudNativePG
operator (typically `cnpg-system`).
2. Keep in mind that the operator's **listening namespaces** may differ from its
installation namespace. Double-check this to avoid configuration issues.
:::
## Verifying the Requirements
Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
### CloudNativePG Version
Ensure you're running a version of CloudNativePG that is compatible with the
plugin. If installed in the default `cnpg-system` namespace, you can verify the
version with:
```sh
kubectl get deployment -n cnpg-system cnpg-controller-manager \
-o jsonpath="{.spec.template.spec.containers[*].image}"
```
Example output:
```output
ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
```
The version **must be 1.26 or newer**.
### cert-manager
Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
tool to confirm that `cert-manager` is installed and available:
```sh
cmctl check api
```
Example output:
```output
The cert-manager API is ready
```
Both checks are required before proceeding with the installation.
## Installing the Barman Cloud Plugin
import { InstallationSnippet } from '@site/src/components/Installation';
Install the plugin using `kubectl` by applying the manifest for the latest
release:
<InstallationSnippet />
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
```
Finally, check that the deployment is up and running:
```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 ready to use.
## Testing the latest development snapshot
You can also test the latest development snapshot of the plugin with the
following command:
```sh
kubectl apply -f \
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
```

86
web/versioned_docs/version-0.10.0/intro.md
View File

@ -1,86 +0,0 @@
---
sidebar_position: 1
sidebar_label: "Introduction"
---
# Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The **Barman Cloud Plugin** for [CloudNativePG](https://cloudnative-pg.io/)
enables online continuous physical backups of PostgreSQL clusters to object storage
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
project.
:::important
If you plan to migrate your existing CloudNativePG cluster to the new
plugin-based approach using the Barman Cloud Plugin, see
["Migrating from Built-in CloudNativePG Backup"](migration.md)
for detailed instructions.
:::
## Requirements
Before using the Barman Cloud Plugin, ensure that the following components are
installed and properly configured:
- [CloudNativePG](https://cloudnative-pg.io) version 1.26 or later
- We strongly recommend version 1.27.0 or later, which includes improved
error handling and status reporting for the plugin.
- If you are running an earlier release, refer to the
[upgrade guide](https://cloudnative-pg.io/documentation/current/installation_upgrade).
- [cert-manager](https://cert-manager.io/)
- The recommended way to enable secure TLS communication between the plugin
and the operator.
- Alternatively, you can provide your own certificate bundles. See the
[CloudNativePG documentation on TLS configuration](https://cloudnative-pg.io/documentation/current/cnpg_i/#configuring-tls-certificates).
- [`kubectl-cnpg`](https://cloudnative-pg.io/documentation/current/kubectl-plugin/)
plugin (optional but recommended)
- Simplifies debugging and monitoring with additional status and inspection
commands.
- Multiple installation options are available in the
[installation guide](https://cloudnative-pg.io/documentation/current/kubectl-plugin/#install).
## Key Features
This plugin provides the following capabilities:
- Physical online backup of the data directory
- Physical restore of the data directory
- Write-Ahead Log (WAL) archiving
- WAL restore
- Full cluster recovery
- Point-in-Time Recovery (PITR)
- Seamless integration with replica clusters for bootstrap and WAL restore from archive
:::important
The Barman Cloud Plugin is designed to **replace the in-tree object storage support**
previously provided via the `.spec.backup.barmanObjectStore` section in the
`Cluster` resource.
Backups created using the in-tree approach are fully supported and compatible
with this plugin.
:::
## Supported Object Storage Providers
The plugin works with all storage backends supported by `barman-cloud`, including:
- **Amazon S3**
- **Google Cloud Storage**
- **Microsoft Azure Blob Storage**
In addition, the following S3-compatible and simulator solutions have been
tested and verified:
- [MinIO](https://min.io/) – An S3-compatible storage solution
- [Azurite](https://github.com/Azure/Azurite) – A simulator for Azure Blob Storage
- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage
:::tip
For more details, refer to [Object Store Providers](object_stores.md).
:::

274
web/versioned_docs/version-0.10.0/migration.md
View File

@ -1,274 +0,0 @@
---
sidebar_position: 40
---
# Migrating from Built-in CloudNativePG Backup
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting
from version 1.26** and will be removed in a future release.
If you're currently relying on the built-in Barman Cloud integration, you can
migrate seamlessly to the new **plugin-based architecture** using the Barman
Cloud Plugin, without data loss. Follow these steps:
- [Install the Barman Cloud Plugin](installation.mdx)
- Create an `ObjectStore` resource by translating the contents of the
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
definition
- Modify the `Cluster` resource in a single atomic change to switch from
in-tree backup to the plugin
- Update any `ScheduledBackup` resources to use the plugin
- Update the `externalClusters` configuration, where applicable
:::tip
For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground),
which demonstrates a full migration.
:::
---
## Step 1: Define the `ObjectStore`
Begin by creating an `ObjectStore` resource in the same namespace as your
PostgreSQL `Cluster`.
There is a **direct mapping** between the `.spec.backup.barmanObjectStore`
section in CloudNativePG and the `.spec.configuration` field in the
`ObjectStore` CR. The conversion is mostly mechanical, with one key difference:
:::warning
In the plugin architecture, retention policies are defined as part of the `ObjectStore`.
In contrast, the in-tree implementation defined them at the `Cluster` level.
:::
If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration
to `.spec.retentionPolicy` in the `ObjectStore`.
---
### Example
Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration
taken from the CloudNativePG Playground project:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-eu
spec:
# [...]
backup:
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
This configuration translates to the following `ObjectStore` resource for the
plugin:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
As you can see, the contents of `barmanObjectStore` have been copied directly
under the `configuration` field of the `ObjectStore` resource, using the same
secret references.
## Step 2: Update the `Cluster` for plugin WAL archiving
Once the `ObjectStore` resource is in place, update the `Cluster` resource as
follows in a single atomic change:
- Remove the `.spec.backup.barmanObjectStore` section
- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the
`ObjectStore`)
- Remove the entire `spec.backup` section if it is now empty
- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in
[Configuring WAL archiving](usage.md#configuring-wal-archiving)
This will trigger a rolling update of the `Cluster`, switching continuous
backup from the in-tree implementation to the plugin-based approach.
### Example
The updated `pg-eu` cluster will have this configuration instead of the
previous `backup` section:
```yaml
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: minio-eu
```
---
## Step 3: Update the `ScheduledBackup`
After switching the `Cluster` to use the plugin, update your `ScheduledBackup`
resources to match.
Set the backup `method` to `plugin` and reference the plugin name via
`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup).
### Example
Original in-tree `ScheduledBackup`:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
```
Updated version using the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
---
## Step 4: Update the `externalClusters` configuration
If your `Cluster` relies on one or more external clusters that use the in-tree
Barman Cloud integration, you need to update those configurations to use the
plugin-based architecture.
When a replica cluster fetches WAL files or base backups from an external
source that used the built-in backup method, follow these steps:
1. Create a corresponding `ObjectStore` resource for the external cluster, as
shown in [Step 1](#step-1-define-the-objectstore)
2. Update the `externalClusters` section of your replica cluster to use the
plugin instead of the in-tree `barmanObjectStore` field
### Example
Consider the original configuration using in-tree Barman Cloud:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
serverName: pg-eu
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Create the `ObjectStore` resource for the external cluster:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Update the external cluster configuration to use the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: minio-eu
serverName: pg-eu
```
## Step 5: Verify your metrics
When migrating from the in-core solution to the plugin-based approach, you need
to monitor a different set of metrics, as described in the
["Observability"](observability.md) section.
The table below summarizes the name changes between the old in-core metrics and
the new plugin-based ones:
| Old metric name | New metric name |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| `cnpg_collector_last_failed_backup_timestamp` | `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp` |
| `cnpg_collector_last_available_backup_timestamp` | `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp` |
| `cnpg_collector_first_recoverability_point` | `barman_cloud_cloudnative_pg_io_first_recoverability_point` |

97
web/versioned_docs/version-0.10.0/misc.md
View File

@ -1,97 +0,0 @@
---
sidebar_position: 90
---
# Miscellaneous
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
## Backup Object Tagging
You can attach key-value metadata tags to backup artifacts—such as base
backups, WAL files, and history files—via the `.spec.configuration` section of
the `ObjectStore` resource.
- `tags`: applied to base backups and WAL files
- `historyTags`: applied to history files only
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
[...]
tags:
backupRetentionPolicy: "expire"
historyTags:
backupRetentionPolicy: "keep"
[...]
```
## Extra Options for Backup and WAL Archiving
You can pass additional command-line arguments to `barman-cloud-backup` and
`barman-cloud-wal-archive` using the `additionalCommandArgs` field in the
`ObjectStore` configuration.
- `.spec.configuration.data.additionalCommandArgs`: for `barman-cloud-backup`
- `.spec.configuration.wal.archiveAdditionalCommandArgs`: for `barman-cloud-wal-archive`
Each field accepts a list of string arguments. If an argument is already
configured elsewhere in the plugin, the duplicate will be ignored.
### Example: Extra Backup Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
data:
additionalCommandArgs:
- "--min-chunk-size=5MB"
- "--read-timeout=60"
```
### Example: Extra WAL Archive Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
wal:
archiveAdditionalCommandArgs:
- "--max-concurrency=1"
- "--read-timeout=60"
```
For a complete list of supported options, refer to the
[official Barman Cloud documentation](https://docs.pgbarman.org/release/latest/).
## Enable the pprof debug server for the sidecar
You can enable the instance sidecar's pprof debug HTTP server by adding the `--pprof-server=<address>` flag to the container's
arguments via `.spec.instanceSidecarConfiguration.additionalContainerArgs`.
Pass a bind address in the form `<host>:<port>` (for example, `0.0.0.0:6061`).
An empty value disables the server (disabled by default).
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
instanceSidecarConfiguration:
additionalContainerArgs:
- "--pprof-server=0.0.0.0:6061"
```

454
web/versioned_docs/version-0.10.0/object_stores.md
View File

@ -1,454 +0,0 @@
---
sidebar_position: 50
---
# Object Store Providers
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin enables the storage of PostgreSQL cluster backup files
in any object storage service supported by the
[Barman Cloud infrastructure](https://docs.pgbarman.org/release/latest/).
Currently, Barman Cloud supports the following providers:
- [Amazon S3](#aws-s3)
- [Microsoft Azure Blob Storage](#azure-blob-storage)
- [Google Cloud Storage](#google-cloud-storage)
You may also use any S3- or Azure-compatible implementation of the above
services.
To configure object storage with Barman Cloud, you must define an
[`ObjectStore` object](plugin-barman-cloud.v1.md#objectstore), which
establishes the connection between your PostgreSQL cluster and the object
storage backend.
Configuration details — particularly around authentication — will vary depending on
the specific object storage provider you are using.
The following sections detail the setup for each.
---
## AWS S3
[AWS Simple Storage Service (S3)](https://aws.amazon.com/s3/) is one of the
most widely adopted object storage solutions.
The Barman Cloud plugin for CloudNativePG integrates with S3 through two
primary authentication mechanisms:
- [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) —
recommended for clusters running on EKS
- Access keys — using `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY` credentials
### Access Keys
To authenticate using access keys, you’ll need:
- `ACCESS_KEY_ID`: the public key used to authenticate to S3
- `ACCESS_SECRET_KEY`: the corresponding secret key
- `ACCESS_SESSION_TOKEN`: (optional) a temporary session token, if required
These credentials must be stored securely in a Kubernetes secret:
```sh
kubectl create secret generic aws-creds \
--from-literal=ACCESS_KEY_ID=<access key here> \
--from-literal=ACCESS_SECRET_KEY=<secret key here>
# --from-literal=ACCESS_SESSION_TOKEN=<session token here> # if required
```
The credentials will be encrypted at rest if your Kubernetes environment
supports it.
You can then reference the secret in your `ObjectStore` definition:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: aws-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
s3Credentials:
accessKeyId:
name: aws-creds
key: ACCESS_KEY_ID
secretAccessKey:
name: aws-creds
key: ACCESS_SECRET_KEY
[...]
```
### IAM Role for Service Account (IRSA)
To use IRSA with EKS, configure the service account of the PostgreSQL cluster
with the appropriate annotation:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
[...]
spec:
serviceAccountTemplate:
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:[...]
[...]
```
### S3 Lifecycle Policy
Barman Cloud uploads backup files to S3 but does not modify them afterward.
To enhance data durability and protect against accidental or malicious loss,
it's recommended to implement the following best practices:
- Enable object versioning
- Enable object locking to prevent objects from being deleted or overwritten
for a defined period or indefinitely (this provides an additional layer of
protection against accidental deletion and ransomware attacks)
- Set lifecycle rules to expire current versions a few days after your Barman
retention window
- Expire non-current versions after a longer period
These strategies help you safeguard backups without requiring broad delete
permissions, ensuring both security and compliance with minimal operational
overhead.
### S3-Compatible Storage Providers
You can use S3-compatible services like **MinIO**, **Linode (Akamai) Object Storage**,
or **DigitalOcean Spaces** by specifying a custom `endpointURL`.
Example with Linode (Akamai) Object Storage (`us-east1`):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/"
endpointURL: "https://us-east1.linodeobjects.com"
s3Credentials:
[...]
[...]
```
Recent changes to the [boto3 implementation](https://github.com/boto/boto3/issues/4392)
of [Amazon S3 Data Integrity Protections](https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html)
may lead to the `x-amz-content-sha256` error when using the Barman Cloud
Plugin.
If you encounter this issue (see [GitHub issue #393](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/393)),
you can apply the following workaround by setting specific environment
variables in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
instanceSidecarConfiguration:
env:
- name: AWS_REQUEST_CHECKSUM_CALCULATION
value: when_required
- name: AWS_RESPONSE_CHECKSUM_VALIDATION
value: when_required
[...]
```
These settings ensure that checksum calculations and validations are only
applied when explicitly required, avoiding compatibility issues with certain
S3-compatible storage providers.
Example with DigitalOcean Spaces (SFO3, path-style):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: digitalocean-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
endpointURL: "https://sfo3.digitaloceanspaces.com"
s3Credentials:
[...]
[...]
```
### Using Object Storage with a Private CA
For object storage services (e.g., MinIO) that use HTTPS with certificates
signed by a private CA, set the `endpointCA` field in the `ObjectStore`
definition. Unless you already have it, create a Kubernetes `Secret` with the
CA bundle:
```sh
kubectl create secret generic my-ca-secret --from-file=ca.crt
```
Then reference it:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
endpointURL: <myEndpointURL>
endpointCA:
name: my-ca-secret
key: ca.crt
[...]
```
<!-- TODO: does this also apply to the plugin? -->
:::note
If you want `ConfigMaps` and `Secrets` to be **automatically** reloaded by
instances, you can add a label with the key `cnpg.io/reload` to the
`Secrets`/`ConfigMaps`. Otherwise, you will have to reload the instances using the
`kubectl cnpg reload` subcommand.
:::
---
## Azure Blob Storage
[Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
is Microsoft’s cloud-based object storage solution.
Barman Cloud supports the following authentication methods:
- [Connection String](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string)
- Storage Account Name + [Access Key](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
- Storage Account Name + [SAS Token](https://learn.microsoft.com/en-us/azure/storage/blobs/sas-service-create)
- [Azure AD Workload Identity](https://azure.github.io/azure-workload-identity/docs/introduction.html)
### Azure AD Workload Identity
This method avoids storing credentials in Kubernetes via the
`.spec.configuration.inheritFromAzureAD` option:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
inheritFromAzureAD: true
[...]
```
### Access Key, SAS Token, or Connection String
Store credentials in a Kubernetes secret:
```sh
kubectl create secret generic azure-creds \
--from-literal=AZURE_STORAGE_ACCOUNT=<storage account name> \
--from-literal=AZURE_STORAGE_KEY=<storage account key> \
--from-literal=AZURE_STORAGE_SAS_TOKEN=<SAS token> \
--from-literal=AZURE_STORAGE_CONNECTION_STRING=<connection string>
```
Then reference the required keys in your `ObjectStore`:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
connectionString:
name: azure-creds
key: AZURE_CONNECTION_STRING
storageAccount:
name: azure-creds
key: AZURE_STORAGE_ACCOUNT
storageKey:
name: azure-creds
key: AZURE_STORAGE_KEY
storageSasToken:
name: azure-creds
key: AZURE_STORAGE_SAS_TOKEN
[...]
```
For Azure Blob, the destination path format is:
```
<http|https>://<account-name>.<service-name>.core.windows.net/<container>/<blob>
```
### Azure-Compatible Providers
If you're using a different implementation (e.g., Azurite or emulator):
```
<http|https>://<local-machine-address>:<port>/<account-name>/<container>/<blob>
```
---
## Google Cloud Storage
[Google Cloud Storage](https://cloud.google.com/storage/) is supported with two
authentication modes:
- **GKE Workload Identity** (recommended inside Google Kubernetes Engine)
- **Service Account JSON key** via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
### GKE Workload Identity
Use the [Workload Identity authentication](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
when running in GKE:
1. Set `googleCredentials.gkeEnvironment` to `true` in the `ObjectStore`
resource
2. Annotate the `serviceAccountTemplate` in the `Cluster` resource with the GCP
service account
For example, in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
gkeEnvironment: true
```
And in the `Cluster` resource:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
serviceAccountTemplate:
metadata:
annotations:
iam.gke.io/gcp-service-account: [...].iam.gserviceaccount.com
```
### Service Account JSON Key
Follow Google’s [authentication setup](https://cloud.google.com/docs/authentication/getting-started),
then:
```sh
kubectl create secret generic backup-creds --from-file=gcsCredentials=gcs_credentials_file.json
```
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
applicationCredentials:
name: backup-creds
key: gcsCredentials
[...]
```
:::important
This authentication method generates a JSON file within the container
with all the credentials required to access your Google Cloud Storage
bucket. As a result, if someone gains access to the `Pod`, they will also have
write permissions to the bucket.
:::
---
## MinIO Object Store
In order to use the Tenant resource you first need to deploy the
[MinIO operator](https://docs.min.io/community/minio-object-store/operations/deployments/installation.html).
For the latest documentation of MinIO, please refer to the
[MinIO official documentation](https://docs.min.io/community/minio-object-store/).
MinIO Object Store's API is compatible with S3, and the default configuration of the Tenant
will create these services:
- `<tenant>-console` on port 9090 (with autocert) or 9443 (without autocert)
- `<tenant>-hl` on port 9000
Where `<tenant>` is the `metadata.name` you assigned to your Tenant resource.
:::note
The `<tenant>-console` service will only be available if you have enabled the
[MinIO Console](https://docs.min.io/community/minio-object-store/administration/minio-console.html).
For example, the following Tenant:
```yml
apiVersion: minio.min.io/v2
kind: Tenant
metadata:
name: cnpg-backups
spec:
[...]
```
would have services called `cnpg-backups-console` and `cnpg-backups-hl` respectively.
The `console` service is for managing the tenant, while the `hl` service exposes the S3
compatible API. If your tenant is configured with `requestAutoCert` you will communicate
to these services over HTTPS, if not you will use HTTP.
For authentication you can use your username and password, or create an access key.
Whichever method you choose, it has to be stored as a secret.
```sh
kubectl create secret generic minio-creds \
--from-literal=MINIO_ACCESS_KEY=<minio access key or username> \
--from-literal=MINIO_SECRET_KEY=<minio secret key or password>
```
Finally, create the Barman ObjectStore:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
destinationPath: s3://BUCKET_NAME/
endpointURL: http://<tenant>-hl:9000
s3Credentials:
accessKeyId:
name: minio-creds
key: MINIO_ACCESS_KEY
secretAccessKey:
name: minio-creds
key: MINIO_SECRET_KEY
[...]
```
:::important
Verify on `s3://BUCKET_NAME/` the presence of archived WAL files before
proceeding with a backup.
:::
---

24
web/versioned_docs/version-0.10.0/observability.md
View File

@ -1,24 +0,0 @@
---
sidebar_position: 55
---
# Observability
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin exposes the following metrics through the native
Prometheus exporter of the instance manager:
- `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp`:
the UNIX timestamp of the most recent failed backup.
- `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp`:
the UNIX timestamp of the most recent successfully available backup.
- `barman_cloud_cloudnative_pg_io_first_recoverability_point`:
the UNIX timestamp representing the earliest point in time from which the
cluster can be recovered.
These metrics supersede the previously available in-core metrics that used the
`cnpg_collector` prefix. The new metrics are exposed under the
`barman_cloud_cloudnative_pg_io` prefix instead.

19
web/versioned_docs/version-0.10.0/parameters.md
View File

@ -1,19 +0,0 @@
---
sidebar_position: 100
---
# Parameters
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The following parameters are available for the Barman Cloud Plugin:
- `barmanObjectName`: references the `ObjectStore` resource to be used by the
plugin.
- `serverName`: Specifies the server name in the object store.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::

108
web/versioned_docs/version-0.10.0/plugin-barman-cloud.v1.md
View File

@ -1,108 +0,0 @@
# API Reference
## Packages
- [barmancloud.cnpg.io/v1](#barmancloudcnpgiov1)
## barmancloud.cnpg.io/v1
Package v1 contains API Schema definitions for the barmancloud v1 API group
### Resource Types
- [ObjectStore](#objectstore)
#### InstanceSidecarConfiguration
InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.
_Appears in:_
- [ObjectStoreSpec](#objectstorespec)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#envvar-v1-core) array_ | The environment to be explicitly passed to the sidecar | | | |
| `retentionPolicyIntervalSeconds` _integer_ | The retentionCheckInterval defines the frequency at which the<br />system checks and enforces retention policies. | | 1800 | |
| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#resourcerequirements-v1-core)_ | Resources define cpu/memory requests and limits for the sidecar that runs in the instance pods. | | | |
| `additionalContainerArgs` _string array_ | AdditionalContainerArgs is an optional list of command-line arguments<br />to be passed to the sidecar container when it starts.<br />The provided arguments are appended to the container’s default arguments. | | | |
| `logLevel` _string_ | The log level for PostgreSQL instances. Valid values are: `error`, `warning`, `info` (default), `debug`, `trace` | | info | Enum: [error warning info debug trace] <br /> |
#### ObjectStore
ObjectStore is the Schema for the objectstores API.
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `apiVersion` _string_ | `barmancloud.cnpg.io/v1` | True | | |
| `kind` _string_ | `ObjectStore` | True | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | True | | |
| `spec` _[ObjectStoreSpec](#objectstorespec)_ | Specification of the desired behavior of the ObjectStore.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | True | | |
| `status` _[ObjectStoreStatus](#objectstorestatus)_ | Most recently observed status of the ObjectStore. This data may not be up to<br />date. Populated by the system. Read-only.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | | | |
#### ObjectStoreSpec
ObjectStoreSpec defines the desired state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `configuration` _[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)_ | The configuration for the barman-cloud tool suite | True | | |
| `retentionPolicy` _string_ | RetentionPolicy is the retention policy to be used for backups<br />and WALs (i.e. '60d'). The retention policy is expressed in the form<br />of `XXu` where `XX` is a positive integer and `u` is in `[dwm]` -<br />days, weeks, months. | | | Pattern: `^[1-9][0-9]*[dwm]$` <br /> |
| `instanceSidecarConfiguration` _[InstanceSidecarConfiguration](#instancesidecarconfiguration)_ | The configuration for the sidecar that runs in the instance pods | | | |
#### ObjectStoreStatus
ObjectStoreStatus defines the observed state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `serverRecoveryWindow` _object (keys:string, values:[RecoveryWindow](#recoverywindow))_ | ServerRecoveryWindow maps each server to its recovery window | True | | |
#### RecoveryWindow
RecoveryWindow represents the time span between the first
recoverability point and the last successful backup of a PostgreSQL
server, defining the period during which data can be restored.
_Appears in:_
- [ObjectStoreStatus](#objectstorestatus)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `firstRecoverabilityPoint` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The first recoverability point in a PostgreSQL server refers to<br />the earliest point in time to which the database can be<br />restored. | True | | |
| `lastSuccessfulBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last successful backup time | True | | |
| `lastFailedBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last failed backup time | True | | |

219
web/versioned_docs/version-0.10.0/resource-name-migration.md
View File

@ -1,219 +0,0 @@
---
sidebar_position: 90
---
# Resource name migration guide
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::warning
Before proceeding with the migration process, please:
1. **Read this guide in its entirety** to understand what changes will be made
2. **Test in a non-production environment** first if possible
3. **Ensure you have proper backups** of your cluster configuration
This migration will delete old RBAC resources only after the
`plugin-barman-cloud` upgrade. While the operation is designed to be safe, you
should review and understand the changes before proceeding. The maintainers of
this project are not responsible for any issues that may arise during
migration.
**Note:** This guide assumes you are using the default `cnpg-system` namespace.
:::
## Overview
Starting from version **0.8.0**, the `plugin-barman-cloud` deployment manifests
use more specific, prefixed resource names to avoid conflicts with other
components deployed in the same Kubernetes cluster.
## What Changed
The following resources have been renamed to use proper prefixes.
### Cluster-scoped Resources
| Old Name | New Name |
|----------------------------|------------------------------------------|
| `metrics-auth-role` | `barman-plugin-metrics-auth-role` |
| `metrics-auth-rolebinding` | `barman-plugin-metrics-auth-rolebinding` |
| `metrics-reader` | `barman-plugin-metrics-reader` |
| `objectstore-viewer-role` | `barman-plugin-objectstore-viewer-role` |
| `objectstore-editor-role` | `barman-plugin-objectstore-editor-role` |
### Namespace-scoped Resources
| Old Name | New Name | Namespace |
|-------------------------------|---------------------------------------------|---------------|
| `leader-election-role` | `barman-plugin-leader-election-role` | `cnpg-system` |
| `leader-election-rolebinding` | `barman-plugin-leader-election-rolebinding` | `cnpg-system` |
## Why This Change?
Using generic names for cluster-wide resources is discouraged as they may
conflict with other components deployed in the same cluster. The new names make
it clear that these resources belong to the Barman Cloud plugin and help avoid
naming collisions.
## Migration Instructions
This three steps migration process is straightforward and can be completed with
a few `kubectl` commands.
### Step 1: Upgrade plugin-barman-cloud
Please refer to the [Installation](installation.mdx) section to deploy the new
`plugin-barman-cloud` release.
### Step 2: Delete Old Cluster-scoped Resources
:::danger Verify Resources Before Deletion
**IMPORTANT**: The old resource names are generic and could potentially belong
to other components in your cluster.
**Before deleting each resource, verify it belongs to the Barman Cloud plugin
by checking:**
- For `objectstore-*` roles: Look for `barmancloud.cnpg.io` in the API groups
- For `metrics-*` roles: Check if they reference the `plugin-barman-cloud`
ServiceAccount in `cnpg-system` namespace
- For other roles: Look for labels like `app.kubernetes.io/name: plugin-barman-cloud`
If a resource doesn't have these indicators, **DO NOT DELETE IT** as it may
belong to another application.
Carefully review the output of each verification command before proceeding with
the `delete`.
:::
:::tip Dry Run First
You can add `--dry-run=client` to any `kubectl delete` command to preview what
would be deleted without actually removing anything.
:::
**Only proceed if you've verified these resources belong to the Barman Cloud
plugin (see warning above).**
For each resource below, first verify it belongs to Barman Cloud, then delete
it:
```bash
# 1. Check metrics-auth-rolebinding FIRST (we'll check the role after)
# Look for references to plugin-barman-cloud ServiceAccount
kubectl describe clusterrolebinding metrics-auth-rolebinding
# If it references plugin-barman-cloud ServiceAccount in cnpg-system namespace,
# delete it:
kubectl delete clusterrolebinding metrics-auth-rolebinding
# 2. Check metrics-auth-role
# Look for references to authentication.k8s.io and authorization.k8s.io
kubectl describe clusterrole metrics-auth-role
# Verify it's not being used by any other rolebindings:
kubectl get clusterrolebinding -o json \
| jq -r '.items[] | select(.roleRef.name=="metrics-auth-role") \
| .metadata.name'
# If the above returns nothing (role is not in use) and the role looks like the
# Barman Cloud one, delete it (see warnings section):
kubectl delete clusterrole metrics-auth-role
# 3. Check objectstore-viewer-role
# Look for barmancloud.cnpg.io API group or
# for `app.kubernetes.io/name: plugin-barman-cloud` label
kubectl describe clusterrole objectstore-viewer-role
# If it shows barmancloud.cnpg.io in API groups, delete it:
kubectl delete clusterrole objectstore-viewer-role
# 4. Check objectstore-editor-role
# Look for barmancloud.cnpg.io API group or
# for `app.kubernetes.io/name: plugin-barman-cloud` label
kubectl describe clusterrole objectstore-editor-role
# If it shows barmancloud.cnpg.io in API groups, delete it:
kubectl delete clusterrole objectstore-editor-role
# 5. Check metrics-reader (MOST DANGEROUS - very generic name)
# First, check if it's being used by any rolebindings OTHER than barman's:
kubectl get clusterrolebinding -o json | jq -r '.items[] \
| select(.roleRef.name=="metrics-reader") \
| "\(.metadata.name) -> \(.subjects[0].name) in \(.subjects[0].namespace)"'
# If this shows ANY rolebindings, review them carefully. Only proceed if
# they're all Barman-related. Then check the role itself:
kubectl describe clusterrole metrics-reader
# If it ONLY has nonResourceURLs: /metrics and NO other rolebindings use it,
# delete it:
kubectl delete clusterrole metrics-reader
```
:::warning
The `metrics-reader` role is particularly dangerous to delete blindly. Many
monitoring systems use this exact name. Only delete it if:
1. You've verified it ONLY grants access to `/metrics`
2. No other rolebindings reference it (checked with the jq command above)
3. You're certain it was created by the Barman Cloud plugin
If you're unsure, it's safer to leave it and let the new
`barman-plugin-metrics-reader` role coexist with it.
:::
If any resource is not found during the `describe` command, that's okay - it
means it was never created or already deleted. Simply skip the delete command
for that resource.
### Step 3: Delete Old Namespace-scoped Resources
Delete the old namespace-scoped resources in the `cnpg-system` namespace:
```bash
# Delete the old leader-election resources
kubectl delete role leader-election-role -n cnpg-system
kubectl delete rolebinding leader-election-rolebinding -n cnpg-system
```
If any resource is not found, that's okay - it means it was never created or
already deleted.
## Impact
- **Permissions:** If you have custom RBAC rules or tools that reference the
old resource names, they will need to be updated.
- **External Users:** If end users have been granted the
`objectstore-viewer-role` or `objectstore-editor-role`, they will need to be
re-granted the new role names (`barman-plugin-objectstore-viewer-role` and
`barman-plugin-objectstore-editor-role`).
## Verification
After migration, verify that the new resources are created:
```bash
# Check cluster-scoped resources
kubectl get clusterrole | grep barman
kubectl get clusterrolebinding | grep barman
# Check namespace-scoped resources
kubectl get role,rolebinding -n cnpg-system | grep barman
```
You should see the new prefixed resource names.
## Troubleshooting
### Plugin Not Starting After Migration
If the plugin fails to start after migration, check:
1. **ServiceAccount permissions:** Ensure the `plugin-barman-cloud` ServiceAccount is bound to the new roles:
```bash
kubectl get clusterrolebinding barman-plugin-metrics-auth-rolebinding -o yaml
kubectl get rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system -o yaml
```
2. **Role references:** Verify that the rolebindings reference the correct role names:
```bash
kubectl describe rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system
kubectl describe clusterrolebinding barman-plugin-metrics-auth-rolebinding
```
## Support
If you encounter issues during migration, please open an issue on the [GitHub
repository](https://github.com/cloudnative-pg/plugin-barman-cloud/issues).

38
web/versioned_docs/version-0.10.0/retention.md
View File

@ -1,38 +0,0 @@
---
sidebar_position: 60
---
# Retention Policies
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin supports **automated cleanup of obsolete backups** via
retention policies, configured in the `.spec.retentionPolicy` field of the
`ObjectStore` resource.
:::note
This feature uses the `barman-cloud-backup-delete` command with the
`--retention-policy "RECOVERY WINDOW OF {{ value }} {{ unit }}"` syntax.
:::
#### Example: 30-Day Retention Policy
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
[...]
retentionPolicy: "30d"
````
:::note
A **recovery window retention policy** ensures the cluster can be restored to
any point in time between the calculated *Point of Recoverability* (PoR) and
the latest WAL archive. The PoR is defined as `current time - recovery window`.
The **first valid backup** is the most recent backup completed before the PoR.
Backups older than that are marked as *obsolete* and deleted after the next
backup completes.
:::

591
web/versioned_docs/version-0.10.0/troubleshooting.md
View File

@ -1,591 +0,0 @@
---
sidebar_position: 90
---
# Troubleshooting
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
This guide helps you diagnose and resolve common issues with the Barman Cloud
plugin.
:::important
We are continuously improving the integration between CloudNativePG and the
Barman Cloud plugin as it moves toward greater stability and maturity. For this
reason, we recommend using the latest available version of both components.
See the [*Requirements* section](intro.md#requirements) for details.
:::
:::note
The following commands assume you installed the CloudNativePG operator in
the default `cnpg-system` namespace. If you installed it in a different
namespace, adjust the commands accordingly.
:::
## Viewing Logs
To troubleshoot effectively, you’ll often need to review logs from multiple
sources:
```sh
# View operator logs (includes plugin interaction logs)
kubectl logs -n cnpg-system deployment/cnpg-controller-manager -f
# View plugin manager logs
kubectl logs -n cnpg-system deployment/barman-cloud -f
# View sidecar container logs (Barman Cloud operations)
kubectl logs -n <namespace> <cluster-pod-name> -c plugin-barman-cloud -f
# View all containers in a pod
kubectl logs -n <namespace> <cluster-pod-name> --all-containers=true
# View previous container logs (if container restarted)
kubectl logs -n <namespace> <cluster-pod-name> -c plugin-barman-cloud --previous
```
## Common Issues
### Plugin Installation Issues
#### Plugin pods not starting
**Symptoms:**
- Plugin pods stuck in `CrashLoopBackOff` or `Error`
- Plugin deployment not ready
**Possible causes and solutions:**
1. **Certificate issues**
```sh
# Check if cert-manager is installed and running
kubectl get pods -n cert-manager
# Check if the plugin certificate is created
kubectl get certificates -n cnpg-system
```
If cert-manager is not installed, install it first:
```sh
# Note: other installation methods for cert-manager are available
kubectl apply -f \
https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
```
If you are using your own certificates without cert-manager, you will need
to verify the entire certificate chain yourself.
2. **Image pull errors**
```sh
# Check pod events for image pull errors
kubectl describe pod -n cnpg-system -l app=barman-cloud
```
Verify the image exists and you have proper credentials if using a private
registry.
3. **Resource constraints**
```sh
# Check node resources
kubectl top nodes
kubectl describe nodes
```
Make sure your cluster has sufficient CPU and memory resources.
### Backup Failures
#### Quick Backup Troubleshooting Checklist
When a backup fails, follow these steps in order:
1. **Check backup status**:
```sh
kubectl get backups.postgresql.cnpg.io -n <namespace>
```
2. **Get error details and target pod**:
```sh
kubectl describe backups.postgresql.cnpg.io \
-n <namespace> <backup-name>
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}'
```
3. **Check the target pod’s sidecar logs**:
```sh
TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}')
kubectl logs \
-n <namespace> $TARGET_POD -c plugin-barman-cloud \
--tail=100 | grep -E "ERROR|FATAL|panic"
```
4. **Check cluster events**:
```sh
kubectl get events -n <namespace> \
--field-selector involvedObject.name=<cluster-name> \
--sort-by='.lastTimestamp'
```
5. **Verify plugin is running**:
```sh
kubectl get pods \
-n cnpg-system -l app=barman-cloud
```
6. **Check operator logs**:
```sh
kubectl logs \
-n cnpg-system deployment/cnpg-controller-manager \
--tail=100 | grep -i "backup\|plugin"
```
7. **Check plugin manager logs**:
```sh
kubectl logs \
-n cnpg-system deployment/barman-cloud --tail=100
```
#### Backup job fails immediately
**Symptoms:**
- Backup pods terminate with error
- No backup files appear in object storage
- Backup shows `failed` phase with various error messages
**Common failure modes and solutions:**
1. **"requested plugin is not available" errors**
```
requested plugin is not available: barman
requested plugin is not available: barman-cloud
requested plugin is not available: barman-cloud.cloudnative-pg.io
```
**Cause:** The plugin name in the Cluster configuration doesn’t match the
deployed plugin, or the plugin isn’t registered.
**Solution:**
a. **Check plugin registration:**
```sh
# If you have the `cnpg` plugin installed (v1.27.0+)
kubectl cnpg status -n <namespace> <cluster-name>
```
Look for the "Plugins status" section:
```
Plugins status
Name Version Status Reported Operator Capabilities
---- ------- ------ ------------------------------
barman-cloud.cloudnative-pg.io 0.6.0 N/A Reconciler Hooks, Lifecycle Service
```
b. **Verify plugin name in `Cluster` spec**:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
plugins:
- name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: <your-objectstore-name>
```
c. **Check plugin deployment is running**:
```sh
kubectl get deployment -n cnpg-system barman-cloud
```
2. **"rpc error: code = Unknown desc = panic caught: assignment to entry in nil map" errors**
**Cause:** Misconfiguration in the `ObjectStore` (e.g., typo or missing field).
**Solution:**
- Review sidecar logs for details
- Verify `ObjectStore` configuration and secrets
- Common issues include:
- Missing or incorrect secret references
- Typos in configuration parameters
- Missing required environment variables in secrets
#### Backup performance issues
**Symptoms:**
- Backups take extremely long
- Backups timeout
**Plugin-specific considerations:**
1. **Check `ObjectStore` parallelism settings**
- Adjust `maxParallel` in `ObjectStore` configuration
- Monitor sidecar container resource usage during backups
2. **Verify plugin resource allocation**
- Check if the sidecar container has sufficient CPU/memory
- Review plugin container logs for resource-related warnings
:::tip
For Barman-specific features like compression, encryption, and performance
tuning, refer to the [Barman documentation](https://docs.pgbarman.org/latest/).
:::
### WAL Archiving Issues
#### WAL archiving stops
**Symptoms:**
- WAL files accumulate on the primary
- Cluster shows WAL archiving warnings
- Sidecar logs show WAL errors
**Debugging steps:**
1. **Check plugin sidecar logs for WAL archiving errors**
```sh
# Check recent WAL archive operations in sidecar
kubectl logs -n <namespace> <primary-pod> -c plugin-barman-cloud \
--tail=50 | grep -i wal
```
2. **Check ObjectStore configuration for WAL settings**
- Ensure ObjectStore has proper WAL retention settings
- Verify credentials have permissions for WAL operations
### Restore Issues
#### Restore fails during recovery
**Symptoms:**
- New cluster stuck in recovery
- Plugin sidecar shows restore errors
- PostgreSQL won’t start
**Debugging steps:**
1. **Check plugin sidecar logs during restore**
```sh
# Check the sidecar logs on the recovering cluster pods
kubectl logs -n <namespace> <cluster-pod-name> \
-c plugin-barman-cloud --tail=100
# Look for restore-related errors
kubectl logs -n <namespace> <cluster-pod-name> \
-c plugin-barman-cloud | grep -E "restore|recovery|ERROR"
```
2. **Verify plugin can access backups**
```sh
# Check if `ObjectStore` is properly configured for restore
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Check PostgreSQL recovery logs
kubectl logs -n <namespace> <cluster-pod> \
-c postgres | grep -i recovery
```
:::tip
For detailed Barman restore operations and troubleshooting, refer to the
[Barman documentation](https://docs.pgbarman.org/latest/barman-cloud-restore.html).
:::
#### Point-in-time recovery (PITR) configuration issues
**Symptoms:**
- PITR doesn’t reach target time
- WAL access errors
- Recovery halts early
**Debugging steps:**
1. **Verify PITR configuration in the `Cluster` spec**
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: <cluster-restore-name>
spec:
storage:
size: 1Gi
bootstrap:
recovery:
source: origin
recoveryTarget:
targetTime: "2024-01-15T10:30:00Z"
externalClusters:
- name: origin
plugin:
enabled: true
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: <object-store-name>
serverName: <source-cluster-name>
```
2. **Check sidecar logs for WAL-related errors**
```sh
kubectl logs -n <namespace> <cluster-pod> \
-c plugin-barman-cloud | grep -i wal
```
:::note
Timestamps without an explicit timezone suffix
(e.g., `2024-01-15 10:30:00`) are interpreted as UTC.
:::
:::warning
Always specify an explicit timezone in your timestamp to avoid ambiguity.
For example, use `2024-01-15T10:30:00Z` or `2024-01-15T10:30:00+02:00`
instead of `2024-01-15 10:30:00`.
:::
:::note
For detailed PITR configuration and WAL management, see the
[Barman PITR documentation](https://docs.pgbarman.org/latest/).
:::
### Plugin Configuration Issues
#### Plugin cannot connect to object storage
**Symptoms:**
- Sidecar logs show connection errors
- Backups fail with authentication or network errors
- `ObjectStore` resource reports errors
**Solution:**
1. **Verify `ObjectStore` CRD configuration and secrets**
```sh
# Check ObjectStore resource status
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Verify the secret exists and has correct keys for your provider
kubectl get secret -n <namespace> <secret-name> \
-o jsonpath='{.data}' | jq 'keys'
```
2. **Check sidecar logs for connectivity issues**
```sh
kubectl logs -n <namespace> <cluster-pod> \
-c plugin-barman-cloud | grep -E "connect|timeout|SSL|cert"
```
3. **Adjust provider-specific settings (endpoint, path style, etc.)**
- See [Object Store Configuration](object_stores.md) for provider-specific settings
- Ensure `endpointURL` match your storage type
- Verify network policies allow egress to your storage provider
## Diagnostic Commands
### Using the `cnpg` plugin for `kubectl`
The `cnpg` plugin for `kubectl` provides extended debugging capabilities.
Keep it updated:
```sh
# Install or update the `cnpg` plugin
kubectl krew install cnpg
# Or using an alternative method: https://cloudnative-pg.io/documentation/current/kubectl-plugin/#install
# Check plugin status (requires CNPG 1.27.0+)
kubectl cnpg status <cluster-name> -n <namespace>
# View cluster status in detail
kubectl cnpg status <cluster-name> -n <namespace> --verbose
```
## Getting Help
If problems persist:
1. **Check the documentation**
- [Installation Guide](installation.mdx)
- [Object Store Configuration](object_stores.md) (for provider-specific settings)
- [Usage Examples](usage.md)
2. **Gather diagnostic information**
```sh
# Create a diagnostic bundle (⚠️ sanitize these before sharing!)
kubectl get objectstores.barmancloud.cnpg.io -A -o yaml > /tmp/objectstores.yaml
kubectl get clusters.postgresql.cnpg.io -A -o yaml > /tmp/clusters.yaml
kubectl logs -n cnpg-system deployment/barman-cloud --tail=1000 > /tmp/plugin.log
```
3. **Community support**
- CloudNativePG Slack: [#cloudnativepg-users](https://cloud-native.slack.com/messages/cloudnativepg-users)
- GitHub Issues: [plugin-barman-cloud](https://github.com/cloudnative-pg/plugin-barman-cloud/issues)
4. **Include when reporting**
- CloudNativePG version
- Plugin version
- Kubernetes version
- Cloud provider and region
- Relevant configuration (⚠️ sanitize/redact sensitive information)
- Error messages and logs
- Steps to reproduce
## Known Issues and Limitations
### Current Known Issues
1. **Migration compatibility**: After migrating from in-tree backup to the
plugin, the `kubectl cnpg backup` command syntax has changed
([#353](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/353)):
```sh
# Old command (in-tree, no longer works after migration)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=barmanObjectStore
# New command (plugin-based)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin --plugin-name=barman-cloud.cloudnative-pg.io
```
### Plugin Limitations
1. **Installation method**: Currently only supports manifest and Kustomize
installation ([#351](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/351) -
Helm chart requested)
2. **Sidecar resource sharing**: The plugin sidecar container shares pod
resources with PostgreSQL
3. **Plugin restart behavior**: Restarting the sidecar container requires
restarting the entire PostgreSQL pod
## Recap of General Debugging Steps
### Check Backup Status and Identify the Target Instance
```sh
# List all backups and their status
kubectl get backups.postgresql.cnpg.io -n <namespace>
# Get detailed backup information including error messages and target instance
kubectl describe backups.postgresql.cnpg.io \
-n <namespace> <backup-name>
# Extract the target pod name from a failed backup
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}'
# Get more details including the target pod, method, phase, and error
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='Pod: {.status.instanceID.podName}{"\n"}Method: {.status.method}{"\n"}Phase: {.status.phase}{"\n"}Error: {.status.error}{"\n"}'
# Check the cluster status for backup-related information
kubectl cnpg status <cluster-name> -n <namespace> --verbose
```
### Check Sidecar Logs on the Backup Target Pod
```sh
# Identify which pod was the backup target (from the previous step)
TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}')
echo "Backup target pod: $TARGET_POD"
# Check the sidecar logs on the specific target pod
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud --tail=100
# Follow the logs in real time
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud -f
# Check for specific errors in the target pod around the backup time
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud --since=10m | grep -E "ERROR|FATAL|panic|failed"
# Alternative: List all cluster pods and their roles
kubectl get pods -n <namespace> -l cnpg.io/cluster=<cluster-name> \
-o custom-columns=NAME:.metadata.name,ROLE:.metadata.labels.cnpg\\.io/instanceRole,INSTANCE:.metadata.labels.cnpg\\.io/instanceName
# Check sidecar logs on ALL cluster pods (if the target is unclear)
for pod in $(kubectl get pods -n <namespace> -l cnpg.io/cluster=<cluster-name> -o name); do
echo "=== Checking $pod ==="
kubectl logs -n <namespace> $pod -c plugin-barman-cloud \
--tail=20 | grep -i error || echo "No errors found"
done
```
### Check Events for Backup-Related Issues
```sh
# Check events for the cluster
kubectl get events -n <namespace> \
--field-selector involvedObject.name=<cluster-name>
# Check events for failed backups
kubectl get events -n <namespace> \
--field-selector involvedObject.kind=Backup
# Get all recent events in the namespace
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -20
```
### Verify `ObjectStore` Configuration
```sh
# Check the ObjectStore resource
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Verify the secret exists and has the correct keys
kubectl get secret -n <namespace> <secret-name> -o yaml
# Alternatively
kubectl get secret -n <namespace> <secret-name> -o jsonpath='{.data}' | jq 'keys'
```
### Common Error Messages and Solutions
* **"AccessDenied" or "403 Forbidden"** — Check cloud credentials and bucket permissions.
* **"NoSuchBucket"** — Verify the bucket exists and the endpoint URL is correct.
* **"Connection timeout"** — Check network connectivity and firewall rules.
* **"SSL certificate problem"** — For self-signed certificates, verify the CA bundle configuration.

16
web/versioned_docs/version-0.10.0/upgrades.mdx
View File

@ -1,16 +0,0 @@
---
sidebar_position: 25
---
# Upgrades
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
You can upgrade the plugin simply by installing the new version. Unless
explicitly stated below or in the release notes, no special steps are required.
## Upgrading to version 0.8.x from previous versions
Version **0.8.0** introduces breaking changes to resource naming.
To complete the upgrade successfully, follow the instructions in the
["Resource name migration guide"](resource-name-migration.md).

283
web/versioned_docs/version-0.10.0/usage.md
View File

@ -1,283 +0,0 @@
---
sidebar_position: 30
---
# Using the Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
After [installing the plugin](installation.mdx) in the same namespace as the
CloudNativePG operator, enabling your PostgreSQL cluster to use the Barman
Cloud Plugin involves just a few steps:
- Defining the object store containing your WAL archive and base backups, using
your preferred [provider](object_stores.md)
- Instructing the Postgres cluster to use the Barman Cloud Plugin
From that moment, you’ll be able to issue on-demand backups or define a backup
schedule, as well as rely on the object store for recovery operations.
The rest of this page details each step, using MinIO as object store provider.
## Defining the `ObjectStore`
An `ObjectStore` resource must be created for each object store used in your
PostgreSQL architecture. Here's an example configuration 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` schema follows the same format 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/current/appendixes/backup_barmanobjectstore/)
for additional details.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::
## Configuring WAL Archiving
Once the `ObjectStore` is defined, you can configure your PostgreSQL cluster
to archive WALs by referencing the store in the `.spec.plugins` section:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
instances: 3
imagePullPolicy: Always
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
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. Backups can be
created either declaratively (with YAML manifests) or imperatively (with the
`cnpg` plugin).
### Declarative approach (YAML manifest)
Create a backup resource by applying a YAML manifest:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
name: backup-example
spec:
cluster:
name: cluster-example
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
### Imperative approach (using the `cnpg` plugin)
The quickest way to trigger an on-demand backup is with the `cnpg` plugin:
```bash
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin \
--plugin-name=barman-cloud.cloudnative-pg.io
```
:::note Migration from in-tree backups
If you are migrating from the in-tree backup system, note the change in syntax:
```bash
# Old command (in-tree backup)
kubectl cnpg backup -n <namespace> <cluster-name> --method=barmanObjectStore
# New command (plugin-based backup)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin \
--plugin-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
```
:::important
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
isWALArchiver: true
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
isWALArchiver: true
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
```
## Configuring the plugin instance sidecar
The Barman Cloud Plugin runs as a sidecar container next to each PostgreSQL
instance pod. It manages backup, WAL archiving, and restore processes.
Configuration comes from multiple `ObjectStore` resources:
1. The one referenced in the
`.spec.plugins` section of the `Cluster`. This is the
object store used for WAL archiving and base backups.
2. The one referenced in the external cluster
used in the `.spec.replica.source` section of the `Cluster`. This is
used by the log-shipping designated primary to get the WAL files.
3. The one referenced in the
`.spec.bootstrap.recovery.source` section of the `Cluster`. Used by
the initial recovery job to create the cluster from an existing backup.
You can fine-tune sidecar behavior in the `.spec.instanceSidecarConfiguration`
of your ObjectStore. These settings apply to all PostgreSQL instances that use
this object store. Any updates take effect at the next `Cluster` reconciliation,
and could generate a rollout of the `Cluster`.
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
# [...]
instanceSidecarConfiguration:
retentionPolicyIntervalSeconds: 1800
resources:
requests:
memory: "XXX"
cpu: "YYY"
limits:
memory: "XXX"
cpu: "YYY"
```
:::note
If more than one `ObjectStore` applies, the `instanceSidecarConfiguration` of
the one set in `.spec.plugins` has priority.
:::

43
web/versioned_docs/version-0.11.0/compression.md
View File

@ -1,43 +0,0 @@
---
sidebar_position: 80
---
# Compression
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
By default, backups and WAL files are archived **uncompressed**. However, the
Barman Cloud Plugin supports multiple compression algorithms via
`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
for space, speed, or a balance of both.
### Supported Compression Algorithms
- `bzip2`
- `gzip`
- `lz4` (WAL only)
- `snappy`
- `xz` (WAL only)
- `zstd` (WAL only)
Compression settings for base backups and WAL archives are configured
independently. For implementation details, refer to the corresponding API
definitions:
- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
:::important
Compression impacts both performance and storage efficiency. Choose the right
algorithm based on your recovery time objectives (RTO), storage capacity, and
network throughput.
:::
## Compression Benchmark (on MinIO)
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |

177
web/versioned_docs/version-0.11.0/concepts.md
View File

@ -1,177 +0,0 @@
---
sidebar_position: 10
---
# Main Concepts
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::important
Before proceeding, make sure to review the following sections of the
CloudNativePG documentation:
- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
:::
The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
supporting continuous physical backups and WAL archiving to an **object
store**—without interrupting write operations.
It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
of a PostgreSQL cluster.
## The Object Store
At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
which acts as the interface between the PostgreSQL cluster and the target
object storage system. It allows you to configure:
- **Authentication and bucket location** via the `.spec.configuration` section
- **WAL archiving** settings—such as compression type, parallelism, and
server-side encryption—under `.spec.configuration.wal`
- **Base backup options**—with similar settings for compression, concurrency,
and encryption—under `.spec.configuration.data`
- **Retention policies** to manage the life-cycle of archived WALs and backups
via `.spec.configuration.retentionPolicy`
WAL files are archived in the `wals` directory, while base backups are stored
as **tarballs** in the `base` directory, following the
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
The plugin also offers advanced capabilities, including
[backup tagging](misc.md#backup-object-tagging) and
[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving).
:::tip
For details, refer to the
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).
:::
## Integration with a CloudNativePG Cluster
CloudNativePG can delegate continuous backup and recovery responsibilities to
the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
to be defined.
:::important
While it is technically possible to reuse the same `ObjectStore` for multiple
`Cluster` resources within the same namespace, it is strongly recommended to
dedicate one object store per PostgreSQL cluster to ensure data isolation and
operational clarity.
:::
The following example demonstrates how to configure a CloudNativePG cluster
named `cluster-example` to use a previously defined `ObjectStore` (also named
`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
WAL archiving through the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
# Other cluster settings...
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: cluster-example
```
## Backup of a Postgres Cluster
Once the object store is defined and the `Cluster` is configured to use the
Barman Cloud Plugin, **WAL archiving is activated immediately** on the
PostgreSQL primary.
Physical base backups are seamlessly managed by CloudNativePG using the
`Backup` and `ScheduledBackup` resources, respectively for
[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
and
[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
backups.
To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
configure the `pluginConfiguration` section as shown:
```yaml
[...]
spec:
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
[...]
```
With this configuration, CloudNativePG supports:
- Backups from both **primary** and **standby** instances
- Backups from **designated primaries** in a distributed topology using
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
:::tip
For details on how to back up from a standby, refer to the official documentation:
[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
:::
:::important
Both backup and WAL archiving operations are executed by sidecar containers
running in the same pod as the PostgreSQL `Cluster` primary instance—except
when backups are taken from a standby, in which case the sidecar runs alongside
the standby pod.
The sidecar containers use a [dedicated container image](images.md) that
includes only the supported version of Barman Cloud.
:::
## Recovery of a Postgres Cluster
In PostgreSQL, *recovery* refers to the process of starting a database instance
from an existing backup. The Barman Cloud Plugin integrates with CloudNativePG
to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
object store.
Recovery in this context is *not in-place*: it bootstraps a brand-new
PostgreSQL cluster from a backup and replays the necessary WAL files to reach
the desired recovery target.
To perform a recovery, define an *external cluster* that references the
appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
of the target cluster:
```yaml
[...]
spec:
[...]
bootstrap:
recovery:
source: source
externalClusters:
- name: source
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: cluster-example
serverName: cluster-example
[...]
```
The critical element here is the `externalClusters` section of the `Cluster`
resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
Cloud Plugin to access the object store for recovery.
This same mechanism can be used for a variety of scenarios enabled by the
CloudNativePG API, including:
* **Full cluster recovery** from the latest backup
* **Point-in-Time Recovery (PITR)**
* Bootstrapping **replica clusters** in a distributed topology
:::tip
For complete instructions and advanced use cases, refer to the official
[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
:::

37
web/versioned_docs/version-0.11.0/images.md
View File

@ -1,37 +0,0 @@
---
sidebar_position: 99
---
# Container Images
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin is distributed using two container images:
- One for deploying the plugin components
- One for the sidecar that runs alongside each PostgreSQL instance in a
CloudNativePG `Cluster` using the plugin
## Plugin Container Image
The plugin image contains the logic required to operate the Barman Cloud Plugin
within your Kubernetes environment with CloudNativePG. It is published on the
GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
This image is built from the
[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
in the plugin repository.
## Sidecar Container Image
The sidecar image is used within each PostgreSQL pod in the cluster. It
includes the latest supported version of Barman Cloud and is responsible for
performing WAL archiving and backups on behalf of CloudNativePG.
It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
built from the
[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
These sidecar images are designed to work seamlessly with the
[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
maintained by the CloudNativePG Community.

109
web/versioned_docs/version-0.11.0/installation.mdx
View File

@ -1,109 +0,0 @@
---
sidebar_position: 20
---
# Installation
:::important
1. The plugin **must** be installed in the same namespace as the CloudNativePG
operator (typically `cnpg-system`).
2. Keep in mind that the operator's **listening namespaces** may differ from its
installation namespace. Double-check this to avoid configuration issues.
:::
## Verifying the Requirements
Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
### CloudNativePG Version
Ensure you're running a version of CloudNativePG that is compatible with the
plugin. If installed in the default `cnpg-system` namespace, you can verify the
version with:
```sh
kubectl get deployment -n cnpg-system cnpg-controller-manager \
-o jsonpath="{.spec.template.spec.containers[*].image}"
```
Example output:
```output
ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
```
The version **must be 1.26 or newer**.
### cert-manager
Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
tool to confirm that `cert-manager` is installed and available:
```sh
cmctl check api
```
Example output:
```output
The cert-manager API is ready
```
Both checks are required before proceeding with the installation.
## Installing the Barman Cloud Plugin
import { InstallationSnippet } from '@site/src/components/Installation';
Install the plugin using `kubectl` by applying the manifest for the latest
release:
<InstallationSnippet />
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
```
Finally, check that the deployment is up and running:
```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 ready to use.
## Testing the latest development snapshot
You can also test the latest development snapshot of the plugin with the
following command:
```sh
kubectl apply -f \
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
```

86
web/versioned_docs/version-0.11.0/intro.md
View File

@ -1,86 +0,0 @@
---
sidebar_position: 1
sidebar_label: "Introduction"
---
# Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The **Barman Cloud Plugin** for [CloudNativePG](https://cloudnative-pg.io/)
enables online continuous physical backups of PostgreSQL clusters to object storage
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
project.
:::important
If you plan to migrate your existing CloudNativePG cluster to the new
plugin-based approach using the Barman Cloud Plugin, see
["Migrating from Built-in CloudNativePG Backup"](migration.md)
for detailed instructions.
:::
## Requirements
Before using the Barman Cloud Plugin, ensure that the following components are
installed and properly configured:
- [CloudNativePG](https://cloudnative-pg.io) version 1.26 or later
- We strongly recommend version 1.27.0 or later, which includes improved
error handling and status reporting for the plugin.
- If you are running an earlier release, refer to the
[upgrade guide](https://cloudnative-pg.io/documentation/current/installation_upgrade).
- [cert-manager](https://cert-manager.io/)
- The recommended way to enable secure TLS communication between the plugin
and the operator.
- Alternatively, you can provide your own certificate bundles. See the
[CloudNativePG documentation on TLS configuration](https://cloudnative-pg.io/documentation/current/cnpg_i/#configuring-tls-certificates).
- [`kubectl-cnpg`](https://cloudnative-pg.io/documentation/current/kubectl-plugin/)
plugin (optional but recommended)
- Simplifies debugging and monitoring with additional status and inspection
commands.
- Multiple installation options are available in the
[installation guide](https://cloudnative-pg.io/documentation/current/kubectl-plugin/#install).
## Key Features
This plugin provides the following capabilities:
- Physical online backup of the data directory
- Physical restore of the data directory
- Write-Ahead Log (WAL) archiving
- WAL restore
- Full cluster recovery
- Point-in-Time Recovery (PITR)
- Seamless integration with replica clusters for bootstrap and WAL restore from archive
:::important
The Barman Cloud Plugin is designed to **replace the in-tree object storage support**
previously provided via the `.spec.backup.barmanObjectStore` section in the
`Cluster` resource.
Backups created using the in-tree approach are fully supported and compatible
with this plugin.
:::
## Supported Object Storage Providers
The plugin works with all storage backends supported by `barman-cloud`, including:
- **Amazon S3**
- **Google Cloud Storage**
- **Microsoft Azure Blob Storage**
In addition, the following S3-compatible and simulator solutions have been
tested and verified:
- [MinIO](https://min.io/) – An S3-compatible storage solution
- [Azurite](https://github.com/Azure/Azurite) – A simulator for Azure Blob Storage
- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage
:::tip
For more details, refer to [Object Store Providers](object_stores.md).
:::

274
web/versioned_docs/version-0.11.0/migration.md
View File

@ -1,274 +0,0 @@
---
sidebar_position: 40
---
# Migrating from Built-in CloudNativePG Backup
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting
from version 1.26** and will be removed in a future release.
If you're currently relying on the built-in Barman Cloud integration, you can
migrate seamlessly to the new **plugin-based architecture** using the Barman
Cloud Plugin, without data loss. Follow these steps:
- [Install the Barman Cloud Plugin](installation.mdx)
- Create an `ObjectStore` resource by translating the contents of the
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
definition
- Modify the `Cluster` resource in a single atomic change to switch from
in-tree backup to the plugin
- Update any `ScheduledBackup` resources to use the plugin
- Update the `externalClusters` configuration, where applicable
:::tip
For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground),
which demonstrates a full migration.
:::
---
## Step 1: Define the `ObjectStore`
Begin by creating an `ObjectStore` resource in the same namespace as your
PostgreSQL `Cluster`.
There is a **direct mapping** between the `.spec.backup.barmanObjectStore`
section in CloudNativePG and the `.spec.configuration` field in the
`ObjectStore` CR. The conversion is mostly mechanical, with one key difference:
:::warning
In the plugin architecture, retention policies are defined as part of the `ObjectStore`.
In contrast, the in-tree implementation defined them at the `Cluster` level.
:::
If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration
to `.spec.retentionPolicy` in the `ObjectStore`.
---
### Example
Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration
taken from the CloudNativePG Playground project:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-eu
spec:
# [...]
backup:
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
This configuration translates to the following `ObjectStore` resource for the
plugin:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
As you can see, the contents of `barmanObjectStore` have been copied directly
under the `configuration` field of the `ObjectStore` resource, using the same
secret references.
## Step 2: Update the `Cluster` for plugin WAL archiving
Once the `ObjectStore` resource is in place, update the `Cluster` resource as
follows in a single atomic change:
- Remove the `.spec.backup.barmanObjectStore` section
- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the
`ObjectStore`)
- Remove the entire `spec.backup` section if it is now empty
- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in
[Configuring WAL archiving](usage.md#configuring-wal-archiving)
This will trigger a rolling update of the `Cluster`, switching continuous
backup from the in-tree implementation to the plugin-based approach.
### Example
The updated `pg-eu` cluster will have this configuration instead of the
previous `backup` section:
```yaml
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: minio-eu
```
---
## Step 3: Update the `ScheduledBackup`
After switching the `Cluster` to use the plugin, update your `ScheduledBackup`
resources to match.
Set the backup `method` to `plugin` and reference the plugin name via
`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup).
### Example
Original in-tree `ScheduledBackup`:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
```
Updated version using the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
---
## Step 4: Update the `externalClusters` configuration
If your `Cluster` relies on one or more external clusters that use the in-tree
Barman Cloud integration, you need to update those configurations to use the
plugin-based architecture.
When a replica cluster fetches WAL files or base backups from an external
source that used the built-in backup method, follow these steps:
1. Create a corresponding `ObjectStore` resource for the external cluster, as
shown in [Step 1](#step-1-define-the-objectstore)
2. Update the `externalClusters` section of your replica cluster to use the
plugin instead of the in-tree `barmanObjectStore` field
### Example
Consider the original configuration using in-tree Barman Cloud:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
serverName: pg-eu
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Create the `ObjectStore` resource for the external cluster:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Update the external cluster configuration to use the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: minio-eu
serverName: pg-eu
```
## Step 5: Verify your metrics
When migrating from the in-core solution to the plugin-based approach, you need
to monitor a different set of metrics, as described in the
["Observability"](observability.md) section.
The table below summarizes the name changes between the old in-core metrics and
the new plugin-based ones:
| Old metric name | New metric name |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| `cnpg_collector_last_failed_backup_timestamp` | `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp` |
| `cnpg_collector_last_available_backup_timestamp` | `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp` |
| `cnpg_collector_first_recoverability_point` | `barman_cloud_cloudnative_pg_io_first_recoverability_point` |

97
web/versioned_docs/version-0.11.0/misc.md
View File

@ -1,97 +0,0 @@
---
sidebar_position: 90
---
# Miscellaneous
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
## Backup Object Tagging
You can attach key-value metadata tags to backup artifacts—such as base
backups, WAL files, and history files—via the `.spec.configuration` section of
the `ObjectStore` resource.
- `tags`: applied to base backups and WAL files
- `historyTags`: applied to history files only
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
[...]
tags:
backupRetentionPolicy: "expire"
historyTags:
backupRetentionPolicy: "keep"
[...]
```
## Extra Options for Backup and WAL Archiving
You can pass additional command-line arguments to `barman-cloud-backup` and
`barman-cloud-wal-archive` using the `additionalCommandArgs` field in the
`ObjectStore` configuration.
- `.spec.configuration.data.additionalCommandArgs`: for `barman-cloud-backup`
- `.spec.configuration.wal.archiveAdditionalCommandArgs`: for `barman-cloud-wal-archive`
Each field accepts a list of string arguments. If an argument is already
configured elsewhere in the plugin, the duplicate will be ignored.
### Example: Extra Backup Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
data:
additionalCommandArgs:
- "--min-chunk-size=5MB"
- "--read-timeout=60"
```
### Example: Extra WAL Archive Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
wal:
archiveAdditionalCommandArgs:
- "--max-concurrency=1"
- "--read-timeout=60"
```
For a complete list of supported options, refer to the
[official Barman Cloud documentation](https://docs.pgbarman.org/release/latest/).
## Enable the pprof debug server for the sidecar
You can enable the instance sidecar's pprof debug HTTP server by adding the `--pprof-server=<address>` flag to the container's
arguments via `.spec.instanceSidecarConfiguration.additionalContainerArgs`.
Pass a bind address in the form `<host>:<port>` (for example, `0.0.0.0:6061`).
An empty value disables the server (disabled by default).
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
instanceSidecarConfiguration:
additionalContainerArgs:
- "--pprof-server=0.0.0.0:6061"
```

498
web/versioned_docs/version-0.11.0/object_stores.md
View File

@ -1,498 +0,0 @@
---
sidebar_position: 50
---
# Object Store Providers
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin enables the storage of PostgreSQL cluster backup files
in any object storage service supported by the
[Barman Cloud infrastructure](https://docs.pgbarman.org/release/latest/).
Currently, Barman Cloud supports the following providers:
- [Amazon S3](#aws-s3)
- [Microsoft Azure Blob Storage](#azure-blob-storage)
- [Google Cloud Storage](#google-cloud-storage)
You may also use any S3- or Azure-compatible implementation of the above
services.
To configure object storage with Barman Cloud, you must define an
[`ObjectStore` object](plugin-barman-cloud.v1.md#objectstore), which
establishes the connection between your PostgreSQL cluster and the object
storage backend.
Configuration details — particularly around authentication — will vary depending on
the specific object storage provider you are using.
The following sections detail the setup for each.
:::note Authentication Methods
The Barman Cloud Plugin does not independently test all authentication methods
supported by `barman-cloud`. The plugin's responsibility is limited to passing
the provided credentials to `barman-cloud`, which then handles authentication
according to its own implementation. Users should refer to the
[Barman Cloud documentation](https://docs.pgbarman.org/release/latest/) to
verify that their chosen authentication method is supported and properly
configured.
:::
---
## AWS S3
[AWS Simple Storage Service (S3)](https://aws.amazon.com/s3/) is one of the
most widely adopted object storage solutions.
The Barman Cloud plugin for CloudNativePG integrates with S3 through two
primary authentication mechanisms:
- [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) —
recommended for clusters running on EKS
- Access keys — using `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY` credentials
### Access Keys
To authenticate using access keys, you’ll need:
- `ACCESS_KEY_ID`: the public key used to authenticate to S3
- `ACCESS_SECRET_KEY`: the corresponding secret key
- `ACCESS_SESSION_TOKEN`: (optional) a temporary session token, if required
These credentials must be stored securely in a Kubernetes secret:
```sh
kubectl create secret generic aws-creds \
--from-literal=ACCESS_KEY_ID=<access key here> \
--from-literal=ACCESS_SECRET_KEY=<secret key here>
# --from-literal=ACCESS_SESSION_TOKEN=<session token here> # if required
```
The credentials will be encrypted at rest if your Kubernetes environment
supports it.
You can then reference the secret in your `ObjectStore` definition:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: aws-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
s3Credentials:
accessKeyId:
name: aws-creds
key: ACCESS_KEY_ID
secretAccessKey:
name: aws-creds
key: ACCESS_SECRET_KEY
[...]
```
### IAM Role for Service Account (IRSA)
To use IRSA with EKS, configure the service account of the PostgreSQL cluster
with the appropriate annotation:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
[...]
spec:
serviceAccountTemplate:
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:[...]
[...]
```
### S3 Lifecycle Policy
Barman Cloud uploads backup files to S3 but does not modify them afterward.
To enhance data durability and protect against accidental or malicious loss,
it's recommended to implement the following best practices:
- Enable object versioning
- Enable object locking to prevent objects from being deleted or overwritten
for a defined period or indefinitely (this provides an additional layer of
protection against accidental deletion and ransomware attacks)
- Set lifecycle rules to expire current versions a few days after your Barman
retention window
- Expire non-current versions after a longer period
These strategies help you safeguard backups without requiring broad delete
permissions, ensuring both security and compliance with minimal operational
overhead.
### S3-Compatible Storage Providers
You can use S3-compatible services like **MinIO**, **Linode (Akamai) Object Storage**,
or **DigitalOcean Spaces** by specifying a custom `endpointURL`.
Example with Linode (Akamai) Object Storage (`us-east1`):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/"
endpointURL: "https://us-east1.linodeobjects.com"
s3Credentials:
[...]
[...]
```
Recent changes to the [boto3 implementation](https://github.com/boto/boto3/issues/4392)
of [Amazon S3 Data Integrity Protections](https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html)
may lead to the `x-amz-content-sha256` error when using the Barman Cloud
Plugin.
If you encounter this issue (see [GitHub issue #393](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/393)),
you can apply the following workaround by setting specific environment
variables in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
instanceSidecarConfiguration:
env:
- name: AWS_REQUEST_CHECKSUM_CALCULATION
value: when_required
- name: AWS_RESPONSE_CHECKSUM_VALIDATION
value: when_required
[...]
```
These settings ensure that checksum calculations and validations are only
applied when explicitly required, avoiding compatibility issues with certain
S3-compatible storage providers.
Example with DigitalOcean Spaces (SFO3, path-style):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: digitalocean-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
endpointURL: "https://sfo3.digitaloceanspaces.com"
s3Credentials:
[...]
[...]
```
### Using Object Storage with a Private CA
For object storage services (e.g., MinIO) that use HTTPS with certificates
signed by a private CA, set the `endpointCA` field in the `ObjectStore`
definition. Unless you already have it, create a Kubernetes `Secret` with the
CA bundle:
```sh
kubectl create secret generic my-ca-secret --from-file=ca.crt
```
Then reference it:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
endpointURL: <myEndpointURL>
endpointCA:
name: my-ca-secret
key: ca.crt
[...]
```
<!-- TODO: does this also apply to the plugin? -->
:::note
If you want `ConfigMaps` and `Secrets` to be **automatically** reloaded by
instances, you can add a label with the key `cnpg.io/reload` to the
`Secrets`/`ConfigMaps`. Otherwise, you will have to reload the instances using the
`kubectl cnpg reload` subcommand.
:::
---
## Azure Blob Storage
[Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
is Microsoft’s cloud-based object storage solution.
Barman Cloud supports the following authentication methods:
- [Connection String](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string)
- Storage Account Name + [Storage Account Access Key](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
- Storage Account Name + [Storage Account SAS Token](https://learn.microsoft.com/en-us/azure/storage/blobs/sas-service-create)
- [Azure AD Managed Identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview)
- [Default Azure Credentials](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet)
### Azure AD Managed Identity
This method avoids storing credentials in Kubernetes by enabling the
usage of [Azure Managed Identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) authentication mechanism.
This can be enabled by setting the `inheritFromAzureAD` option to `true`.
Managed Identity can be configured for the AKS Cluster by following
the [Azure documentation](https://learn.microsoft.com/en-us/azure/aks/use-managed-identity?pivots=system-assigned).
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
inheritFromAzureAD: true
[...]
```
### Default Azure Credentials
The `useDefaultAzureCredentials` option enables the default Azure credentials
flow, which uses [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.defaultazurecredential)
to automatically discover and use available credentials in the following order:
1. **Environment Variables** — `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID` for Service Principal authentication
2. **Managed Identity** — Uses the managed identity assigned to the pod
3. **Azure CLI** — Uses credentials from the Azure CLI if available
4. **Azure PowerShell** — Uses credentials from Azure PowerShell if available
This approach is particularly useful for getting started with development and testing; it allows
the SDK to attempt multiple authentication mechanisms seamlessly across different environments.
However, this is not recommended for production. Please refer to the
[official Azure guidance](https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#usage-guidance-for-defaultazurecredential)
for a comprehensive understanding of `DefaultAzureCredential`.
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
useDefaultAzureCredentials: true
[...]
```
### Access Key, SAS Token, or Connection String
Store credentials in a Kubernetes secret:
```sh
kubectl create secret generic azure-creds \
--from-literal=AZURE_STORAGE_ACCOUNT=<storage account name> \
--from-literal=AZURE_STORAGE_KEY=<storage account key> \
--from-literal=AZURE_STORAGE_SAS_TOKEN=<SAS token> \
--from-literal=AZURE_STORAGE_CONNECTION_STRING=<connection string>
```
Then reference the required keys in your `ObjectStore`:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
connectionString:
name: azure-creds
key: AZURE_CONNECTION_STRING
storageAccount:
name: azure-creds
key: AZURE_STORAGE_ACCOUNT
storageKey:
name: azure-creds
key: AZURE_STORAGE_KEY
storageSasToken:
name: azure-creds
key: AZURE_STORAGE_SAS_TOKEN
[...]
```
For Azure Blob, the destination path format is:
```
<http|https>://<account-name>.<service-name>.core.windows.net/<container>/<blob>
```
### Azure-Compatible Providers
If you're using a different implementation (e.g., Azurite or emulator):
```
<http|https>://<local-machine-address>:<port>/<account-name>/<container>/<blob>
```
---
## Google Cloud Storage
[Google Cloud Storage](https://cloud.google.com/storage/) is supported with two
authentication modes:
- **GKE Workload Identity** (recommended inside Google Kubernetes Engine)
- **Service Account JSON key** via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
### GKE Workload Identity
Use the [Workload Identity authentication](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
when running in GKE:
1. Set `googleCredentials.gkeEnvironment` to `true` in the `ObjectStore`
resource
2. Annotate the `serviceAccountTemplate` in the `Cluster` resource with the GCP
service account
For example, in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
gkeEnvironment: true
```
And in the `Cluster` resource:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
serviceAccountTemplate:
metadata:
annotations:
iam.gke.io/gcp-service-account: [...].iam.gserviceaccount.com
```
### Service Account JSON Key
Follow Google’s [authentication setup](https://cloud.google.com/docs/authentication/getting-started),
then:
```sh
kubectl create secret generic backup-creds --from-file=gcsCredentials=gcs_credentials_file.json
```
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
applicationCredentials:
name: backup-creds
key: gcsCredentials
[...]
```
:::important
This authentication method generates a JSON file within the container
with all the credentials required to access your Google Cloud Storage
bucket. As a result, if someone gains access to the `Pod`, they will also have
write permissions to the bucket.
:::
---
## MinIO Object Store
In order to use the Tenant resource you first need to deploy the
[MinIO operator](https://docs.min.io/community/minio-object-store/operations/deployments/installation.html).
For the latest documentation of MinIO, please refer to the
[MinIO official documentation](https://docs.min.io/community/minio-object-store/).
MinIO Object Store's API is compatible with S3, and the default configuration of the Tenant
will create these services:
- `<tenant>-console` on port 9090 (with autocert) or 9443 (without autocert)
- `<tenant>-hl` on port 9000
Where `<tenant>` is the `metadata.name` you assigned to your Tenant resource.
:::note
The `<tenant>-console` service will only be available if you have enabled the
[MinIO Console](https://docs.min.io/community/minio-object-store/administration/minio-console.html).
For example, the following Tenant:
```yml
apiVersion: minio.min.io/v2
kind: Tenant
metadata:
name: cnpg-backups
spec:
[...]
```
would have services called `cnpg-backups-console` and `cnpg-backups-hl` respectively.
The `console` service is for managing the tenant, while the `hl` service exposes the S3
compatible API. If your tenant is configured with `requestAutoCert` you will communicate
to these services over HTTPS, if not you will use HTTP.
For authentication you can use your username and password, or create an access key.
Whichever method you choose, it has to be stored as a secret.
```sh
kubectl create secret generic minio-creds \
--from-literal=MINIO_ACCESS_KEY=<minio access key or username> \
--from-literal=MINIO_SECRET_KEY=<minio secret key or password>
```
Finally, create the Barman ObjectStore:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
destinationPath: s3://BUCKET_NAME/
endpointURL: http://<tenant>-hl:9000
s3Credentials:
accessKeyId:
name: minio-creds
key: MINIO_ACCESS_KEY
secretAccessKey:
name: minio-creds
key: MINIO_SECRET_KEY
[...]
```
:::important
Verify on `s3://BUCKET_NAME/` the presence of archived WAL files before
proceeding with a backup.
:::
---

24
web/versioned_docs/version-0.11.0/observability.md
View File

@ -1,24 +0,0 @@
---
sidebar_position: 55
---
# Observability
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin exposes the following metrics through the native
Prometheus exporter of the instance manager:
- `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp`:
the UNIX timestamp of the most recent failed backup.
- `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp`:
the UNIX timestamp of the most recent successfully available backup.
- `barman_cloud_cloudnative_pg_io_first_recoverability_point`:
the UNIX timestamp representing the earliest point in time from which the
cluster can be recovered.
These metrics supersede the previously available in-core metrics that used the
`cnpg_collector` prefix. The new metrics are exposed under the
`barman_cloud_cloudnative_pg_io` prefix instead.

19
web/versioned_docs/version-0.11.0/parameters.md
View File

@ -1,19 +0,0 @@
---
sidebar_position: 100
---
# Parameters
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The following parameters are available for the Barman Cloud Plugin:
- `barmanObjectName`: references the `ObjectStore` resource to be used by the
plugin.
- `serverName`: Specifies the server name in the object store.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::

108
web/versioned_docs/version-0.11.0/plugin-barman-cloud.v1.md
View File

@ -1,108 +0,0 @@
# API Reference
## Packages
- [barmancloud.cnpg.io/v1](#barmancloudcnpgiov1)
## barmancloud.cnpg.io/v1
Package v1 contains API Schema definitions for the barmancloud v1 API group
### Resource Types
- [ObjectStore](#objectstore)
#### InstanceSidecarConfiguration
InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.
_Appears in:_
- [ObjectStoreSpec](#objectstorespec)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#envvar-v1-core) array_ | The environment to be explicitly passed to the sidecar | | | |
| `retentionPolicyIntervalSeconds` _integer_ | The retentionCheckInterval defines the frequency at which the<br />system checks and enforces retention policies. | | 1800 | |
| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#resourcerequirements-v1-core)_ | Resources define cpu/memory requests and limits for the sidecar that runs in the instance pods. | | | |
| `additionalContainerArgs` _string array_ | AdditionalContainerArgs is an optional list of command-line arguments<br />to be passed to the sidecar container when it starts.<br />The provided arguments are appended to the container’s default arguments. | | | |
| `logLevel` _string_ | The log level for PostgreSQL instances. Valid values are: `error`, `warning`, `info` (default), `debug`, `trace` | | info | Enum: [error warning info debug trace] <br /> |
#### ObjectStore
ObjectStore is the Schema for the objectstores API.
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `apiVersion` _string_ | `barmancloud.cnpg.io/v1` | True | | |
| `kind` _string_ | `ObjectStore` | True | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | True | | |
| `spec` _[ObjectStoreSpec](#objectstorespec)_ | Specification of the desired behavior of the ObjectStore.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | True | | |
| `status` _[ObjectStoreStatus](#objectstorestatus)_ | Most recently observed status of the ObjectStore. This data may not be up to<br />date. Populated by the system. Read-only.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | | | |
#### ObjectStoreSpec
ObjectStoreSpec defines the desired state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `configuration` _[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)_ | The configuration for the barman-cloud tool suite | True | | |
| `retentionPolicy` _string_ | RetentionPolicy is the retention policy to be used for backups<br />and WALs (i.e. '60d'). The retention policy is expressed in the form<br />of `XXu` where `XX` is a positive integer and `u` is in `[dwm]` -<br />days, weeks, months. | | | Pattern: `^[1-9][0-9]*[dwm]$` <br /> |
| `instanceSidecarConfiguration` _[InstanceSidecarConfiguration](#instancesidecarconfiguration)_ | The configuration for the sidecar that runs in the instance pods | | | |
#### ObjectStoreStatus
ObjectStoreStatus defines the observed state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `serverRecoveryWindow` _object (keys:string, values:[RecoveryWindow](#recoverywindow))_ | ServerRecoveryWindow maps each server to its recovery window | True | | |
#### RecoveryWindow
RecoveryWindow represents the time span between the first
recoverability point and the last successful backup of a PostgreSQL
server, defining the period during which data can be restored.
_Appears in:_
- [ObjectStoreStatus](#objectstorestatus)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `firstRecoverabilityPoint` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The first recoverability point in a PostgreSQL server refers to<br />the earliest point in time to which the database can be<br />restored. | True | | |
| `lastSuccessfulBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last successful backup time | True | | |
| `lastFailedBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last failed backup time | True | | |

219
web/versioned_docs/version-0.11.0/resource-name-migration.md
View File

@ -1,219 +0,0 @@
---
sidebar_position: 90
---
# Resource name migration guide
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::warning
Before proceeding with the migration process, please:
1. **Read this guide in its entirety** to understand what changes will be made
2. **Test in a non-production environment** first if possible
3. **Ensure you have proper backups** of your cluster configuration
This migration will delete old RBAC resources only after the
`plugin-barman-cloud` upgrade. While the operation is designed to be safe, you
should review and understand the changes before proceeding. The maintainers of
this project are not responsible for any issues that may arise during
migration.
**Note:** This guide assumes you are using the default `cnpg-system` namespace.
:::
## Overview
Starting from version **0.8.0**, the `plugin-barman-cloud` deployment manifests
use more specific, prefixed resource names to avoid conflicts with other
components deployed in the same Kubernetes cluster.
## What Changed
The following resources have been renamed to use proper prefixes.
### Cluster-scoped Resources
| Old Name | New Name |
|----------------------------|------------------------------------------|
| `metrics-auth-role` | `barman-plugin-metrics-auth-role` |
| `metrics-auth-rolebinding` | `barman-plugin-metrics-auth-rolebinding` |
| `metrics-reader` | `barman-plugin-metrics-reader` |
| `objectstore-viewer-role` | `barman-plugin-objectstore-viewer-role` |
| `objectstore-editor-role` | `barman-plugin-objectstore-editor-role` |
### Namespace-scoped Resources
| Old Name | New Name | Namespace |
|-------------------------------|---------------------------------------------|---------------|
| `leader-election-role` | `barman-plugin-leader-election-role` | `cnpg-system` |
| `leader-election-rolebinding` | `barman-plugin-leader-election-rolebinding` | `cnpg-system` |
## Why This Change?
Using generic names for cluster-wide resources is discouraged as they may
conflict with other components deployed in the same cluster. The new names make
it clear that these resources belong to the Barman Cloud plugin and help avoid
naming collisions.
## Migration Instructions
This three steps migration process is straightforward and can be completed with
a few `kubectl` commands.
### Step 1: Upgrade plugin-barman-cloud
Please refer to the [Installation](installation.mdx) section to deploy the new
`plugin-barman-cloud` release.
### Step 2: Delete Old Cluster-scoped Resources
:::danger Verify Resources Before Deletion
**IMPORTANT**: The old resource names are generic and could potentially belong
to other components in your cluster.
**Before deleting each resource, verify it belongs to the Barman Cloud plugin
by checking:**
- For `objectstore-*` roles: Look for `barmancloud.cnpg.io` in the API groups
- For `metrics-*` roles: Check if they reference the `plugin-barman-cloud`
ServiceAccount in `cnpg-system` namespace
- For other roles: Look for labels like `app.kubernetes.io/name: plugin-barman-cloud`
If a resource doesn't have these indicators, **DO NOT DELETE IT** as it may
belong to another application.
Carefully review the output of each verification command before proceeding with
the `delete`.
:::
:::tip Dry Run First
You can add `--dry-run=client` to any `kubectl delete` command to preview what
would be deleted without actually removing anything.
:::
**Only proceed if you've verified these resources belong to the Barman Cloud
plugin (see warning above).**
For each resource below, first verify it belongs to Barman Cloud, then delete
it:
```bash
# 1. Check metrics-auth-rolebinding FIRST (we'll check the role after)
# Look for references to plugin-barman-cloud ServiceAccount
kubectl describe clusterrolebinding metrics-auth-rolebinding
# If it references plugin-barman-cloud ServiceAccount in cnpg-system namespace,
# delete it:
kubectl delete clusterrolebinding metrics-auth-rolebinding
# 2. Check metrics-auth-role
# Look for references to authentication.k8s.io and authorization.k8s.io
kubectl describe clusterrole metrics-auth-role
# Verify it's not being used by any other rolebindings:
kubectl get clusterrolebinding -o json \
| jq -r '.items[] | select(.roleRef.name=="metrics-auth-role") \
| .metadata.name'
# If the above returns nothing (role is not in use) and the role looks like the
# Barman Cloud one, delete it (see warnings section):
kubectl delete clusterrole metrics-auth-role
# 3. Check objectstore-viewer-role
# Look for barmancloud.cnpg.io API group or
# for `app.kubernetes.io/name: plugin-barman-cloud` label
kubectl describe clusterrole objectstore-viewer-role
# If it shows barmancloud.cnpg.io in API groups, delete it:
kubectl delete clusterrole objectstore-viewer-role
# 4. Check objectstore-editor-role
# Look for barmancloud.cnpg.io API group or
# for `app.kubernetes.io/name: plugin-barman-cloud` label
kubectl describe clusterrole objectstore-editor-role
# If it shows barmancloud.cnpg.io in API groups, delete it:
kubectl delete clusterrole objectstore-editor-role
# 5. Check metrics-reader (MOST DANGEROUS - very generic name)
# First, check if it's being used by any rolebindings OTHER than barman's:
kubectl get clusterrolebinding -o json | jq -r '.items[] \
| select(.roleRef.name=="metrics-reader") \
| "\(.metadata.name) -> \(.subjects[0].name) in \(.subjects[0].namespace)"'
# If this shows ANY rolebindings, review them carefully. Only proceed if
# they're all Barman-related. Then check the role itself:
kubectl describe clusterrole metrics-reader
# If it ONLY has nonResourceURLs: /metrics and NO other rolebindings use it,
# delete it:
kubectl delete clusterrole metrics-reader
```
:::warning
The `metrics-reader` role is particularly dangerous to delete blindly. Many
monitoring systems use this exact name. Only delete it if:
1. You've verified it ONLY grants access to `/metrics`
2. No other rolebindings reference it (checked with the jq command above)
3. You're certain it was created by the Barman Cloud plugin
If you're unsure, it's safer to leave it and let the new
`barman-plugin-metrics-reader` role coexist with it.
:::
If any resource is not found during the `describe` command, that's okay - it
means it was never created or already deleted. Simply skip the delete command
for that resource.
### Step 3: Delete Old Namespace-scoped Resources
Delete the old namespace-scoped resources in the `cnpg-system` namespace:
```bash
# Delete the old leader-election resources
kubectl delete role leader-election-role -n cnpg-system
kubectl delete rolebinding leader-election-rolebinding -n cnpg-system
```
If any resource is not found, that's okay - it means it was never created or
already deleted.
## Impact
- **Permissions:** If you have custom RBAC rules or tools that reference the
old resource names, they will need to be updated.
- **External Users:** If end users have been granted the
`objectstore-viewer-role` or `objectstore-editor-role`, they will need to be
re-granted the new role names (`barman-plugin-objectstore-viewer-role` and
`barman-plugin-objectstore-editor-role`).
## Verification
After migration, verify that the new resources are created:
```bash
# Check cluster-scoped resources
kubectl get clusterrole | grep barman
kubectl get clusterrolebinding | grep barman
# Check namespace-scoped resources
kubectl get role,rolebinding -n cnpg-system | grep barman
```
You should see the new prefixed resource names.
## Troubleshooting
### Plugin Not Starting After Migration
If the plugin fails to start after migration, check:
1. **ServiceAccount permissions:** Ensure the `plugin-barman-cloud` ServiceAccount is bound to the new roles:
```bash
kubectl get clusterrolebinding barman-plugin-metrics-auth-rolebinding -o yaml
kubectl get rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system -o yaml
```
2. **Role references:** Verify that the rolebindings reference the correct role names:
```bash
kubectl describe rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system
kubectl describe clusterrolebinding barman-plugin-metrics-auth-rolebinding
```
## Support
If you encounter issues during migration, please open an issue on the [GitHub
repository](https://github.com/cloudnative-pg/plugin-barman-cloud/issues).

38
web/versioned_docs/version-0.11.0/retention.md
View File

@ -1,38 +0,0 @@
---
sidebar_position: 60
---
# Retention Policies
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin supports **automated cleanup of obsolete backups** via
retention policies, configured in the `.spec.retentionPolicy` field of the
`ObjectStore` resource.
:::note
This feature uses the `barman-cloud-backup-delete` command with the
`--retention-policy "RECOVERY WINDOW OF {{ value }} {{ unit }}"` syntax.
:::
#### Example: 30-Day Retention Policy
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
[...]
retentionPolicy: "30d"
````
:::note
A **recovery window retention policy** ensures the cluster can be restored to
any point in time between the calculated *Point of Recoverability* (PoR) and
the latest WAL archive. The PoR is defined as `current time - recovery window`.
The **first valid backup** is the most recent backup completed before the PoR.
Backups older than that are marked as *obsolete* and deleted after the next
backup completes.
:::

591
web/versioned_docs/version-0.11.0/troubleshooting.md
View File

@ -1,591 +0,0 @@
---
sidebar_position: 90
---
# Troubleshooting
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
This guide helps you diagnose and resolve common issues with the Barman Cloud
plugin.
:::important
We are continuously improving the integration between CloudNativePG and the
Barman Cloud plugin as it moves toward greater stability and maturity. For this
reason, we recommend using the latest available version of both components.
See the [*Requirements* section](intro.md#requirements) for details.
:::
:::note
The following commands assume you installed the CloudNativePG operator in
the default `cnpg-system` namespace. If you installed it in a different
namespace, adjust the commands accordingly.
:::
## Viewing Logs
To troubleshoot effectively, you’ll often need to review logs from multiple
sources:
```sh
# View operator logs (includes plugin interaction logs)
kubectl logs -n cnpg-system deployment/cnpg-controller-manager -f
# View plugin manager logs
kubectl logs -n cnpg-system deployment/barman-cloud -f
# View sidecar container logs (Barman Cloud operations)
kubectl logs -n <namespace> <cluster-pod-name> -c plugin-barman-cloud -f
# View all containers in a pod
kubectl logs -n <namespace> <cluster-pod-name> --all-containers=true
# View previous container logs (if container restarted)
kubectl logs -n <namespace> <cluster-pod-name> -c plugin-barman-cloud --previous
```
## Common Issues
### Plugin Installation Issues
#### Plugin pods not starting
**Symptoms:**
- Plugin pods stuck in `CrashLoopBackOff` or `Error`
- Plugin deployment not ready
**Possible causes and solutions:**
1. **Certificate issues**
```sh
# Check if cert-manager is installed and running
kubectl get pods -n cert-manager
# Check if the plugin certificate is created
kubectl get certificates -n cnpg-system
```
If cert-manager is not installed, install it first:
```sh
# Note: other installation methods for cert-manager are available
kubectl apply -f \
https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
```
If you are using your own certificates without cert-manager, you will need
to verify the entire certificate chain yourself.
2. **Image pull errors**
```sh
# Check pod events for image pull errors
kubectl describe pod -n cnpg-system -l app=barman-cloud
```
Verify the image exists and you have proper credentials if using a private
registry.
3. **Resource constraints**
```sh
# Check node resources
kubectl top nodes
kubectl describe nodes
```
Make sure your cluster has sufficient CPU and memory resources.
### Backup Failures
#### Quick Backup Troubleshooting Checklist
When a backup fails, follow these steps in order:
1. **Check backup status**:
```sh
kubectl get backups.postgresql.cnpg.io -n <namespace>
```
2. **Get error details and target pod**:
```sh
kubectl describe backups.postgresql.cnpg.io \
-n <namespace> <backup-name>
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}'
```
3. **Check the target pod’s sidecar logs**:
```sh
TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}')
kubectl logs \
-n <namespace> $TARGET_POD -c plugin-barman-cloud \
--tail=100 | grep -E "ERROR|FATAL|panic"
```
4. **Check cluster events**:
```sh
kubectl get events -n <namespace> \
--field-selector involvedObject.name=<cluster-name> \
--sort-by='.lastTimestamp'
```
5. **Verify plugin is running**:
```sh
kubectl get pods \
-n cnpg-system -l app=barman-cloud
```
6. **Check operator logs**:
```sh
kubectl logs \
-n cnpg-system deployment/cnpg-controller-manager \
--tail=100 | grep -i "backup\|plugin"
```
7. **Check plugin manager logs**:
```sh
kubectl logs \
-n cnpg-system deployment/barman-cloud --tail=100
```
#### Backup job fails immediately
**Symptoms:**
- Backup pods terminate with error
- No backup files appear in object storage
- Backup shows `failed` phase with various error messages
**Common failure modes and solutions:**
1. **"requested plugin is not available" errors**
```
requested plugin is not available: barman
requested plugin is not available: barman-cloud
requested plugin is not available: barman-cloud.cloudnative-pg.io
```
**Cause:** The plugin name in the Cluster configuration doesn’t match the
deployed plugin, or the plugin isn’t registered.
**Solution:**
a. **Check plugin registration:**
```sh
# If you have the `cnpg` plugin installed (v1.27.0+)
kubectl cnpg status -n <namespace> <cluster-name>
```
Look for the "Plugins status" section:
```
Plugins status
Name Version Status Reported Operator Capabilities
---- ------- ------ ------------------------------
barman-cloud.cloudnative-pg.io 0.6.0 N/A Reconciler Hooks, Lifecycle Service
```
b. **Verify plugin name in `Cluster` spec**:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
plugins:
- name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: <your-objectstore-name>
```
c. **Check plugin deployment is running**:
```sh
kubectl get deployment -n cnpg-system barman-cloud
```
2. **"rpc error: code = Unknown desc = panic caught: assignment to entry in nil map" errors**
**Cause:** Misconfiguration in the `ObjectStore` (e.g., typo or missing field).
**Solution:**
- Review sidecar logs for details
- Verify `ObjectStore` configuration and secrets
- Common issues include:
- Missing or incorrect secret references
- Typos in configuration parameters
- Missing required environment variables in secrets
#### Backup performance issues
**Symptoms:**
- Backups take extremely long
- Backups timeout
**Plugin-specific considerations:**
1. **Check `ObjectStore` parallelism settings**
- Adjust `maxParallel` in `ObjectStore` configuration
- Monitor sidecar container resource usage during backups
2. **Verify plugin resource allocation**
- Check if the sidecar container has sufficient CPU/memory
- Review plugin container logs for resource-related warnings
:::tip
For Barman-specific features like compression, encryption, and performance
tuning, refer to the [Barman documentation](https://docs.pgbarman.org/latest/).
:::
### WAL Archiving Issues
#### WAL archiving stops
**Symptoms:**
- WAL files accumulate on the primary
- Cluster shows WAL archiving warnings
- Sidecar logs show WAL errors
**Debugging steps:**
1. **Check plugin sidecar logs for WAL archiving errors**
```sh
# Check recent WAL archive operations in sidecar
kubectl logs -n <namespace> <primary-pod> -c plugin-barman-cloud \
--tail=50 | grep -i wal
```
2. **Check ObjectStore configuration for WAL settings**
- Ensure ObjectStore has proper WAL retention settings
- Verify credentials have permissions for WAL operations
### Restore Issues
#### Restore fails during recovery
**Symptoms:**
- New cluster stuck in recovery
- Plugin sidecar shows restore errors
- PostgreSQL won’t start
**Debugging steps:**
1. **Check plugin sidecar logs during restore**
```sh
# Check the sidecar logs on the recovering cluster pods
kubectl logs -n <namespace> <cluster-pod-name> \
-c plugin-barman-cloud --tail=100
# Look for restore-related errors
kubectl logs -n <namespace> <cluster-pod-name> \
-c plugin-barman-cloud | grep -E "restore|recovery|ERROR"
```
2. **Verify plugin can access backups**
```sh
# Check if `ObjectStore` is properly configured for restore
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Check PostgreSQL recovery logs
kubectl logs -n <namespace> <cluster-pod> \
-c postgres | grep -i recovery
```
:::tip
For detailed Barman restore operations and troubleshooting, refer to the
[Barman documentation](https://docs.pgbarman.org/latest/barman-cloud-restore.html).
:::
#### Point-in-time recovery (PITR) configuration issues
**Symptoms:**
- PITR doesn’t reach target time
- WAL access errors
- Recovery halts early
**Debugging steps:**
1. **Verify PITR configuration in the `Cluster` spec**
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: <cluster-restore-name>
spec:
storage:
size: 1Gi
bootstrap:
recovery:
source: origin
recoveryTarget:
targetTime: "2024-01-15T10:30:00Z"
externalClusters:
- name: origin
plugin:
enabled: true
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: <object-store-name>
serverName: <source-cluster-name>
```
2. **Check sidecar logs for WAL-related errors**
```sh
kubectl logs -n <namespace> <cluster-pod> \
-c plugin-barman-cloud | grep -i wal
```
:::note
Timestamps without an explicit timezone suffix
(e.g., `2024-01-15 10:30:00`) are interpreted as UTC.
:::
:::warning
Always specify an explicit timezone in your timestamp to avoid ambiguity.
For example, use `2024-01-15T10:30:00Z` or `2024-01-15T10:30:00+02:00`
instead of `2024-01-15 10:30:00`.
:::
:::note
For detailed PITR configuration and WAL management, see the
[Barman PITR documentation](https://docs.pgbarman.org/latest/).
:::
### Plugin Configuration Issues
#### Plugin cannot connect to object storage
**Symptoms:**
- Sidecar logs show connection errors
- Backups fail with authentication or network errors
- `ObjectStore` resource reports errors
**Solution:**
1. **Verify `ObjectStore` CRD configuration and secrets**
```sh
# Check ObjectStore resource status
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Verify the secret exists and has correct keys for your provider
kubectl get secret -n <namespace> <secret-name> \
-o jsonpath='{.data}' | jq 'keys'
```
2. **Check sidecar logs for connectivity issues**
```sh
kubectl logs -n <namespace> <cluster-pod> \
-c plugin-barman-cloud | grep -E "connect|timeout|SSL|cert"
```
3. **Adjust provider-specific settings (endpoint, path style, etc.)**
- See [Object Store Configuration](object_stores.md) for provider-specific settings
- Ensure `endpointURL` is set correctly for your storage provider
- Verify network policies allow egress to your storage provider
## Diagnostic Commands
### Using the `cnpg` plugin for `kubectl`
The `cnpg` plugin for `kubectl` provides extended debugging capabilities.
Keep it updated:
```sh
# Install or update the `cnpg` plugin
kubectl krew install cnpg
# Or using an alternative method: https://cloudnative-pg.io/documentation/current/kubectl-plugin/#install
# Check plugin status (requires CNPG 1.27.0+)
kubectl cnpg status <cluster-name> -n <namespace>
# View cluster status in detail
kubectl cnpg status <cluster-name> -n <namespace> --verbose
```
## Getting Help
If problems persist:
1. **Check the documentation**
- [Installation Guide](installation.mdx)
- [Object Store Configuration](object_stores.md) (for provider-specific settings)
- [Usage Examples](usage.md)
2. **Gather diagnostic information**
```sh
# Create a diagnostic bundle (⚠️ sanitize these before sharing!)
kubectl get objectstores.barmancloud.cnpg.io -A -o yaml > /tmp/objectstores.yaml
kubectl get clusters.postgresql.cnpg.io -A -o yaml > /tmp/clusters.yaml
kubectl logs -n cnpg-system deployment/barman-cloud --tail=1000 > /tmp/plugin.log
```
3. **Community support**
- CloudNativePG Slack: [#cloudnativepg-users](https://cloud-native.slack.com/messages/cloudnativepg-users)
- GitHub Issues: [plugin-barman-cloud](https://github.com/cloudnative-pg/plugin-barman-cloud/issues)
4. **Include when reporting**
- CloudNativePG version
- Plugin version
- Kubernetes version
- Cloud provider and region
- Relevant configuration (⚠️ sanitize/redact sensitive information)
- Error messages and logs
- Steps to reproduce
## Known Issues and Limitations
### Current Known Issues
1. **Migration compatibility**: After migrating from in-tree backup to the
plugin, the `kubectl cnpg backup` command syntax has changed
([#353](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/353)):
```sh
# Old command (in-tree, no longer works after migration)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=barmanObjectStore
# New command (plugin-based)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin --plugin-name=barman-cloud.cloudnative-pg.io
```
### Plugin Limitations
1. **Installation method**: Currently only supports manifest and Kustomize
installation ([#351](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/351) -
Helm chart requested)
2. **Sidecar resource sharing**: The plugin sidecar container shares pod
resources with PostgreSQL
3. **Plugin restart behavior**: Restarting the sidecar container requires
restarting the entire PostgreSQL pod
## Recap of General Debugging Steps
### Check Backup Status and Identify the Target Instance
```sh
# List all backups and their status
kubectl get backups.postgresql.cnpg.io -n <namespace>
# Get detailed backup information including error messages and target instance
kubectl describe backups.postgresql.cnpg.io \
-n <namespace> <backup-name>
# Extract the target pod name from a failed backup
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}'
# Get more details including the target pod, method, phase, and error
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='Pod: {.status.instanceID.podName}{"\n"}Method: {.status.method}{"\n"}Phase: {.status.phase}{"\n"}Error: {.status.error}{"\n"}'
# Check the cluster status for backup-related information
kubectl cnpg status <cluster-name> -n <namespace> --verbose
```
### Check Sidecar Logs on the Backup Target Pod
```sh
# Identify which pod was the backup target (from the previous step)
TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}')
echo "Backup target pod: $TARGET_POD"
# Check the sidecar logs on the specific target pod
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud --tail=100
# Follow the logs in real time
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud -f
# Check for specific errors in the target pod around the backup time
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud --since=10m | grep -E "ERROR|FATAL|panic|failed"
# Alternative: List all cluster pods and their roles
kubectl get pods -n <namespace> -l cnpg.io/cluster=<cluster-name> \
-o custom-columns=NAME:.metadata.name,ROLE:.metadata.labels.cnpg\\.io/instanceRole,INSTANCE:.metadata.labels.cnpg\\.io/instanceName
# Check sidecar logs on ALL cluster pods (if the target is unclear)
for pod in $(kubectl get pods -n <namespace> -l cnpg.io/cluster=<cluster-name> -o name); do
echo "=== Checking $pod ==="
kubectl logs -n <namespace> $pod -c plugin-barman-cloud \
--tail=20 | grep -i error || echo "No errors found"
done
```
### Check Events for Backup-Related Issues
```sh
# Check events for the cluster
kubectl get events -n <namespace> \
--field-selector involvedObject.name=<cluster-name>
# Check events for failed backups
kubectl get events -n <namespace> \
--field-selector involvedObject.kind=Backup
# Get all recent events in the namespace
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -20
```
### Verify `ObjectStore` Configuration
```sh
# Check the ObjectStore resource
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Verify the secret exists and has the correct keys
kubectl get secret -n <namespace> <secret-name> -o yaml
# Alternatively
kubectl get secret -n <namespace> <secret-name> -o jsonpath='{.data}' | jq 'keys'
```
### Common Error Messages and Solutions
* **"AccessDenied" or "403 Forbidden"** — Check cloud credentials and bucket permissions.
* **"NoSuchBucket"** — Verify the bucket exists and the endpoint URL is correct.
* **"Connection timeout"** — Check network connectivity and firewall rules.
* **"SSL certificate problem"** — For self-signed certificates, verify the CA bundle configuration.

16
web/versioned_docs/version-0.11.0/upgrades.mdx
View File

@ -1,16 +0,0 @@
---
sidebar_position: 25
---
# Upgrades
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
You can upgrade the plugin simply by installing the new version. Unless
explicitly stated below or in the release notes, no special steps are required.
## Upgrading to version 0.8.x from previous versions
Version **0.8.0** introduces breaking changes to resource naming.
To complete the upgrade successfully, follow the instructions in the
["Resource name migration guide"](resource-name-migration.md).

283
web/versioned_docs/version-0.11.0/usage.md
View File

@ -1,283 +0,0 @@
---
sidebar_position: 30
---
# Using the Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
After [installing the plugin](installation.mdx) in the same namespace as the
CloudNativePG operator, enabling your PostgreSQL cluster to use the Barman
Cloud Plugin involves just a few steps:
- Defining the object store containing your WAL archive and base backups, using
your preferred [provider](object_stores.md)
- Instructing the Postgres cluster to use the Barman Cloud Plugin
From that moment, you’ll be able to issue on-demand backups or define a backup
schedule, as well as rely on the object store for recovery operations.
The rest of this page details each step, using MinIO as object store provider.
## Defining the `ObjectStore`
An `ObjectStore` resource must be created for each object store used in your
PostgreSQL architecture. Here's an example configuration 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` schema follows the same format 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/current/appendixes/backup_barmanobjectstore/)
for additional details.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::
## Configuring WAL Archiving
Once the `ObjectStore` is defined, you can configure your PostgreSQL cluster
to archive WALs by referencing the store in the `.spec.plugins` section:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
instances: 3
imagePullPolicy: Always
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
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. Backups can be
created either declaratively (with YAML manifests) or imperatively (with the
`cnpg` plugin).
### Declarative approach (YAML manifest)
Create a backup resource by applying a YAML manifest:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
name: backup-example
spec:
cluster:
name: cluster-example
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
### Imperative approach (using the `cnpg` plugin)
The quickest way to trigger an on-demand backup is with the `cnpg` plugin:
```bash
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin \
--plugin-name=barman-cloud.cloudnative-pg.io
```
:::note Migration from in-tree backups
If you are migrating from the in-tree backup system, note the change in syntax:
```bash
# Old command (in-tree backup)
kubectl cnpg backup -n <namespace> <cluster-name> --method=barmanObjectStore
# New command (plugin-based backup)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin \
--plugin-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
```
:::important
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
isWALArchiver: true
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
isWALArchiver: true
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
```
## Configuring the plugin instance sidecar
The Barman Cloud Plugin runs as a sidecar container next to each PostgreSQL
instance pod. It manages backup, WAL archiving, and restore processes.
Configuration comes from multiple `ObjectStore` resources:
1. The one referenced in the
`.spec.plugins` section of the `Cluster`. This is the
object store used for WAL archiving and base backups.
2. The one referenced in the external cluster
used in the `.spec.replica.source` section of the `Cluster`. This is
used by the log-shipping designated primary to get the WAL files.
3. The one referenced in the
`.spec.bootstrap.recovery.source` section of the `Cluster`. Used by
the initial recovery job to create the cluster from an existing backup.
You can fine-tune sidecar behavior in the `.spec.instanceSidecarConfiguration`
of your ObjectStore. These settings apply to all PostgreSQL instances that use
this object store. Any updates take effect at the next `Cluster` reconciliation,
and could generate a rollout of the `Cluster`.
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
# [...]
instanceSidecarConfiguration:
retentionPolicyIntervalSeconds: 1800
resources:
requests:
memory: "XXX"
cpu: "YYY"
limits:
memory: "XXX"
cpu: "YYY"
```
:::note
If more than one `ObjectStore` applies, the `instanceSidecarConfiguration` of
the one set in `.spec.plugins` has priority.
:::

43
web/versioned_docs/version-0.12.0/compression.md
View File

@ -1,43 +0,0 @@
---
sidebar_position: 80
---
# Compression
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
By default, backups and WAL files are archived **uncompressed**. However, the
Barman Cloud Plugin supports multiple compression algorithms via
`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
for space, speed, or a balance of both.
### Supported Compression Algorithms
- `bzip2`
- `gzip`
- `lz4` (WAL only)
- `snappy`
- `xz` (WAL only)
- `zstd` (WAL only)
Compression settings for base backups and WAL archives are configured
independently. For implementation details, refer to the corresponding API
definitions:
- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
:::important
Compression impacts both performance and storage efficiency. Choose the right
algorithm based on your recovery time objectives (RTO), storage capacity, and
network throughput.
:::
## Compression Benchmark (on MinIO)
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |

177
web/versioned_docs/version-0.12.0/concepts.md
View File

@ -1,177 +0,0 @@
---
sidebar_position: 10
---
# Main Concepts
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::important
Before proceeding, make sure to review the following sections of the
CloudNativePG documentation:
- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
:::
The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
supporting continuous physical backups and WAL archiving to an **object
store**—without interrupting write operations.
It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
of a PostgreSQL cluster.
## The Object Store
At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
which acts as the interface between the PostgreSQL cluster and the target
object storage system. It allows you to configure:
- **Authentication and bucket location** via the `.spec.configuration` section
- **WAL archiving** settings—such as compression type, parallelism, and
server-side encryption—under `.spec.configuration.wal`
- **Base backup options**—with similar settings for compression, concurrency,
and encryption—under `.spec.configuration.data`
- **Retention policies** to manage the life-cycle of archived WALs and backups
via `.spec.configuration.retentionPolicy`
WAL files are archived in the `wals` directory, while base backups are stored
as **tarballs** in the `base` directory, following the
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
The plugin also offers advanced capabilities, including
[backup tagging](misc.md#backup-object-tagging) and
[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving).
:::tip
For details, refer to the
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).
:::
## Integration with a CloudNativePG Cluster
CloudNativePG can delegate continuous backup and recovery responsibilities to
the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
to be defined.
:::important
While it is technically possible to reuse the same `ObjectStore` for multiple
`Cluster` resources within the same namespace, it is strongly recommended to
dedicate one object store per PostgreSQL cluster to ensure data isolation and
operational clarity.
:::
The following example demonstrates how to configure a CloudNativePG cluster
named `cluster-example` to use a previously defined `ObjectStore` (also named
`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
WAL archiving through the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
# Other cluster settings...
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: cluster-example
```
## Backup of a Postgres Cluster
Once the object store is defined and the `Cluster` is configured to use the
Barman Cloud Plugin, **WAL archiving is activated immediately** on the
PostgreSQL primary.
Physical base backups are seamlessly managed by CloudNativePG using the
`Backup` and `ScheduledBackup` resources, respectively for
[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
and
[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
backups.
To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
configure the `pluginConfiguration` section as shown:
```yaml
[...]
spec:
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
[...]
```
With this configuration, CloudNativePG supports:
- Backups from both **primary** and **standby** instances
- Backups from **designated primaries** in a distributed topology using
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
:::tip
For details on how to back up from a standby, refer to the official documentation:
[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
:::
:::important
Both backup and WAL archiving operations are executed by sidecar containers
running in the same pod as the PostgreSQL `Cluster` primary instance—except
when backups are taken from a standby, in which case the sidecar runs alongside
the standby pod.
The sidecar containers use a [dedicated container image](images.md) that
includes only the supported version of Barman Cloud.
:::
## Recovery of a Postgres Cluster
In PostgreSQL, *recovery* refers to the process of starting a database instance
from an existing backup. The Barman Cloud Plugin integrates with CloudNativePG
to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
object store.
Recovery in this context is *not in-place*: it bootstraps a brand-new
PostgreSQL cluster from a backup and replays the necessary WAL files to reach
the desired recovery target.
To perform a recovery, define an *external cluster* that references the
appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
of the target cluster:
```yaml
[...]
spec:
[...]
bootstrap:
recovery:
source: source
externalClusters:
- name: source
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: cluster-example
serverName: cluster-example
[...]
```
The critical element here is the `externalClusters` section of the `Cluster`
resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
Cloud Plugin to access the object store for recovery.
This same mechanism can be used for a variety of scenarios enabled by the
CloudNativePG API, including:
* **Full cluster recovery** from the latest backup
* **Point-in-Time Recovery (PITR)**
* Bootstrapping **replica clusters** in a distributed topology
:::tip
For complete instructions and advanced use cases, refer to the official
[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
:::

37
web/versioned_docs/version-0.12.0/images.md
View File

@ -1,37 +0,0 @@
---
sidebar_position: 99
---
# Container Images
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin is distributed using two container images:
- One for deploying the plugin components
- One for the sidecar that runs alongside each PostgreSQL instance in a
CloudNativePG `Cluster` using the plugin
## Plugin Container Image
The plugin image contains the logic required to operate the Barman Cloud Plugin
within your Kubernetes environment with CloudNativePG. It is published on the
GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
This image is built from the
[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
in the plugin repository.
## Sidecar Container Image
The sidecar image is used within each PostgreSQL pod in the cluster. It
includes the latest supported version of Barman Cloud and is responsible for
performing WAL archiving and backups on behalf of CloudNativePG.
It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
built from the
[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
These sidecar images are designed to work seamlessly with the
[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
maintained by the CloudNativePG Community.

109
web/versioned_docs/version-0.12.0/installation.mdx
View File

@ -1,109 +0,0 @@
---
sidebar_position: 20
---
# Installation
:::important
1. The plugin **must** be installed in the same namespace as the CloudNativePG
operator (typically `cnpg-system`).
2. Keep in mind that the operator's **listening namespaces** may differ from its
installation namespace. Double-check this to avoid configuration issues.
:::
## Verifying the Requirements
Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
### CloudNativePG Version
Ensure you're running a version of CloudNativePG that is compatible with the
plugin. If installed in the default `cnpg-system` namespace, you can verify the
version with:
```sh
kubectl get deployment -n cnpg-system cnpg-controller-manager \
-o jsonpath="{.spec.template.spec.containers[*].image}"
```
Example output:
```output
ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
```
The version **must be 1.26 or newer**.
### cert-manager
Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
tool to confirm that `cert-manager` is installed and available:
```sh
cmctl check api
```
Example output:
```output
The cert-manager API is ready
```
Both checks are required before proceeding with the installation.
## Installing the Barman Cloud Plugin
import { InstallationSnippet } from '@site/src/components/Installation';
Install the plugin using `kubectl` by applying the manifest for the latest
release:
<InstallationSnippet />
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
```
Finally, check that the deployment is up and running:
```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 ready to use.
## Testing the latest development snapshot
You can also test the latest development snapshot of the plugin with the
following command:
```sh
kubectl apply -f \
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
```

86
web/versioned_docs/version-0.12.0/intro.md
View File

@ -1,86 +0,0 @@
---
sidebar_position: 1
sidebar_label: "Introduction"
---
# Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The **Barman Cloud Plugin** for [CloudNativePG](https://cloudnative-pg.io/)
enables online continuous physical backups of PostgreSQL clusters to object storage
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
project.
:::important
If you plan to migrate your existing CloudNativePG cluster to the new
plugin-based approach using the Barman Cloud Plugin, see
["Migrating from Built-in CloudNativePG Backup"](migration.md)
for detailed instructions.
:::
## Requirements
Before using the Barman Cloud Plugin, ensure that the following components are
installed and properly configured:
- [CloudNativePG](https://cloudnative-pg.io) version 1.26 or later
- We strongly recommend version 1.27.0 or later, which includes improved
error handling and status reporting for the plugin.
- If you are running an earlier release, refer to the
[upgrade guide](https://cloudnative-pg.io/documentation/current/installation_upgrade).
- [cert-manager](https://cert-manager.io/)
- The recommended way to enable secure TLS communication between the plugin
and the operator.
- Alternatively, you can provide your own certificate bundles. See the
[CloudNativePG documentation on TLS configuration](https://cloudnative-pg.io/documentation/current/cnpg_i/#configuring-tls-certificates).
- [`kubectl-cnpg`](https://cloudnative-pg.io/documentation/current/kubectl-plugin/)
plugin (optional but recommended)
- Simplifies debugging and monitoring with additional status and inspection
commands.
- Multiple installation options are available in the
[installation guide](https://cloudnative-pg.io/documentation/current/kubectl-plugin/#install).
## Key Features
This plugin provides the following capabilities:
- Physical online backup of the data directory
- Physical restore of the data directory
- Write-Ahead Log (WAL) archiving
- WAL restore
- Full cluster recovery
- Point-in-Time Recovery (PITR)
- Seamless integration with replica clusters for bootstrap and WAL restore from archive
:::important
The Barman Cloud Plugin is designed to **replace the in-tree object storage support**
previously provided via the `.spec.backup.barmanObjectStore` section in the
`Cluster` resource.
Backups created using the in-tree approach are fully supported and compatible
with this plugin.
:::
## Supported Object Storage Providers
The plugin works with all storage backends supported by `barman-cloud`, including:
- **Amazon S3**
- **Google Cloud Storage**
- **Microsoft Azure Blob Storage**
In addition, the following S3-compatible and simulator solutions have been
tested and verified:
- [MinIO](https://min.io/) – An S3-compatible storage solution
- [Azurite](https://github.com/Azure/Azurite) – A simulator for Azure Blob Storage
- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage
:::tip
For more details, refer to [Object Store Providers](object_stores.md).
:::

274
web/versioned_docs/version-0.12.0/migration.md
View File

@ -1,274 +0,0 @@
---
sidebar_position: 40
---
# Migrating from Built-in CloudNativePG Backup
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting
from version 1.26** and will be removed in a future release.
If you're currently relying on the built-in Barman Cloud integration, you can
migrate seamlessly to the new **plugin-based architecture** using the Barman
Cloud Plugin, without data loss. Follow these steps:
- [Install the Barman Cloud Plugin](installation.mdx)
- Create an `ObjectStore` resource by translating the contents of the
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
definition
- Modify the `Cluster` resource in a single atomic change to switch from
in-tree backup to the plugin
- Update any `ScheduledBackup` resources to use the plugin
- Update the `externalClusters` configuration, where applicable
:::tip
For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground),
which demonstrates a full migration.
:::
---
## Step 1: Define the `ObjectStore`
Begin by creating an `ObjectStore` resource in the same namespace as your
PostgreSQL `Cluster`.
There is a **direct mapping** between the `.spec.backup.barmanObjectStore`
section in CloudNativePG and the `.spec.configuration` field in the
`ObjectStore` CR. The conversion is mostly mechanical, with one key difference:
:::warning
In the plugin architecture, retention policies are defined as part of the `ObjectStore`.
In contrast, the in-tree implementation defined them at the `Cluster` level.
:::
If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration
to `.spec.retentionPolicy` in the `ObjectStore`.
---
### Example
Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration
taken from the CloudNativePG Playground project:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-eu
spec:
# [...]
backup:
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
This configuration translates to the following `ObjectStore` resource for the
plugin:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
As you can see, the contents of `barmanObjectStore` have been copied directly
under the `configuration` field of the `ObjectStore` resource, using the same
secret references.
## Step 2: Update the `Cluster` for plugin WAL archiving
Once the `ObjectStore` resource is in place, update the `Cluster` resource as
follows in a single atomic change:
- Remove the `.spec.backup.barmanObjectStore` section
- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the
`ObjectStore`)
- Remove the entire `spec.backup` section if it is now empty
- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in
[Configuring WAL archiving](usage.md#configuring-wal-archiving)
This will trigger a rolling update of the `Cluster`, switching continuous
backup from the in-tree implementation to the plugin-based approach.
### Example
The updated `pg-eu` cluster will have this configuration instead of the
previous `backup` section:
```yaml
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: minio-eu
```
---
## Step 3: Update the `ScheduledBackup`
After switching the `Cluster` to use the plugin, update your `ScheduledBackup`
resources to match.
Set the backup `method` to `plugin` and reference the plugin name via
`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup).
### Example
Original in-tree `ScheduledBackup`:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
```
Updated version using the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
---
## Step 4: Update the `externalClusters` configuration
If your `Cluster` relies on one or more external clusters that use the in-tree
Barman Cloud integration, you need to update those configurations to use the
plugin-based architecture.
When a replica cluster fetches WAL files or base backups from an external
source that used the built-in backup method, follow these steps:
1. Create a corresponding `ObjectStore` resource for the external cluster, as
shown in [Step 1](#step-1-define-the-objectstore)
2. Update the `externalClusters` section of your replica cluster to use the
plugin instead of the in-tree `barmanObjectStore` field
### Example
Consider the original configuration using in-tree Barman Cloud:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
serverName: pg-eu
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Create the `ObjectStore` resource for the external cluster:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Update the external cluster configuration to use the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: minio-eu
serverName: pg-eu
```
## Step 5: Verify your metrics
When migrating from the in-core solution to the plugin-based approach, you need
to monitor a different set of metrics, as described in the
["Observability"](observability.md) section.
The table below summarizes the name changes between the old in-core metrics and
the new plugin-based ones:
| Old metric name | New metric name |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| `cnpg_collector_last_failed_backup_timestamp` | `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp` |
| `cnpg_collector_last_available_backup_timestamp` | `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp` |
| `cnpg_collector_first_recoverability_point` | `barman_cloud_cloudnative_pg_io_first_recoverability_point` |

97
web/versioned_docs/version-0.12.0/misc.md
View File

@ -1,97 +0,0 @@
---
sidebar_position: 90
---
# Miscellaneous
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
## Backup Object Tagging
You can attach key-value metadata tags to backup artifacts—such as base
backups, WAL files, and history files—via the `.spec.configuration` section of
the `ObjectStore` resource.
- `tags`: applied to base backups and WAL files
- `historyTags`: applied to history files only
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
[...]
tags:
backupRetentionPolicy: "expire"
historyTags:
backupRetentionPolicy: "keep"
[...]
```
## Extra Options for Backup and WAL Archiving
You can pass additional command-line arguments to `barman-cloud-backup` and
`barman-cloud-wal-archive` using the `additionalCommandArgs` field in the
`ObjectStore` configuration.
- `.spec.configuration.data.additionalCommandArgs`: for `barman-cloud-backup`
- `.spec.configuration.wal.archiveAdditionalCommandArgs`: for `barman-cloud-wal-archive`
Each field accepts a list of string arguments. If an argument is already
configured elsewhere in the plugin, the duplicate will be ignored.
### Example: Extra Backup Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
data:
additionalCommandArgs:
- "--min-chunk-size=5MB"
- "--read-timeout=60"
```
### Example: Extra WAL Archive Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
wal:
archiveAdditionalCommandArgs:
- "--max-concurrency=1"
- "--read-timeout=60"
```
For a complete list of supported options, refer to the
[official Barman Cloud documentation](https://docs.pgbarman.org/release/latest/).
## Enable the pprof debug server for the sidecar
You can enable the instance sidecar's pprof debug HTTP server by adding the `--pprof-server=<address>` flag to the container's
arguments via `.spec.instanceSidecarConfiguration.additionalContainerArgs`.
Pass a bind address in the form `<host>:<port>` (for example, `0.0.0.0:6061`).
An empty value disables the server (disabled by default).
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
instanceSidecarConfiguration:
additionalContainerArgs:
- "--pprof-server=0.0.0.0:6061"
```

497
web/versioned_docs/version-0.12.0/object_stores.md
View File

@ -1,497 +0,0 @@
---
sidebar_position: 50
---
# Object Store Providers
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin enables the storage of PostgreSQL cluster backup files
in any object storage service supported by the
[Barman Cloud infrastructure](https://docs.pgbarman.org/release/latest/).
Currently, Barman Cloud supports the following providers:
- [Amazon S3](#aws-s3)
- [Microsoft Azure Blob Storage](#azure-blob-storage)
- [Google Cloud Storage](#google-cloud-storage)
You may also use any S3- or Azure-compatible implementation of the above
services.
To configure object storage with Barman Cloud, you must define an
[`ObjectStore` object](plugin-barman-cloud.v1.md#objectstore), which
establishes the connection between your PostgreSQL cluster and the object
storage backend.
Configuration details — particularly around authentication — will vary depending on
the specific object storage provider you are using.
The following sections detail the setup for each.
:::note Authentication Methods
The Barman Cloud Plugin does not independently test all authentication methods
supported by `barman-cloud`. The plugin's responsibility is limited to passing
the provided credentials to `barman-cloud`, which then handles authentication
according to its own implementation. Users should refer to the
[Barman Cloud documentation](https://docs.pgbarman.org/release/latest/) to
verify that their chosen authentication method is supported and properly
configured.
:::
---
## AWS S3
[AWS Simple Storage Service (S3)](https://aws.amazon.com/s3/) is one of the
most widely adopted object storage solutions.
The Barman Cloud plugin for CloudNativePG integrates with S3 through two
primary authentication mechanisms:
- [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) —
recommended for clusters running on EKS
- Access keys — using `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY` credentials
### Access Keys
To authenticate using access keys, you’ll need:
- `ACCESS_KEY_ID`: the public key used to authenticate to S3
- `ACCESS_SECRET_KEY`: the corresponding secret key
- `ACCESS_SESSION_TOKEN`: (optional) a temporary session token, if required
These credentials must be stored securely in a Kubernetes secret:
```sh
kubectl create secret generic aws-creds \
--from-literal=ACCESS_KEY_ID=<access key here> \
--from-literal=ACCESS_SECRET_KEY=<secret key here>
# --from-literal=ACCESS_SESSION_TOKEN=<session token here> # if required
```
The credentials will be encrypted at rest if your Kubernetes environment
supports it.
You can then reference the secret in your `ObjectStore` definition:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: aws-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
s3Credentials:
accessKeyId:
name: aws-creds
key: ACCESS_KEY_ID
secretAccessKey:
name: aws-creds
key: ACCESS_SECRET_KEY
[...]
```
### IAM Role for Service Account (IRSA)
To use IRSA with EKS, configure the service account of the PostgreSQL cluster
with the appropriate annotation:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
[...]
spec:
serviceAccountTemplate:
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:[...]
[...]
```
### S3 Lifecycle Policy
Barman Cloud uploads backup files to S3 but does not modify them afterward.
To enhance data durability and protect against accidental or malicious loss,
it's recommended to implement the following best practices:
- Enable object versioning
- Enable object locking to prevent objects from being deleted or overwritten
for a defined period or indefinitely (this provides an additional layer of
protection against accidental deletion and ransomware attacks)
- Set lifecycle rules to expire current versions a few days after your Barman
retention window
- Expire non-current versions after a longer period
These strategies help you safeguard backups without requiring broad delete
permissions, ensuring both security and compliance with minimal operational
overhead.
### S3-Compatible Storage Providers
You can use S3-compatible services like **MinIO**, **Linode (Akamai) Object Storage**,
or **DigitalOcean Spaces** by specifying a custom `endpointURL`.
Example with Linode (Akamai) Object Storage (`us-east1`):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/"
endpointURL: "https://us-east1.linodeobjects.com"
s3Credentials:
[...]
[...]
```
Recent changes to the [boto3 implementation](https://github.com/boto/boto3/issues/4392)
of [Amazon S3 Data Integrity Protections](https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html)
may lead to the `x-amz-content-sha256` error when using the Barman Cloud
Plugin.
If you encounter this issue (see [GitHub issue #393](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/393)),
you can apply the following workaround by setting specific environment
variables in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
instanceSidecarConfiguration:
env:
- name: AWS_REQUEST_CHECKSUM_CALCULATION
value: when_required
- name: AWS_RESPONSE_CHECKSUM_VALIDATION
value: when_required
[...]
```
These settings ensure that checksum calculations and validations are only
applied when explicitly required, avoiding compatibility issues with certain
S3-compatible storage providers.
Example with DigitalOcean Spaces (SFO3, path-style):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: digitalocean-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
endpointURL: "https://sfo3.digitaloceanspaces.com"
s3Credentials:
[...]
[...]
```
### Using Object Storage with a Private CA
For object storage services (e.g., MinIO) that use HTTPS with certificates
signed by a private CA, set the `endpointCA` field in the `ObjectStore`
definition. Unless you already have it, create a Kubernetes `Secret` with the
CA bundle:
```sh
kubectl create secret generic my-ca-secret --from-file=ca.crt
```
Then reference it:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
endpointURL: <myEndpointURL>
endpointCA:
name: my-ca-secret
key: ca.crt
[...]
```
<!-- TODO: does this also apply to the plugin? -->
:::note
If you want `ConfigMaps` and `Secrets` to be **automatically** reloaded by
instances, you can add a label with the key `cnpg.io/reload` to the
`Secrets`/`ConfigMaps`. Otherwise, you will have to reload the instances using the
`kubectl cnpg reload` subcommand.
:::
---
## Azure Blob Storage
[Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
is Microsoft’s cloud-based object storage solution.
Barman Cloud supports the following authentication methods:
- [Connection String](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string)
- Storage Account Name + [Storage Account Access Key](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
- Storage Account Name + [Storage Account SAS Token](https://learn.microsoft.com/en-us/azure/storage/blobs/sas-service-create)
- [Azure AD Managed Identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview)
- [Default Azure Credentials](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet)
### Azure AD Managed Identity
This method avoids storing credentials in Kubernetes by enabling the
usage of [Azure Managed Identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) authentication mechanism.
This can be enabled by setting the `inheritFromAzureAD` option to `true`.
Managed Identity can be configured for the AKS Cluster by following
the [Azure documentation](https://learn.microsoft.com/en-us/azure/aks/use-managed-identity?pivots=system-assigned).
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
inheritFromAzureAD: true
[...]
```
### Default Azure Credentials
The `useDefaultAzureCredentials` option enables the default Azure credentials
flow, which uses [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.defaultazurecredential)
to automatically discover and use available credentials in the following order:
1. **Environment Variables** — `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID` for Service Principal authentication
2. **Managed Identity** — Uses the managed identity assigned to the pod
3. **Azure CLI** — Uses credentials from the Azure CLI if available
4. **Azure PowerShell** — Uses credentials from Azure PowerShell if available
This approach is particularly useful for getting started with development and testing; it allows
the SDK to attempt multiple authentication mechanisms seamlessly across different environments.
However, this is not recommended for production. Please refer to the
[official Azure guidance](https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#usage-guidance-for-defaultazurecredential)
for a comprehensive understanding of `DefaultAzureCredential`.
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
useDefaultAzureCredentials: true
[...]
```
### Access Key, SAS Token, or Connection String
Store credentials in a Kubernetes secret:
```sh
kubectl create secret generic azure-creds \
--from-literal=AZURE_STORAGE_ACCOUNT=<storage account name> \
--from-literal=AZURE_STORAGE_KEY=<storage account key> \
--from-literal=AZURE_STORAGE_SAS_TOKEN=<SAS token> \
--from-literal=AZURE_STORAGE_CONNECTION_STRING=<connection string>
```
Then reference the required keys in your `ObjectStore`:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
connectionString:
name: azure-creds
key: AZURE_CONNECTION_STRING
storageAccount:
name: azure-creds
key: AZURE_STORAGE_ACCOUNT
storageKey:
name: azure-creds
key: AZURE_STORAGE_KEY
storageSasToken:
name: azure-creds
key: AZURE_STORAGE_SAS_TOKEN
[...]
```
For Azure Blob, the destination path format is:
```
<http|https>://<account-name>.<service-name>.core.windows.net/<container>/<blob>
```
### Azure-Compatible Providers
If you're using a different implementation (e.g., Azurite or emulator):
```
<http|https>://<local-machine-address>:<port>/<account-name>/<container>/<blob>
```
---
## Google Cloud Storage
[Google Cloud Storage](https://cloud.google.com/storage/) is supported with two
authentication modes:
- **GKE Workload Identity** (recommended inside Google Kubernetes Engine)
- **Service Account JSON key** via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
### GKE Workload Identity
Use the [Workload Identity authentication](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
when running in GKE:
1. Set `googleCredentials.gkeEnvironment` to `true` in the `ObjectStore`
resource
2. Annotate the `serviceAccountTemplate` in the `Cluster` resource with the GCP
service account
For example, in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
gkeEnvironment: true
```
And in the `Cluster` resource:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
serviceAccountTemplate:
metadata:
annotations:
iam.gke.io/gcp-service-account: [...].iam.gserviceaccount.com
```
### Service Account JSON Key
Follow Google’s [authentication setup](https://cloud.google.com/docs/authentication/getting-started),
then:
```sh
kubectl create secret generic backup-creds --from-file=gcsCredentials=gcs_credentials_file.json
```
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
applicationCredentials:
name: backup-creds
key: gcsCredentials
[...]
```
:::important
This authentication method generates a JSON file within the container
with all the credentials required to access your Google Cloud Storage
bucket. As a result, if someone gains access to the `Pod`, they will also have
write permissions to the bucket.
:::
---
## MinIO Object Store
In order to use the Tenant resource you first need to deploy the
[MinIO operator](https://docs.min.io/community/minio-object-store/operations/deployments/installation.html).
For the latest documentation of MinIO, please refer to the
[MinIO official documentation](https://docs.min.io/community/minio-object-store/).
MinIO Object Store's API is compatible with S3, and the default configuration of the Tenant
will create these services:
- `<tenant>-console` on port 9090 (with autocert) or 9443 (without autocert)
- `<tenant>-hl` on port 9000
Where `<tenant>` is the `metadata.name` you assigned to your Tenant resource.
:::note
The `<tenant>-console` service will only be available if you have enabled the
[MinIO Console](https://docs.min.io/community/minio-object-store/administration/minio-console.html).
For example, the following Tenant:
```yml
apiVersion: minio.min.io/v2
kind: Tenant
metadata:
name: cnpg-backups
spec:
[...]
```
would have services called `cnpg-backups-console` and `cnpg-backups-hl` respectively.
The `console` service is for managing the tenant, while the `hl` service exposes the S3
compatible API. If your tenant is configured with `requestAutoCert` you will communicate
to these services over HTTPS, if not you will use HTTP.
For authentication you can use your username and password, or create an access key.
Whichever method you choose, it has to be stored as a secret.
```sh
kubectl create secret generic minio-creds \
--from-literal=MINIO_ACCESS_KEY=<minio access key or username> \
--from-literal=MINIO_SECRET_KEY=<minio secret key or password>
```
Finally, create the Barman ObjectStore:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
destinationPath: s3://BUCKET_NAME/
endpointURL: http://<tenant>-hl:9000
s3Credentials:
accessKeyId:
name: minio-creds
key: MINIO_ACCESS_KEY
secretAccessKey:
name: minio-creds
key: MINIO_SECRET_KEY
[...]
```
:::important
Verify on `s3://BUCKET_NAME/` the presence of archived WAL files before
proceeding with a backup.
:::
---

24
web/versioned_docs/version-0.12.0/observability.md
View File

@ -1,24 +0,0 @@
---
sidebar_position: 55
---
# Observability
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin exposes the following metrics through the native
Prometheus exporter of the instance manager:
- `barman_cloud_cloudnative_pg_io_last_failed_backup_timestamp`:
the UNIX timestamp of the most recent failed backup.
- `barman_cloud_cloudnative_pg_io_last_available_backup_timestamp`:
the UNIX timestamp of the most recent successfully available backup.
- `barman_cloud_cloudnative_pg_io_first_recoverability_point`:
the UNIX timestamp representing the earliest point in time from which the
cluster can be recovered.
These metrics supersede the previously available in-core metrics that used the
`cnpg_collector` prefix. The new metrics are exposed under the
`barman_cloud_cloudnative_pg_io` prefix instead.

19
web/versioned_docs/version-0.12.0/parameters.md
View File

@ -1,19 +0,0 @@
---
sidebar_position: 100
---
# Parameters
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The following parameters are available for the Barman Cloud Plugin:
- `barmanObjectName`: references the `ObjectStore` resource to be used by the
plugin.
- `serverName`: Specifies the server name in the object store.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::

108
web/versioned_docs/version-0.12.0/plugin-barman-cloud.v1.md
View File

@ -1,108 +0,0 @@
# API Reference
## Packages
- [barmancloud.cnpg.io/v1](#barmancloudcnpgiov1)
## barmancloud.cnpg.io/v1
Package v1 contains API Schema definitions for the barmancloud v1 API group
### Resource Types
- [ObjectStore](#objectstore)
#### InstanceSidecarConfiguration
InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.
_Appears in:_
- [ObjectStoreSpec](#objectstorespec)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#envvar-v1-core) array_ | The environment to be explicitly passed to the sidecar | | | |
| `retentionPolicyIntervalSeconds` _integer_ | The retentionCheckInterval defines the frequency at which the<br />system checks and enforces retention policies. | | 1800 | |
| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#resourcerequirements-v1-core)_ | Resources define cpu/memory requests and limits for the sidecar that runs in the instance pods. | | | |
| `additionalContainerArgs` _string array_ | AdditionalContainerArgs is an optional list of command-line arguments<br />to be passed to the sidecar container when it starts.<br />The provided arguments are appended to the container’s default arguments. | | | |
| `logLevel` _string_ | The log level for PostgreSQL instances. Valid values are: `error`, `warning`, `info` (default), `debug`, `trace` | | info | Enum: [error warning info debug trace] <br /> |
#### ObjectStore
ObjectStore is the Schema for the objectstores API.
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `apiVersion` _string_ | `barmancloud.cnpg.io/v1` | True | | |
| `kind` _string_ | `ObjectStore` | True | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | True | | |
| `spec` _[ObjectStoreSpec](#objectstorespec)_ | Specification of the desired behavior of the ObjectStore.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | True | | |
| `status` _[ObjectStoreStatus](#objectstorestatus)_ | Most recently observed status of the ObjectStore. This data may not be up to<br />date. Populated by the system. Read-only.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | | | |
#### ObjectStoreSpec
ObjectStoreSpec defines the desired state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `configuration` _[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)_ | The configuration for the barman-cloud tool suite | True | | |
| `retentionPolicy` _string_ | RetentionPolicy is the retention policy to be used for backups<br />and WALs (i.e. '60d'). The retention policy is expressed in the form<br />of `XXu` where `XX` is a positive integer and `u` is in `[dwm]` -<br />days, weeks, months. | | | Pattern: `^[1-9][0-9]*[dwm]$` <br /> |
| `instanceSidecarConfiguration` _[InstanceSidecarConfiguration](#instancesidecarconfiguration)_ | The configuration for the sidecar that runs in the instance pods | | | |
#### ObjectStoreStatus
ObjectStoreStatus defines the observed state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `serverRecoveryWindow` _object (keys:string, values:[RecoveryWindow](#recoverywindow))_ | ServerRecoveryWindow maps each server to its recovery window | True | | |
#### RecoveryWindow
RecoveryWindow represents the time span between the first
recoverability point and the last successful backup of a PostgreSQL
server, defining the period during which data can be restored.
_Appears in:_
- [ObjectStoreStatus](#objectstorestatus)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `firstRecoverabilityPoint` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The first recoverability point in a PostgreSQL server refers to<br />the earliest point in time to which the database can be<br />restored. | True | | |
| `lastSuccessfulBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last successful backup time | True | | |
| `lastFailedBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last failed backup time | True | | |

219
web/versioned_docs/version-0.12.0/resource-name-migration.md
View File

@ -1,219 +0,0 @@
---
sidebar_position: 90
---
# Resource name migration guide
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::warning
Before proceeding with the migration process, please:
1. **Read this guide in its entirety** to understand what changes will be made
2. **Test in a non-production environment** first if possible
3. **Ensure you have proper backups** of your cluster configuration
This migration will delete old RBAC resources only after the
`plugin-barman-cloud` upgrade. While the operation is designed to be safe, you
should review and understand the changes before proceeding. The maintainers of
this project are not responsible for any issues that may arise during
migration.
**Note:** This guide assumes you are using the default `cnpg-system` namespace.
:::
## Overview
Starting from version **0.8.0**, the `plugin-barman-cloud` deployment manifests
use more specific, prefixed resource names to avoid conflicts with other
components deployed in the same Kubernetes cluster.
## What Changed
The following resources have been renamed to use proper prefixes.
### Cluster-scoped Resources
| Old Name | New Name |
|----------------------------|------------------------------------------|
| `metrics-auth-role` | `barman-plugin-metrics-auth-role` |
| `metrics-auth-rolebinding` | `barman-plugin-metrics-auth-rolebinding` |
| `metrics-reader` | `barman-plugin-metrics-reader` |
| `objectstore-viewer-role` | `barman-plugin-objectstore-viewer-role` |
| `objectstore-editor-role` | `barman-plugin-objectstore-editor-role` |
### Namespace-scoped Resources
| Old Name | New Name | Namespace |
|-------------------------------|---------------------------------------------|---------------|
| `leader-election-role` | `barman-plugin-leader-election-role` | `cnpg-system` |
| `leader-election-rolebinding` | `barman-plugin-leader-election-rolebinding` | `cnpg-system` |
## Why This Change?
Using generic names for cluster-wide resources is discouraged as they may
conflict with other components deployed in the same cluster. The new names make
it clear that these resources belong to the Barman Cloud plugin and help avoid
naming collisions.
## Migration Instructions
This three steps migration process is straightforward and can be completed with
a few `kubectl` commands.
### Step 1: Upgrade plugin-barman-cloud
Please refer to the [Installation](installation.mdx) section to deploy the new
`plugin-barman-cloud` release.
### Step 2: Delete Old Cluster-scoped Resources
:::danger Verify Resources Before Deletion
**IMPORTANT**: The old resource names are generic and could potentially belong
to other components in your cluster.
**Before deleting each resource, verify it belongs to the Barman Cloud plugin
by checking:**
- For `objectstore-*` roles: Look for `barmancloud.cnpg.io` in the API groups
- For `metrics-*` roles: Check if they reference the `plugin-barman-cloud`
ServiceAccount in `cnpg-system` namespace
- For other roles: Look for labels like `app.kubernetes.io/name: plugin-barman-cloud`
If a resource doesn't have these indicators, **DO NOT DELETE IT** as it may
belong to another application.
Carefully review the output of each verification command before proceeding with
the `delete`.
:::
:::tip Dry Run First
You can add `--dry-run=client` to any `kubectl delete` command to preview what
would be deleted without actually removing anything.
:::
**Only proceed if you've verified these resources belong to the Barman Cloud
plugin (see warning above).**
For each resource below, first verify it belongs to Barman Cloud, then delete
it:
```bash
# 1. Check metrics-auth-rolebinding FIRST (we'll check the role after)
# Look for references to plugin-barman-cloud ServiceAccount
kubectl describe clusterrolebinding metrics-auth-rolebinding
# If it references plugin-barman-cloud ServiceAccount in cnpg-system namespace,
# delete it:
kubectl delete clusterrolebinding metrics-auth-rolebinding
# 2. Check metrics-auth-role
# Look for references to authentication.k8s.io and authorization.k8s.io
kubectl describe clusterrole metrics-auth-role
# Verify it's not being used by any other rolebindings:
kubectl get clusterrolebinding -o json \
| jq -r '.items[] | select(.roleRef.name=="metrics-auth-role") \
| .metadata.name'
# If the above returns nothing (role is not in use) and the role looks like the
# Barman Cloud one, delete it (see warnings section):
kubectl delete clusterrole metrics-auth-role
# 3. Check objectstore-viewer-role
# Look for barmancloud.cnpg.io API group or
# for `app.kubernetes.io/name: plugin-barman-cloud` label
kubectl describe clusterrole objectstore-viewer-role
# If it shows barmancloud.cnpg.io in API groups, delete it:
kubectl delete clusterrole objectstore-viewer-role
# 4. Check objectstore-editor-role
# Look for barmancloud.cnpg.io API group or
# for `app.kubernetes.io/name: plugin-barman-cloud` label
kubectl describe clusterrole objectstore-editor-role
# If it shows barmancloud.cnpg.io in API groups, delete it:
kubectl delete clusterrole objectstore-editor-role
# 5. Check metrics-reader (MOST DANGEROUS - very generic name)
# First, check if it's being used by any rolebindings OTHER than barman's:
kubectl get clusterrolebinding -o json | jq -r '.items[] \
| select(.roleRef.name=="metrics-reader") \
| "\(.metadata.name) -> \(.subjects[0].name) in \(.subjects[0].namespace)"'
# If this shows ANY rolebindings, review them carefully. Only proceed if
# they're all Barman-related. Then check the role itself:
kubectl describe clusterrole metrics-reader
# If it ONLY has nonResourceURLs: /metrics and NO other rolebindings use it,
# delete it:
kubectl delete clusterrole metrics-reader
```
:::warning
The `metrics-reader` role is particularly dangerous to delete blindly. Many
monitoring systems use this exact name. Only delete it if:
1. You've verified it ONLY grants access to `/metrics`
2. No other rolebindings reference it (checked with the jq command above)
3. You're certain it was created by the Barman Cloud plugin
If you're unsure, it's safer to leave it and let the new
`barman-plugin-metrics-reader` role coexist with it.
:::
If any resource is not found during the `describe` command, that's okay - it
means it was never created or already deleted. Simply skip the delete command
for that resource.
### Step 3: Delete Old Namespace-scoped Resources
Delete the old namespace-scoped resources in the `cnpg-system` namespace:
```bash
# Delete the old leader-election resources
kubectl delete role leader-election-role -n cnpg-system
kubectl delete rolebinding leader-election-rolebinding -n cnpg-system
```
If any resource is not found, that's okay - it means it was never created or
already deleted.
## Impact
- **Permissions:** If you have custom RBAC rules or tools that reference the
old resource names, they will need to be updated.
- **External Users:** If end users have been granted the
`objectstore-viewer-role` or `objectstore-editor-role`, they will need to be
re-granted the new role names (`barman-plugin-objectstore-viewer-role` and
`barman-plugin-objectstore-editor-role`).
## Verification
After migration, verify that the new resources are created:
```bash
# Check cluster-scoped resources
kubectl get clusterrole | grep barman
kubectl get clusterrolebinding | grep barman
# Check namespace-scoped resources
kubectl get role,rolebinding -n cnpg-system | grep barman
```
You should see the new prefixed resource names.
## Troubleshooting
### Plugin Not Starting After Migration
If the plugin fails to start after migration, check:
1. **ServiceAccount permissions:** Ensure the `plugin-barman-cloud` ServiceAccount is bound to the new roles:
```bash
kubectl get clusterrolebinding barman-plugin-metrics-auth-rolebinding -o yaml
kubectl get rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system -o yaml
```
2. **Role references:** Verify that the rolebindings reference the correct role names:
```bash
kubectl describe rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system
kubectl describe clusterrolebinding barman-plugin-metrics-auth-rolebinding
```
## Support
If you encounter issues during migration, please open an issue on the [GitHub
repository](https://github.com/cloudnative-pg/plugin-barman-cloud/issues).

38
web/versioned_docs/version-0.12.0/retention.md
View File

@ -1,38 +0,0 @@
---
sidebar_position: 60
---
# Retention Policies
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin supports **automated cleanup of obsolete backups** via
retention policies, configured in the `.spec.retentionPolicy` field of the
`ObjectStore` resource.
:::note
This feature uses the `barman-cloud-backup-delete` command with the
`--retention-policy "RECOVERY WINDOW OF {{ value }} {{ unit }}"` syntax.
:::
#### Example: 30-Day Retention Policy
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
[...]
retentionPolicy: "30d"
````
:::note
A **recovery window retention policy** ensures the cluster can be restored to
any point in time between the calculated *Point of Recoverability* (PoR) and
the latest WAL archive. The PoR is defined as `current time - recovery window`.
The **first valid backup** is the most recent backup completed before the PoR.
Backups older than that are marked as *obsolete* and deleted after the next
backup completes.
:::

591
web/versioned_docs/version-0.12.0/troubleshooting.md
View File

@ -1,591 +0,0 @@
---
sidebar_position: 90
---
# Troubleshooting
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
This guide helps you diagnose and resolve common issues with the Barman Cloud
plugin.
:::important
We are continuously improving the integration between CloudNativePG and the
Barman Cloud plugin as it moves toward greater stability and maturity. For this
reason, we recommend using the latest available version of both components.
See the [*Requirements* section](intro.md#requirements) for details.
:::
:::note
The following commands assume you installed the CloudNativePG operator in
the default `cnpg-system` namespace. If you installed it in a different
namespace, adjust the commands accordingly.
:::
## Viewing Logs
To troubleshoot effectively, you’ll often need to review logs from multiple
sources:
```sh
# View operator logs (includes plugin interaction logs)
kubectl logs -n cnpg-system deployment/cnpg-controller-manager -f
# View plugin manager logs
kubectl logs -n cnpg-system deployment/barman-cloud -f
# View sidecar container logs (Barman Cloud operations)
kubectl logs -n <namespace> <cluster-pod-name> -c plugin-barman-cloud -f
# View all containers in a pod
kubectl logs -n <namespace> <cluster-pod-name> --all-containers=true
# View previous container logs (if container restarted)
kubectl logs -n <namespace> <cluster-pod-name> -c plugin-barman-cloud --previous
```
## Common Issues
### Plugin Installation Issues
#### Plugin pods not starting
**Symptoms:**
- Plugin pods stuck in `CrashLoopBackOff` or `Error`
- Plugin deployment not ready
**Possible causes and solutions:**
1. **Certificate issues**
```sh
# Check if cert-manager is installed and running
kubectl get pods -n cert-manager
# Check if the plugin certificate is created
kubectl get certificates -n cnpg-system
```
If cert-manager is not installed, install it first:
```sh
# Note: other installation methods for cert-manager are available
kubectl apply -f \
https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
```
If you are using your own certificates without cert-manager, you will need
to verify the entire certificate chain yourself.
2. **Image pull errors**
```sh
# Check pod events for image pull errors
kubectl describe pod -n cnpg-system -l app=barman-cloud
```
Verify the image exists and you have proper credentials if using a private
registry.
3. **Resource constraints**
```sh
# Check node resources
kubectl top nodes
kubectl describe nodes
```
Make sure your cluster has sufficient CPU and memory resources.
### Backup Failures
#### Quick Backup Troubleshooting Checklist
When a backup fails, follow these steps in order:
1. **Check backup status**:
```sh
kubectl get backups.postgresql.cnpg.io -n <namespace>
```
2. **Get error details and target pod**:
```sh
kubectl describe backups.postgresql.cnpg.io \
-n <namespace> <backup-name>
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}'
```
3. **Check the target pod’s sidecar logs**:
```sh
TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}')
kubectl logs \
-n <namespace> $TARGET_POD -c plugin-barman-cloud \
--tail=100 | grep -E "ERROR|FATAL|panic"
```
4. **Check cluster events**:
```sh
kubectl get events -n <namespace> \
--field-selector involvedObject.name=<cluster-name> \
--sort-by='.lastTimestamp'
```
5. **Verify plugin is running**:
```sh
kubectl get pods \
-n cnpg-system -l app=barman-cloud
```
6. **Check operator logs**:
```sh
kubectl logs \
-n cnpg-system deployment/cnpg-controller-manager \
--tail=100 | grep -i "backup\|plugin"
```
7. **Check plugin manager logs**:
```sh
kubectl logs \
-n cnpg-system deployment/barman-cloud --tail=100
```
#### Backup job fails immediately
**Symptoms:**
- Backup pods terminate with error
- No backup files appear in object storage
- Backup shows `failed` phase with various error messages
**Common failure modes and solutions:**
1. **"requested plugin is not available" errors**
```
requested plugin is not available: barman
requested plugin is not available: barman-cloud
requested plugin is not available: barman-cloud.cloudnative-pg.io
```
**Cause:** The plugin name in the Cluster configuration doesn’t match the
deployed plugin, or the plugin isn’t registered.
**Solution:**
a. **Check plugin registration:**
```sh
# If you have the `cnpg` plugin installed (v1.27.0+)
kubectl cnpg status -n <namespace> <cluster-name>
```
Look for the "Plugins status" section:
```
Plugins status
Name Version Status Reported Operator Capabilities
---- ------- ------ ------------------------------
barman-cloud.cloudnative-pg.io 0.6.0 N/A Reconciler Hooks, Lifecycle Service
```
b. **Verify plugin name in `Cluster` spec**:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
plugins:
- name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: <your-objectstore-name>
```
c. **Check plugin deployment is running**:
```sh
kubectl get deployment -n cnpg-system barman-cloud
```
2. **"rpc error: code = Unknown desc = panic caught: assignment to entry in nil map" errors**
**Cause:** Misconfiguration in the `ObjectStore` (e.g., typo or missing field).
**Solution:**
- Review sidecar logs for details
- Verify `ObjectStore` configuration and secrets
- Common issues include:
- Missing or incorrect secret references
- Typos in configuration parameters
- Missing required environment variables in secrets
#### Backup performance issues
**Symptoms:**
- Backups take extremely long
- Backups timeout
**Plugin-specific considerations:**
1. **Check `ObjectStore` parallelism settings**
- Adjust `maxParallel` in `ObjectStore` configuration
- Monitor sidecar container resource usage during backups
2. **Verify plugin resource allocation**
- Check if the sidecar container has sufficient CPU/memory
- Review plugin container logs for resource-related warnings
:::tip
For Barman-specific features like compression, encryption, and performance
tuning, refer to the [Barman documentation](https://docs.pgbarman.org/latest/).
:::
### WAL Archiving Issues
#### WAL archiving stops
**Symptoms:**
- WAL files accumulate on the primary
- Cluster shows WAL archiving warnings
- Sidecar logs show WAL errors
**Debugging steps:**
1. **Check plugin sidecar logs for WAL archiving errors**
```sh
# Check recent WAL archive operations in sidecar
kubectl logs -n <namespace> <primary-pod> -c plugin-barman-cloud \
--tail=50 | grep -i wal
```
2. **Check ObjectStore configuration for WAL settings**
- Ensure ObjectStore has proper WAL retention settings
- Verify credentials have permissions for WAL operations
### Restore Issues
#### Restore fails during recovery
**Symptoms:**
- New cluster stuck in recovery
- Plugin sidecar shows restore errors
- PostgreSQL won’t start
**Debugging steps:**
1. **Check plugin sidecar logs during restore**
```sh
# Check the sidecar logs on the recovering cluster pods
kubectl logs -n <namespace> <cluster-pod-name> \
-c plugin-barman-cloud --tail=100
# Look for restore-related errors
kubectl logs -n <namespace> <cluster-pod-name> \
-c plugin-barman-cloud | grep -E "restore|recovery|ERROR"
```
2. **Verify plugin can access backups**
```sh
# Check if `ObjectStore` is properly configured for restore
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Check PostgreSQL recovery logs
kubectl logs -n <namespace> <cluster-pod> \
-c postgres | grep -i recovery
```
:::tip
For detailed Barman restore operations and troubleshooting, refer to the
[Barman documentation](https://docs.pgbarman.org/latest/barman-cloud-restore.html).
:::
#### Point-in-time recovery (PITR) configuration issues
**Symptoms:**
- PITR doesn’t reach target time
- WAL access errors
- Recovery halts early
**Debugging steps:**
1. **Verify PITR configuration in the `Cluster` spec**
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: <cluster-restore-name>
spec:
storage:
size: 1Gi
bootstrap:
recovery:
source: origin
recoveryTarget:
targetTime: "2024-01-15T10:30:00Z"
externalClusters:
- name: origin
plugin:
enabled: true
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: <object-store-name>
serverName: <source-cluster-name>
```
2. **Check sidecar logs for WAL-related errors**
```sh
kubectl logs -n <namespace> <cluster-pod> \
-c plugin-barman-cloud | grep -i wal
```
:::note
Timestamps without an explicit timezone suffix
(e.g., `2024-01-15 10:30:00`) are interpreted as UTC.
:::
:::warning
Always specify an explicit timezone in your timestamp to avoid ambiguity.
For example, use `2024-01-15T10:30:00Z` or `2024-01-15T10:30:00+02:00`
instead of `2024-01-15 10:30:00`.
:::
:::note
For detailed PITR configuration and WAL management, see the
[Barman PITR documentation](https://docs.pgbarman.org/latest/).
:::
### Plugin Configuration Issues
#### Plugin cannot connect to object storage
**Symptoms:**
- Sidecar logs show connection errors
- Backups fail with authentication or network errors
- `ObjectStore` resource reports errors
**Solution:**
1. **Verify `ObjectStore` CRD configuration and secrets**
```sh
# Check ObjectStore resource status
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Verify the secret exists and has correct keys for your provider
kubectl get secret -n <namespace> <secret-name> \
-o jsonpath='{.data}' | jq 'keys'
```
2. **Check sidecar logs for connectivity issues**
```sh
kubectl logs -n <namespace> <cluster-pod> \
-c plugin-barman-cloud | grep -E "connect|timeout|SSL|cert"
```
3. **Adjust provider-specific settings (endpoint, path style, etc.)**
- See [Object Store Configuration](object_stores.md) for provider-specific settings
- Ensure `endpointURL` is set correctly for your storage provider
- Verify network policies allow egress to your storage provider
## Diagnostic Commands
### Using the `cnpg` plugin for `kubectl`
The `cnpg` plugin for `kubectl` provides extended debugging capabilities.
Keep it updated:
```sh
# Install or update the `cnpg` plugin
kubectl krew install cnpg
# Or using an alternative method: https://cloudnative-pg.io/documentation/current/kubectl-plugin/#install
# Check plugin status (requires CNPG 1.27.0+)
kubectl cnpg status <cluster-name> -n <namespace>
# View cluster status in detail
kubectl cnpg status <cluster-name> -n <namespace> --verbose
```
## Getting Help
If problems persist:
1. **Check the documentation**
- [Installation Guide](installation.mdx)
- [Object Store Configuration](object_stores.md) (for provider-specific settings)
- [Usage Examples](usage.md)
2. **Gather diagnostic information**
```sh
# Create a diagnostic bundle (⚠️ sanitize these before sharing!)
kubectl get objectstores.barmancloud.cnpg.io -A -o yaml > /tmp/objectstores.yaml
kubectl get clusters.postgresql.cnpg.io -A -o yaml > /tmp/clusters.yaml
kubectl logs -n cnpg-system deployment/barman-cloud --tail=1000 > /tmp/plugin.log
```
3. **Community support**
- CloudNativePG Slack: [#cloudnativepg-users](https://cloud-native.slack.com/messages/cloudnativepg-users)
- GitHub Issues: [plugin-barman-cloud](https://github.com/cloudnative-pg/plugin-barman-cloud/issues)
4. **Include when reporting**
- CloudNativePG version
- Plugin version
- Kubernetes version
- Cloud provider and region
- Relevant configuration (⚠️ sanitize/redact sensitive information)
- Error messages and logs
- Steps to reproduce
## Known Issues and Limitations
### Current Known Issues
1. **Migration compatibility**: After migrating from in-tree backup to the
plugin, the `kubectl cnpg backup` command syntax has changed
([#353](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/353)):
```sh
# Old command (in-tree, no longer works after migration)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=barmanObjectStore
# New command (plugin-based)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin --plugin-name=barman-cloud.cloudnative-pg.io
```
### Plugin Limitations
1. **Installation method**: Currently only supports manifest and Kustomize
installation ([#351](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/351) -
Helm chart requested)
2. **Sidecar resource sharing**: The plugin sidecar container shares pod
resources with PostgreSQL
3. **Plugin restart behavior**: Restarting the sidecar container requires
restarting the entire PostgreSQL pod
## Recap of General Debugging Steps
### Check Backup Status and Identify the Target Instance
```sh
# List all backups and their status
kubectl get backups.postgresql.cnpg.io -n <namespace>
# Get detailed backup information including error messages and target instance
kubectl describe backups.postgresql.cnpg.io \
-n <namespace> <backup-name>
# Extract the target pod name from a failed backup
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}'
# Get more details including the target pod, method, phase, and error
kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='Pod: {.status.instanceID.podName}{"\n"}Method: {.status.method}{"\n"}Phase: {.status.phase}{"\n"}Error: {.status.error}{"\n"}'
# Check the cluster status for backup-related information
kubectl cnpg status <cluster-name> -n <namespace> --verbose
```
### Check Sidecar Logs on the Backup Target Pod
```sh
# Identify which pod was the backup target (from the previous step)
TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \
-n <namespace> <backup-name> \
-o jsonpath='{.status.instanceID.podName}')
echo "Backup target pod: $TARGET_POD"
# Check the sidecar logs on the specific target pod
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud --tail=100
# Follow the logs in real time
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud -f
# Check for specific errors in the target pod around the backup time
kubectl logs -n <namespace> $TARGET_POD \
-c plugin-barman-cloud --since=10m | grep -E "ERROR|FATAL|panic|failed"
# Alternative: List all cluster pods and their roles
kubectl get pods -n <namespace> -l cnpg.io/cluster=<cluster-name> \
-o custom-columns=NAME:.metadata.name,ROLE:.metadata.labels.cnpg\\.io/instanceRole,INSTANCE:.metadata.labels.cnpg\\.io/instanceName
# Check sidecar logs on ALL cluster pods (if the target is unclear)
for pod in $(kubectl get pods -n <namespace> -l cnpg.io/cluster=<cluster-name> -o name); do
echo "=== Checking $pod ==="
kubectl logs -n <namespace> $pod -c plugin-barman-cloud \
--tail=20 | grep -i error || echo "No errors found"
done
```
### Check Events for Backup-Related Issues
```sh
# Check events for the cluster
kubectl get events -n <namespace> \
--field-selector involvedObject.name=<cluster-name>
# Check events for failed backups
kubectl get events -n <namespace> \
--field-selector involvedObject.kind=Backup
# Get all recent events in the namespace
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -20
```
### Verify `ObjectStore` Configuration
```sh
# Check the ObjectStore resource
kubectl get objectstores.barmancloud.cnpg.io \
-n <namespace> <objectstore-name> -o yaml
# Verify the secret exists and has the correct keys
kubectl get secret -n <namespace> <secret-name> -o yaml
# Alternatively
kubectl get secret -n <namespace> <secret-name> -o jsonpath='{.data}' | jq 'keys'
```
### Common Error Messages and Solutions
* **"AccessDenied" or "403 Forbidden"** — Check cloud credentials and bucket permissions.
* **"NoSuchBucket"** — Verify the bucket exists and the endpoint URL is correct.
* **"Connection timeout"** — Check network connectivity and firewall rules.
* **"SSL certificate problem"** — For self-signed certificates, verify the CA bundle configuration.

16
web/versioned_docs/version-0.12.0/upgrades.mdx
View File

@ -1,16 +0,0 @@
---
sidebar_position: 25
---
# Upgrades
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
You can upgrade the plugin simply by installing the new version. Unless
explicitly stated below or in the release notes, no special steps are required.
## Upgrading to version 0.8.x from previous versions
Version **0.8.0** introduces breaking changes to resource naming.
To complete the upgrade successfully, follow the instructions in the
["Resource name migration guide"](resource-name-migration.md).

283
web/versioned_docs/version-0.12.0/usage.md
View File

@ -1,283 +0,0 @@
---
sidebar_position: 30
---
# Using the Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
After [installing the plugin](installation.mdx) in the same namespace as the
CloudNativePG operator, enabling your PostgreSQL cluster to use the Barman
Cloud Plugin involves just a few steps:
- Defining the object store containing your WAL archive and base backups, using
your preferred [provider](object_stores.md)
- Instructing the Postgres cluster to use the Barman Cloud Plugin
From that moment, you’ll be able to issue on-demand backups or define a backup
schedule, as well as rely on the object store for recovery operations.
The rest of this page details each step, using MinIO as object store provider.
## Defining the `ObjectStore`
An `ObjectStore` resource must be created for each object store used in your
PostgreSQL architecture. Here's an example configuration 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` schema follows the same format 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/current/appendixes/backup_barmanobjectstore/)
for additional details.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::
## Configuring WAL Archiving
Once the `ObjectStore` is defined, you can configure your PostgreSQL cluster
to archive WALs by referencing the store in the `.spec.plugins` section:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
instances: 3
imagePullPolicy: Always
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
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. Backups can be
created either declaratively (with YAML manifests) or imperatively (with the
`cnpg` plugin).
### Declarative approach (YAML manifest)
Create a backup resource by applying a YAML manifest:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
name: backup-example
spec:
cluster:
name: cluster-example
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
### Imperative approach (using the `cnpg` plugin)
The quickest way to trigger an on-demand backup is with the `cnpg` plugin:
```bash
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin \
--plugin-name=barman-cloud.cloudnative-pg.io
```
:::note Migration from in-tree backups
If you are migrating from the in-tree backup system, note the change in syntax:
```bash
# Old command (in-tree backup)
kubectl cnpg backup -n <namespace> <cluster-name> --method=barmanObjectStore
# New command (plugin-based backup)
kubectl cnpg backup -n <namespace> <cluster-name> \
--method=plugin \
--plugin-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
```
:::important
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
isWALArchiver: true
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
isWALArchiver: true
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
```
## Configuring the plugin instance sidecar
The Barman Cloud Plugin runs as a sidecar container next to each PostgreSQL
instance pod. It manages backup, WAL archiving, and restore processes.
Configuration comes from multiple `ObjectStore` resources:
1. The one referenced in the
`.spec.plugins` section of the `Cluster`. This is the
object store used for WAL archiving and base backups.
2. The one referenced in the external cluster
used in the `.spec.replica.source` section of the `Cluster`. This is
used by the log-shipping designated primary to get the WAL files.
3. The one referenced in the
`.spec.bootstrap.recovery.source` section of the `Cluster`. Used by
the initial recovery job to create the cluster from an existing backup.
You can fine-tune sidecar behavior in the `.spec.instanceSidecarConfiguration`
of your ObjectStore. These settings apply to all PostgreSQL instances that use
this object store. Any updates take effect at the next `Cluster` reconciliation,
and could generate a rollout of the `Cluster`.
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
# [...]
instanceSidecarConfiguration:
retentionPolicyIntervalSeconds: 1800
resources:
requests:
memory: "XXX"
cpu: "YYY"
limits:
memory: "XXX"
cpu: "YYY"
```
:::note
If more than one `ObjectStore` applies, the `instanceSidecarConfiguration` of
the one set in `.spec.plugins` has priority.
:::

15
web/versioned_docs/version-0.3.0/welcome.md
View File

@ -1,15 +0,0 @@
---
sidebar_position: 1
sidebar_label: "Welcome"
---
# Barman Cloud CNPG-I plugin
**Status:** EXPERIMENTAL
Welcome to the documentation of the [barman-cloud](https://pgbarman.org/) CNPG-I
plugin for [CloudNativePG](https://cloudnative-pg.io/).
Documentation for version **0.3.0** of the plugin is available in the
[README](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/v0.3.0/README.md)
on GitHub.

43
web/versioned_docs/version-0.4.0/compression.md
View File

@ -1,43 +0,0 @@
---
sidebar_position: 80
---
# Compression
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
By default, backups and WAL files are archived **uncompressed**. However, the
Barman Cloud Plugin supports multiple compression algorithms via
`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
for space, speed, or a balance of both.
### Supported Compression Algorithms
- `bzip2`
- `gzip`
- `lz4` (WAL only)
- `snappy`
- `xz` (WAL only)
- `zstd` (WAL only)
Compression settings for base backups and WAL archives are configured
independently. For implementation details, refer to the corresponding API
definitions:
- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
:::important
Compression impacts both performance and storage efficiency. Choose the right
algorithm based on your recovery time objectives (RTO), storage capacity, and
network throughput.
:::
## Compression Benchmark (on MinIO)
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |

177
web/versioned_docs/version-0.4.0/concepts.md
View File

@ -1,177 +0,0 @@
---
sidebar_position: 10
---
# Main Concepts
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::important
Before proceeding, make sure to review the following sections of the
CloudNativePG documentation:
- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
:::
The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
supporting continuous physical backups and WAL archiving to an **object
store**—without interrupting write operations.
It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
of a PostgreSQL cluster.
## The Object Store
At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
which acts as the interface between the PostgreSQL cluster and the target
object storage system. It allows you to configure:
- **Authentication and bucket location** via the `.spec.configuration` section
- **WAL archiving** settings—such as compression type, parallelism, and
server-side encryption—under `.spec.configuration.wal`
- **Base backup options**—with similar settings for compression, concurrency,
and encryption—under `.spec.configuration.data`
- **Retention policies** to manage the life-cycle of archived WALs and backups
via `.spec.configuration.retentionPolicy`
WAL files are archived in the `wals` directory, while base backups are stored
as **tarballs** in the `base` directory, following the
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
The plugin also offers advanced capabilities, including
[backup tagging](misc.md#backup-object-tagging) and
[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving).
:::tip
For details, refer to the
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).
:::
## Integration with a CloudNativePG Cluster
CloudNativePG can delegate continuous backup and recovery responsibilities to
the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
to be defined.
:::important
While it is technically possible to reuse the same `ObjectStore` for multiple
`Cluster` resources within the same namespace, it is strongly recommended to
dedicate one object store per PostgreSQL cluster to ensure data isolation and
operational clarity.
:::
The following example demonstrates how to configure a CloudNativePG cluster
named `cluster-example` to use a previously defined `ObjectStore` (also named
`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
WAL archiving through the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
# Other cluster settings...
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: cluster-example
```
## Backup of a Postgres Cluster
Once the object store is defined and the `Cluster` is configured to use the
Barman Cloud Plugin, **WAL archiving is activated immediately** on the
PostgreSQL primary.
Physical base backups are seamlessly managed by CloudNativePG using the
`Backup` and `ScheduledBackup` resources, respectively for
[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
and
[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
backups.
To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
configure the `pluginConfiguration` section as shown:
```yaml
[...]
spec:
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
[...]
```
With this configuration, CloudNativePG supports:
- Backups from both **primary** and **standby** instances
- Backups from **designated primaries** in a distributed topology using
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
:::tip
For details on how to back up from a standby, refer to the official documentation:
[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
:::
:::important
Both backup and WAL archiving operations are executed by sidecar containers
running in the same pod as the PostgreSQL `Cluster` primary instance—except
when backups are taken from a standby, in which case the sidecar runs alongside
the standby pod.
The sidecar containers use a [dedicated container image](images.md) that
includes only the supported version of Barman Cloud.
:::
## Recovery of a Postgres Cluster
In PostgreSQL, *recovery* refers to the process of starting a database instance
from an existing backup. The Barman Cloud Plugin integrates with CloudNativePG
to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
object store.
Recovery in this context is *not in-place*: it bootstraps a brand-new
PostgreSQL cluster from a backup and replays the necessary WAL files to reach
the desired recovery target.
To perform a recovery, define an *external cluster* that references the
appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
of the target cluster:
```yaml
[...]
spec:
[...]
bootstrap:
recovery:
source: source
externalClusters:
- name: source
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: cluster-example
serverName: cluster-example
[...]
```
The critical element here is the `externalClusters` section of the `Cluster`
resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
Cloud Plugin to access the object store for recovery.
This same mechanism can be used for a variety of scenarios enabled by the
CloudNativePG API, including:
* **Full cluster recovery** from the latest backup
* **Point-in-Time Recovery (PITR)**
* Bootstrapping **replica clusters** in a distributed topology
:::tip
For complete instructions and advanced use cases, refer to the official
[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
:::

37
web/versioned_docs/version-0.4.0/images.md
View File

@ -1,37 +0,0 @@
---
sidebar_position: 99
---
# Container Images
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin is distributed using two container images:
- One for deploying the plugin components
- One for the sidecar that runs alongside each PostgreSQL instance in a
CloudNativePG `Cluster` using the plugin
## Plugin Container Image
The plugin image contains the logic required to operate the Barman Cloud Plugin
within your Kubernetes environment with CloudNativePG. It is published on the
GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
This image is built from the
[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
in the plugin repository.
## Sidecar Container Image
The sidecar image is used within each PostgreSQL pod in the cluster. It
includes the latest supported version of Barman Cloud and is responsible for
performing WAL archiving and backups on behalf of CloudNativePG.
It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
built from the
[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
These sidecar images are designed to work seamlessly with the
[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
maintained by the CloudNativePG Community.

117
web/versioned_docs/version-0.4.0/installation.md
View File

@ -1,117 +0,0 @@
---
sidebar_position: 20
---
# Installation
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::important
1. The plugin **must** be installed in the same namespace as the CloudNativePG
operator (typically `cnpg-system`).
2. Keep in mind that the operator's **listening namespaces** may differ from its
installation namespace. Double-check this to avoid configuration issues.
:::
## Verifying the Requirements
Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
### CloudNativePG Version
Ensure you're running a version of CloudNativePG that is compatible with the
plugin. If installed in the default `cnpg-system` namespace, you can verify the
version with:
```sh
kubectl get deployment -n cnpg-system cnpg-controller-manager -o yaml \
| grep ghcr.io/cloudnative-pg/cloudnative-pg
```
Example output:
```output
image: ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
```
The version **must be 1.26 or newer**.
### cert-manager
Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
tool to confirm that `cert-manager` is installed and available:
```sh
cmctl check api
```
Example output:
```output
The cert-manager API is ready
```
Both checks are required before proceeding with the installation.
## Installing the Barman Cloud Plugin
Install the plugin using `kubectl` by applying the manifest for the latest
release:
<!-- x-release-please-start-version -->
```sh
kubectl apply -f \
https://github.com/cloudnative-pg/plugin-barman-cloud/releases/download/v0.4.0/manifest.yaml
```
<!-- x-release-please-end -->
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
```
Finally, check that the deployment is up and running:
```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 ready to use.
## Testing the latest development snapshot
You can also test the latest development snapshot of the plugin with the
following command:
```sh
kubectl apply -f \
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
```

67
web/versioned_docs/version-0.4.0/intro.md
View File

@ -1,67 +0,0 @@
---
sidebar_position: 1
sidebar_label: "Introduction"
---
# Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The **Barman Cloud Plugin** for [CloudNativePG](https://cloudnative-pg.io/)
enables online continuous physical backups of PostgreSQL clusters to object storage
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
project.
:::important
If you plan to migrate your existing CloudNativePG cluster to the new
plugin-based approach using the Barman Cloud Plugin, see
["Migrating from Built-in CloudNativePG Backup"](migration.md)
for detailed instructions.
:::
## Requirements
To use the Barman Cloud Plugin, you need:
- [CloudNativePG](https://cloudnative-pg.io) version **1.26** <!-- ADD WHEN 1.27 IS OUT "or later" -->
- [cert-manager](https://cert-manager.io/) to enable TLS communication between
the plugin and the operator
## Key Features
This plugin provides the following capabilities:
- Physical online backup of the data directory
- Physical restore of the data directory
- Write-Ahead Log (WAL) archiving
- WAL restore
- Full cluster recovery
- Point-in-Time Recovery (PITR)
- Seamless integration with replica clusters for bootstrap and WAL restore from archive
:::important
The Barman Cloud Plugin is designed to **replace the in-tree object storage support**
previously provided via the `.spec.backup.barmanObjectStore` section in the
`Cluster` resource.
Backups created using the in-tree approach are fully supported and compatible
with this plugin.
:::
## Supported Object Storage Providers
The plugin works with all storage backends supported by `barman-cloud`, including:
- **Amazon S3**
- **Google Cloud Storage**
- **Microsoft Azure Blob Storage**
In addition, the following S3-compatible and simulator solutions have been
tested and verified:
- [MinIO](https://min.io/) – An S3-compatible storage solution
- [Azurite](https://github.com/Azure/Azurite) – A simulator for Azure Blob Storage
- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage
:::tip
For more details, refer to [Object Store Providers](object_stores.md).
:::

259
web/versioned_docs/version-0.4.0/migration.md
View File

@ -1,259 +0,0 @@
---
sidebar_position: 40
---
# Migrating from Built-in CloudNativePG Backup
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting
from version 1.26** and will be removed in a future release.
If you're currently relying on the built-in Barman Cloud integration, you can
migrate seamlessly to the new **plugin-based architecture** using the Barman
Cloud Plugin, with **no downtime**. Follow these steps:
- [Install the Barman Cloud Plugin](installation.md)
- Create an `ObjectStore` resource by translating the contents of the
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
definition
- Modify the `Cluster` resource in a single atomic change to switch from
in-tree backup to the plugin
- Update any `ScheduledBackup` resources to use the plugin
- Update the `externalClusters` configuration, where applicable
:::tip
For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground),
which demonstrates a full migration.
:::
---
## Step 1: Define the `ObjectStore`
Begin by creating an `ObjectStore` resource in the same namespace as your
PostgreSQL `Cluster`.
There is a **direct mapping** between the `.spec.backup.barmanObjectStore`
section in CloudNativePG and the `.spec.configuration` field in the
`ObjectStore` CR. The conversion is mostly mechanical, with one key difference:
:::warning
In the plugin architecture, retention policies are defined as part of the `ObjectStore`.
In contrast, the in-tree implementation defined them at the `Cluster` level.
:::
If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration
to `.spec.retentionPolicy` in the `ObjectStore`.
---
### Example
Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration
taken from the CloudNativePG Playground project:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-eu
spec:
# [...]
backup:
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
This configuration translates to the following `ObjectStore` resource for the
plugin:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
As you can see, the contents of `barmanObjectStore` have been copied directly
under the `configuration` field of the `ObjectStore` resource, using the same
secret references.
## Step 2: Update the `Cluster` for plugin WAL archiving
Once the `ObjectStore` resource is in place, update the `Cluster` resource as
follows in a single atomic change:
- Remove the `.spec.backup.barmanObjectStore` section
- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the
`ObjectStore`)
- Remove the entire `spec.backup` section if it is now empty
- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in
[Configuring WAL archiving](usage.md#configuring-wal-archiving)
This will trigger a rolling update of the `Cluster`, switching continuous
backup from the in-tree implementation to the plugin-based approach.
### Example
The updated `pg-eu` cluster will have this configuration instead of the
previous `backup` section:
```yaml
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: minio-eu
```
---
## Step 3: Update the `ScheduledBackup`
After switching the `Cluster` to use the plugin, update your `ScheduledBackup`
resources to match.
Set the backup `method` to `plugin` and reference the plugin name via
`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup).
### Example
Original in-tree `ScheduledBackup`:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
```
Updated version using the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
---
## Step 4: Update the `externalClusters` configuration
If your `Cluster` relies on one or more external clusters that use the in-tree
Barman Cloud integration, you need to update those configurations to use the
plugin-based architecture.
When a replica cluster fetches WAL files or base backups from an external
source that used the built-in backup method, follow these steps:
1. Create a corresponding `ObjectStore` resource for the external cluster, as
shown in [Step 1](#step-1-define-the-objectstore)
2. Update the `externalClusters` section of your replica cluster to use the
plugin instead of the in-tree `barmanObjectStore` field
### Example
Consider the original configuration using in-tree Barman Cloud:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
serverName: pg-eu
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Create the `ObjectStore` resource for the external cluster:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Update the external cluster configuration to use the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: minio-eu
serverName: pg-eu
```

76
web/versioned_docs/version-0.4.0/misc.md
View File

@ -1,76 +0,0 @@
---
sidebar_position: 90
---
# Miscellaneous
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
## Backup Object Tagging
You can attach key-value metadata tags to backup artifacts—such as base
backups, WAL files, and history files—via the `.spec.configuration` section of
the `ObjectStore` resource.
- `tags`: applied to base backups and WAL files
- `historyTags`: applied to history files only
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
[...]
tags:
backupRetentionPolicy: "expire"
historyTags:
backupRetentionPolicy: "keep"
[...]
```
## Extra Options for Backup and WAL Archiving
You can pass additional command-line arguments to `barman-cloud-backup` and
`barman-cloud-wal-archive` using the `additionalCommandArgs` field in the
`ObjectStore` configuration.
- `.spec.configuration.data.additionalCommandArgs`: for `barman-cloud-backup`
- `.spec.configuration.wal.additionalCommandArgs`: for `barman-cloud-wal-archive`
Each field accepts a list of string arguments. If an argument is already
configured elsewhere in the plugin, the duplicate will be ignored.
### Example: Extra Backup Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
data:
additionalCommandArgs:
- "--min-chunk-size=5MB"
- "--read-timeout=60"
```
### Example: Extra WAL Archive Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
wal:
additionalCommandArgs:
- "--max-concurrency=1"
- "--read-timeout=60"
```
For a complete list of supported options, refer to the
[official Barman Cloud documentation](https://docs.pgbarman.org/release/latest/).

465
web/versioned_docs/version-0.4.0/object_stores.md
View File

@ -1,465 +0,0 @@
---
sidebar_position: 50
---
# Object Store Providers
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin enables the storage of PostgreSQL cluster backup files
in any object storage service supported by the
[Barman Cloud infrastructure](https://docs.pgbarman.org/release/latest/).
Currently, Barman Cloud supports the following providers:
- [Amazon S3](#aws-s3)
- [Microsoft Azure Blob Storage](#azure-blob-storage)
- [Google Cloud Storage](#google-cloud-storage)
You may also use any S3- or Azure-compatible implementation of the above
services.
To configure object storage with Barman Cloud, you must define an
[`ObjectStore` object](plugin-barman-cloud.v1.md#objectstore), which
establishes the connection between your PostgreSQL cluster and the object
storage backend.
Configuration details — particularly around authentication — will vary depending on
the specific object storage provider you are using.
The following sections detail the setup for each.
---
## AWS S3
[AWS Simple Storage Service (S3)](https://aws.amazon.com/s3/) is one of the
most widely adopted object storage solutions.
The Barman Cloud plugin for CloudNativePG integrates with S3 through two
primary authentication mechanisms:
- [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) —
recommended for clusters running on EKS
- Access keys — using `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY` credentials
### Access Keys
To authenticate using access keys, you’ll need:
- `ACCESS_KEY_ID`: the public key used to authenticate to S3
- `ACCESS_SECRET_KEY`: the corresponding secret key
- `ACCESS_SESSION_TOKEN`: (optional) a temporary session token, if required
These credentials must be stored securely in a Kubernetes secret:
```sh
kubectl create secret generic aws-creds \
--from-literal=ACCESS_KEY_ID=<access key here> \
--from-literal=ACCESS_SECRET_KEY=<secret key here>
# --from-literal=ACCESS_SESSION_TOKEN=<session token here> # if required
```
The credentials will be encrypted at rest if your Kubernetes environment
supports it.
You can then reference the secret in your `ObjectStore` definition:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: aws-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
s3Credentials:
accessKeyId:
name: aws-creds
key: ACCESS_KEY_ID
secretAccessKey:
name: aws-creds
key: ACCESS_SECRET_KEY
[...]
```
### IAM Role for Service Account (IRSA)
To use IRSA with EKS, configure the service account of the PostgreSQL cluster
with the appropriate annotation:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
[...]
spec:
serviceAccountTemplate:
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:[...]
[...]
```
### S3 Lifecycle Policy
Barman Cloud uploads backup files to S3 but does not modify them afterward.
To enhance data durability and protect against accidental or malicious loss,
it's recommended to implement the following best practices:
- Enable object versioning
- Enable object locking to prevent objects from being deleted or overwritten
for a defined period or indefinitely (this provides an additional layer of
protection against accidental deletion and ransomware attacks)
- Set lifecycle rules to expire current versions a few days after your Barman
retention window
- Expire non-current versions after a longer period
These strategies help you safeguard backups without requiring broad delete
permissions, ensuring both security and compliance with minimal operational
overhead.
### S3-Compatible Storage Providers
You can use S3-compatible services like **MinIO**, **Linode (Akamai) Object Storage**,
or **DigitalOcean Spaces** by specifying a custom `endpointURL`.
Example with Linode (Akamai) Object Storage (`us-east1`):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/"
endpointURL: "https://us-east1.linodeobjects.com"
s3Credentials:
[...]
[...]
```
Example with DigitalOcean Spaces (SFO3, path-style):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: digitalocean-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
endpointURL: "https://sfo3.digitaloceanspaces.com"
s3Credentials:
[...]
[...]
```
### Using Object Storage with a Private CA
For object storage services (e.g., MinIO) that use HTTPS with certificates
signed by a private CA, set the `endpointCA` field in the `ObjectStore`
definition. Unless you already have it, create a Kubernetes `Secret` with the
CA bundle:
```sh
kubectl create secret generic my-ca-secret --from-file=ca.crt
```
Then reference it:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
endpointURL: <myEndpointURL>
endpointCA:
name: my-ca-secret
key: ca.crt
[...]
```
<!-- TODO: does this also apply to the plugin? -->
:::note
If you want `ConfigMaps` and `Secrets` to be **automatically** reloaded by
instances, you can add a label with the key `cnpg.io/reload` to the
`Secrets`/`ConfigMaps`. Otherwise, you will have to reload the instances using the
`kubectl cnpg reload` subcommand.
:::
---
## Azure Blob Storage
[Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
is Microsoft’s cloud-based object storage solution.
Barman Cloud supports the following authentication methods:
- [Connection String](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string)
- Storage Account Name + [Access Key](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
- Storage Account Name + [SAS Token](https://learn.microsoft.com/en-us/azure/storage/blobs/sas-service-create)
- [Azure AD Workload Identity](https://azure.github.io/azure-workload-identity/docs/introduction.html)
### Azure AD Workload Identity
This method avoids storing credentials in Kubernetes via the
`.spec.configuration.inheritFromAzureAD` option:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
inheritFromAzureAD: true
[...]
```
### Access Key, SAS Token, or Connection String
Store credentials in a Kubernetes secret:
```sh
kubectl create secret generic azure-creds \
--from-literal=AZURE_STORAGE_ACCOUNT=<storage account name> \
--from-literal=AZURE_STORAGE_KEY=<storage account key> \
--from-literal=AZURE_STORAGE_SAS_TOKEN=<SAS token> \
--from-literal=AZURE_STORAGE_CONNECTION_STRING=<connection string>
```
Then reference the required keys in your `ObjectStore`:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
connectionString:
name: azure-creds
key: AZURE_CONNECTION_STRING
storageAccount:
name: azure-creds
key: AZURE_STORAGE_ACCOUNT
storageKey:
name: azure-creds
key: AZURE_STORAGE_KEY
storageSasToken:
name: azure-creds
key: AZURE_STORAGE_SAS_TOKEN
[...]
```
For Azure Blob, the destination path format is:
```
<http|https>://<account-name>.<service-name>.core.windows.net/<container>/<blob>
```
### Azure-Compatible Providers
If you're using a different implementation (e.g., Azurite or emulator):
```
<http|https>://<local-machine-address>:<port>/<account-name>/<container>/<blob>
```
---
## Google Cloud Storage
[Google Cloud Storage](https://cloud.google.com/storage/) is supported with two
authentication modes:
- **GKE Workload Identity** (recommended inside Google Kubernetes Engine)
- **Service Account JSON key** via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
### GKE Workload Identity
Use the [Workload Identity authentication](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
when running in GKE:
1. Set `googleCredentials.gkeEnvironment` to `true` in the `ObjectStore`
resource
2. Annotate the `serviceAccountTemplate` in the `Cluster` resource with the GCP
service account
For example, in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
gkeEnvironment: true
```
And in the `Cluster` resource:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
serviceAccountTemplate:
metadata:
annotations:
iam.gke.io/gcp-service-account: [...].iam.gserviceaccount.com
```
### Service Account JSON Key
Follow Google’s [authentication setup](https://cloud.google.com/docs/authentication/getting-started),
then:
```sh
kubectl create secret generic backup-creds --from-file=gcsCredentials=gcs_credentials_file.json
```
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
applicationCredentials:
name: backup-creds
key: gcsCredentials
[...]
```
:::important
This authentication method generates a JSON file within the container
with all the credentials required to access your Google Cloud Storage
bucket. As a result, if someone gains access to the `Pod`, they will also have
write permissions to the bucket.
:::
---
## MinIO Gateway
MinIO Gateway can proxy requests to cloud object storage providers like S3 or GCS.
For more information, refer to [MinIO official documentation](https://docs.min.io/).
### Setup
Create MinIO access credentials:
```sh
kubectl create secret generic minio-creds \
--from-literal=MINIO_ACCESS_KEY=<minio access key> \
--from-literal=MINIO_SECRET_KEY=<minio secret key>
```
:::note
Cloud Object Storage credentials will be used only by MinIO Gateway in this
case.
:::
Expose MinIO Gateway via `ClusterIP`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: minio-gateway-service
spec:
type: ClusterIP
ports:
- port: 9000
targetPort: 9000
protocol: TCP
selector:
app: minio
```
Here follows an excerpt of an example of deployment relaying to S3:
```yaml
apiVersion: apps/v1
kind: Deployment
[...]
spec:
containers:
- name: minio
image: minio/minio:RELEASE.2020-06-03T22-13-49Z
args: ["gateway", "s3"]
ports:
- containerPort: 9000
env:
- name: MINIO_ACCESS_KEY
valueFrom:
secretKeyRef:
name: minio-creds
key: MINIO_ACCESS_KEY
- name: MINIO_SECRET_KEY
valueFrom:
secretKeyRef:
name: minio-creds
key: MINIO_SECRET_KEY
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-creds
key: ACCESS_KEY_ID
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-creds
key: ACCESS_SECRET_KEY
# Uncomment the below section if session token is required
# - name: AWS_SESSION_TOKEN
# valueFrom:
# secretKeyRef:
# name: aws-creds
# key: ACCESS_SESSION_TOKEN
```
Proceed by configuring MinIO Gateway service as the `endpointURL` in the
`ObjectStore` definition, then choose a bucket name to replace `BUCKET_NAME`:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
destinationPath: s3://BUCKET_NAME/
endpointURL: http://minio-gateway-service:9000
s3Credentials:
accessKeyId:
name: minio-creds
key: MINIO_ACCESS_KEY
secretAccessKey:
name: minio-creds
key: MINIO_SECRET_KEY
[...]
```
:::important
Verify on `s3://BUCKET_NAME/` the presence of archived WAL files before
proceeding with a backup.
:::
---

19
web/versioned_docs/version-0.4.0/parameters.md
View File

@ -1,19 +0,0 @@
---
sidebar_position: 100
---
# Parameters
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The following parameters are available for the Barman Cloud Plugin:
- `barmanObjectName`: references the `ObjectStore` resource to be used by the
plugin.
- `serverName`: Specifies the server name in the object store.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::

105
web/versioned_docs/version-0.4.0/plugin-barman-cloud.v1.md
View File

@ -1,105 +0,0 @@
# API Reference
## Packages
- [barmancloud.cnpg.io/v1](#barmancloudcnpgiov1)
## barmancloud.cnpg.io/v1
Package v1 contains API Schema definitions for the barmancloud v1 API group
### Resource Types
- [ObjectStore](#objectstore)
#### InstanceSidecarConfiguration
InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.
_Appears in:_
- [ObjectStoreSpec](#objectstorespec)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#envvar-v1-core) array_ | The environment to be explicitly passed to the sidecar | | | |
| `retentionPolicyIntervalSeconds` _integer_ | The retentionCheckInterval defines the frequency at which the<br />system checks and enforces retention policies. | | 1800 | |
| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#resourcerequirements-v1-core)_ | Resources define cpu/memory requests and limits for the sidecar that runs in the instance pods. | | | |
#### ObjectStore
ObjectStore is the Schema for the objectstores API.
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `apiVersion` _string_ | `barmancloud.cnpg.io/v1` | True | | |
| `kind` _string_ | `ObjectStore` | True | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | True | | |
| `spec` _[ObjectStoreSpec](#objectstorespec)_ | Specification of the desired behavior of the ObjectStore.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | True | | |
| `status` _[ObjectStoreStatus](#objectstorestatus)_ | Most recently observed status of the ObjectStore. This data may not be up to<br />date. Populated by the system. Read-only.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | | | |
#### ObjectStoreSpec
ObjectStoreSpec defines the desired state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `configuration` _[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)_ | The configuration for the barman-cloud tool suite | True | | |
| `retentionPolicy` _string_ | RetentionPolicy is the retention policy to be used for backups<br />and WALs (i.e. '60d'). The retention policy is expressed in the form<br />of `XXu` where `XX` is a positive integer and `u` is in `[dwm]` -<br />days, weeks, months. | | | Pattern: `^[1-9][0-9]*[dwm]$` <br /> |
| `instanceSidecarConfiguration` _[InstanceSidecarConfiguration](#instancesidecarconfiguration)_ | The configuration for the sidecar that runs in the instance pods | | | |
#### ObjectStoreStatus
ObjectStoreStatus defines the observed state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `serverRecoveryWindow` _object (keys:string, values:[RecoveryWindow](#recoverywindow))_ | ServerRecoveryWindow maps each server to its recovery window | True | | |
#### RecoveryWindow
RecoveryWindow represents the time span between the first
recoverability point and the last successful backup of a PostgreSQL
server, defining the period during which data can be restored.
_Appears in:_
- [ObjectStoreStatus](#objectstorestatus)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `firstRecoverabilityPoint` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The first recoverability point in a PostgreSQL server refers to<br />the earliest point in time to which the database can be<br />restored. | True | | |
| `lastSuccussfulBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last successful backup time | True | | |

38
web/versioned_docs/version-0.4.0/retention.md
View File

@ -1,38 +0,0 @@
---
sidebar_position: 60
---
# Retention Policies
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin supports **automated cleanup of obsolete backups** via
retention policies, configured in the `.spec.retentionPolicy` field of the
`ObjectStore` resource.
:::note
This feature uses the `barman-cloud-backup-delete` command with the
`--retention-policy "RECOVERY WINDOW OF {{ value }} {{ unit }}"` syntax.
:::
#### Example: 30-Day Retention Policy
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
[...]
retentionPolicy: "30d"
````
:::note
A **recovery window retention policy** ensures the cluster can be restored to
any point in time between the calculated *Point of Recoverability* (PoR) and
the latest WAL archive. The PoR is defined as `current time - recovery window`.
The **first valid backup** is the most recent backup completed before the PoR.
Backups older than that are marked as *obsolete* and deleted after the next
backup completes.
:::

258
web/versioned_docs/version-0.4.0/usage.md
View File

@ -1,258 +0,0 @@
---
sidebar_position: 30
---
# Using the Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
After [installing the plugin](installation.md) in the same namespace as the
CloudNativePG operator, enabling your PostgreSQL cluster to use the Barman
Cloud Plugin involves just a few steps:
- Defining the object store containing your WAL archive and base backups, using
your preferred [provider](object_stores.md)
- Instructing the Postgres cluster to use the Barman Cloud Plugin
From that moment, you’ll be able to issue on-demand backups or define a backup
schedule, as well as rely on the object store for recovery operations.
The rest of this page details each step, using MinIO as object store provider.
## Defining the `ObjectStore`
An `ObjectStore` resource must be created for each object store used in your
PostgreSQL architecture. Here's an example configuration 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` schema follows the same format 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/current/appendixes/backup_barmanobjectstore/)
for additional details.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::
## Configuring WAL Archiving
Once the `ObjectStore` is defined, you can configure your PostgreSQL cluster
to archive WALs by referencing the store in the `.spec.plugins` section:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
instances: 3
imagePullPolicy: Always
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
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 issue an
on-demand backup, use the following configuration with the plugin method:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
name: backup-example
spec:
cluster:
name: cluster-example
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
:::note
You can apply the same concept to the `ScheduledBackup` resource.
:::
## 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
```
:::important
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
isWALArchiver: true
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
isWALArchiver: true
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
```
## Configuring the plugin instance sidecar
The Barman Cloud Plugin runs as a sidecar container next to each PostgreSQL
instance pod. It manages backup, WAL archiving, and restore processes.
Configuration comes from multiple `ObjectStore` resources:
1. The one referenced in the
`.spec.plugins` section of the `Cluster`. This is the
object store used for WAL archiving and base backups.
2. The one referenced in the external cluster
used in the `.spec.replica.source` section of the `Cluster`. This is
used by the log-shipping designated primary to get the WAL files.
3. The one referenced in the
`.spec.bootstrap.recovery.source` section of the `Cluster`. Used by
the initial recovery job to create the cluster from an existing backup.
You can fine-tune sidecar behavior in the `.spec.instanceSidecarConfiguration`
of your ObjectStore. These settings apply to all PostgreSQL instances that use
this object store. Any updates take effect at the next `Cluster` reconciliation,
and could generate a rollout of the `Cluster`.
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
# [...]
instanceSidecarConfiguration:
retentionPolicyIntervalSeconds: 1800
resources:
requests:
memory: "XXX"
cpu: "YYY"
limits:
memory: "XXX"
cpu: "YYY"
```
:::note
If more than one `ObjectStore` applies, the `instanceSidecarConfiguration` of
the one set in `.spec.plugins` has priority.
:::

43
web/versioned_docs/version-0.4.1/compression.md
View File

@ -1,43 +0,0 @@
---
sidebar_position: 80
---
# Compression
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
By default, backups and WAL files are archived **uncompressed**. However, the
Barman Cloud Plugin supports multiple compression algorithms via
`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
for space, speed, or a balance of both.
### Supported Compression Algorithms
- `bzip2`
- `gzip`
- `lz4` (WAL only)
- `snappy`
- `xz` (WAL only)
- `zstd` (WAL only)
Compression settings for base backups and WAL archives are configured
independently. For implementation details, refer to the corresponding API
definitions:
- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
:::important
Compression impacts both performance and storage efficiency. Choose the right
algorithm based on your recovery time objectives (RTO), storage capacity, and
network throughput.
:::
## Compression Benchmark (on MinIO)
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |

177
web/versioned_docs/version-0.4.1/concepts.md
View File

@ -1,177 +0,0 @@
---
sidebar_position: 10
---
# Main Concepts
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::important
Before proceeding, make sure to review the following sections of the
CloudNativePG documentation:
- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
:::
The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
supporting continuous physical backups and WAL archiving to an **object
store**—without interrupting write operations.
It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
of a PostgreSQL cluster.
## The Object Store
At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
which acts as the interface between the PostgreSQL cluster and the target
object storage system. It allows you to configure:
- **Authentication and bucket location** via the `.spec.configuration` section
- **WAL archiving** settings—such as compression type, parallelism, and
server-side encryption—under `.spec.configuration.wal`
- **Base backup options**—with similar settings for compression, concurrency,
and encryption—under `.spec.configuration.data`
- **Retention policies** to manage the life-cycle of archived WALs and backups
via `.spec.configuration.retentionPolicy`
WAL files are archived in the `wals` directory, while base backups are stored
as **tarballs** in the `base` directory, following the
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
The plugin also offers advanced capabilities, including
[backup tagging](misc.md#backup-object-tagging) and
[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving).
:::tip
For details, refer to the
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).
:::
## Integration with a CloudNativePG Cluster
CloudNativePG can delegate continuous backup and recovery responsibilities to
the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
to be defined.
:::important
While it is technically possible to reuse the same `ObjectStore` for multiple
`Cluster` resources within the same namespace, it is strongly recommended to
dedicate one object store per PostgreSQL cluster to ensure data isolation and
operational clarity.
:::
The following example demonstrates how to configure a CloudNativePG cluster
named `cluster-example` to use a previously defined `ObjectStore` (also named
`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
WAL archiving through the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
# Other cluster settings...
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: cluster-example
```
## Backup of a Postgres Cluster
Once the object store is defined and the `Cluster` is configured to use the
Barman Cloud Plugin, **WAL archiving is activated immediately** on the
PostgreSQL primary.
Physical base backups are seamlessly managed by CloudNativePG using the
`Backup` and `ScheduledBackup` resources, respectively for
[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
and
[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
backups.
To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
configure the `pluginConfiguration` section as shown:
```yaml
[...]
spec:
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
[...]
```
With this configuration, CloudNativePG supports:
- Backups from both **primary** and **standby** instances
- Backups from **designated primaries** in a distributed topology using
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
:::tip
For details on how to back up from a standby, refer to the official documentation:
[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
:::
:::important
Both backup and WAL archiving operations are executed by sidecar containers
running in the same pod as the PostgreSQL `Cluster` primary instance—except
when backups are taken from a standby, in which case the sidecar runs alongside
the standby pod.
The sidecar containers use a [dedicated container image](images.md) that
includes only the supported version of Barman Cloud.
:::
## Recovery of a Postgres Cluster
In PostgreSQL, *recovery* refers to the process of starting a database instance
from an existing backup. The Barman Cloud Plugin integrates with CloudNativePG
to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
object store.
Recovery in this context is *not in-place*: it bootstraps a brand-new
PostgreSQL cluster from a backup and replays the necessary WAL files to reach
the desired recovery target.
To perform a recovery, define an *external cluster* that references the
appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
of the target cluster:
```yaml
[...]
spec:
[...]
bootstrap:
recovery:
source: source
externalClusters:
- name: source
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: cluster-example
serverName: cluster-example
[...]
```
The critical element here is the `externalClusters` section of the `Cluster`
resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
Cloud Plugin to access the object store for recovery.
This same mechanism can be used for a variety of scenarios enabled by the
CloudNativePG API, including:
* **Full cluster recovery** from the latest backup
* **Point-in-Time Recovery (PITR)**
* Bootstrapping **replica clusters** in a distributed topology
:::tip
For complete instructions and advanced use cases, refer to the official
[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
:::

37
web/versioned_docs/version-0.4.1/images.md
View File

@ -1,37 +0,0 @@
---
sidebar_position: 99
---
# Container Images
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin is distributed using two container images:
- One for deploying the plugin components
- One for the sidecar that runs alongside each PostgreSQL instance in a
CloudNativePG `Cluster` using the plugin
## Plugin Container Image
The plugin image contains the logic required to operate the Barman Cloud Plugin
within your Kubernetes environment with CloudNativePG. It is published on the
GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
This image is built from the
[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
in the plugin repository.
## Sidecar Container Image
The sidecar image is used within each PostgreSQL pod in the cluster. It
includes the latest supported version of Barman Cloud and is responsible for
performing WAL archiving and backups on behalf of CloudNativePG.
It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
built from the
[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
These sidecar images are designed to work seamlessly with the
[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
maintained by the CloudNativePG Community.

109
web/versioned_docs/version-0.4.1/installation.mdx
View File

@ -1,109 +0,0 @@
---
sidebar_position: 20
---
# Installation
:::important
1. The plugin **must** be installed in the same namespace as the CloudNativePG
operator (typically `cnpg-system`).
2. Keep in mind that the operator's **listening namespaces** may differ from its
installation namespace. Double-check this to avoid configuration issues.
:::
## Verifying the Requirements
Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
### CloudNativePG Version
Ensure you're running a version of CloudNativePG that is compatible with the
plugin. If installed in the default `cnpg-system` namespace, you can verify the
version with:
```sh
kubectl get deployment -n cnpg-system cnpg-controller-manager -o yaml \
| grep ghcr.io/cloudnative-pg/cloudnative-pg
```
Example output:
```output
image: ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
```
The version **must be 1.26 or newer**.
### cert-manager
Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
tool to confirm that `cert-manager` is installed and available:
```sh
cmctl check api
```
Example output:
```output
The cert-manager API is ready
```
Both checks are required before proceeding with the installation.
## Installing the Barman Cloud Plugin
import { InstallationSnippet } from '@site/src/components/Installation';
Install the plugin using `kubectl` by applying the manifest for the latest
release:
<InstallationSnippet />
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
```
Finally, check that the deployment is up and running:
```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 ready to use.
## Testing the latest development snapshot
You can also test the latest development snapshot of the plugin with the
following command:
```sh
kubectl apply -f \
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
```

67
web/versioned_docs/version-0.4.1/intro.md
View File

@ -1,67 +0,0 @@
---
sidebar_position: 1
sidebar_label: "Introduction"
---
# Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The **Barman Cloud Plugin** for [CloudNativePG](https://cloudnative-pg.io/)
enables online continuous physical backups of PostgreSQL clusters to object storage
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
project.
:::important
If you plan to migrate your existing CloudNativePG cluster to the new
plugin-based approach using the Barman Cloud Plugin, see
["Migrating from Built-in CloudNativePG Backup"](migration.md)
for detailed instructions.
:::
## Requirements
To use the Barman Cloud Plugin, you need:
- [CloudNativePG](https://cloudnative-pg.io) version **1.26** <!-- ADD WHEN 1.27 IS OUT "or later" -->
- [cert-manager](https://cert-manager.io/) to enable TLS communication between
the plugin and the operator
## Key Features
This plugin provides the following capabilities:
- Physical online backup of the data directory
- Physical restore of the data directory
- Write-Ahead Log (WAL) archiving
- WAL restore
- Full cluster recovery
- Point-in-Time Recovery (PITR)
- Seamless integration with replica clusters for bootstrap and WAL restore from archive
:::important
The Barman Cloud Plugin is designed to **replace the in-tree object storage support**
previously provided via the `.spec.backup.barmanObjectStore` section in the
`Cluster` resource.
Backups created using the in-tree approach are fully supported and compatible
with this plugin.
:::
## Supported Object Storage Providers
The plugin works with all storage backends supported by `barman-cloud`, including:
- **Amazon S3**
- **Google Cloud Storage**
- **Microsoft Azure Blob Storage**
In addition, the following S3-compatible and simulator solutions have been
tested and verified:
- [MinIO](https://min.io/) – An S3-compatible storage solution
- [Azurite](https://github.com/Azure/Azurite) – A simulator for Azure Blob Storage
- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage
:::tip
For more details, refer to [Object Store Providers](object_stores.md).
:::

259
web/versioned_docs/version-0.4.1/migration.md
View File

@ -1,259 +0,0 @@
---
sidebar_position: 40
---
# Migrating from Built-in CloudNativePG Backup
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting
from version 1.26** and will be removed in a future release.
If you're currently relying on the built-in Barman Cloud integration, you can
migrate seamlessly to the new **plugin-based architecture** using the Barman
Cloud Plugin, without data loss. Follow these steps:
- [Install the Barman Cloud Plugin](installation.mdx)
- Create an `ObjectStore` resource by translating the contents of the
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
definition
- Modify the `Cluster` resource in a single atomic change to switch from
in-tree backup to the plugin
- Update any `ScheduledBackup` resources to use the plugin
- Update the `externalClusters` configuration, where applicable
:::tip
For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground),
which demonstrates a full migration.
:::
---
## Step 1: Define the `ObjectStore`
Begin by creating an `ObjectStore` resource in the same namespace as your
PostgreSQL `Cluster`.
There is a **direct mapping** between the `.spec.backup.barmanObjectStore`
section in CloudNativePG and the `.spec.configuration` field in the
`ObjectStore` CR. The conversion is mostly mechanical, with one key difference:
:::warning
In the plugin architecture, retention policies are defined as part of the `ObjectStore`.
In contrast, the in-tree implementation defined them at the `Cluster` level.
:::
If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration
to `.spec.retentionPolicy` in the `ObjectStore`.
---
### Example
Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration
taken from the CloudNativePG Playground project:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-eu
spec:
# [...]
backup:
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
This configuration translates to the following `ObjectStore` resource for the
plugin:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
As you can see, the contents of `barmanObjectStore` have been copied directly
under the `configuration` field of the `ObjectStore` resource, using the same
secret references.
## Step 2: Update the `Cluster` for plugin WAL archiving
Once the `ObjectStore` resource is in place, update the `Cluster` resource as
follows in a single atomic change:
- Remove the `.spec.backup.barmanObjectStore` section
- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the
`ObjectStore`)
- Remove the entire `spec.backup` section if it is now empty
- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in
[Configuring WAL archiving](usage.md#configuring-wal-archiving)
This will trigger a rolling update of the `Cluster`, switching continuous
backup from the in-tree implementation to the plugin-based approach.
### Example
The updated `pg-eu` cluster will have this configuration instead of the
previous `backup` section:
```yaml
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: minio-eu
```
---
## Step 3: Update the `ScheduledBackup`
After switching the `Cluster` to use the plugin, update your `ScheduledBackup`
resources to match.
Set the backup `method` to `plugin` and reference the plugin name via
`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup).
### Example
Original in-tree `ScheduledBackup`:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
```
Updated version using the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
---
## Step 4: Update the `externalClusters` configuration
If your `Cluster` relies on one or more external clusters that use the in-tree
Barman Cloud integration, you need to update those configurations to use the
plugin-based architecture.
When a replica cluster fetches WAL files or base backups from an external
source that used the built-in backup method, follow these steps:
1. Create a corresponding `ObjectStore` resource for the external cluster, as
shown in [Step 1](#step-1-define-the-objectstore)
2. Update the `externalClusters` section of your replica cluster to use the
plugin instead of the in-tree `barmanObjectStore` field
### Example
Consider the original configuration using in-tree Barman Cloud:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
serverName: pg-eu
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Create the `ObjectStore` resource for the external cluster:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Update the external cluster configuration to use the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: minio-eu
serverName: pg-eu
```

76
web/versioned_docs/version-0.4.1/misc.md
View File

@ -1,76 +0,0 @@
---
sidebar_position: 90
---
# Miscellaneous
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
## Backup Object Tagging
You can attach key-value metadata tags to backup artifacts—such as base
backups, WAL files, and history files—via the `.spec.configuration` section of
the `ObjectStore` resource.
- `tags`: applied to base backups and WAL files
- `historyTags`: applied to history files only
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
[...]
tags:
backupRetentionPolicy: "expire"
historyTags:
backupRetentionPolicy: "keep"
[...]
```
## Extra Options for Backup and WAL Archiving
You can pass additional command-line arguments to `barman-cloud-backup` and
`barman-cloud-wal-archive` using the `additionalCommandArgs` field in the
`ObjectStore` configuration.
- `.spec.configuration.data.additionalCommandArgs`: for `barman-cloud-backup`
- `.spec.configuration.wal.additionalCommandArgs`: for `barman-cloud-wal-archive`
Each field accepts a list of string arguments. If an argument is already
configured elsewhere in the plugin, the duplicate will be ignored.
### Example: Extra Backup Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
data:
additionalCommandArgs:
- "--min-chunk-size=5MB"
- "--read-timeout=60"
```
### Example: Extra WAL Archive Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
wal:
additionalCommandArgs:
- "--max-concurrency=1"
- "--read-timeout=60"
```
For a complete list of supported options, refer to the
[official Barman Cloud documentation](https://docs.pgbarman.org/release/latest/).

465
web/versioned_docs/version-0.4.1/object_stores.md
View File

@ -1,465 +0,0 @@
---
sidebar_position: 50
---
# Object Store Providers
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin enables the storage of PostgreSQL cluster backup files
in any object storage service supported by the
[Barman Cloud infrastructure](https://docs.pgbarman.org/release/latest/).
Currently, Barman Cloud supports the following providers:
- [Amazon S3](#aws-s3)
- [Microsoft Azure Blob Storage](#azure-blob-storage)
- [Google Cloud Storage](#google-cloud-storage)
You may also use any S3- or Azure-compatible implementation of the above
services.
To configure object storage with Barman Cloud, you must define an
[`ObjectStore` object](plugin-barman-cloud.v1.md#objectstore), which
establishes the connection between your PostgreSQL cluster and the object
storage backend.
Configuration details — particularly around authentication — will vary depending on
the specific object storage provider you are using.
The following sections detail the setup for each.
---
## AWS S3
[AWS Simple Storage Service (S3)](https://aws.amazon.com/s3/) is one of the
most widely adopted object storage solutions.
The Barman Cloud plugin for CloudNativePG integrates with S3 through two
primary authentication mechanisms:
- [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) —
recommended for clusters running on EKS
- Access keys — using `ACCESS_KEY_ID` and `ACCESS_SECRET_KEY` credentials
### Access Keys
To authenticate using access keys, you’ll need:
- `ACCESS_KEY_ID`: the public key used to authenticate to S3
- `ACCESS_SECRET_KEY`: the corresponding secret key
- `ACCESS_SESSION_TOKEN`: (optional) a temporary session token, if required
These credentials must be stored securely in a Kubernetes secret:
```sh
kubectl create secret generic aws-creds \
--from-literal=ACCESS_KEY_ID=<access key here> \
--from-literal=ACCESS_SECRET_KEY=<secret key here>
# --from-literal=ACCESS_SESSION_TOKEN=<session token here> # if required
```
The credentials will be encrypted at rest if your Kubernetes environment
supports it.
You can then reference the secret in your `ObjectStore` definition:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: aws-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
s3Credentials:
accessKeyId:
name: aws-creds
key: ACCESS_KEY_ID
secretAccessKey:
name: aws-creds
key: ACCESS_SECRET_KEY
[...]
```
### IAM Role for Service Account (IRSA)
To use IRSA with EKS, configure the service account of the PostgreSQL cluster
with the appropriate annotation:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
[...]
spec:
serviceAccountTemplate:
metadata:
annotations:
eks.amazonaws.com/role-arn: arn:[...]
[...]
```
### S3 Lifecycle Policy
Barman Cloud uploads backup files to S3 but does not modify them afterward.
To enhance data durability and protect against accidental or malicious loss,
it's recommended to implement the following best practices:
- Enable object versioning
- Enable object locking to prevent objects from being deleted or overwritten
for a defined period or indefinitely (this provides an additional layer of
protection against accidental deletion and ransomware attacks)
- Set lifecycle rules to expire current versions a few days after your Barman
retention window
- Expire non-current versions after a longer period
These strategies help you safeguard backups without requiring broad delete
permissions, ensuring both security and compliance with minimal operational
overhead.
### S3-Compatible Storage Providers
You can use S3-compatible services like **MinIO**, **Linode (Akamai) Object Storage**,
or **DigitalOcean Spaces** by specifying a custom `endpointURL`.
Example with Linode (Akamai) Object Storage (`us-east1`):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: linode-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/"
endpointURL: "https://us-east1.linodeobjects.com"
s3Credentials:
[...]
[...]
```
Example with DigitalOcean Spaces (SFO3, path-style):
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: digitalocean-store
spec:
configuration:
destinationPath: "s3://BUCKET_NAME/path/to/folder"
endpointURL: "https://sfo3.digitaloceanspaces.com"
s3Credentials:
[...]
[...]
```
### Using Object Storage with a Private CA
For object storage services (e.g., MinIO) that use HTTPS with certificates
signed by a private CA, set the `endpointCA` field in the `ObjectStore`
definition. Unless you already have it, create a Kubernetes `Secret` with the
CA bundle:
```sh
kubectl create secret generic my-ca-secret --from-file=ca.crt
```
Then reference it:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
endpointURL: <myEndpointURL>
endpointCA:
name: my-ca-secret
key: ca.crt
[...]
```
<!-- TODO: does this also apply to the plugin? -->
:::note
If you want `ConfigMaps` and `Secrets` to be **automatically** reloaded by
instances, you can add a label with the key `cnpg.io/reload` to the
`Secrets`/`ConfigMaps`. Otherwise, you will have to reload the instances using the
`kubectl cnpg reload` subcommand.
:::
---
## Azure Blob Storage
[Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/)
is Microsoft’s cloud-based object storage solution.
Barman Cloud supports the following authentication methods:
- [Connection String](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string)
- Storage Account Name + [Access Key](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage)
- Storage Account Name + [SAS Token](https://learn.microsoft.com/en-us/azure/storage/blobs/sas-service-create)
- [Azure AD Workload Identity](https://azure.github.io/azure-workload-identity/docs/introduction.html)
### Azure AD Workload Identity
This method avoids storing credentials in Kubernetes via the
`.spec.configuration.inheritFromAzureAD` option:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
inheritFromAzureAD: true
[...]
```
### Access Key, SAS Token, or Connection String
Store credentials in a Kubernetes secret:
```sh
kubectl create secret generic azure-creds \
--from-literal=AZURE_STORAGE_ACCOUNT=<storage account name> \
--from-literal=AZURE_STORAGE_KEY=<storage account key> \
--from-literal=AZURE_STORAGE_SAS_TOKEN=<SAS token> \
--from-literal=AZURE_STORAGE_CONNECTION_STRING=<connection string>
```
Then reference the required keys in your `ObjectStore`:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: azure-store
spec:
configuration:
destinationPath: "<destination path here>"
azureCredentials:
connectionString:
name: azure-creds
key: AZURE_CONNECTION_STRING
storageAccount:
name: azure-creds
key: AZURE_STORAGE_ACCOUNT
storageKey:
name: azure-creds
key: AZURE_STORAGE_KEY
storageSasToken:
name: azure-creds
key: AZURE_STORAGE_SAS_TOKEN
[...]
```
For Azure Blob, the destination path format is:
```
<http|https>://<account-name>.<service-name>.core.windows.net/<container>/<blob>
```
### Azure-Compatible Providers
If you're using a different implementation (e.g., Azurite or emulator):
```
<http|https>://<local-machine-address>:<port>/<account-name>/<container>/<blob>
```
---
## Google Cloud Storage
[Google Cloud Storage](https://cloud.google.com/storage/) is supported with two
authentication modes:
- **GKE Workload Identity** (recommended inside Google Kubernetes Engine)
- **Service Account JSON key** via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
### GKE Workload Identity
Use the [Workload Identity authentication](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
when running in GKE:
1. Set `googleCredentials.gkeEnvironment` to `true` in the `ObjectStore`
resource
2. Annotate the `serviceAccountTemplate` in the `Cluster` resource with the GCP
service account
For example, in the `ObjectStore` resource:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
gkeEnvironment: true
```
And in the `Cluster` resource:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
spec:
serviceAccountTemplate:
metadata:
annotations:
iam.gke.io/gcp-service-account: [...].iam.gserviceaccount.com
```
### Service Account JSON Key
Follow Google’s [authentication setup](https://cloud.google.com/docs/authentication/getting-started),
then:
```sh
kubectl create secret generic backup-creds --from-file=gcsCredentials=gcs_credentials_file.json
```
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: google-store
spec:
configuration:
destinationPath: "gs://<bucket>/<folder>"
googleCredentials:
applicationCredentials:
name: backup-creds
key: gcsCredentials
[...]
```
:::important
This authentication method generates a JSON file within the container
with all the credentials required to access your Google Cloud Storage
bucket. As a result, if someone gains access to the `Pod`, they will also have
write permissions to the bucket.
:::
---
## MinIO Gateway
MinIO Gateway can proxy requests to cloud object storage providers like S3 or GCS.
For more information, refer to [MinIO official documentation](https://docs.min.io/).
### Setup
Create MinIO access credentials:
```sh
kubectl create secret generic minio-creds \
--from-literal=MINIO_ACCESS_KEY=<minio access key> \
--from-literal=MINIO_SECRET_KEY=<minio secret key>
```
:::note
Cloud Object Storage credentials will be used only by MinIO Gateway in this
case.
:::
Expose MinIO Gateway via `ClusterIP`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: minio-gateway-service
spec:
type: ClusterIP
ports:
- port: 9000
targetPort: 9000
protocol: TCP
selector:
app: minio
```
Here follows an excerpt of an example of deployment relaying to S3:
```yaml
apiVersion: apps/v1
kind: Deployment
[...]
spec:
containers:
- name: minio
image: minio/minio:RELEASE.2020-06-03T22-13-49Z
args: ["gateway", "s3"]
ports:
- containerPort: 9000
env:
- name: MINIO_ACCESS_KEY
valueFrom:
secretKeyRef:
name: minio-creds
key: MINIO_ACCESS_KEY
- name: MINIO_SECRET_KEY
valueFrom:
secretKeyRef:
name: minio-creds
key: MINIO_SECRET_KEY
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-creds
key: ACCESS_KEY_ID
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-creds
key: ACCESS_SECRET_KEY
# Uncomment the below section if session token is required
# - name: AWS_SESSION_TOKEN
# valueFrom:
# secretKeyRef:
# name: aws-creds
# key: ACCESS_SESSION_TOKEN
```
Proceed by configuring MinIO Gateway service as the `endpointURL` in the
`ObjectStore` definition, then choose a bucket name to replace `BUCKET_NAME`:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
destinationPath: s3://BUCKET_NAME/
endpointURL: http://minio-gateway-service:9000
s3Credentials:
accessKeyId:
name: minio-creds
key: MINIO_ACCESS_KEY
secretAccessKey:
name: minio-creds
key: MINIO_SECRET_KEY
[...]
```
:::important
Verify on `s3://BUCKET_NAME/` the presence of archived WAL files before
proceeding with a backup.
:::
---

19
web/versioned_docs/version-0.4.1/parameters.md
View File

@ -1,19 +0,0 @@
---
sidebar_position: 100
---
# Parameters
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The following parameters are available for the Barman Cloud Plugin:
- `barmanObjectName`: references the `ObjectStore` resource to be used by the
plugin.
- `serverName`: Specifies the server name in the object store.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::

105
web/versioned_docs/version-0.4.1/plugin-barman-cloud.v1.md
View File

@ -1,105 +0,0 @@
# API Reference
## Packages
- [barmancloud.cnpg.io/v1](#barmancloudcnpgiov1)
## barmancloud.cnpg.io/v1
Package v1 contains API Schema definitions for the barmancloud v1 API group
### Resource Types
- [ObjectStore](#objectstore)
#### InstanceSidecarConfiguration
InstanceSidecarConfiguration defines the configuration for the sidecar that runs in the instance pods.
_Appears in:_
- [ObjectStoreSpec](#objectstorespec)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#envvar-v1-core) array_ | The environment to be explicitly passed to the sidecar | | | |
| `retentionPolicyIntervalSeconds` _integer_ | The retentionCheckInterval defines the frequency at which the<br />system checks and enforces retention policies. | | 1800 | |
| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#resourcerequirements-v1-core)_ | Resources define cpu/memory requests and limits for the sidecar that runs in the instance pods. | | | |
#### ObjectStore
ObjectStore is the Schema for the objectstores API.
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `apiVersion` _string_ | `barmancloud.cnpg.io/v1` | True | | |
| `kind` _string_ | `ObjectStore` | True | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | True | | |
| `spec` _[ObjectStoreSpec](#objectstorespec)_ | Specification of the desired behavior of the ObjectStore.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | True | | |
| `status` _[ObjectStoreStatus](#objectstorestatus)_ | Most recently observed status of the ObjectStore. This data may not be up to<br />date. Populated by the system. Read-only.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | | | |
#### ObjectStoreSpec
ObjectStoreSpec defines the desired state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `configuration` _[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)_ | The configuration for the barman-cloud tool suite | True | | |
| `retentionPolicy` _string_ | RetentionPolicy is the retention policy to be used for backups<br />and WALs (i.e. '60d'). The retention policy is expressed in the form<br />of `XXu` where `XX` is a positive integer and `u` is in `[dwm]` -<br />days, weeks, months. | | | Pattern: `^[1-9][0-9]*[dwm]$` <br /> |
| `instanceSidecarConfiguration` _[InstanceSidecarConfiguration](#instancesidecarconfiguration)_ | The configuration for the sidecar that runs in the instance pods | | | |
#### ObjectStoreStatus
ObjectStoreStatus defines the observed state of ObjectStore.
_Appears in:_
- [ObjectStore](#objectstore)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `serverRecoveryWindow` _object (keys:string, values:[RecoveryWindow](#recoverywindow))_ | ServerRecoveryWindow maps each server to its recovery window | True | | |
#### RecoveryWindow
RecoveryWindow represents the time span between the first
recoverability point and the last successful backup of a PostgreSQL
server, defining the period during which data can be restored.
_Appears in:_
- [ObjectStoreStatus](#objectstorestatus)
| Field | Description | Required | Default | Validation |
| --- | --- | --- | --- | --- |
| `firstRecoverabilityPoint` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The first recoverability point in a PostgreSQL server refers to<br />the earliest point in time to which the database can be<br />restored. | True | | |
| `lastSuccussfulBackupTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#time-v1-meta)_ | The last successful backup time | True | | |

38
web/versioned_docs/version-0.4.1/retention.md
View File

@ -1,38 +0,0 @@
---
sidebar_position: 60
---
# Retention Policies
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin supports **automated cleanup of obsolete backups** via
retention policies, configured in the `.spec.retentionPolicy` field of the
`ObjectStore` resource.
:::note
This feature uses the `barman-cloud-backup-delete` command with the
`--retention-policy "RECOVERY WINDOW OF {{ value }} {{ unit }}"` syntax.
:::
#### Example: 30-Day Retention Policy
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
[...]
retentionPolicy: "30d"
````
:::note
A **recovery window retention policy** ensures the cluster can be restored to
any point in time between the calculated *Point of Recoverability* (PoR) and
the latest WAL archive. The PoR is defined as `current time - recovery window`.
The **first valid backup** is the most recent backup completed before the PoR.
Backups older than that are marked as *obsolete* and deleted after the next
backup completes.
:::

258
web/versioned_docs/version-0.4.1/usage.md
View File

@ -1,258 +0,0 @@
---
sidebar_position: 30
---
# Using the Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
After [installing the plugin](installation.mdx) in the same namespace as the
CloudNativePG operator, enabling your PostgreSQL cluster to use the Barman
Cloud Plugin involves just a few steps:
- Defining the object store containing your WAL archive and base backups, using
your preferred [provider](object_stores.md)
- Instructing the Postgres cluster to use the Barman Cloud Plugin
From that moment, you’ll be able to issue on-demand backups or define a backup
schedule, as well as rely on the object store for recovery operations.
The rest of this page details each step, using MinIO as object store provider.
## Defining the `ObjectStore`
An `ObjectStore` resource must be created for each object store used in your
PostgreSQL architecture. Here's an example configuration 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` schema follows the same format 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/current/appendixes/backup_barmanobjectstore/)
for additional details.
:::important
The `serverName` parameter in the `ObjectStore` resource is retained solely for
API compatibility with the in-tree `barmanObjectStore` and must always be left empty.
When needed, use the `serverName` plugin parameter in the Cluster configuration instead.
:::
## Configuring WAL Archiving
Once the `ObjectStore` is defined, you can configure your PostgreSQL cluster
to archive WALs by referencing the store in the `.spec.plugins` section:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
instances: 3
imagePullPolicy: Always
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
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 issue an
on-demand backup, use the following configuration with the plugin method:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
name: backup-example
spec:
cluster:
name: cluster-example
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
:::note
You can apply the same concept to the `ScheduledBackup` resource.
:::
## 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
```
:::important
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
isWALArchiver: true
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
isWALArchiver: true
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
```
## Configuring the plugin instance sidecar
The Barman Cloud Plugin runs as a sidecar container next to each PostgreSQL
instance pod. It manages backup, WAL archiving, and restore processes.
Configuration comes from multiple `ObjectStore` resources:
1. The one referenced in the
`.spec.plugins` section of the `Cluster`. This is the
object store used for WAL archiving and base backups.
2. The one referenced in the external cluster
used in the `.spec.replica.source` section of the `Cluster`. This is
used by the log-shipping designated primary to get the WAL files.
3. The one referenced in the
`.spec.bootstrap.recovery.source` section of the `Cluster`. Used by
the initial recovery job to create the cluster from an existing backup.
You can fine-tune sidecar behavior in the `.spec.instanceSidecarConfiguration`
of your ObjectStore. These settings apply to all PostgreSQL instances that use
this object store. Any updates take effect at the next `Cluster` reconciliation,
and could generate a rollout of the `Cluster`.
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-store
spec:
configuration:
# [...]
instanceSidecarConfiguration:
retentionPolicyIntervalSeconds: 1800
resources:
requests:
memory: "XXX"
cpu: "YYY"
limits:
memory: "XXX"
cpu: "YYY"
```
:::note
If more than one `ObjectStore` applies, the `instanceSidecarConfiguration` of
the one set in `.spec.plugins` has priority.
:::

43
web/versioned_docs/version-0.5.0/compression.md
View File

@ -1,43 +0,0 @@
---
sidebar_position: 80
---
# Compression
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
By default, backups and WAL files are archived **uncompressed**. However, the
Barman Cloud Plugin supports multiple compression algorithms via
`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
for space, speed, or a balance of both.
### Supported Compression Algorithms
- `bzip2`
- `gzip`
- `lz4` (WAL only)
- `snappy`
- `xz` (WAL only)
- `zstd` (WAL only)
Compression settings for base backups and WAL archives are configured
independently. For implementation details, refer to the corresponding API
definitions:
- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
:::important
Compression impacts both performance and storage efficiency. Choose the right
algorithm based on your recovery time objectives (RTO), storage capacity, and
network throughput.
:::
## Compression Benchmark (on MinIO)
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |

177
web/versioned_docs/version-0.5.0/concepts.md
View File

@ -1,177 +0,0 @@
---
sidebar_position: 10
---
# Main Concepts
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
:::important
Before proceeding, make sure to review the following sections of the
CloudNativePG documentation:
- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
:::
The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
supporting continuous physical backups and WAL archiving to an **object
store**—without interrupting write operations.
It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
of a PostgreSQL cluster.
## The Object Store
At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
which acts as the interface between the PostgreSQL cluster and the target
object storage system. It allows you to configure:
- **Authentication and bucket location** via the `.spec.configuration` section
- **WAL archiving** settings—such as compression type, parallelism, and
server-side encryption—under `.spec.configuration.wal`
- **Base backup options**—with similar settings for compression, concurrency,
and encryption—under `.spec.configuration.data`
- **Retention policies** to manage the life-cycle of archived WALs and backups
via `.spec.configuration.retentionPolicy`
WAL files are archived in the `wals` directory, while base backups are stored
as **tarballs** in the `base` directory, following the
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
The plugin also offers advanced capabilities, including
[backup tagging](misc.md#backup-object-tagging) and
[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving).
:::tip
For details, refer to the
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).
:::
## Integration with a CloudNativePG Cluster
CloudNativePG can delegate continuous backup and recovery responsibilities to
the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
to be defined.
:::important
While it is technically possible to reuse the same `ObjectStore` for multiple
`Cluster` resources within the same namespace, it is strongly recommended to
dedicate one object store per PostgreSQL cluster to ensure data isolation and
operational clarity.
:::
The following example demonstrates how to configure a CloudNativePG cluster
named `cluster-example` to use a previously defined `ObjectStore` (also named
`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
WAL archiving through the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: cluster-example
spec:
# Other cluster settings...
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: cluster-example
```
## Backup of a Postgres Cluster
Once the object store is defined and the `Cluster` is configured to use the
Barman Cloud Plugin, **WAL archiving is activated immediately** on the
PostgreSQL primary.
Physical base backups are seamlessly managed by CloudNativePG using the
`Backup` and `ScheduledBackup` resources, respectively for
[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
and
[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
backups.
To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
configure the `pluginConfiguration` section as shown:
```yaml
[...]
spec:
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
[...]
```
With this configuration, CloudNativePG supports:
- Backups from both **primary** and **standby** instances
- Backups from **designated primaries** in a distributed topology using
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
:::tip
For details on how to back up from a standby, refer to the official documentation:
[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
:::
:::important
Both backup and WAL archiving operations are executed by sidecar containers
running in the same pod as the PostgreSQL `Cluster` primary instance—except
when backups are taken from a standby, in which case the sidecar runs alongside
the standby pod.
The sidecar containers use a [dedicated container image](images.md) that
includes only the supported version of Barman Cloud.
:::
## Recovery of a Postgres Cluster
In PostgreSQL, *recovery* refers to the process of starting a database instance
from an existing backup. The Barman Cloud Plugin integrates with CloudNativePG
to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
object store.
Recovery in this context is *not in-place*: it bootstraps a brand-new
PostgreSQL cluster from a backup and replays the necessary WAL files to reach
the desired recovery target.
To perform a recovery, define an *external cluster* that references the
appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
of the target cluster:
```yaml
[...]
spec:
[...]
bootstrap:
recovery:
source: source
externalClusters:
- name: source
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: cluster-example
serverName: cluster-example
[...]
```
The critical element here is the `externalClusters` section of the `Cluster`
resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
Cloud Plugin to access the object store for recovery.
This same mechanism can be used for a variety of scenarios enabled by the
CloudNativePG API, including:
* **Full cluster recovery** from the latest backup
* **Point-in-Time Recovery (PITR)**
* Bootstrapping **replica clusters** in a distributed topology
:::tip
For complete instructions and advanced use cases, refer to the official
[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
:::

37
web/versioned_docs/version-0.5.0/images.md
View File

@ -1,37 +0,0 @@
---
sidebar_position: 99
---
# Container Images
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The Barman Cloud Plugin is distributed using two container images:
- One for deploying the plugin components
- One for the sidecar that runs alongside each PostgreSQL instance in a
CloudNativePG `Cluster` using the plugin
## Plugin Container Image
The plugin image contains the logic required to operate the Barman Cloud Plugin
within your Kubernetes environment with CloudNativePG. It is published on the
GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
This image is built from the
[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
in the plugin repository.
## Sidecar Container Image
The sidecar image is used within each PostgreSQL pod in the cluster. It
includes the latest supported version of Barman Cloud and is responsible for
performing WAL archiving and backups on behalf of CloudNativePG.
It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
built from the
[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
These sidecar images are designed to work seamlessly with the
[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
maintained by the CloudNativePG Community.

109
web/versioned_docs/version-0.5.0/installation.mdx
View File

@ -1,109 +0,0 @@
---
sidebar_position: 20
---
# Installation
:::important
1. The plugin **must** be installed in the same namespace as the CloudNativePG
operator (typically `cnpg-system`).
2. Keep in mind that the operator's **listening namespaces** may differ from its
installation namespace. Double-check this to avoid configuration issues.
:::
## Verifying the Requirements
Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
### CloudNativePG Version
Ensure you're running a version of CloudNativePG that is compatible with the
plugin. If installed in the default `cnpg-system` namespace, you can verify the
version with:
```sh
kubectl get deployment -n cnpg-system cnpg-controller-manager -o yaml \
| grep ghcr.io/cloudnative-pg/cloudnative-pg
```
Example output:
```output
image: ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
```
The version **must be 1.26 or newer**.
### cert-manager
Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
tool to confirm that `cert-manager` is installed and available:
```sh
cmctl check api
```
Example output:
```output
The cert-manager API is ready
```
Both checks are required before proceeding with the installation.
## Installing the Barman Cloud Plugin
import { InstallationSnippet } from '@site/src/components/Installation';
Install the plugin using `kubectl` by applying the manifest for the latest
release:
<InstallationSnippet />
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
```
Finally, check that the deployment is up and running:
```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 ready to use.
## Testing the latest development snapshot
You can also test the latest development snapshot of the plugin with the
following command:
```sh
kubectl apply -f \
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
```

67
web/versioned_docs/version-0.5.0/intro.md
View File

@ -1,67 +0,0 @@
---
sidebar_position: 1
sidebar_label: "Introduction"
---
# Barman Cloud Plugin
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The **Barman Cloud Plugin** for [CloudNativePG](https://cloudnative-pg.io/)
enables online continuous physical backups of PostgreSQL clusters to object storage
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
project.
:::important
If you plan to migrate your existing CloudNativePG cluster to the new
plugin-based approach using the Barman Cloud Plugin, see
["Migrating from Built-in CloudNativePG Backup"](migration.md)
for detailed instructions.
:::
## Requirements
To use the Barman Cloud Plugin, you need:
- [CloudNativePG](https://cloudnative-pg.io) version **1.26** <!-- ADD WHEN 1.27 IS OUT "or later" -->
- [cert-manager](https://cert-manager.io/) to enable TLS communication between
the plugin and the operator
## Key Features
This plugin provides the following capabilities:
- Physical online backup of the data directory
- Physical restore of the data directory
- Write-Ahead Log (WAL) archiving
- WAL restore
- Full cluster recovery
- Point-in-Time Recovery (PITR)
- Seamless integration with replica clusters for bootstrap and WAL restore from archive
:::important
The Barman Cloud Plugin is designed to **replace the in-tree object storage support**
previously provided via the `.spec.backup.barmanObjectStore` section in the
`Cluster` resource.
Backups created using the in-tree approach are fully supported and compatible
with this plugin.
:::
## Supported Object Storage Providers
The plugin works with all storage backends supported by `barman-cloud`, including:
- **Amazon S3**
- **Google Cloud Storage**
- **Microsoft Azure Blob Storage**
In addition, the following S3-compatible and simulator solutions have been
tested and verified:
- [MinIO](https://min.io/) – An S3-compatible storage solution
- [Azurite](https://github.com/Azure/Azurite) – A simulator for Azure Blob Storage
- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage
:::tip
For more details, refer to [Object Store Providers](object_stores.md).
:::

259
web/versioned_docs/version-0.5.0/migration.md
View File

@ -1,259 +0,0 @@
---
sidebar_position: 40
---
# Migrating from Built-in CloudNativePG Backup
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting
from version 1.26** and will be removed in a future release.
If you're currently relying on the built-in Barman Cloud integration, you can
migrate seamlessly to the new **plugin-based architecture** using the Barman
Cloud Plugin, without data loss. Follow these steps:
- [Install the Barman Cloud Plugin](installation.mdx)
- Create an `ObjectStore` resource by translating the contents of the
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
definition
- Modify the `Cluster` resource in a single atomic change to switch from
in-tree backup to the plugin
- Update any `ScheduledBackup` resources to use the plugin
- Update the `externalClusters` configuration, where applicable
:::tip
For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground),
which demonstrates a full migration.
:::
---
## Step 1: Define the `ObjectStore`
Begin by creating an `ObjectStore` resource in the same namespace as your
PostgreSQL `Cluster`.
There is a **direct mapping** between the `.spec.backup.barmanObjectStore`
section in CloudNativePG and the `.spec.configuration` field in the
`ObjectStore` CR. The conversion is mostly mechanical, with one key difference:
:::warning
In the plugin architecture, retention policies are defined as part of the `ObjectStore`.
In contrast, the in-tree implementation defined them at the `Cluster` level.
:::
If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration
to `.spec.retentionPolicy` in the `ObjectStore`.
---
### Example
Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration
taken from the CloudNativePG Playground project:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-eu
spec:
# [...]
backup:
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
This configuration translates to the following `ObjectStore` resource for the
plugin:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
As you can see, the contents of `barmanObjectStore` have been copied directly
under the `configuration` field of the `ObjectStore` resource, using the same
secret references.
## Step 2: Update the `Cluster` for plugin WAL archiving
Once the `ObjectStore` resource is in place, update the `Cluster` resource as
follows in a single atomic change:
- Remove the `.spec.backup.barmanObjectStore` section
- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the
`ObjectStore`)
- Remove the entire `spec.backup` section if it is now empty
- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in
[Configuring WAL archiving](usage.md#configuring-wal-archiving)
This will trigger a rolling update of the `Cluster`, switching continuous
backup from the in-tree implementation to the plugin-based approach.
### Example
The updated `pg-eu` cluster will have this configuration instead of the
previous `backup` section:
```yaml
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: minio-eu
```
---
## Step 3: Update the `ScheduledBackup`
After switching the `Cluster` to use the plugin, update your `ScheduledBackup`
resources to match.
Set the backup `method` to `plugin` and reference the plugin name via
`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup).
### Example
Original in-tree `ScheduledBackup`:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
```
Updated version using the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: pg-eu-backup
spec:
cluster:
name: pg-eu
schedule: '0 0 0 * * *'
backupOwnerReference: self
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
```
---
## Step 4: Update the `externalClusters` configuration
If your `Cluster` relies on one or more external clusters that use the in-tree
Barman Cloud integration, you need to update those configurations to use the
plugin-based architecture.
When a replica cluster fetches WAL files or base backups from an external
source that used the built-in backup method, follow these steps:
1. Create a corresponding `ObjectStore` resource for the external cluster, as
shown in [Step 1](#step-1-define-the-objectstore)
2. Update the `externalClusters` section of your replica cluster to use the
plugin instead of the in-tree `barmanObjectStore` field
### Example
Consider the original configuration using in-tree Barman Cloud:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
barmanObjectStore:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
serverName: pg-eu
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Create the `ObjectStore` resource for the external cluster:
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: minio-eu
spec:
configuration:
destinationPath: s3://backups/
endpointURL: http://minio-eu:9000
s3Credentials:
accessKeyId:
name: minio-eu
key: ACCESS_KEY_ID
secretAccessKey:
name: minio-eu
key: ACCESS_SECRET_KEY
wal:
compression: gzip
```
Update the external cluster configuration to use the plugin:
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: pg-us
spec:
# [...]
externalClusters:
- name: pg-eu
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: minio-eu
serverName: pg-eu
```

76
web/versioned_docs/version-0.5.0/misc.md
View File

@ -1,76 +0,0 @@
---
sidebar_position: 90
---
# Miscellaneous
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
## Backup Object Tagging
You can attach key-value metadata tags to backup artifacts—such as base
backups, WAL files, and history files—via the `.spec.configuration` section of
the `ObjectStore` resource.
- `tags`: applied to base backups and WAL files
- `historyTags`: applied to history files only
### Example
```yaml
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
[...]
tags:
backupRetentionPolicy: "expire"
historyTags:
backupRetentionPolicy: "keep"
[...]
```
## Extra Options for Backup and WAL Archiving
You can pass additional command-line arguments to `barman-cloud-backup` and
`barman-cloud-wal-archive` using the `additionalCommandArgs` field in the
`ObjectStore` configuration.
- `.spec.configuration.data.additionalCommandArgs`: for `barman-cloud-backup`
- `.spec.configuration.wal.additionalCommandArgs`: for `barman-cloud-wal-archive`
Each field accepts a list of string arguments. If an argument is already
configured elsewhere in the plugin, the duplicate will be ignored.
### Example: Extra Backup Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
data:
additionalCommandArgs:
- "--min-chunk-size=5MB"
- "--read-timeout=60"
```
### Example: Extra WAL Archive Options
```yaml
kind: ObjectStore
metadata:
name: my-store
spec:
configuration:
wal:
additionalCommandArgs:
- "--max-concurrency=1"
- "--read-timeout=60"
```
For a complete list of supported options, refer to the
[official Barman Cloud documentation](https://docs.pgbarman.org/release/latest/).

Some files were not shown because too many files have changed in this diff Show More