From c2bfe1217e8542c80dd2b099d8d966e725e2b280 Mon Sep 17 00:00:00 2001 From: Armando Ruocco Date: Mon, 27 Oct 2025 15:08:11 +0100 Subject: [PATCH] feat(rbac)!: prefix all resource names to avoid cluster conflicts (#593) BREAKING CHANGE: All RBAC resource names have been renamed with consistent prefixes to prevent naming conflicts with other cluster components. Users must migrate their existing installations by deleting old resources and applying the new manifest. See the migration guide for detailed instructions (when the 0.8.0 will be published): https://cloudnative-pg.io/plugin-barman-cloud/resource-name-migration/ Closes #395 Signed-off-by: Armando Ruocco Signed-off-by: Jonathan Battiato Signed-off-by: Gabriele Bartolini Signed-off-by: Marco Nenciarini Co-authored-by: Jonathan Battiato Co-authored-by: Gabriele Bartolini Co-authored-by: Marco Nenciarini --- .wordlist.txt | 5 + CHANGELOG.md | 8 + config/default/kustomization.yaml | 2 +- config/rbac/leader_election_role.yaml | 2 +- config/rbac/leader_election_role_binding.yaml | 4 +- config/rbac/metrics_auth_role.yaml | 2 +- config/rbac/metrics_auth_role_binding.yaml | 4 +- config/rbac/metrics_reader_role.yaml | 2 +- config/rbac/objectstore_editor_role.yaml | 2 +- config/rbac/objectstore_viewer_role.yaml | 2 +- manifest.yaml | 18 +- web/docs/resource-name-migration.md | 219 ++++++++++++++++++ web/docs/upgrades.mdx | 16 ++ 13 files changed, 267 insertions(+), 19 deletions(-) create mode 100644 web/docs/resource-name-migration.md create mode 100644 web/docs/upgrades.mdx diff --git a/.wordlist.txt b/.wordlist.txt index e872a38..d5fa782 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -49,6 +49,7 @@ SPDX SPDX SSL ServerRecoveryWindow +ServiceAccount Slonik TLS TODO @@ -106,6 +107,7 @@ involvedObject io isWALArchiver jq +json jsonpath kb krew @@ -118,6 +120,7 @@ md minio namespace namespaces +nonResourceURLs objectstore objectstores pluginConfiguration @@ -131,7 +134,9 @@ recoverability repos retentionCheckInterval retentionPolicy +roleRef rolebinding +rolebindings rollout rpc sc diff --git a/CHANGELOG.md b/CHANGELOG.md index b2f1b86..c46909a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [Unreleased] + +### BREAKING CHANGES + +* **manifests:** Resource names have been prefixed to avoid cluster conflicts + - All cluster-scoped and namespace-scoped resources now use the `barman-plugin-` prefix for consistency + - See the [Resource Name Migration Guide](https://cloudnative-pg.io/plugin-barman-cloud/resource-name-migration/) for detailed migration instructions + ## [0.7.0](https://github.com/cloudnative-pg/plugin-barman-cloud/compare/v0.6.0...v0.7.0) (2025-09-25) diff --git a/config/default/kustomization.yaml b/config/default/kustomization.yaml index 93664f3..55202da 100644 --- a/config/default/kustomization.yaml +++ b/config/default/kustomization.yaml @@ -6,7 +6,7 @@ namespace: plugin-barman-cloud-system # "wordpress" becomes "alices-wordpress". # Note that it should also match with the prefix (text before '-') of the namespace # field above. -namePrefix: plugin-barman-cloud- +#namePrefix: plugin-barman-cloud- # Labels to add to all resources and selectors. #labels: diff --git a/config/rbac/leader_election_role.yaml b/config/rbac/leader_election_role.yaml index a70e4fc..f2197af 100644 --- a/config/rbac/leader_election_role.yaml +++ b/config/rbac/leader_election_role.yaml @@ -5,7 +5,7 @@ metadata: labels: app.kubernetes.io/name: plugin-barman-cloud app.kubernetes.io/managed-by: kustomize - name: leader-election-role + name: barman-plugin-leader-election-role rules: - apiGroups: - "" diff --git a/config/rbac/leader_election_role_binding.yaml b/config/rbac/leader_election_role_binding.yaml index 5915f2c..ddb2f00 100644 --- a/config/rbac/leader_election_role_binding.yaml +++ b/config/rbac/leader_election_role_binding.yaml @@ -4,11 +4,11 @@ metadata: labels: app.kubernetes.io/name: plugin-barman-cloud app.kubernetes.io/managed-by: kustomize - name: leader-election-rolebinding + name: barman-plugin-leader-election-rolebinding roleRef: apiGroup: rbac.authorization.k8s.io kind: Role - name: leader-election-role + name: barman-plugin-leader-election-role subjects: - kind: ServiceAccount name: plugin-barman-cloud diff --git a/config/rbac/metrics_auth_role.yaml b/config/rbac/metrics_auth_role.yaml index 32d2e4e..abcb1ec 100644 --- a/config/rbac/metrics_auth_role.yaml +++ b/config/rbac/metrics_auth_role.yaml @@ -1,7 +1,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: - name: metrics-auth-role + name: barman-plugin-metrics-auth-role rules: - apiGroups: - authentication.k8s.io diff --git a/config/rbac/metrics_auth_role_binding.yaml b/config/rbac/metrics_auth_role_binding.yaml index a41825d..841b0af 100644 --- a/config/rbac/metrics_auth_role_binding.yaml +++ b/config/rbac/metrics_auth_role_binding.yaml @@ -1,11 +1,11 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: - name: metrics-auth-rolebinding + name: barman-plugin-metrics-auth-rolebinding roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole - name: metrics-auth-role + name: barman-plugin-metrics-auth-role subjects: - kind: ServiceAccount name: plugin-barman-cloud diff --git a/config/rbac/metrics_reader_role.yaml b/config/rbac/metrics_reader_role.yaml index 51a75db..2236c56 100644 --- a/config/rbac/metrics_reader_role.yaml +++ b/config/rbac/metrics_reader_role.yaml @@ -1,7 +1,7 @@ apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: - name: metrics-reader + name: barman-plugin-metrics-reader rules: - nonResourceURLs: - "/metrics" diff --git a/config/rbac/objectstore_editor_role.yaml b/config/rbac/objectstore_editor_role.yaml index 684d824..418ad0d 100644 --- a/config/rbac/objectstore_editor_role.yaml +++ b/config/rbac/objectstore_editor_role.yaml @@ -5,7 +5,7 @@ metadata: labels: app.kubernetes.io/name: plugin-barman-cloud app.kubernetes.io/managed-by: kustomize - name: objectstore-editor-role + name: barman-plugin-objectstore-editor-role rules: - apiGroups: - barmancloud.cnpg.io diff --git a/config/rbac/objectstore_viewer_role.yaml b/config/rbac/objectstore_viewer_role.yaml index 7c10c4e..26c051a 100644 --- a/config/rbac/objectstore_viewer_role.yaml +++ b/config/rbac/objectstore_viewer_role.yaml @@ -5,7 +5,7 @@ metadata: labels: app.kubernetes.io/name: plugin-barman-cloud app.kubernetes.io/managed-by: kustomize - name: objectstore-viewer-role + name: barman-plugin-objectstore-viewer-role rules: - apiGroups: - barmancloud.cnpg.io diff --git a/manifest.yaml b/manifest.yaml index 27ab676..95ed059 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -707,7 +707,7 @@ metadata: labels: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: plugin-barman-cloud - name: leader-election-role + name: barman-plugin-leader-election-role namespace: cnpg-system rules: - apiGroups: @@ -745,7 +745,7 @@ rules: apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: - name: metrics-auth-role + name: barman-plugin-metrics-auth-role rules: - apiGroups: - authentication.k8s.io @@ -763,7 +763,7 @@ rules: apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: - name: metrics-reader + name: barman-plugin-metrics-reader rules: - nonResourceURLs: - /metrics @@ -776,7 +776,7 @@ metadata: labels: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: plugin-barman-cloud - name: objectstore-editor-role + name: barman-plugin-objectstore-editor-role rules: - apiGroups: - barmancloud.cnpg.io @@ -803,7 +803,7 @@ metadata: labels: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: plugin-barman-cloud - name: objectstore-viewer-role + name: barman-plugin-objectstore-viewer-role rules: - apiGroups: - barmancloud.cnpg.io @@ -894,12 +894,12 @@ metadata: labels: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: plugin-barman-cloud - name: leader-election-rolebinding + name: barman-plugin-leader-election-rolebinding namespace: cnpg-system roleRef: apiGroup: rbac.authorization.k8s.io kind: Role - name: leader-election-role + name: barman-plugin-leader-election-role subjects: - kind: ServiceAccount name: plugin-barman-cloud @@ -908,11 +908,11 @@ subjects: apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: - name: metrics-auth-rolebinding + name: barman-plugin-metrics-auth-rolebinding roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole - name: metrics-auth-role + name: barman-plugin-metrics-auth-role subjects: - kind: ServiceAccount name: plugin-barman-cloud diff --git a/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md new file mode 100644 index 0000000..f5c1cc3 --- /dev/null +++ b/web/docs/resource-name-migration.md @@ -0,0 +1,219 @@ +--- +sidebar_position: 90 +--- + +# Resource name migration guide + + + +:::warning +Before proceeding with the migration process, please: +1. **Read this guide in its entirety** to understand what changes will be made +2. **Test in a non-production environment** first if possible +3. **Ensure you have proper backups** of your cluster configuration + +This migration will delete old RBAC resources only after the +`plugin-barman-cloud` upgrade. While the operation is designed to be safe, you +should review and understand the changes before proceeding. The maintainers of +this project are not responsible for any issues that may arise during +migration. + +**Note:** This guide assumes you are using the default `cnpg-system` namespace. +::: + +## Overview + +Starting from version **0.8.0**, the `plugin-barman-cloud` deployment manifests +use more specific, prefixed resource names to avoid conflicts with other +components deployed in the same Kubernetes cluster. + +## What Changed + +The following resources have been renamed to use proper prefixes. + +### Cluster-scoped Resources + +| Old Name | New Name | +|----------------------------|------------------------------------------| +| `metrics-auth-role` | `barman-plugin-metrics-auth-role` | +| `metrics-auth-rolebinding` | `barman-plugin-metrics-auth-rolebinding` | +| `metrics-reader` | `barman-plugin-metrics-reader` | +| `objectstore-viewer-role` | `barman-plugin-objectstore-viewer-role` | +| `objectstore-editor-role` | `barman-plugin-objectstore-editor-role` | + +### Namespace-scoped Resources + +| Old Name | New Name | Namespace | +|-------------------------------|---------------------------------------------|---------------| +| `leader-election-role` | `barman-plugin-leader-election-role` | `cnpg-system` | +| `leader-election-rolebinding` | `barman-plugin-leader-election-rolebinding` | `cnpg-system` | + +## Why This Change? + +Using generic names for cluster-wide resources is discouraged as they may +conflict with other components deployed in the same cluster. The new names make +it clear that these resources belong to the Barman Cloud plugin and help avoid +naming collisions. + +## Migration Instructions + +This three steps migration process is straightforward and can be completed with +a few `kubectl` commands. + +### Step 1: Upgrade plugin-barman-cloud + +Please refer to the [Installation](installation.mdx) section to deploy the new +`plugin-barman-cloud` release. + +### Step 2: Delete Old Cluster-scoped Resources + +:::danger Verify Resources Before Deletion +**IMPORTANT**: The old resource names are generic and could potentially belong +to other components in your cluster. + +**Before deleting each resource, verify it belongs to the Barman Cloud plugin +by checking:** +- For `objectstore-*` roles: Look for `barmancloud.cnpg.io` in the API groups +- For `metrics-*` roles: Check if they reference the `plugin-barman-cloud` + ServiceAccount in `cnpg-system` namespace +- For other roles: Look for labels like `app.kubernetes.io/name: plugin-barman-cloud` + +If a resource doesn't have these indicators, **DO NOT DELETE IT** as it may +belong to another application. + +Carefully review the output of each verification command before proceeding with +the `delete`. +::: + +:::tip Dry Run First +You can add `--dry-run=client` to any `kubectl delete` command to preview what +would be deleted without actually removing anything. +::: + +**Only proceed if you've verified these resources belong to the Barman Cloud +plugin (see warning above).** + +For each resource below, first verify it belongs to Barman Cloud, then delete +it: + +```bash +# 1. Check metrics-auth-rolebinding FIRST (we'll check the role after) +# Look for references to plugin-barman-cloud ServiceAccount +kubectl describe clusterrolebinding metrics-auth-rolebinding +# If it references plugin-barman-cloud ServiceAccount in cnpg-system namespace, +# delete it: +kubectl delete clusterrolebinding metrics-auth-rolebinding + +# 2. Check metrics-auth-role +# Look for references to authentication.k8s.io and authorization.k8s.io +kubectl describe clusterrole metrics-auth-role +# Verify it's not being used by any other rolebindings: +kubectl get clusterrolebinding -o json \ + | jq -r '.items[] | select(.roleRef.name=="metrics-auth-role") \ + | .metadata.name' +# If the above returns nothing (role is not in use) and the role looks like the +# Barman Cloud one, delete it (see warnings section): +kubectl delete clusterrole metrics-auth-role + +# 3. Check objectstore-viewer-role +# Look for barmancloud.cnpg.io API group or +# for `app.kubernetes.io/name: plugin-barman-cloud` label +kubectl describe clusterrole objectstore-viewer-role +# If it shows barmancloud.cnpg.io in API groups, delete it: +kubectl delete clusterrole objectstore-viewer-role + +# 4. Check objectstore-editor-role +# Look for barmancloud.cnpg.io API group or +# for `app.kubernetes.io/name: plugin-barman-cloud` label +kubectl describe clusterrole objectstore-editor-role +# If it shows barmancloud.cnpg.io in API groups, delete it: +kubectl delete clusterrole objectstore-editor-role + +# 5. Check metrics-reader (MOST DANGEROUS - very generic name) +# First, check if it's being used by any rolebindings OTHER than barman's: +kubectl get clusterrolebinding -o json | jq -r '.items[] \ + | select(.roleRef.name=="metrics-reader") \ + | "\(.metadata.name) -> \(.subjects[0].name) in \(.subjects[0].namespace)"' +# If this shows ANY rolebindings, review them carefully. Only proceed if +# they're all Barman-related. Then check the role itself: +kubectl describe clusterrole metrics-reader +# If it ONLY has nonResourceURLs: /metrics and NO other rolebindings use it, +# delete it: +kubectl delete clusterrole metrics-reader +``` + +:::warning +The `metrics-reader` role is particularly dangerous to delete blindly. Many +monitoring systems use this exact name. Only delete it if: + +1. You've verified it ONLY grants access to `/metrics` +2. No other rolebindings reference it (checked with the jq command above) +3. You're certain it was created by the Barman Cloud plugin + +If you're unsure, it's safer to leave it and let the new +`barman-plugin-metrics-reader` role coexist with it. +::: + +If any resource is not found during the `describe` command, that's okay - it +means it was never created or already deleted. Simply skip the delete command +for that resource. + +### Step 3: Delete Old Namespace-scoped Resources + +Delete the old namespace-scoped resources in the `cnpg-system` namespace: + +```bash +# Delete the old leader-election resources +kubectl delete role leader-election-role -n cnpg-system +kubectl delete rolebinding leader-election-rolebinding -n cnpg-system +``` + +If any resource is not found, that's okay - it means it was never created or +already deleted. + +## Impact + +- **Permissions:** If you have custom RBAC rules or tools that reference the + old resource names, they will need to be updated. +- **External Users:** If end users have been granted the + `objectstore-viewer-role` or `objectstore-editor-role`, they will need to be + re-granted the new role names (`barman-plugin-objectstore-viewer-role` and + `barman-plugin-objectstore-editor-role`). + +## Verification + +After migration, verify that the new resources are created: + +```bash +# Check cluster-scoped resources +kubectl get clusterrole | grep barman +kubectl get clusterrolebinding | grep barman + +# Check namespace-scoped resources +kubectl get role,rolebinding -n cnpg-system | grep barman +``` + +You should see the new prefixed resource names. + +## Troubleshooting + +### Plugin Not Starting After Migration + +If the plugin fails to start after migration, check: + +1. **ServiceAccount permissions:** Ensure the `plugin-barman-cloud` ServiceAccount is bound to the new roles: + ```bash + kubectl get clusterrolebinding barman-plugin-metrics-auth-rolebinding -o yaml + kubectl get rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system -o yaml + ``` + +2. **Role references:** Verify that the rolebindings reference the correct role names: + ```bash + kubectl describe rolebinding barman-plugin-leader-election-rolebinding -n cnpg-system + kubectl describe clusterrolebinding barman-plugin-metrics-auth-rolebinding + ``` + +## Support + +If you encounter issues during migration, please open an issue on the [GitHub +repository](https://github.com/cloudnative-pg/plugin-barman-cloud/issues). diff --git a/web/docs/upgrades.mdx b/web/docs/upgrades.mdx new file mode 100644 index 0000000..0ab9ddb --- /dev/null +++ b/web/docs/upgrades.mdx @@ -0,0 +1,16 @@ +--- +sidebar_position: 25 +--- + +# Upgrades + + + +You can upgrade the plugin simply by installing the new version. Unless +explicitly stated below or in the release notes, no special steps are required. + +## Upgrading to version 0.8.x from previous versions + +Version **0.8.0** introduces breaking changes to resource naming. +To complete the upgrade successfully, follow the instructions in the +["Resource name migration guide"](resource-name-migration.md).