From 6f712151df9f6dd8fe0e8f0f374de92f90827c7e Mon Sep 17 00:00:00 2001 From: Krypton Date: Thu, 3 Sep 2026 17:35:45 +0200 Subject: [PATCH] docs: add Helm chart installation (#599) Add Helm chart install steps next to kubectl, for the current docs and the 0.13.0 and 0.14.0 versioned snapshots. Pin the chart's image tag to the plugin version on older releases. The chart ships after the plugin, so its own version numbers don't map to ours, and we skip the pin on the latest release since the chart already defaults to itself there. On the current docs, make clear the Helm tab installs the latest release, not a main-branch build. Only kubectl can test a main-branch build. Closes #351 Signed-off-by: Krypton Signed-off-by: danishedb Signed-off-by: Marco Nenciarini Co-authored-by: danishedb Co-authored-by: Marco Nenciarini --- web/docs/installation.mdx | 48 ++++++++++++++++++- web/docs/troubleshooting.md | 9 +--- web/src/components/HelmInstallation/index.tsx | 36 ++++++++++++++ web/src/components/Installation/index.tsx | 13 +++-- .../version-0.13.0/installation.mdx | 46 +++++++++++++++++- .../version-0.13.0/troubleshooting.md | 9 +--- .../version-0.14.0/installation.mdx | 44 ++++++++++++++++- .../version-0.14.0/troubleshooting.md | 9 +--- 8 files changed, 183 insertions(+), 31 deletions(-) create mode 100644 web/src/components/HelmInstallation/index.tsx diff --git a/web/docs/installation.mdx b/web/docs/installation.mdx index 4c1c48a..bff100b 100644 --- a/web/docs/installation.mdx +++ b/web/docs/installation.mdx @@ -54,7 +54,47 @@ Both checks are required before proceeding with the installation. ## Installing the Barman Cloud Plugin +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { InstallationSnippet, ManifestVersion } from '@site/src/components/Installation'; +import { HelmInstallationSnippet } from '@site/src/components/HelmInstallation'; + + + + +The plugin can be installed using the provided [Helm chart](https://github.com/cloudnative-pg/charts/tree/main/charts/plugin-barman-cloud). +This installs the latest published chart release; to test an unreleased +development snapshot instead, switch to the [**Manifest (kubectl)**](./?install-method=kubectl#installing-the-barman-cloud-plugin) tab. + + + +Example output: + +```output +Release "plugin-barman-cloud" does not exist. Installing it now. +NAME: plugin-barman-cloud +LAST DEPLOYED: Wed Jul 1 09:05:16 2026 +NAMESPACE: cnpg-system +STATUS: deployed +REVISION: 1 +DESCRIPTION: Install complete +TEST SUITE: None +``` + +Finally, check that the deployment is up and running: + +```sh +kubectl -n cnpg-system rollout status deploy/plugin-barman-cloud +``` + +Example output: + +```output +deployment "plugin-barman-cloud" successfully rolled out +``` + + + Install the plugin using `kubectl` by applying the manifest for : @@ -85,8 +125,7 @@ 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 +kubectl -n cnpg-system rollout status deploy/barman-cloud ``` Example output: @@ -95,6 +134,11 @@ Example output: deployment "barman-cloud" successfully rolled out ``` + + + +--- + This confirms that the plugin is deployed and ready to use. ## Testing the latest development snapshot diff --git a/web/docs/troubleshooting.md b/web/docs/troubleshooting.md index fe57262..c57a81e 100644 --- a/web/docs/troubleshooting.md +++ b/web/docs/troubleshooting.md @@ -485,14 +485,10 @@ If problems persist: ### 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 +1. **Sidecar resource sharing**: The plugin sidecar container shares pod resources with PostgreSQL -3. **Plugin restart behavior**: Restarting the sidecar container requires +2. **Plugin restart behavior**: Restarting the sidecar container requires restarting the entire PostgreSQL pod ## Recap of General Debugging Steps @@ -588,4 +584,3 @@ kubectl get secret -n -o jsonpath='{.data}' | jq 'keys * **"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/src/components/HelmInstallation/index.tsx b/web/src/components/HelmInstallation/index.tsx new file mode 100644 index 0000000..af5f79b --- /dev/null +++ b/web/src/components/HelmInstallation/index.tsx @@ -0,0 +1,36 @@ +import {ReactElement} from 'react'; +import CodeBlock from '@theme/CodeBlock'; +import {useActiveVersion, useLatestVersion} from '@docusaurus/plugin-content-docs/client'; + +// HelmInstallationSnippet is the Helm command to install the plugin. +// +// - Latest release: no override. The chart already defaults to +// itself. +// - Older release: pin image.tag and sidecarImage.tag to that +// version. We check this again on every build using +// useLatestVersion, so an old page updates itself once a newer +// version ships. +// - Dev docs: also no override, but this does NOT install a dev +// build. Setting the tag alone would not be enough, since the +// chart's own templates (CRDs, RBAC...) can be older than what +// main needs. Use the kubectl method to test a dev build. +export function HelmInstallationSnippet(): ReactElement { + const activeVersion = useActiveVersion('default'); + const latestVersion = useLatestVersion('default'); + const isOlderRelease = activeVersion + && activeVersion.name !== 'current' + && activeVersion.name !== latestVersion.name; + const setArgs = isOlderRelease + ? ` \\ + --set image.tag=v${activeVersion.name} \\ + --set sidecarImage.tag=v${activeVersion.name}` + : ''; + return ( + + {`helm repo add cnpg https://cloudnative-pg.github.io/charts --force-update +helm upgrade --install plugin-barman-cloud \\ + --namespace cnpg-system${setArgs} \\ + cnpg/plugin-barman-cloud`} + + ); +} diff --git a/web/src/components/Installation/index.tsx b/web/src/components/Installation/index.tsx index 359bd95..787c73f 100644 --- a/web/src/components/Installation/index.tsx +++ b/web/src/components/Installation/index.tsx @@ -1,5 +1,7 @@ import {ReactElement} from 'react'; import CodeBlock from '@theme/CodeBlock'; +import Link from '@docusaurus/Link'; +import {useLocation} from '@docusaurus/router'; import {useActiveVersion} from '@docusaurus/plugin-content-docs/client'; // DEV_MANIFEST_URL is the URL of the manifest.yaml on the main branch of the plugin repo. @@ -31,14 +33,17 @@ export function ManifestVersion(): ReactElement { : <>the latest development snapshot from the main branch; } -// DevSnapshotSection offers the main-branch manifest as an alternative; -// on the Dev docs the main install already is that manifest, so hide it. +// DevSnapshotSection shows how to test the main-branch manifest. On +// the Dev docs, the kubectl install above already does that, so we +// hide this section there. (The Helm tab there installs the latest +// release, not a dev build.) export function DevSnapshotSection(): ReactElement { const activeVersion = useActiveVersion('default'); + const {pathname} = useLocation(); if (!activeVersion || activeVersion.name === 'current') { return ( -

The install - command above already applies the latest development +

The kubectl + install command above already applies the latest development snapshot from the main branch.

); } diff --git a/web/versioned_docs/version-0.13.0/installation.mdx b/web/versioned_docs/version-0.13.0/installation.mdx index 4c1c48a..9df96d1 100644 --- a/web/versioned_docs/version-0.13.0/installation.mdx +++ b/web/versioned_docs/version-0.13.0/installation.mdx @@ -54,7 +54,45 @@ Both checks are required before proceeding with the installation. ## Installing the Barman Cloud Plugin +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { InstallationSnippet, ManifestVersion } from '@site/src/components/Installation'; +import { HelmInstallationSnippet } from '@site/src/components/HelmInstallation'; + + + + +The plugin can be installed using the provided [Helm chart](https://github.com/cloudnative-pg/charts/tree/main/charts/plugin-barman-cloud): + + + +Example output: + +```output +Release "plugin-barman-cloud" does not exist. Installing it now. +NAME: plugin-barman-cloud +LAST DEPLOYED: Wed Jul 1 09:05:16 2026 +NAMESPACE: cnpg-system +STATUS: deployed +REVISION: 1 +DESCRIPTION: Install complete +TEST SUITE: None +``` + +Finally, check that the deployment is up and running: + +```sh +kubectl -n cnpg-system rollout status deploy/plugin-barman-cloud +``` + +Example output: + +```output +deployment "plugin-barman-cloud" successfully rolled out +``` + + + Install the plugin using `kubectl` by applying the manifest for : @@ -85,8 +123,7 @@ 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 +kubectl -n cnpg-system rollout status deploy/barman-cloud ``` Example output: @@ -95,6 +132,11 @@ Example output: deployment "barman-cloud" successfully rolled out ``` + + + +--- + This confirms that the plugin is deployed and ready to use. ## Testing the latest development snapshot diff --git a/web/versioned_docs/version-0.13.0/troubleshooting.md b/web/versioned_docs/version-0.13.0/troubleshooting.md index fe57262..c57a81e 100644 --- a/web/versioned_docs/version-0.13.0/troubleshooting.md +++ b/web/versioned_docs/version-0.13.0/troubleshooting.md @@ -485,14 +485,10 @@ If problems persist: ### 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 +1. **Sidecar resource sharing**: The plugin sidecar container shares pod resources with PostgreSQL -3. **Plugin restart behavior**: Restarting the sidecar container requires +2. **Plugin restart behavior**: Restarting the sidecar container requires restarting the entire PostgreSQL pod ## Recap of General Debugging Steps @@ -588,4 +584,3 @@ kubectl get secret -n -o jsonpath='{.data}' | jq 'keys * **"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.14.0/installation.mdx b/web/versioned_docs/version-0.14.0/installation.mdx index 4c1c48a..a4cb684 100644 --- a/web/versioned_docs/version-0.14.0/installation.mdx +++ b/web/versioned_docs/version-0.14.0/installation.mdx @@ -54,7 +54,45 @@ Both checks are required before proceeding with the installation. ## Installing the Barman Cloud Plugin +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { InstallationSnippet, ManifestVersion } from '@site/src/components/Installation'; +import { HelmInstallationSnippet } from '@site/src/components/HelmInstallation'; + + + + +The plugin can be installed using the provided [Helm chart](https://github.com/cloudnative-pg/charts/tree/main/charts/plugin-barman-cloud): + + + +Example output: + +```output +Release "plugin-barman-cloud" does not exist. Installing it now. +NAME: plugin-barman-cloud +LAST DEPLOYED: Wed Jul 1 09:05:16 2026 +NAMESPACE: cnpg-system +STATUS: deployed +REVISION: 1 +DESCRIPTION: Install complete +TEST SUITE: None +``` + +Finally, check that the deployment is up and running: + +```sh +kubectl -n cnpg-system rollout status deploy/plugin-barman-cloud +``` + +Example output: + +```output +deployment "plugin-barman-cloud" successfully rolled out +``` + + + Install the plugin using `kubectl` by applying the manifest for : @@ -85,8 +123,7 @@ 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 +kubectl -n cnpg-system rollout status deploy/barman-cloud ``` Example output: @@ -95,6 +132,9 @@ Example output: deployment "barman-cloud" successfully rolled out ``` + + + This confirms that the plugin is deployed and ready to use. ## Testing the latest development snapshot diff --git a/web/versioned_docs/version-0.14.0/troubleshooting.md b/web/versioned_docs/version-0.14.0/troubleshooting.md index fe57262..c57a81e 100644 --- a/web/versioned_docs/version-0.14.0/troubleshooting.md +++ b/web/versioned_docs/version-0.14.0/troubleshooting.md @@ -485,14 +485,10 @@ If problems persist: ### 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 +1. **Sidecar resource sharing**: The plugin sidecar container shares pod resources with PostgreSQL -3. **Plugin restart behavior**: Restarting the sidecar container requires +2. **Plugin restart behavior**: Restarting the sidecar container requires restarting the entire PostgreSQL pod ## Recap of General Debugging Steps @@ -588,4 +584,3 @@ kubectl get secret -n -o jsonpath='{.data}' | jq 'keys * **"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. -