From a29aa1c91af0bc7cb4a7511c49dcc461900e9a13 Mon Sep 17 00:00:00 2001 From: Marco Nenciarini Date: Mon, 22 Sep 2025 10:26:43 +0200 Subject: [PATCH 01/13] fix(logs): log the correct name when on ObjectStore not found error (#540) Closes #539 Signed-off-by: Marco Nenciarini --- internal/cnpgi/operator/reconciler.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/internal/cnpgi/operator/reconciler.go b/internal/cnpgi/operator/reconciler.go index ec80f13..bb6c60b 100644 --- a/internal/cnpgi/operator/reconciler.go +++ b/internal/cnpgi/operator/reconciler.go @@ -81,8 +81,8 @@ func (r ReconcilerImplementation) Pre( if apierrs.IsNotFound(err) { contextLogger.Info( "barman object configuration not found, requeuing", - "name", pluginConfiguration.BarmanObjectName, - "namespace", cluster.Namespace) + "name", barmanObjectKey.Name, + "namespace", barmanObjectKey.Namespace) return &reconciler.ReconcilerHooksResult{ Behavior: reconciler.ReconcilerHooksResult_BEHAVIOR_REQUEUE, }, nil From 329d7c851f9631fabd1d02feb0b43811b29aff97 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Mon, 22 Sep 2025 10:27:55 +0200 Subject: [PATCH 02/13] chore(deps): update golangci/golangci-lint docker tag to v2.5.0 (#542) | datasource | package | from | to | | ---------- | ---------------------- | ------ | ------ | | docker | golangci/golangci-lint | v2.4.0 | v2.5.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- Taskfile.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Taskfile.yml b/Taskfile.yml index 4f34412..8151e37 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -21,7 +21,7 @@ tasks: # renovate: datasource=git-refs depName=golangci-lint lookupName=https://github.com/sagikazarmark/daggerverse currentValue=main DAGGER_GOLANGCI_LINT_SHA: 88056b48085a170fbf7638e106efbecd26c6573d # renovate: datasource=docker depName=golangci/golangci-lint versioning=semver - GOLANGCI_LINT_VERSION: v2.4.0 + GOLANGCI_LINT_VERSION: v2.5.0 cmds: - > GITHUB_REF= dagger -sc "github.com/sagikazarmark/daggerverse/golangci-lint@${DAGGER_GOLANGCI_LINT_SHA} From bb04a049d3f3f08ce66bcddb26ef5676c76f9eaa Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Mon, 22 Sep 2025 10:28:43 +0200 Subject: [PATCH 03/13] chore(deps): lock file maintenance (#543) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- web/yarn.lock | 274 ++++++++++++++++++++++++++------------------------ 1 file changed, 143 insertions(+), 131 deletions(-) diff --git a/web/yarn.lock b/web/yarn.lock index 304b9d7..1c16da4 100644 --- a/web/yarn.lock +++ b/web/yarn.lock @@ -1104,15 +1104,15 @@ resolved "https://registry.yarnpkg.com/@csstools/media-query-list-parser/-/media-query-list-parser-4.0.3.tgz#7aec77bcb89c2da80ef207e73f474ef9e1b3cdf1" integrity sha512-HAYH7d3TLRHDOUQK4mZKf9k9Ph/m8Akstg66ywKR4SFAigjs3yBiUeZtFxywiTm5moZMAp/5W/ZuFnNXXYLuuQ== -"@csstools/postcss-alpha-function@^1.0.0": - version "1.0.0" - resolved "https://registry.yarnpkg.com/@csstools/postcss-alpha-function/-/postcss-alpha-function-1.0.0.tgz#8764fbbf25a5f1e106fb623ae632e01a220a6fc2" - integrity sha512-r2L8KNg5Wriq5n8IUQcjzy2Rh37J5YjzP9iOyHZL5fxdWYHB08vqykHQa4wAzN/tXwDuCHnhQDGCtxfS76xn7g== +"@csstools/postcss-alpha-function@^1.0.1": + version "1.0.1" + resolved "https://registry.yarnpkg.com/@csstools/postcss-alpha-function/-/postcss-alpha-function-1.0.1.tgz#7989605711de7831bc7cd75b94c9b5bac9c3728e" + integrity sha512-isfLLwksH3yHkFXfCI2Gcaqg7wGGHZZwunoJzEZk0yKYIokgre6hYVFibKL3SYAoR1kBXova8LB+JoO5vZzi9w== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" "@csstools/postcss-cascade-layers@^5.0.2": @@ -1123,58 +1123,69 @@ "@csstools/selector-specificity" "^5.0.0" postcss-selector-parser "^7.0.0" -"@csstools/postcss-color-function-display-p3-linear@^1.0.0": - version "1.0.0" - resolved "https://registry.yarnpkg.com/@csstools/postcss-color-function-display-p3-linear/-/postcss-color-function-display-p3-linear-1.0.0.tgz#27395b62a5d9a108eefcc0eb463247a15f4269a1" - integrity sha512-7q+OuUqfowRrP84m/Jl0wv3pfCQyUTCW5MxDIux+/yty5IkUUHOTigCjrC0Fjy3OT0ncGLudHbfLWmP7E1arNA== - dependencies: - "@csstools/css-color-parser" "^3.1.0" - "@csstools/css-parser-algorithms" "^3.0.5" - "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" - "@csstools/utilities" "^2.0.0" - -"@csstools/postcss-color-function@^4.0.11": - version "4.0.11" - resolved "https://registry.yarnpkg.com/@csstools/postcss-color-function/-/postcss-color-function-4.0.11.tgz#03c34a51dc00943a6674294fb1163e7af9e87ffd" - integrity sha512-AtH22zLHTLm64HLdpv5EedT/zmYTm1MtdQbQhRZXxEB6iYtS6SrS1jLX3TcmUWMFzpumK/OVylCm3HcLms4slw== - dependencies: - "@csstools/css-color-parser" "^3.1.0" - "@csstools/css-parser-algorithms" "^3.0.5" - "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" - "@csstools/utilities" "^2.0.0" - -"@csstools/postcss-color-mix-function@^3.0.11": - version "3.0.11" - resolved "https://registry.yarnpkg.com/@csstools/postcss-color-mix-function/-/postcss-color-mix-function-3.0.11.tgz#6db0a1c749fabaf2bf978b37044700d1c1b09fc2" - integrity sha512-cQpXBelpTx0YhScZM5Ve0jDCA4RzwFc7oNafzZOGgCHt/GQVYiU8Vevz9QJcwy/W0Pyi/BneY+KMjz23lI9r+Q== - dependencies: - "@csstools/css-color-parser" "^3.1.0" - "@csstools/css-parser-algorithms" "^3.0.5" - "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" - "@csstools/utilities" "^2.0.0" - -"@csstools/postcss-color-mix-variadic-function-arguments@^1.0.1": +"@csstools/postcss-color-function-display-p3-linear@^1.0.1": version "1.0.1" - resolved "https://registry.yarnpkg.com/@csstools/postcss-color-mix-variadic-function-arguments/-/postcss-color-mix-variadic-function-arguments-1.0.1.tgz#2dd9d66ded0d41cd7b2c13a1188f03e894c17d7e" - integrity sha512-c7hyBtbF+jlHIcUGVdWY06bHICgguV9ypfcELU3eU3W/9fiz2dxM8PqxQk2ndXYTzLnwPvNNqu1yCmQ++N6Dcg== + resolved "https://registry.yarnpkg.com/@csstools/postcss-color-function-display-p3-linear/-/postcss-color-function-display-p3-linear-1.0.1.tgz#3017ff5e1f65307d6083e58e93d76724fb1ebf9f" + integrity sha512-E5qusdzhlmO1TztYzDIi8XPdPoYOjoTY6HBYBCYSj+Gn4gQRBlvjgPQXzfzuPQqt8EhkC/SzPKObg4Mbn8/xMg== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" -"@csstools/postcss-content-alt-text@^2.0.7": - version "2.0.7" - resolved "https://registry.yarnpkg.com/@csstools/postcss-content-alt-text/-/postcss-content-alt-text-2.0.7.tgz#ac0a263e8acb0be99cdcfc0b1792c62141825747" - integrity sha512-cq/zWaEkpcg3RttJ5+GdNwk26NwxY5KgqgtNL777Fdd28AVGHxuBvqmK4Jq4oKhW1NX4M2LbgYAVVN0NZ+/XYQ== +"@csstools/postcss-color-function@^4.0.12": + version "4.0.12" + resolved "https://registry.yarnpkg.com/@csstools/postcss-color-function/-/postcss-color-function-4.0.12.tgz#a7c85a98c77b522a194a1bbb00dd207f40c7a771" + integrity sha512-yx3cljQKRaSBc2hfh8rMZFZzChaFgwmO2JfFgFr1vMcF3C/uyy5I4RFIBOIWGq1D+XbKCG789CGkG6zzkLpagA== + dependencies: + "@csstools/css-color-parser" "^3.1.0" + "@csstools/css-parser-algorithms" "^3.0.5" + "@csstools/css-tokenizer" "^3.0.4" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" + "@csstools/utilities" "^2.0.0" + +"@csstools/postcss-color-mix-function@^3.0.12": + version "3.0.12" + resolved "https://registry.yarnpkg.com/@csstools/postcss-color-mix-function/-/postcss-color-mix-function-3.0.12.tgz#2f1ee9f8208077af069545c9bd79bb9733382c2a" + integrity sha512-4STERZfCP5Jcs13P1U5pTvI9SkgLgfMUMhdXW8IlJWkzOOOqhZIjcNhWtNJZes2nkBDsIKJ0CJtFtuaZ00moag== + dependencies: + "@csstools/css-color-parser" "^3.1.0" + "@csstools/css-parser-algorithms" "^3.0.5" + "@csstools/css-tokenizer" "^3.0.4" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" + "@csstools/utilities" "^2.0.0" + +"@csstools/postcss-color-mix-variadic-function-arguments@^1.0.2": + version "1.0.2" + resolved "https://registry.yarnpkg.com/@csstools/postcss-color-mix-variadic-function-arguments/-/postcss-color-mix-variadic-function-arguments-1.0.2.tgz#b4012b62a4eaa24d694172bb7137f9d2319cb8f2" + integrity sha512-rM67Gp9lRAkTo+X31DUqMEq+iK+EFqsidfecmhrteErxJZb6tUoJBVQca1Vn1GpDql1s1rD1pKcuYzMsg7Z1KQ== + dependencies: + "@csstools/css-color-parser" "^3.1.0" + "@csstools/css-parser-algorithms" "^3.0.5" + "@csstools/css-tokenizer" "^3.0.4" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" + "@csstools/utilities" "^2.0.0" + +"@csstools/postcss-content-alt-text@^2.0.8": + version "2.0.8" + resolved "https://registry.yarnpkg.com/@csstools/postcss-content-alt-text/-/postcss-content-alt-text-2.0.8.tgz#1d52da1762893c32999ff76839e48d6ec7c7a4cb" + integrity sha512-9SfEW9QCxEpTlNMnpSqFaHyzsiRpZ5J5+KqCu1u5/eEJAWsMhzT40qf0FIbeeglEvrGRMdDzAxMIz3wqoGSb+Q== dependencies: "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" + "@csstools/utilities" "^2.0.0" + +"@csstools/postcss-contrast-color-function@^2.0.12": + version "2.0.12" + resolved "https://registry.yarnpkg.com/@csstools/postcss-contrast-color-function/-/postcss-contrast-color-function-2.0.12.tgz#ca46986d095c60f208d9e3f24704d199c9172637" + integrity sha512-YbwWckjK3qwKjeYz/CijgcS7WDUCtKTd8ShLztm3/i5dhh4NaqzsbYnhm4bjrpFpnLZ31jVcbK8YL77z3GBPzA== + dependencies: + "@csstools/css-color-parser" "^3.1.0" + "@csstools/css-parser-algorithms" "^3.0.5" + "@csstools/css-tokenizer" "^3.0.4" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" "@csstools/postcss-exponential-functions@^2.0.9": @@ -1203,34 +1214,34 @@ "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" -"@csstools/postcss-gradients-interpolation-method@^5.0.11": - version "5.0.11" - resolved "https://registry.yarnpkg.com/@csstools/postcss-gradients-interpolation-method/-/postcss-gradients-interpolation-method-5.0.11.tgz#f1c5c431a44ed9655cb408aea8666ed2c5250490" - integrity sha512-8M3mcNTL3cGIJXDnvrJ2oWEcKi3zyw7NeYheFKePUlBmLYm1gkw9Rr/BA7lFONrOPeQA3yeMPldrrws6lqHrug== +"@csstools/postcss-gradients-interpolation-method@^5.0.12": + version "5.0.12" + resolved "https://registry.yarnpkg.com/@csstools/postcss-gradients-interpolation-method/-/postcss-gradients-interpolation-method-5.0.12.tgz#0955cce4d97203b861bf66742bbec611b2f3661c" + integrity sha512-jugzjwkUY0wtNrZlFeyXzimUL3hN4xMvoPnIXxoZqxDvjZRiSh+itgHcVUWzJ2VwD/VAMEgCLvtaJHX+4Vj3Ow== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" -"@csstools/postcss-hwb-function@^4.0.11": - version "4.0.11" - resolved "https://registry.yarnpkg.com/@csstools/postcss-hwb-function/-/postcss-hwb-function-4.0.11.tgz#4bb173f1c8c2361bf46a842a948ee687471ae4ea" - integrity sha512-9meZbsVWTZkWsSBazQips3cHUOT29a/UAwFz0AMEXukvpIGGDR9+GMl3nIckWO5sPImsadu4F5Zy+zjt8QgCdA== +"@csstools/postcss-hwb-function@^4.0.12": + version "4.0.12" + resolved "https://registry.yarnpkg.com/@csstools/postcss-hwb-function/-/postcss-hwb-function-4.0.12.tgz#07f7ecb08c50e094673bd20eaf7757db0162beee" + integrity sha512-mL/+88Z53KrE4JdePYFJAQWFrcADEqsLprExCM04GDNgHIztwFzj0Mbhd/yxMBngq0NIlz58VVxjt5abNs1VhA== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" -"@csstools/postcss-ic-unit@^4.0.3": - version "4.0.3" - resolved "https://registry.yarnpkg.com/@csstools/postcss-ic-unit/-/postcss-ic-unit-4.0.3.tgz#ba0375e9d346e6e5a42dc8c2cb1133b2262f9ffa" - integrity sha512-RtYYm2qUIu9vAaHB0cC8rQGlOCQAUgEc2tMr7ewlGXYipBQKjoWmyVArqsk7SEr8N3tErq6P6UOJT3amaVof5Q== +"@csstools/postcss-ic-unit@^4.0.4": + version "4.0.4" + resolved "https://registry.yarnpkg.com/@csstools/postcss-ic-unit/-/postcss-ic-unit-4.0.4.tgz#2ee2da0690db7edfbc469279711b9e69495659d2" + integrity sha512-yQ4VmossuOAql65sCPppVO1yfb7hDscf4GseF0VCA/DTDaBc0Wtf8MTqVPfjGYlT5+2buokG0Gp7y0atYZpwjg== dependencies: - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" postcss-value-parser "^4.2.0" @@ -1247,14 +1258,14 @@ "@csstools/selector-specificity" "^5.0.0" postcss-selector-parser "^7.0.0" -"@csstools/postcss-light-dark-function@^2.0.10": - version "2.0.10" - resolved "https://registry.yarnpkg.com/@csstools/postcss-light-dark-function/-/postcss-light-dark-function-2.0.10.tgz#b606f13d1f81efd297763c6ad1ac515c3ca4165b" - integrity sha512-g7Lwb294lSoNnyrwcqoooh9fTAp47rRNo+ILg7SLRSMU3K9ePIwRt566sNx+pehiCelv4E1ICaU1EwLQuyF2qw== +"@csstools/postcss-light-dark-function@^2.0.11": + version "2.0.11" + resolved "https://registry.yarnpkg.com/@csstools/postcss-light-dark-function/-/postcss-light-dark-function-2.0.11.tgz#0df448aab9a33cb9a085264ff1f396fb80c4437d" + integrity sha512-fNJcKXJdPM3Lyrbmgw2OBbaioU7yuKZtiXClf4sGdQttitijYlZMD5K7HrC/eF83VRWRrYq6OZ0Lx92leV2LFA== dependencies: "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" "@csstools/postcss-logical-float-and-clear@^3.0.0": @@ -1321,21 +1332,21 @@ dependencies: postcss-value-parser "^4.2.0" -"@csstools/postcss-oklab-function@^4.0.11": - version "4.0.11" - resolved "https://registry.yarnpkg.com/@csstools/postcss-oklab-function/-/postcss-oklab-function-4.0.11.tgz#d69242a9b027dda731bd79db7293bc938bb6df97" - integrity sha512-9f03ZGxZ2VmSCrM4SDXlAYP+Xpu4VFzemfQUQFL9OYxAbpvDy0FjDipZ0i8So1pgs8VIbQI0bNjFWgfdpGw8ig== +"@csstools/postcss-oklab-function@^4.0.12": + version "4.0.12" + resolved "https://registry.yarnpkg.com/@csstools/postcss-oklab-function/-/postcss-oklab-function-4.0.12.tgz#416640ef10227eea1375b47b72d141495950971d" + integrity sha512-HhlSmnE1NKBhXsTnNGjxvhryKtO7tJd1w42DKOGFD6jSHtYOrsJTQDKPMwvOfrzUAk8t7GcpIfRyM7ssqHpFjg== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" -"@csstools/postcss-progressive-custom-properties@^4.2.0": - version "4.2.0" - resolved "https://registry.yarnpkg.com/@csstools/postcss-progressive-custom-properties/-/postcss-progressive-custom-properties-4.2.0.tgz#7f15349c2cd108478d28e1503c660d4037925030" - integrity sha512-fWCXRasX17N1NCPTCuwC3FJDV+Wc031f16cFuuMEfIsYJ1q5ABCa59W0C6VeMGqjNv6ldf37vvwXXAeaZjD9PA== +"@csstools/postcss-progressive-custom-properties@^4.2.1": + version "4.2.1" + resolved "https://registry.yarnpkg.com/@csstools/postcss-progressive-custom-properties/-/postcss-progressive-custom-properties-4.2.1.tgz#c39780b9ff0d554efb842b6bd75276aa6f1705db" + integrity sha512-uPiiXf7IEKtUQXsxu6uWtOlRMXd2QWWy5fhxHDnPdXKCQckPP3E34ZgDoZ62r2iT+UOgWsSbM4NvHE5m3mAEdw== dependencies: postcss-value-parser "^4.2.0" @@ -1348,15 +1359,15 @@ "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" -"@csstools/postcss-relative-color-syntax@^3.0.11": - version "3.0.11" - resolved "https://registry.yarnpkg.com/@csstools/postcss-relative-color-syntax/-/postcss-relative-color-syntax-3.0.11.tgz#d81d59ff123fa5f3e4a0493b1e2b0585353bb541" - integrity sha512-oQ5fZvkcBrWR+k6arHXk0F8FlkmD4IxM+rcGDLWrF2f31tWyEM3lSraeWAV0f7BGH6LIrqmyU3+Qo/1acfoJng== +"@csstools/postcss-relative-color-syntax@^3.0.12": + version "3.0.12" + resolved "https://registry.yarnpkg.com/@csstools/postcss-relative-color-syntax/-/postcss-relative-color-syntax-3.0.12.tgz#ced792450102441f7c160e1d106f33e4b44181f8" + integrity sha512-0RLIeONxu/mtxRtf3o41Lq2ghLimw0w9ByLWnnEVuy89exmEEq8bynveBxNW3nyHqLAFEeNtVEmC1QK9MZ8Huw== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" "@csstools/postcss-scope-pseudo-class@^4.0.1": @@ -3115,9 +3126,9 @@ balanced-match@^1.0.0: integrity sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw== baseline-browser-mapping@^2.8.3: - version "2.8.5" - resolved "https://registry.yarnpkg.com/baseline-browser-mapping/-/baseline-browser-mapping-2.8.5.tgz#3147fe6b01a0c49ce1952daebcfc2057fc43fedb" - integrity sha512-TiU4qUT9jdCuh4aVOG7H1QozyeI2sZRqoRPdqBIaslfNt4WUSanRBueAwl2x5jt4rXBMim3lIN2x6yT8PDi24Q== + version "2.8.6" + resolved "https://registry.yarnpkg.com/baseline-browser-mapping/-/baseline-browser-mapping-2.8.6.tgz#c37dea4291ed8d01682f85661dbe87967028642e" + integrity sha512-wrH5NNqren/QMtKUEEJf7z86YjfqW/2uw3IL3/xpqZUC95SSVIFXYQeeGjL6FT/X68IROu6RMehZQS5foy2BXw== batch@0.6.1: version "0.6.1" @@ -3208,7 +3219,7 @@ braces@^3.0.3, braces@~3.0.2: dependencies: fill-range "^7.1.1" -browserslist@^4.0.0, browserslist@^4.23.0, browserslist@^4.24.0, browserslist@^4.24.4, browserslist@^4.25.1, browserslist@^4.25.3: +browserslist@^4.0.0, browserslist@^4.23.0, browserslist@^4.24.0, browserslist@^4.24.4, browserslist@^4.25.3, browserslist@^4.26.0: version "4.26.2" resolved "https://registry.yarnpkg.com/browserslist/-/browserslist-4.26.2.tgz#7db3b3577ec97f1140a52db4936654911078cef3" integrity sha512-ECFzp6uFOSB+dcZ5BK/IBaGWssbSYBHvuMeMt3MMFyhI0Z8SqGgEkBLARgpRH3hutIgPVsALcMwbDrJqPxQ65A== @@ -3697,9 +3708,9 @@ css-blank-pseudo@^7.0.1: postcss-selector-parser "^7.0.0" css-declaration-sorter@^7.2.0: - version "7.2.0" - resolved "https://registry.yarnpkg.com/css-declaration-sorter/-/css-declaration-sorter-7.2.0.tgz#6dec1c9523bc4a643e088aab8f09e67a54961024" - integrity sha512-h70rUM+3PNFuaBDTLe8wF/cdWu+dOZmb7pJt8Z2sedYbAcQVQV/tEchueg3GWxwqS0cxtbxmaHEdkNACqcvsow== + version "7.3.0" + resolved "https://registry.yarnpkg.com/css-declaration-sorter/-/css-declaration-sorter-7.3.0.tgz#edc45c36bcdfea0788b1d4452829f142ef1c4a4a" + integrity sha512-LQF6N/3vkAMYF4xoHLJfG718HRJh34Z8BnNhd6bosOMIVjMlhuZK5++oZa3uYAgrI5+7x2o27gUqTR2U/KjUOQ== css-has-pseudo@^7.0.3: version "7.0.3" @@ -3784,10 +3795,10 @@ css-what@^6.0.1, css-what@^6.1.0: resolved "https://registry.yarnpkg.com/css-what/-/css-what-6.2.2.tgz#cdcc8f9b6977719fdfbd1de7aec24abf756b9dea" integrity sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA== -cssdb@^8.4.0: - version "8.4.0" - resolved "https://registry.yarnpkg.com/cssdb/-/cssdb-8.4.0.tgz#232a1aa7751983ed2b40331634902d4c93f0456c" - integrity sha512-lyATYGyvXwQ8h55WeQeEHXhI+47rl52pXSYkFK/ZrCbAJSgVIaPFjYc3RM8TpRHKk7W3wsAZImmLps+P5VyN9g== +cssdb@^8.4.2: + version "8.4.2" + resolved "https://registry.yarnpkg.com/cssdb/-/cssdb-8.4.2.tgz#1a367ab1904c97af0bb2c7ae179764deae7b078b" + integrity sha512-PzjkRkRUS+IHDJohtxkIczlxPPZqRo0nXplsYXOMBRPjcVRjj1W4DfvRgshUYTVuUigU7ptVYkFJQ7abUB0nyg== cssesc@^3.0.0: version "3.0.0" @@ -4102,9 +4113,9 @@ ee-first@1.1.1: integrity sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow== electron-to-chromium@^1.5.218: - version "1.5.221" - resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.221.tgz#bd98014b2a247701c4ebd713080448d539545d79" - integrity sha512-/1hFJ39wkW01ogqSyYoA4goOXOtMRy6B+yvA1u42nnsEGtHzIzmk93aPISumVQeblj47JUHLC9coCjUxb1EvtQ== + version "1.5.222" + resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.222.tgz#965c93783ad989116b74593ae3068b9466fdb237" + integrity sha512-gA7psSwSwQRE60CEoLz6JBCQPIxNeuzB2nL8vE03GK/OHxlvykbLyeiumQy1iH5C2f3YbRAZpGCMT12a/9ih9w== emoji-regex@^8.0.0: version "8.0.0" @@ -6839,15 +6850,15 @@ postcss-clamp@^4.1.0: dependencies: postcss-value-parser "^4.2.0" -postcss-color-functional-notation@^7.0.11: - version "7.0.11" - resolved "https://registry.yarnpkg.com/postcss-color-functional-notation/-/postcss-color-functional-notation-7.0.11.tgz#ad6b3d2e71fedd94a932f96260b596c33c53c6a5" - integrity sha512-zfqoUSaHMko/k2PA9xnaydVTHqYv5vphq5Q2AHcG/dCdv/OkHYWcVWfVTBKZ526uzT8L7NghuvSw3C9PxlKnLg== +postcss-color-functional-notation@^7.0.12: + version "7.0.12" + resolved "https://registry.yarnpkg.com/postcss-color-functional-notation/-/postcss-color-functional-notation-7.0.12.tgz#9a3df2296889e629fde18b873bb1f50a4ecf4b83" + integrity sha512-TLCW9fN5kvO/u38/uesdpbx3e8AkTYhMvDZYa9JpmImWuTE99bDQ7GU7hdOADIZsiI9/zuxfAJxny/khknp1Zw== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" postcss-color-hex-alpha@^10.0.0: @@ -6949,12 +6960,12 @@ postcss-discard-unused@^6.0.5: dependencies: postcss-selector-parser "^6.0.16" -postcss-double-position-gradients@^6.0.3: - version "6.0.3" - resolved "https://registry.yarnpkg.com/postcss-double-position-gradients/-/postcss-double-position-gradients-6.0.3.tgz#d8c4b126af89855a3aa6687e5b1a0d5460d4a5b7" - integrity sha512-Dl0Z9sdbMwrPslgOaGBZRGo3TASmmgTcqcUODr82MTYyJk6devXZM6MlQjpQKMJqlLJ6oL1w78U7IXFdPA5+ug== +postcss-double-position-gradients@^6.0.4: + version "6.0.4" + resolved "https://registry.yarnpkg.com/postcss-double-position-gradients/-/postcss-double-position-gradients-6.0.4.tgz#b482d08b5ced092b393eb297d07976ab482d4cad" + integrity sha512-m6IKmxo7FxSP5nF2l63QbCC3r+bWpFUWmZXZf096WxG0m7Vl1Q1+ruFOhpdDRmKrRS+S3Jtk+TVk/7z0+BVK6g== dependencies: - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" postcss-value-parser "^4.2.0" @@ -6990,15 +7001,15 @@ postcss-image-set-function@^7.0.0: "@csstools/utilities" "^2.0.0" postcss-value-parser "^4.2.0" -postcss-lab-function@^7.0.11: - version "7.0.11" - resolved "https://registry.yarnpkg.com/postcss-lab-function/-/postcss-lab-function-7.0.11.tgz#455934181eea130f8e649c1f54692e1768046f6a" - integrity sha512-BEA4jId8uQe1gyjZZ6Bunb6ZsH2izks+v25AxQJDBtigXCjTLmCPWECwQpLTtcxH589MVxhs/9TAmRC6lUEmXQ== +postcss-lab-function@^7.0.12: + version "7.0.12" + resolved "https://registry.yarnpkg.com/postcss-lab-function/-/postcss-lab-function-7.0.12.tgz#eb555ac542607730eb0a87555074e4a5c6eef6e4" + integrity sha512-tUcyRk1ZTPec3OuKFsqtRzW2Go5lehW29XA21lZ65XmzQkz43VY2tyWEC202F7W3mILOjw0voOiuxRGTsN+J9w== dependencies: "@csstools/css-color-parser" "^3.1.0" "@csstools/css-parser-algorithms" "^3.0.5" "@csstools/css-tokenizer" "^3.0.4" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/utilities" "^2.0.0" postcss-loader@^7.3.4: @@ -7207,26 +7218,27 @@ postcss-place@^10.0.0: postcss-value-parser "^4.2.0" postcss-preset-env@^10.2.1: - version "10.3.1" - resolved "https://registry.yarnpkg.com/postcss-preset-env/-/postcss-preset-env-10.3.1.tgz#f3799f0f7a7ea384b3c16e073055c231d11bb3bf" - integrity sha512-8ZOOWVwQ0iMpfEYkYo+U6W7fE2dJ/tP6dtEFwPJ66eB5JjnFupfYh+y6zo+vWDO72nGhKOVdxwhTjfzcSNRg4Q== + version "10.4.0" + resolved "https://registry.yarnpkg.com/postcss-preset-env/-/postcss-preset-env-10.4.0.tgz#fa6167a307f337b2bcdd1d125604ff97cdeb5142" + integrity sha512-2kqpOthQ6JhxqQq1FSAAZGe9COQv75Aw8WbsOvQVNJ2nSevc9Yx/IKZGuZ7XJ+iOTtVon7LfO7ELRzg8AZ+sdw== dependencies: - "@csstools/postcss-alpha-function" "^1.0.0" + "@csstools/postcss-alpha-function" "^1.0.1" "@csstools/postcss-cascade-layers" "^5.0.2" - "@csstools/postcss-color-function" "^4.0.11" - "@csstools/postcss-color-function-display-p3-linear" "^1.0.0" - "@csstools/postcss-color-mix-function" "^3.0.11" - "@csstools/postcss-color-mix-variadic-function-arguments" "^1.0.1" - "@csstools/postcss-content-alt-text" "^2.0.7" + "@csstools/postcss-color-function" "^4.0.12" + "@csstools/postcss-color-function-display-p3-linear" "^1.0.1" + "@csstools/postcss-color-mix-function" "^3.0.12" + "@csstools/postcss-color-mix-variadic-function-arguments" "^1.0.2" + "@csstools/postcss-content-alt-text" "^2.0.8" + "@csstools/postcss-contrast-color-function" "^2.0.12" "@csstools/postcss-exponential-functions" "^2.0.9" "@csstools/postcss-font-format-keywords" "^4.0.0" "@csstools/postcss-gamut-mapping" "^2.0.11" - "@csstools/postcss-gradients-interpolation-method" "^5.0.11" - "@csstools/postcss-hwb-function" "^4.0.11" - "@csstools/postcss-ic-unit" "^4.0.3" + "@csstools/postcss-gradients-interpolation-method" "^5.0.12" + "@csstools/postcss-hwb-function" "^4.0.12" + "@csstools/postcss-ic-unit" "^4.0.4" "@csstools/postcss-initial" "^2.0.1" "@csstools/postcss-is-pseudo-class" "^5.0.3" - "@csstools/postcss-light-dark-function" "^2.0.10" + "@csstools/postcss-light-dark-function" "^2.0.11" "@csstools/postcss-logical-float-and-clear" "^3.0.0" "@csstools/postcss-logical-overflow" "^2.0.0" "@csstools/postcss-logical-overscroll-behavior" "^2.0.0" @@ -7236,10 +7248,10 @@ postcss-preset-env@^10.2.1: "@csstools/postcss-media-queries-aspect-ratio-number-values" "^3.0.5" "@csstools/postcss-nested-calc" "^4.0.0" "@csstools/postcss-normalize-display-values" "^4.0.0" - "@csstools/postcss-oklab-function" "^4.0.11" - "@csstools/postcss-progressive-custom-properties" "^4.2.0" + "@csstools/postcss-oklab-function" "^4.0.12" + "@csstools/postcss-progressive-custom-properties" "^4.2.1" "@csstools/postcss-random-function" "^2.0.1" - "@csstools/postcss-relative-color-syntax" "^3.0.11" + "@csstools/postcss-relative-color-syntax" "^3.0.12" "@csstools/postcss-scope-pseudo-class" "^4.0.1" "@csstools/postcss-sign-functions" "^1.1.4" "@csstools/postcss-stepped-value-functions" "^4.0.9" @@ -7247,27 +7259,27 @@ postcss-preset-env@^10.2.1: "@csstools/postcss-trigonometric-functions" "^4.0.9" "@csstools/postcss-unset-value" "^4.0.0" autoprefixer "^10.4.21" - browserslist "^4.25.1" + browserslist "^4.26.0" css-blank-pseudo "^7.0.1" css-has-pseudo "^7.0.3" css-prefers-color-scheme "^10.0.0" - cssdb "^8.4.0" + cssdb "^8.4.2" postcss-attribute-case-insensitive "^7.0.1" postcss-clamp "^4.1.0" - postcss-color-functional-notation "^7.0.11" + postcss-color-functional-notation "^7.0.12" postcss-color-hex-alpha "^10.0.0" postcss-color-rebeccapurple "^10.0.0" postcss-custom-media "^11.0.6" postcss-custom-properties "^14.0.6" postcss-custom-selectors "^8.0.5" postcss-dir-pseudo-class "^9.0.1" - postcss-double-position-gradients "^6.0.3" + postcss-double-position-gradients "^6.0.4" postcss-focus-visible "^10.0.1" postcss-focus-within "^9.0.1" postcss-font-variant "^5.0.0" postcss-gap-properties "^6.0.0" postcss-image-set-function "^7.0.0" - postcss-lab-function "^7.0.11" + postcss-lab-function "^7.0.12" postcss-logical "^8.1.0" postcss-nesting "^13.0.2" postcss-opacity-percentage "^3.0.0" From f8964428fd9c52a5d6dac3edc3e3637782a4a0f4 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Mon, 22 Sep 2025 10:29:48 +0200 Subject: [PATCH 04/13] chore(deps): refresh pip-compile outputs (#544) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- containers/sidecar-requirements.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/containers/sidecar-requirements.txt b/containers/sidecar-requirements.txt index 2568e99..487c56f 100644 --- a/containers/sidecar-requirements.txt +++ b/containers/sidecar-requirements.txt @@ -2,7 +2,7 @@ # This file is autogenerated by pip-compile with Python 3.13 # by the following command: # -# pip-compile --allow-unsafe --generate-hashes --output-file=sidecar-requirements.txt --strip-extras sidecar-requirements.in +# pip-compile --allow-unsafe --cert=None --client-cert=None --generate-hashes --index-url=None --output-file=sidecar-requirements.txt --pip-args=None --strip-extras sidecar-requirements.in # azure-core==1.35.1 \ --hash=sha256:12da0c9e08e48e198f9158b56ddbe33b421477e1dc98c2e1c8f9e254d92c468b \ @@ -22,13 +22,13 @@ barman==3.15.0 \ --hash=sha256:96d10c950f8947c821451f3fd387e8c55698b280237d0a9b2ce28c3b96956cd2 \ --hash=sha256:aeda1991637c5c4d4b440eaa08069e855e3c50ff0ea2fc6e08dd881c87eb8ec1 # via -r sidecar-requirements.in -boto3==1.40.33 \ - --hash=sha256:b9548f4cfb44dc9fb7f09741c7dce34350d4a9f904ff0f7f97d699d0586f6b9a \ - --hash=sha256:dc8a37b25f43d458d830a5988283f0a5ac38a47dd2c46cccc5bc40e47fda97c9 +boto3==1.40.35 \ + --hash=sha256:d718df3591c829bcca4c498abb7b09d64d1eecc4e5a2b6cef14b476501211b8a \ + --hash=sha256:f4c1b01dd61e7733b453bca38b004ce030e26ee36e7a3d4a9e45a730b67bc38d # via barman -botocore==1.40.33 \ - --hash=sha256:307e0cb55f4b7307bfd2090fd1c9ca14e1febece5b928144ccc0f78adfd2d864 \ - --hash=sha256:b9a33758913410ca0d81f30dfd9f00c4ff22c72c38fdf679864011afc73d99fd +botocore==1.40.35 \ + --hash=sha256:67e062752ff579c8cc25f30f9c3a84c72d692516a41a9ee1cf17735767ca78be \ + --hash=sha256:c545de2cbbce161f54ca589fbb677bae14cdbfac7d5f1a27f6a620cb057c26f4 # via # boto3 # s3transfer From 2b53ac3c2d8f3821c3cc8cf34bc9d3d0dfbf3bb7 Mon Sep 17 00:00:00 2001 From: Jeff Mealo Date: Mon, 22 Sep 2025 10:47:56 -0400 Subject: [PATCH 05/13] docs: add troubleshooting section (#509) Signed-off-by: Jeff Mealo Signed-off-by: Gabriele Bartolini Signed-off-by: Jonathan Battiato Co-authored-by: Gabriele Bartolini Co-authored-by: Jonathan Battiato --- .wordlist.txt | 21 ++ web/docs/intro.md | 27 +- web/docs/troubleshooting.md | 580 ++++++++++++++++++++++++++++++++++++ web/docs/usage.md | 33 +- 4 files changed, 653 insertions(+), 8 deletions(-) create mode 100644 web/docs/troubleshooting.md diff --git a/.wordlist.txt b/.wordlist.txt index a87ab7b..fd703f4 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,3 +1,4 @@ +AccessDenied AdditionalContainerArgs Akamai Azurite @@ -21,9 +22,12 @@ IRSA IfNotPresent InstanceSidecarConfiguration JSON +Kustomize Lifecycle Linode MinIO +Misconfiguration +NoSuchBucket ObjectMeta ObjectStore ObjectStoreSpec @@ -42,6 +46,7 @@ SAS SFO SPDX SPDX +SSL ServerRecoveryWindow Slonik TLS @@ -54,6 +59,7 @@ amz api apiVersion apiextensions +archiver args auth autocert @@ -61,11 +67,13 @@ aws backend backends barmanObjectName +barmanObjectStore barmancloud boto bzip cd cloudnative +cloudnativepg clusterrole clusterrolebinding cmctl @@ -76,7 +84,9 @@ cpu creds csi customresourcedefinition +declaratively deps +desc devel env externalClusters @@ -88,11 +98,19 @@ hostpath http https imagePullPolicy +instanceID +instanceName +instanceRole +involvedObject io isWALArchiver +jq +jsonpath kb +krew kubectl kubernetes +lastTimestamp lifecycle localhost md @@ -102,6 +120,8 @@ namespaces objectstore objectstores pluginConfiguration +podName +postgres postgresql primaryUpdateStrategy rbac @@ -112,6 +132,7 @@ retentionCheckInterval retentionPolicy rolebinding rollout +rpc sc secretKeyRef selfsigned diff --git a/web/docs/intro.md b/web/docs/intro.md index f22f383..9781d0d 100644 --- a/web/docs/intro.md +++ b/web/docs/intro.md @@ -21,11 +21,30 @@ for detailed instructions. ## Requirements -To use the Barman Cloud Plugin, you need: +Before using the Barman Cloud Plugin, ensure that the following components are +installed and properly configured: -- [CloudNativePG](https://cloudnative-pg.io) version **1.26** -- [cert-manager](https://cert-manager.io/) to enable TLS communication between - the plugin and the operator +- [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 diff --git a/web/docs/troubleshooting.md b/web/docs/troubleshooting.md new file mode 100644 index 0000000..132916b --- /dev/null +++ b/web/docs/troubleshooting.md @@ -0,0 +1,580 @@ +--- +sidebar_position: 90 +--- + +# Troubleshooting + + + +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 -c plugin-barman-cloud -f + +# View all containers in a pod +kubectl logs -n --all-containers=true + +# View previous container logs (if container restarted) +kubectl logs -n -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 + ``` +2. **Get error details and target pod**: + + ```sh + kubectl describe backups.postgresql.cnpg.io \ + -n + + kubectl get backups.postgresql.cnpg.io \ + -n \ + -o jsonpath='{.status.instanceID.podName}' + ``` +3. **Check the target pod’s sidecar logs**: + + ```sh + TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \ + -n \ + -o jsonpath='{.status.instanceID.podName}') + + kubectl logs \ + -n $TARGET_POD -c plugin-barman-cloud \ + --tail=100 | grep -E "ERROR|FATAL|panic" + ``` +4. **Check cluster events**: + + ```sh + kubectl get events -n \ + --field-selector involvedObject.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 + ``` + + 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: + barmanObjectStore: + ``` + + 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 -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 \ + -c plugin-barman-cloud --tail=100 + + # Look for restore-related errors + kubectl logs -n \ + -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 -o yaml + + # Check PostgreSQL recovery logs + kubectl logs -n \ + -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: + spec: + storage: + size: 1Gi + + bootstrap: + recovery: + source: origin + recoveryTarget: + targetTime: "2024-01-15 10:30:00" + + externalClusters: + - name: origin + plugin: + enabled: true + name: barman-cloud.cloudnative-pg.io + parameters: + barmanObjectName: + serverName: + ``` + +2. **Check sidecar logs for WAL-related errors** + + ```sh + kubectl logs -n \ + -c plugin-barman-cloud | grep -i wal + ``` + +:::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 -o yaml + + # Verify the secret exists and has correct keys for your provider + kubectl get secret -n \ + -o jsonpath='{.data}' | jq 'keys' + ``` + +2. **Check sidecar logs for connectivity issues** + ```sh + kubectl logs -n \ + -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` and `s3UsePathStyle` 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 -n + +# View cluster status in detail +kubectl cnpg status -n --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 \ + --method=barmanObjectStore + + # New command (plugin-based) + kubectl cnpg backup -n \ + --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 + +# Get detailed backup information including error messages and target instance +kubectl describe backups.postgresql.cnpg.io \ + -n + +# Extract the target pod name from a failed backup +kubectl get backups.postgresql.cnpg.io \ + -n \ + -o jsonpath='{.status.instanceID.podName}' + +# Get more details including the target pod, method, phase, and error +kubectl get backups.postgresql.cnpg.io \ + -n \ + -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 -n --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 \ + -o jsonpath='{.status.instanceID.podName}') +echo "Backup target pod: $TARGET_POD" + +# Check the sidecar logs on the specific target pod +kubectl logs -n $TARGET_POD \ + -c plugin-barman-cloud --tail=100 + +# Follow the logs in real time +kubectl logs -n $TARGET_POD \ + -c plugin-barman-cloud -f + +# Check for specific errors in the target pod around the backup time +kubectl logs -n $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 -l cnpg.io/cluster= \ + -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 -l cnpg.io/cluster= -o name); do + echo "=== Checking $pod ===" + kubectl logs -n $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 \ + --field-selector involvedObject.name= + +# Check events for failed backups +kubectl get events -n \ + --field-selector involvedObject.kind=Backup + +# Get all recent events in the namespace +kubectl get events -n --sort-by='.lastTimestamp' | tail -20 +``` + +### Verify `ObjectStore` Configuration + +```sh +# Check the ObjectStore resource +kubectl get objectstores.barmancloud.cnpg.io \ + -n -o yaml + +# Verify the secret exists and has the correct keys +kubectl get secret -n -o yaml +# Alternatively +kubectl get secret -n -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. + diff --git a/web/docs/usage.md b/web/docs/usage.md index dcff072..bce6ae3 100644 --- a/web/docs/usage.md +++ b/web/docs/usage.md @@ -81,8 +81,13 @@ 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: +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 @@ -97,8 +102,28 @@ spec: name: barman-cloud.cloudnative-pg.io ``` -:::note -You can apply the same concept to the `ScheduledBackup` resource. +### 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 \ + --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 --method=barmanObjectStore + +# New command (plugin-based backup) +kubectl cnpg backup -n \ + --method=plugin \ + --plugin-name=barman-cloud.cloudnative-pg.io +``` ::: ## Restoring a Cluster From ad15dc8b35f8ece8f08b05b8af781019b225e8c6 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Tue, 23 Sep 2025 09:03:05 +0200 Subject: [PATCH 06/13] chore(deps): update all sagikazarmark daggerverse dependencies to f55cb35 (#546) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- Taskfile.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 8151e37..0ba9359 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -19,7 +19,7 @@ tasks: desc: Run golangci-lint env: # renovate: datasource=git-refs depName=golangci-lint lookupName=https://github.com/sagikazarmark/daggerverse currentValue=main - DAGGER_GOLANGCI_LINT_SHA: 88056b48085a170fbf7638e106efbecd26c6573d + DAGGER_GOLANGCI_LINT_SHA: f55cb35d9ea80497c5906468628f70b805528985 # renovate: datasource=docker depName=golangci/golangci-lint versioning=semver GOLANGCI_LINT_VERSION: v2.5.0 cmds: @@ -482,7 +482,7 @@ tasks: IMAGE_VERSION: '{{regexReplaceAll "(\\d+)/merge" .GITHUB_REF_NAME "pr-${1}"}}' env: # renovate: datasource=git-refs depName=kustomize lookupName=https://github.com/sagikazarmark/daggerverse currentValue=main - DAGGER_KUSTOMIZE_SHA: 88056b48085a170fbf7638e106efbecd26c6573d + DAGGER_KUSTOMIZE_SHA: f55cb35d9ea80497c5906468628f70b805528985 cmds: - > dagger -s call -m https://github.com/sagikazarmark/daggerverse/kustomize@${DAGGER_KUSTOMIZE_SHA} @@ -512,7 +512,7 @@ tasks: - GITHUB_TOKEN env: # renovate: datasource=git-refs depName=gh lookupName=https://github.com/sagikazarmark/daggerverse - DAGGER_GH_SHA: 88056b48085a170fbf7638e106efbecd26c6573d + DAGGER_GH_SHA: f55cb35d9ea80497c5906468628f70b805528985 preconditions: - sh: "[[ {{.GITHUB_REF}} =~ 'refs/tags/v.*' ]]" msg: not a tag, failing From 21604721c49e198098d669ab28b59810eb3f1c57 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Tue, 23 Sep 2025 09:59:56 +0200 Subject: [PATCH 07/13] chore(deps): update all sagikazarmark daggerverse dependencies to 6133ad1 (#547) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- Taskfile.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 0ba9359..4464f49 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -19,7 +19,7 @@ tasks: desc: Run golangci-lint env: # renovate: datasource=git-refs depName=golangci-lint lookupName=https://github.com/sagikazarmark/daggerverse currentValue=main - DAGGER_GOLANGCI_LINT_SHA: f55cb35d9ea80497c5906468628f70b805528985 + DAGGER_GOLANGCI_LINT_SHA: 6133ad18e131b891d4723b8e25d69f5de077b472 # renovate: datasource=docker depName=golangci/golangci-lint versioning=semver GOLANGCI_LINT_VERSION: v2.5.0 cmds: @@ -482,7 +482,7 @@ tasks: IMAGE_VERSION: '{{regexReplaceAll "(\\d+)/merge" .GITHUB_REF_NAME "pr-${1}"}}' env: # renovate: datasource=git-refs depName=kustomize lookupName=https://github.com/sagikazarmark/daggerverse currentValue=main - DAGGER_KUSTOMIZE_SHA: f55cb35d9ea80497c5906468628f70b805528985 + DAGGER_KUSTOMIZE_SHA: 6133ad18e131b891d4723b8e25d69f5de077b472 cmds: - > dagger -s call -m https://github.com/sagikazarmark/daggerverse/kustomize@${DAGGER_KUSTOMIZE_SHA} @@ -512,7 +512,7 @@ tasks: - GITHUB_TOKEN env: # renovate: datasource=git-refs depName=gh lookupName=https://github.com/sagikazarmark/daggerverse - DAGGER_GH_SHA: f55cb35d9ea80497c5906468628f70b805528985 + DAGGER_GH_SHA: 6133ad18e131b891d4723b8e25d69f5de077b472 preconditions: - sh: "[[ {{.GITHUB_REF}} =~ 'refs/tags/v.*' ]]" msg: not a tag, failing From 77aa6e04ff3b8bf69b41c989d22b7d15bf71a475 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Tue, 23 Sep 2025 10:39:04 +0200 Subject: [PATCH 08/13] chore(deps): update all cloudnative-pg daggerverse dependencies to 3923866 (#548) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- Taskfile.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 4464f49..2ab9d07 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -44,7 +44,7 @@ tasks: - wordlist-ordered env: # renovate: datasource=git-refs depName=spellcheck lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main - DAGGER_SPELLCHECK_SHA: 838ccbbd35b0e5e9a7d4af600fa8fa1a4259b1d0 + DAGGER_SPELLCHECK_SHA: 3923866bb6d43e7cf64047b6e910dc90687add2f cmds: - > GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/spellcheck@${DAGGER_SPELLCHECK_SHA} @@ -58,7 +58,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: 838ccbbd35b0e5e9a7d4af600fa8fa1a4259b1d0 + DAGGER_COMMITLINT_SHA: 3923866bb6d43e7cf64047b6e910dc90687add2f cmds: - > GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/commitlint@${DAGGER_COMMITLINT_SHA} @@ -72,7 +72,7 @@ tasks: - wordlist-ordered env: # renovate: datasource=git-refs depName=uncommitted lookupName=https://github.com/cloudnative-pg/daggerverse currentValue=main - DAGGER_UNCOMMITTED_SHA: 838ccbbd35b0e5e9a7d4af600fa8fa1a4259b1d0 + DAGGER_UNCOMMITTED_SHA: 3923866bb6d43e7cf64047b6e910dc90687add2f cmds: - GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/uncommitted@${DAGGER_UNCOMMITTED_SHA} check-uncommitted --source . stdout sources: @@ -84,7 +84,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: 838ccbbd35b0e5e9a7d4af600fa8fa1a4259b1d0 + DAGGER_CRDGENREF_SHA: 3923866bb6d43e7cf64047b6e910dc90687add2f cmds: - > GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/crd-ref-docs@${DAGGER_CRDGENREF_SHA} generate @@ -410,7 +410,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: 838ccbbd35b0e5e9a7d4af600fa8fa1a4259b1d0 + DAGGER_CONTROLLER_GEN_SHA: 3923866bb6d43e7cf64047b6e910dc90687add2f cmds: - > GITHUB_REF= dagger -s call -m github.com/cloudnative-pg/daggerverse/controller-gen@${DAGGER_CONTROLLER_GEN_SHA} From 0501e185bab4969064c5b92977747be30bd38e95 Mon Sep 17 00:00:00 2001 From: Armando Ruocco Date: Wed, 24 Sep 2025 12:32:59 +0200 Subject: [PATCH 09/13] feat: introduce `logLevel` setting to control verbosity (#536) This commit adds a new `logLevel` field to the plugin configuration, allowing users to select the desired log verbosity for the instances (e.g. error, warning, info, debug, trace). Closes #514 Signed-off-by: Armando Ruocco Signed-off-by: Gabriele Bartolini Co-authored-by: Gabriele Bartolini --- .wordlist.txt | 1 + api/v1/objectstore_types.go | 7 +++ .../barmancloud.cnpg.io_objectstores.yaml | 16 ++++++ hack/examples/minio-store.yaml | 3 +- internal/cnpgi/operator/lifecycle.go | 27 +++++++++- internal/cnpgi/operator/lifecycle_test.go | 54 +++++++++++++++++++ manifest.yaml | 16 ++++++ web/docs/plugin-barman-cloud.v1.md | 1 + 8 files changed, 121 insertions(+), 4 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index fd703f4..e872a38 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -13,6 +13,7 @@ DigitalOcean Docusaurus EDB EKS +Enum EnvVar GCP GKE diff --git a/api/v1/objectstore_types.go b/api/v1/objectstore_types.go index d9ceb52..5eeadf0 100644 --- a/api/v1/objectstore_types.go +++ b/api/v1/objectstore_types.go @@ -41,8 +41,15 @@ type InstanceSidecarConfiguration struct { // AdditionalContainerArgs is an optional list of command-line arguments // to be passed to the sidecar container when it starts. // The provided arguments are appended to the container’s default arguments. + // +kubebuilder:validation:XValidation:rule="!self.exists(a, a.startsWith('--log-level'))",reason="FieldValueForbidden",message="do not set --log-level in additionalContainerArgs; use spec.instanceSidecarConfiguration.logLevel" // +optional AdditionalContainerArgs []string `json:"additionalContainerArgs,omitempty"` + + // The log level for PostgreSQL instances. Valid values are: `error`, `warning`, `info` (default), `debug`, `trace` + // +kubebuilder:default:=info + // +kubebuilder:validation:Enum:=error;warning;info;debug;trace + // +optional + LogLevel string `json:"logLevel,omitempty"` } // ObjectStoreSpec defines the desired state of ObjectStore. diff --git a/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml b/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml index 8c7f005..7d12b8c 100644 --- a/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml +++ b/config/crd/bases/barmancloud.cnpg.io_objectstores.yaml @@ -399,6 +399,11 @@ spec: items: type: string type: array + x-kubernetes-validations: + - message: do not set --log-level in additionalContainerArgs; + use spec.instanceSidecarConfiguration.logLevel + reason: FieldValueForbidden + rule: '!self.exists(a, a.startsWith(''--log-level''))' env: description: The environment to be explicitly passed to the sidecar items: @@ -557,6 +562,17 @@ spec: - name type: object type: array + logLevel: + default: info + description: 'The log level for PostgreSQL instances. Valid values + are: `error`, `warning`, `info` (default), `debug`, `trace`' + enum: + - error + - warning + - info + - debug + - trace + type: string resources: description: Resources define cpu/memory requests and limits for the sidecar that runs in the instance pods. diff --git a/hack/examples/minio-store.yaml b/hack/examples/minio-store.yaml index 26ed965..cb9eb65 100644 --- a/hack/examples/minio-store.yaml +++ b/hack/examples/minio-store.yaml @@ -5,6 +5,7 @@ metadata: spec: retentionPolicy: "1m" instanceSidecarConfiguration: + logLevel: "debug" retentionPolicyIntervalSeconds: 1800 resources: requests: @@ -13,8 +14,6 @@ spec: limits: memory: "512Mi" cpu: "500m" - additionalContainerArgs: - - --log-level=debug configuration: endpointCA: name: minio-server-tls diff --git a/internal/cnpgi/operator/lifecycle.go b/internal/cnpgi/operator/lifecycle.go index d7eba1f..a777aaf 100644 --- a/internal/cnpgi/operator/lifecycle.go +++ b/internal/cnpgi/operator/lifecycle.go @@ -236,6 +236,19 @@ func (impl LifecycleImplementation) collectAdditionalInstanceArgs( ctx context.Context, pluginConfiguration *config.PluginConfiguration, ) ([]string, error) { + collectTypedAdditionalArgs := func(store *barmancloudv1.ObjectStore) []string { + if store == nil { + return nil + } + + var args []string + if len(store.Spec.InstanceSidecarConfiguration.LogLevel) > 0 { + args = append(args, fmt.Sprintf("--log-level=%s", store.Spec.InstanceSidecarConfiguration.LogLevel)) + } + + return args + } + // Prefer the cluster object store (backup/archive). If not set, fallback to the recovery object store. // If neither is configured, no additional args are provided. if len(pluginConfiguration.BarmanObjectName) > 0 { @@ -244,7 +257,12 @@ func (impl LifecycleImplementation) collectAdditionalInstanceArgs( return nil, fmt.Errorf("while getting barman object store %s: %w", pluginConfiguration.GetBarmanObjectKey().String(), err) } - return barmanObjectStore.Spec.InstanceSidecarConfiguration.AdditionalContainerArgs, nil + args := barmanObjectStore.Spec.InstanceSidecarConfiguration.AdditionalContainerArgs + args = append( + args, + collectTypedAdditionalArgs(&barmanObjectStore)..., + ) + return args, nil } if len(pluginConfiguration.RecoveryBarmanObjectName) > 0 { @@ -253,7 +271,12 @@ func (impl LifecycleImplementation) collectAdditionalInstanceArgs( return nil, fmt.Errorf("while getting recovery barman object store %s: %w", pluginConfiguration.GetRecoveryBarmanObjectKey().String(), err) } - return barmanObjectStore.Spec.InstanceSidecarConfiguration.AdditionalContainerArgs, nil + args := barmanObjectStore.Spec.InstanceSidecarConfiguration.AdditionalContainerArgs + args = append( + args, + collectTypedAdditionalArgs(&barmanObjectStore)..., + ) + return args, nil } return nil, nil diff --git a/internal/cnpgi/operator/lifecycle_test.go b/internal/cnpgi/operator/lifecycle_test.go index 675d657..48692ff 100644 --- a/internal/cnpgi/operator/lifecycle_test.go +++ b/internal/cnpgi/operator/lifecycle_test.go @@ -313,6 +313,60 @@ var _ = Describe("LifecycleImplementation", func() { Expect(err.Error()).To(ContainSubstring(ns + "/" + pc.RecoveryBarmanObjectName)) Expect(args).To(BeNil()) }) + + It("includes --log-level from primary object store when set", func(ctx SpecContext) { + ns := "test-ns" + cluster := &cnpgv1.Cluster{ObjectMeta: metav1.ObjectMeta{Name: "c", Namespace: ns}} + pc := &config.PluginConfiguration{ + Cluster: cluster, + BarmanObjectName: "primary-store", + } + store := &barmancloudv1.ObjectStore{ + TypeMeta: metav1.TypeMeta{Kind: "ObjectStore", APIVersion: barmancloudv1.GroupVersion.String()}, + ObjectMeta: metav1.ObjectMeta{Name: pc.BarmanObjectName, Namespace: ns}, + Spec: barmancloudv1.ObjectStoreSpec{ + InstanceSidecarConfiguration: barmancloudv1.InstanceSidecarConfiguration{ + AdditionalContainerArgs: []string{"--alpha"}, + LogLevel: "debug", + }, + }, + } + s := runtime.NewScheme() + _ = barmancloudv1.AddToScheme(s) + cli := fake.NewClientBuilder().WithScheme(s).WithRuntimeObjects(store).Build() + + impl := LifecycleImplementation{Client: cli} + args, err := impl.collectAdditionalInstanceArgs(ctx, pc) + Expect(err).NotTo(HaveOccurred()) + Expect(args).To(Equal([]string{"--alpha", "--log-level=debug"})) + }) + + It("includes --log-level from recovery object store when primary not set", func(ctx SpecContext) { + ns := "test-ns" + cluster := &cnpgv1.Cluster{ObjectMeta: metav1.ObjectMeta{Name: "c", Namespace: ns}} + pc := &config.PluginConfiguration{ + Cluster: cluster, + BarmanObjectName: "", + RecoveryBarmanObjectName: "reco-store", + } + store := &barmancloudv1.ObjectStore{ + TypeMeta: metav1.TypeMeta{Kind: "ObjectStore", APIVersion: barmancloudv1.GroupVersion.String()}, + ObjectMeta: metav1.ObjectMeta{Name: pc.RecoveryBarmanObjectName, Namespace: ns}, + Spec: barmancloudv1.ObjectStoreSpec{ + InstanceSidecarConfiguration: barmancloudv1.InstanceSidecarConfiguration{ + LogLevel: "info", + }, + }, + } + s := runtime.NewScheme() + _ = barmancloudv1.AddToScheme(s) + cli := fake.NewClientBuilder().WithScheme(s).WithRuntimeObjects(store).Build() + + impl := LifecycleImplementation{Client: cli} + args, err := impl.collectAdditionalInstanceArgs(ctx, pc) + Expect(err).NotTo(HaveOccurred()) + Expect(args).To(Equal([]string{"--log-level=info"})) + }) }) }) diff --git a/manifest.yaml b/manifest.yaml index 5641fed..f2d601d 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -398,6 +398,11 @@ spec: items: type: string type: array + x-kubernetes-validations: + - message: do not set --log-level in additionalContainerArgs; + use spec.instanceSidecarConfiguration.logLevel + reason: FieldValueForbidden + rule: '!self.exists(a, a.startsWith(''--log-level''))' env: description: The environment to be explicitly passed to the sidecar items: @@ -556,6 +561,17 @@ spec: - name type: object type: array + logLevel: + default: info + description: 'The log level for PostgreSQL instances. Valid values + are: `error`, `warning`, `info` (default), `debug`, `trace`' + enum: + - error + - warning + - info + - debug + - trace + type: string resources: description: Resources define cpu/memory requests and limits for the sidecar that runs in the instance pods. diff --git a/web/docs/plugin-barman-cloud.v1.md b/web/docs/plugin-barman-cloud.v1.md index ea50bd9..7bd607c 100644 --- a/web/docs/plugin-barman-cloud.v1.md +++ b/web/docs/plugin-barman-cloud.v1.md @@ -30,6 +30,7 @@ _Appears in:_ | `retentionPolicyIntervalSeconds` _integer_ | The retentionCheckInterval defines the frequency at which the
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
to be passed to the sidecar container when it starts.
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]
| #### ObjectStore From 65a0d11ec8cf1fc6e3478d49ad88d9ba9c40adf6 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Wed, 24 Sep 2025 19:49:46 +0200 Subject: [PATCH 10/13] fix(deps): update module github.com/cloudnative-pg/cnpg-i-machinery to v0.4.1 (#551) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 10184cb..b8afdd2 100644 --- a/go.mod +++ b/go.mod @@ -8,7 +8,7 @@ require ( github.com/cloudnative-pg/barman-cloud v0.3.3 github.com/cloudnative-pg/cloudnative-pg v1.27.0 github.com/cloudnative-pg/cnpg-i v0.3.0 - github.com/cloudnative-pg/cnpg-i-machinery v0.4.0 + github.com/cloudnative-pg/cnpg-i-machinery v0.4.1 github.com/cloudnative-pg/machinery v0.3.1 github.com/onsi/ginkgo/v2 v2.25.3 github.com/onsi/gomega v1.38.2 diff --git a/go.sum b/go.sum index 26ab4cd..dac10f6 100644 --- a/go.sum +++ b/go.sum @@ -24,8 +24,8 @@ github.com/cloudnative-pg/cloudnative-pg v1.27.0 h1:mp0zlYO4vKAJmQdArWORWKr1lmB4 github.com/cloudnative-pg/cloudnative-pg v1.27.0/go.mod h1:aIVMy0BrfXg+eJuA/ZyRGyOQtPtshw/sCzQnQn3KFUo= github.com/cloudnative-pg/cnpg-i v0.3.0 h1:5ayNOG5x68lU70IVbHDZQrv5p+bErCJ0mqRmOpW2jjE= github.com/cloudnative-pg/cnpg-i v0.3.0/go.mod h1:VOIWWXcJ1RyioK+elR2DGOa4cBA6K+6UQgx05aZmH+g= -github.com/cloudnative-pg/cnpg-i-machinery v0.4.0 h1:16wQt9qFFqvyxeg+9dPt8ic8dh3PRPq0jCGXVuZyjO4= -github.com/cloudnative-pg/cnpg-i-machinery v0.4.0/go.mod h1:4MCJzbCOsB7ianxlm8rqD+gDpkgVTHoTuglle/i72WA= +github.com/cloudnative-pg/cnpg-i-machinery v0.4.1 h1:M4ELhZO0e7UjiV3PZ3uGJOz3SgG/3ThWiqkbrFCcXNE= +github.com/cloudnative-pg/cnpg-i-machinery v0.4.1/go.mod h1:TxwoMgQINOJkS1kepudqCBTYd8QYev6JoT8R52pYD4E= github.com/cloudnative-pg/machinery v0.3.1 h1:KtPA6EwELTUNisCMLiFYkK83GU9606rkGQhDJGPB8Yw= github.com/cloudnative-pg/machinery v0.3.1/go.mod h1:jebuqKxZAbrRKDEEpVCIDMKW+FbWtB9Kf/hb2kMUu9o= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= From 08c3f1c2324d79d6080fbf73f11b4fa715bec4cb Mon Sep 17 00:00:00 2001 From: Leonardo Cecchi Date: Thu, 25 Sep 2025 10:36:48 +0200 Subject: [PATCH 11/13] feat: return proper gRPC error codes for expected conditions (#549) The plugin now returns a 404 status code when a requested WAL file does not exist in the object store. This prevents misleading log entries such as "Error while handling gRPC request" for expected missing-file scenarios. The `ErrEndOfWALStreamReached` now returns `OutOfRange` error. The `ErrMissingPermissions` now returns `FailedPrecondition` error. Signed-off-by: Leonardo Cecchi Signed-off-by: Armando Ruocco Signed-off-by: Marco Nenciarini Co-authored-by: Armando Ruocco Co-authored-by: Marco Nenciarini --- internal/cnpgi/common/errors.go | 31 ++++++++++++++++++++----------- internal/cnpgi/common/wal.go | 22 ++++++++-------------- 2 files changed, 28 insertions(+), 25 deletions(-) diff --git a/internal/cnpgi/common/errors.go b/internal/cnpgi/common/errors.go index 48b2cde..3fc4fe5 100644 --- a/internal/cnpgi/common/errors.go +++ b/internal/cnpgi/common/errors.go @@ -1,16 +1,25 @@ package common -// walNotFoundError is raised when a WAL file has not been found in the object store -type walNotFoundError struct{} +import ( + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" +) -func newWALNotFoundError() *walNotFoundError { return &walNotFoundError{} } +// ErrEndOfWALStreamReached is returned when end of WAL is detected in the cloud archive. +var ErrEndOfWALStreamReached = status.Errorf(codes.OutOfRange, "end of WAL reached") -// ShouldPrintStackTrace tells whether the sidecar log stream should contain the stack trace -func (e walNotFoundError) ShouldPrintStackTrace() bool { - return false -} - -// Error implements the error interface -func (e walNotFoundError) Error() string { - return "WAL file not found" +// ErrMissingPermissions is raised when the sidecar has no +// permission to download the credentials needed to reach +// the object storage. +// This will be fixed by the reconciliation loop in the +// operator plugin. +var ErrMissingPermissions = status.Errorf(codes.FailedPrecondition, + "no permission to download the backup credentials, retrying") + +// newWALNotFoundError returns a error that states that a +// certain WAL file has not been found. This error is +// compatible with GRPC status codes, resulting in a 404 +// being used as a response code. +func newWALNotFoundError(walName string) error { + return status.Errorf(codes.NotFound, "wal %q not found", walName) } diff --git a/internal/cnpgi/common/wal.go b/internal/cnpgi/common/wal.go index 5f6c856..e15e987 100644 --- a/internal/cnpgi/common/wal.go +++ b/internal/cnpgi/common/wal.go @@ -27,13 +27,6 @@ import ( "github.com/cloudnative-pg/plugin-barman-cloud/internal/cnpgi/operator/config" ) -// ErrMissingPermissions is raised when the sidecar has no -// permission to download the credentials needed to reach -// the object storage. -// This will be fixed by the reconciliation loop in the -// operator plugin. -var ErrMissingPermissions = fmt.Errorf("no permission to download the backup credentials, retrying") - // SpoolManagementError is raised when a spool management // error has been detected type SpoolManagementError struct { @@ -95,11 +88,14 @@ func (w WALServiceImplementation) Archive( ctx context.Context, request *wal.WALArchiveRequest, ) (*wal.WALArchiveResult, error) { - contextLogger := log.FromContext(ctx) - contextLogger.Debug("starting wal archive") - baseWalName := path.Base(request.GetSourceFileName()) + contextLogger := log.FromContext(ctx) + contextLogger.Debug("wal archive start", "walName", baseWalName) + defer func() { + contextLogger.Debug("wal archive end", "walName", baseWalName) + }() + // Step 1: parse the configuration and get the environment variables needed // for barman-cloud-wal-archive configuration, err := config.NewFromClusterJSON(request.ClusterDefinition) @@ -122,6 +118,7 @@ func (w WALServiceImplementation) Archive( ) if err != nil { if apierrors.IsForbidden(err) { + contextLogger.Info(ErrMissingPermissions.Error()) return nil, ErrMissingPermissions } return nil, err @@ -350,7 +347,7 @@ func (w WALServiceImplementation) restoreFromBarmanObjectStore( // The failure has already been logged in walRestorer.RestoreList method if walStatus[0].Err != nil { if errors.Is(walStatus[0].Err, barmanRestorer.ErrWALNotFound) { - return newWALNotFoundError() + return newWALNotFoundError(walStatus[0].WalName) } return walStatus[0].Err @@ -457,9 +454,6 @@ func gatherWALFilesToRestore(walName string, parallel int) (walList []string, er return walList, err } -// ErrEndOfWALStreamReached is returned when end of WAL is detected in the cloud archive. -var ErrEndOfWALStreamReached = errors.New("end of WAL reached") - // checkEndOfWALStreamFlag returns ErrEndOfWALStreamReached if the flag is set in the restorer. func checkEndOfWALStreamFlag(walRestorer *barmanRestorer.WALRestorer) error { contain, err := walRestorer.IsEndOfWALStream() From a4469e4d7c9fbc8cb6b89face9e07a63412cdc81 Mon Sep 17 00:00:00 2001 From: Marco Nenciarini Date: Thu, 25 Sep 2025 10:47:16 +0200 Subject: [PATCH 12/13] docs: prepare documentation for release 0.7.0 (#552) Signed-off-by: Marco Nenciarini --- .../version-0.7.0/compression.md | 43 ++ web/versioned_docs/version-0.7.0/concepts.md | 177 ++++++ web/versioned_docs/version-0.7.0/images.md | 37 ++ .../version-0.7.0/installation.mdx | 109 ++++ web/versioned_docs/version-0.7.0/intro.md | 86 +++ web/versioned_docs/version-0.7.0/migration.md | 259 ++++++++ web/versioned_docs/version-0.7.0/misc.md | 76 +++ .../version-0.7.0/object_stores.md | 454 ++++++++++++++ .../version-0.7.0/parameters.md | 19 + .../version-0.7.0/plugin-barman-cloud.v1.md | 108 ++++ web/versioned_docs/version-0.7.0/retention.md | 38 ++ .../version-0.7.0/troubleshooting.md | 580 ++++++++++++++++++ web/versioned_docs/version-0.7.0/usage.md | 283 +++++++++ .../version-0.7.0-sidebars.json | 8 + web/versions.json | 1 + 15 files changed, 2278 insertions(+) create mode 100644 web/versioned_docs/version-0.7.0/compression.md create mode 100644 web/versioned_docs/version-0.7.0/concepts.md create mode 100644 web/versioned_docs/version-0.7.0/images.md create mode 100644 web/versioned_docs/version-0.7.0/installation.mdx create mode 100644 web/versioned_docs/version-0.7.0/intro.md create mode 100644 web/versioned_docs/version-0.7.0/migration.md create mode 100644 web/versioned_docs/version-0.7.0/misc.md create mode 100644 web/versioned_docs/version-0.7.0/object_stores.md create mode 100644 web/versioned_docs/version-0.7.0/parameters.md create mode 100644 web/versioned_docs/version-0.7.0/plugin-barman-cloud.v1.md create mode 100644 web/versioned_docs/version-0.7.0/retention.md create mode 100644 web/versioned_docs/version-0.7.0/troubleshooting.md create mode 100644 web/versioned_docs/version-0.7.0/usage.md create mode 100644 web/versioned_sidebars/version-0.7.0-sidebars.json diff --git a/web/versioned_docs/version-0.7.0/compression.md b/web/versioned_docs/version-0.7.0/compression.md new file mode 100644 index 0000000..2abbede --- /dev/null +++ b/web/versioned_docs/version-0.7.0/compression.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 80 +--- + +# Compression + + + +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 | diff --git a/web/versioned_docs/version-0.7.0/concepts.md b/web/versioned_docs/version-0.7.0/concepts.md new file mode 100644 index 0000000..3832df3 --- /dev/null +++ b/web/versioned_docs/version-0.7.0/concepts.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 10 +--- + +# Main Concepts + + + +:::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/). +::: diff --git a/web/versioned_docs/version-0.7.0/images.md b/web/versioned_docs/version-0.7.0/images.md new file mode 100644 index 0000000..f6c32d3 --- /dev/null +++ b/web/versioned_docs/version-0.7.0/images.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 99 +--- + +# Container Images + + + +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. diff --git a/web/versioned_docs/version-0.7.0/installation.mdx b/web/versioned_docs/version-0.7.0/installation.mdx new file mode 100644 index 0000000..027d1e8 --- /dev/null +++ b/web/versioned_docs/version-0.7.0/installation.mdx @@ -0,0 +1,109 @@ +--- +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: + + + +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 +``` diff --git a/web/versioned_docs/version-0.7.0/intro.md b/web/versioned_docs/version-0.7.0/intro.md new file mode 100644 index 0000000..9781d0d --- /dev/null +++ b/web/versioned_docs/version-0.7.0/intro.md @@ -0,0 +1,86 @@ +--- +sidebar_position: 1 +sidebar_label: "Introduction" +--- + +# Barman Cloud Plugin + + + +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). +::: diff --git a/web/versioned_docs/version-0.7.0/migration.md b/web/versioned_docs/version-0.7.0/migration.md new file mode 100644 index 0000000..43c4b80 --- /dev/null +++ b/web/versioned_docs/version-0.7.0/migration.md @@ -0,0 +1,259 @@ +--- +sidebar_position: 40 +--- + +# Migrating from Built-in CloudNativePG Backup + + + +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 +``` diff --git a/web/versioned_docs/version-0.7.0/misc.md b/web/versioned_docs/version-0.7.0/misc.md new file mode 100644 index 0000000..4d3cefc --- /dev/null +++ b/web/versioned_docs/version-0.7.0/misc.md @@ -0,0 +1,76 @@ +--- +sidebar_position: 90 +--- + +# Miscellaneous + + + +## 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/). diff --git a/web/versioned_docs/version-0.7.0/object_stores.md b/web/versioned_docs/version-0.7.0/object_stores.md new file mode 100644 index 0000000..f1714c9 --- /dev/null +++ b/web/versioned_docs/version-0.7.0/object_stores.md @@ -0,0 +1,454 @@ +--- +sidebar_position: 50 +--- + +# Object Store Providers + + + +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= \ + --from-literal=ACCESS_SECRET_KEY= +# --from-literal=ACCESS_SESSION_TOKEN= # 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 or delete 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: + endpointCA: + name: my-ca-secret + key: ca.crt + [...] +``` + + +:::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: "" + 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= \ + --from-literal=AZURE_STORAGE_KEY= \ + --from-literal=AZURE_STORAGE_SAS_TOKEN= \ + --from-literal=AZURE_STORAGE_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: "" + 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: + +``` +://..core.windows.net// +``` + +### Azure-Compatible Providers + +If you're using a different implementation (e.g., Azurite or emulator): + +``` +://:/// +``` + +--- + +## 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:///" + 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:///" + 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: +- `-console` on port 9090 (with autocert) or 9443 (without autocert) +- `-hl` on port 9000 +Where `` is the `metadata.name` you assigned to your Tenant resource. + +:::note +The `-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= \ + --from-literal=MINIO_SECRET_KEY= +``` + +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://-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. +::: + +--- diff --git a/web/versioned_docs/version-0.7.0/parameters.md b/web/versioned_docs/version-0.7.0/parameters.md new file mode 100644 index 0000000..ca0cd2b --- /dev/null +++ b/web/versioned_docs/version-0.7.0/parameters.md @@ -0,0 +1,19 @@ +--- +sidebar_position: 100 +--- + +# Parameters + + + +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. +::: diff --git a/web/versioned_docs/version-0.7.0/plugin-barman-cloud.v1.md b/web/versioned_docs/version-0.7.0/plugin-barman-cloud.v1.md new file mode 100644 index 0000000..7bd607c --- /dev/null +++ b/web/versioned_docs/version-0.7.0/plugin-barman-cloud.v1.md @@ -0,0 +1,108 @@ +# 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
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
to be passed to the sidecar container when it starts.
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]
| + + +#### 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.
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
date. Populated by the system. Read-only.
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
and WALs (i.e. '60d'). The retention policy is expressed in the form
of `XXu` where `XX` is a positive integer and `u` is in `[dwm]` -
days, weeks, months. | | | Pattern: `^[1-9][0-9]*[dwm]$`
| +| `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
the earliest point in time to which the database can be
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 | | | + + diff --git a/web/versioned_docs/version-0.7.0/retention.md b/web/versioned_docs/version-0.7.0/retention.md new file mode 100644 index 0000000..fefbd08 --- /dev/null +++ b/web/versioned_docs/version-0.7.0/retention.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 60 +--- + +# Retention Policies + + + +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. +::: + diff --git a/web/versioned_docs/version-0.7.0/troubleshooting.md b/web/versioned_docs/version-0.7.0/troubleshooting.md new file mode 100644 index 0000000..132916b --- /dev/null +++ b/web/versioned_docs/version-0.7.0/troubleshooting.md @@ -0,0 +1,580 @@ +--- +sidebar_position: 90 +--- + +# Troubleshooting + + + +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 -c plugin-barman-cloud -f + +# View all containers in a pod +kubectl logs -n --all-containers=true + +# View previous container logs (if container restarted) +kubectl logs -n -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 + ``` +2. **Get error details and target pod**: + + ```sh + kubectl describe backups.postgresql.cnpg.io \ + -n + + kubectl get backups.postgresql.cnpg.io \ + -n \ + -o jsonpath='{.status.instanceID.podName}' + ``` +3. **Check the target pod’s sidecar logs**: + + ```sh + TARGET_POD=$(kubectl get backups.postgresql.cnpg.io \ + -n \ + -o jsonpath='{.status.instanceID.podName}') + + kubectl logs \ + -n $TARGET_POD -c plugin-barman-cloud \ + --tail=100 | grep -E "ERROR|FATAL|panic" + ``` +4. **Check cluster events**: + + ```sh + kubectl get events -n \ + --field-selector involvedObject.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 + ``` + + 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: + barmanObjectStore: + ``` + + 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 -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 \ + -c plugin-barman-cloud --tail=100 + + # Look for restore-related errors + kubectl logs -n \ + -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 -o yaml + + # Check PostgreSQL recovery logs + kubectl logs -n \ + -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: + spec: + storage: + size: 1Gi + + bootstrap: + recovery: + source: origin + recoveryTarget: + targetTime: "2024-01-15 10:30:00" + + externalClusters: + - name: origin + plugin: + enabled: true + name: barman-cloud.cloudnative-pg.io + parameters: + barmanObjectName: + serverName: + ``` + +2. **Check sidecar logs for WAL-related errors** + + ```sh + kubectl logs -n \ + -c plugin-barman-cloud | grep -i wal + ``` + +:::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 -o yaml + + # Verify the secret exists and has correct keys for your provider + kubectl get secret -n \ + -o jsonpath='{.data}' | jq 'keys' + ``` + +2. **Check sidecar logs for connectivity issues** + ```sh + kubectl logs -n \ + -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` and `s3UsePathStyle` 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 -n + +# View cluster status in detail +kubectl cnpg status -n --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 \ + --method=barmanObjectStore + + # New command (plugin-based) + kubectl cnpg backup -n \ + --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 + +# Get detailed backup information including error messages and target instance +kubectl describe backups.postgresql.cnpg.io \ + -n + +# Extract the target pod name from a failed backup +kubectl get backups.postgresql.cnpg.io \ + -n \ + -o jsonpath='{.status.instanceID.podName}' + +# Get more details including the target pod, method, phase, and error +kubectl get backups.postgresql.cnpg.io \ + -n \ + -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 -n --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 \ + -o jsonpath='{.status.instanceID.podName}') +echo "Backup target pod: $TARGET_POD" + +# Check the sidecar logs on the specific target pod +kubectl logs -n $TARGET_POD \ + -c plugin-barman-cloud --tail=100 + +# Follow the logs in real time +kubectl logs -n $TARGET_POD \ + -c plugin-barman-cloud -f + +# Check for specific errors in the target pod around the backup time +kubectl logs -n $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 -l cnpg.io/cluster= \ + -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 -l cnpg.io/cluster= -o name); do + echo "=== Checking $pod ===" + kubectl logs -n $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 \ + --field-selector involvedObject.name= + +# Check events for failed backups +kubectl get events -n \ + --field-selector involvedObject.kind=Backup + +# Get all recent events in the namespace +kubectl get events -n --sort-by='.lastTimestamp' | tail -20 +``` + +### Verify `ObjectStore` Configuration + +```sh +# Check the ObjectStore resource +kubectl get objectstores.barmancloud.cnpg.io \ + -n -o yaml + +# Verify the secret exists and has the correct keys +kubectl get secret -n -o yaml +# Alternatively +kubectl get secret -n -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. + diff --git a/web/versioned_docs/version-0.7.0/usage.md b/web/versioned_docs/version-0.7.0/usage.md new file mode 100644 index 0000000..bce6ae3 --- /dev/null +++ b/web/versioned_docs/version-0.7.0/usage.md @@ -0,0 +1,283 @@ +--- +sidebar_position: 30 +--- + +# Using the Barman Cloud Plugin + + + +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/preview/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 \ + --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 --method=barmanObjectStore + +# New command (plugin-based backup) +kubectl cnpg backup -n \ + --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. +::: diff --git a/web/versioned_sidebars/version-0.7.0-sidebars.json b/web/versioned_sidebars/version-0.7.0-sidebars.json new file mode 100644 index 0000000..1fd014a --- /dev/null +++ b/web/versioned_sidebars/version-0.7.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "docs": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/web/versions.json b/web/versions.json index f3710d6..7480fcf 100644 --- a/web/versions.json +++ b/web/versions.json @@ -1,4 +1,5 @@ [ + "0.7.0", "0.6.0", "0.5.0", "0.4.1", From 69970395e2858d2084e716290170ea2be89f23a2 Mon Sep 17 00:00:00 2001 From: Peggie Date: Thu, 25 Sep 2025 11:28:56 +0200 Subject: [PATCH 13/13] chore(main): release 0.7.0 (#506) Signed-off-by: Peggie --- .release-please-manifest.json | 2 +- CHANGELOG.md | 23 +++++++++++++++++++++++ internal/cnpgi/metadata/constants.go | 2 +- 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index bcd0522..e7ca613 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.6.0" + ".": "0.7.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c55c30..b2f1b86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,28 @@ # Changelog +## [0.7.0](https://github.com/cloudnative-pg/plugin-barman-cloud/compare/v0.6.0...v0.7.0) (2025-09-25) + + +### Features + +* Introduce `logLevel` setting to control verbosity ([#536](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/536)) ([0501e18](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/0501e185bab4969064c5b92977747be30bd38e95)) +* Return proper gRPC error codes for expected conditions ([#549](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/549)) ([08c3f1c](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/08c3f1c2324d79d6080fbf73f11b4fa715bec4cb)) +* **spec:** Add support for additional sidecar container arguments ([#520](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/520)) ([ec352ac](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/ec352ac0fdd31656321e564bcf6a026481ec06e4)) + + +### Bug Fixes + +* Avoid panicking if serverRecoveryWindow has still not been set ([#525](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/525)) ([dfd9861](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/dfd9861a3f9296bffe084a81faa8755ddca95149)), closes [#523](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/523) +* **deps:** Lock file maintenance documentation dependencies ([#534](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/534)) ([0ad066d](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/0ad066d195b8556d9cf13ac0b585bfa6ffe01b75)) +* **deps:** Update all non-major go dependencies ([#521](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/521)) ([df92fa6](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/df92fa6f3e9bfd934da4be2aba4983570f751fad)) +* **deps:** Update kubernetes packages to v0.34.1 ([#530](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/530)) ([eced5ea](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/eced5ea2c6d44ec3fc09b632b42c204a5d469297)) +* **deps:** Update module github.com/cloudnative-pg/cnpg-i-machinery to v0.4.1 ([#551](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/551)) ([65a0d11](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/65a0d11ec8cf1fc6e3478d49ad88d9ba9c40adf6)) +* **deps:** Update module github.com/onsi/ginkgo/v2 to v2.25.1 ([#495](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/495)) ([2dc29a5](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/2dc29a5dbcc4e4a5b79cc2c796d2a451ffcd654a)) +* **deps:** Update module sigs.k8s.io/controller-runtime to v0.22.1 ([#531](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/531)) ([82449d9](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/82449d9351555e3b8ee128f040bffd9799279e72)) +* **logs:** Log the correct name when on ObjectStore not found error ([#540](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/540)) ([a29aa1c](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/a29aa1c91af0bc7cb4a7511c49dcc461900e9a13)), closes [#539](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/539) +* **object-cache:** Improve reliability of object cache management ([#508](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/508)) ([8c3db95](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/8c3db955efc2d23593faa0c6e410e7aa0e427ebf)), closes [#502](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/502) +* Typo in variable name ([#515](https://github.com/cloudnative-pg/plugin-barman-cloud/issues/515)) ([3c0d8c3](https://github.com/cloudnative-pg/plugin-barman-cloud/commit/3c0d8c3a3394d5b628d03c849be86999b2e7887f)) + ## [0.6.0](https://github.com/cloudnative-pg/plugin-barman-cloud/compare/v0.5.0...v0.6.0) (2025-08-21) diff --git a/internal/cnpgi/metadata/constants.go b/internal/cnpgi/metadata/constants.go index 3a5392a..a1d5d00 100644 --- a/internal/cnpgi/metadata/constants.go +++ b/internal/cnpgi/metadata/constants.go @@ -24,7 +24,7 @@ const ( // Data is the metadata of this plugin. var Data = identity.GetPluginMetadataResponse{ Name: PluginName, - Version: "0.6.0", // x-release-please-version + Version: "0.7.0", // x-release-please-version DisplayName: "BarmanCloudInstance", ProjectUrl: "https://github.com/cloudnative-pg/plugin-barman-cloud", RepositoryUrl: "https://github.com/cloudnative-pg/plugin-barman-cloud",