From 27d073a55fd4ebcb357295801a11ecebfdf9ec85 Mon Sep 17 00:00:00 2001 From: Armando Ruocco Date: Tue, 14 Oct 2025 11:24:32 +0200 Subject: [PATCH 1/8] feat(rbac)!: prefix all resource names to avoid cluster conflicts 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: https://cloudnative-pg.io/plugin-barman-cloud/resource-name-migration/ Signed-off-by: Armando Ruocco --- CHANGELOG.md | 8 + 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 +- web/docs/resource-name-migration.md | 189 +++++++++++++ web/static/migration-rbac.yaml | 248 ++++++++++++++++++ 10 files changed, 454 insertions(+), 9 deletions(-) create mode 100644 web/docs/resource-name-migration.md create mode 100644 web/static/migration-rbac.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index b2f1b865..c46909ac 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/rbac/leader_election_role.yaml b/config/rbac/leader_election_role.yaml index a70e4fcc..f2197af5 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 5915f2c9..ddb2f008 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 32d2e4ec..abcb1ec0 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 a41825db..841b0af7 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 51a75db4..2236c567 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 684d8245..418ad0d8 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 7c10c4ee..26c051a5 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/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md new file mode 100644 index 00000000..7965948f --- /dev/null +++ b/web/docs/resource-name-migration.md @@ -0,0 +1,189 @@ +--- +sidebar_position: 41 +--- + +# Resource Name Migration Guide + + + +:::warning +Before running the migration script or applying the manifest, please: +1. **Review the complete manifest** on the [Migration Manifest](migration-manifest.md) page 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 +4. **Verify the resource names match** your current installation (default namespace is `cnpg-system`) + +This migration will delete old RBAC resources and create new ones. 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. +::: + +## 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 + +The migration process is straightforward and can be completed with a few kubectl commands. + +:::danger Verify Resources Before Deletion +**IMPORTANT**: The old resource names are generic and could potentially belong to other components in your cluster. Before deleting, verify they belong to the barman plugin by checking their labels: + +```bash +# Check if the resources have the barman plugin labels +kubectl get clusterrole metrics-auth-role -o yaml | grep -A 5 "labels:" +kubectl get clusterrole metrics-reader -o yaml | grep -A 5 "labels:" +kubectl get clusterrole objectstore-viewer-role -o yaml | grep -A 5 "labels:" +kubectl get clusterrole objectstore-editor-role -o yaml | grep -A 5 "labels:" +kubectl get clusterrolebinding metrics-auth-rolebinding -o yaml | grep -A 5 "labels:" +``` + +Look for labels like `app.kubernetes.io/name: plugin-barman-cloud` or references to `barmancloud.cnpg.io` in the rules. If the resources don't have these indicators, **DO NOT DELETE THEM** as they may belong to another application. + +If you're unsure, you can also check what the resources manage: +```bash +kubectl get clusterrole objectstore-viewer-role -o yaml +kubectl get clusterrole objectstore-editor-role -o yaml +``` + +These should reference `barmancloud.cnpg.io` API groups. If they don't, they are not barman plugin resources. +::: + +:::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. +::: + +### Step 1: Delete Old Cluster-scoped Resources + +**Only proceed if you've verified these resources belong to the barman plugin (see warning above).** + +```bash +# Only delete if this belongs to barman plugin (check labels first) +kubectl delete clusterrole metrics-auth-role + +# Only delete if this belongs to barman plugin (check labels first) +kubectl delete clusterrole metrics-reader + +# Only delete if this belongs to barman plugin (check labels first) +kubectl delete clusterrole objectstore-viewer-role + +# Only delete if this belongs to barman plugin (check labels first) +kubectl delete clusterrole objectstore-editor-role + +# Only delete if this belongs to barman plugin (check labels first) +kubectl delete clusterrolebinding metrics-auth-rolebinding +``` + +If any resource is not found, that's okay - it means it was never created or already deleted. + +### Step 2: Delete Old Namespace-scoped Resources + +These are less likely to conflict, but you should still verify they're in the correct namespace. Replace `cnpg-system` with your namespace if different: + +```bash +# First, verify these exist in your namespace +kubectl get role leader-election-role -n cnpg-system +kubectl get rolebinding leader-election-rolebinding -n cnpg-system + +# Then delete them +kubectl delete role leader-election-role -n cnpg-system +kubectl delete rolebinding leader-election-rolebinding -n cnpg-system +``` + +### Step 3: Apply the New RBAC Manifest + +Download and apply the new manifest with the updated resource names: + +```bash +kubectl apply -f https://cloudnative-pg.io/plugin-barman-cloud/migration-rbac.yaml -n cnpg-system +``` + +Alternatively, you can copy the complete YAML from the [Migration Manifest](migration-manifest.md) page, save it to a file, and apply it locally: + +```bash +kubectl apply -f barman-rbac-new.yaml -n cnpg-system +``` + +:::info +The new manifest will create all RBAC resources with the `barman-plugin-` prefix. Review the [Migration Manifest](migration-manifest.md) page to see exactly what will be created. +::: + +## Impact + +- **Downtime:** The migration requires a brief interruption as the old resources are deleted and new ones are created. The plugin controller may need to restart. +- **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 + ``` + +### Old Resources Still Present + +If old resources weren't deleted properly, you can force delete them: + +```bash +kubectl delete clusterrole metrics-auth-role --ignore-not-found +kubectl delete clusterrole metrics-reader --ignore-not-found +kubectl delete clusterrole objectstore-viewer-role --ignore-not-found +kubectl delete clusterrole objectstore-editor-role --ignore-not-found +kubectl delete clusterrolebinding metrics-auth-rolebinding --ignore-not-found +kubectl delete role leader-election-role -n cnpg-system --ignore-not-found +kubectl delete rolebinding leader-election-rolebinding -n cnpg-system --ignore-not-found +``` + +## 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/static/migration-rbac.yaml b/web/static/migration-rbac.yaml new file mode 100644 index 00000000..ede9bacd --- /dev/null +++ b/web/static/migration-rbac.yaml @@ -0,0 +1,248 @@ +# This manifest contains the RBAC resources for the plugin-barman-cloud migration. +# +# IMPORTANT: This manifest should be applied with the namespace flag: +# kubectl apply -f migration-rbac.yaml -n cnpg-system +# +# If you are using a different namespace, replace 'cnpg-system' with your namespace. +# The namespace-scoped resources (ServiceAccount, Role, RoleBinding) will be created +# in the namespace you specify, while cluster-scoped resources (ClusterRole, ClusterRoleBinding) +# will be created globally but will reference the ServiceAccount in your specified namespace. +# +apiVersion: v1 +kind: ServiceAccount +metadata: + labels: + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/name: plugin-barman-cloud + name: plugin-barman-cloud +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + labels: + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/name: plugin-barman-cloud + name: barman-plugin-leader-election-role +rules: +- apiGroups: + - "" + resources: + - configmaps + verbs: + - get + - list + - watch + - create + - update + - patch + - delete +- apiGroups: + - coordination.k8s.io + resources: + - leases + verbs: + - get + - list + - watch + - create + - update + - patch + - delete +- apiGroups: + - "" + resources: + - events + verbs: + - create + - patch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: barman-plugin-metrics-auth-role +rules: +- apiGroups: + - authentication.k8s.io + resources: + - tokenreviews + verbs: + - create +- apiGroups: + - authorization.k8s.io + resources: + - subjectaccessreviews + verbs: + - create +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: barman-plugin-metrics-reader +rules: +- nonResourceURLs: + - /metrics + verbs: + - get +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + labels: + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/name: plugin-barman-cloud + name: barman-plugin-objectstore-editor-role +rules: +- apiGroups: + - barmancloud.cnpg.io + resources: + - objectstores + verbs: + - create + - delete + - get + - list + - patch + - update + - watch +- apiGroups: + - barmancloud.cnpg.io + resources: + - objectstores/status + verbs: + - get +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + labels: + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/name: plugin-barman-cloud + name: barman-plugin-objectstore-viewer-role +rules: +- apiGroups: + - barmancloud.cnpg.io + resources: + - objectstores + verbs: + - get + - list + - watch +- apiGroups: + - barmancloud.cnpg.io + resources: + - objectstores/status + verbs: + - get +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: plugin-barman-cloud +rules: +- apiGroups: + - "" + resources: + - secrets + verbs: + - create + - delete + - get + - list + - watch +- apiGroups: + - barmancloud.cnpg.io + resources: + - objectstores + verbs: + - create + - delete + - get + - list + - patch + - update + - watch +- apiGroups: + - barmancloud.cnpg.io + resources: + - objectstores/finalizers + verbs: + - update +- apiGroups: + - barmancloud.cnpg.io + resources: + - objectstores/status + verbs: + - get + - patch + - update +- apiGroups: + - postgresql.cnpg.io + resources: + - backups + verbs: + - get + - list + - watch +- apiGroups: + - postgresql.cnpg.io + resources: + - clusters/finalizers + verbs: + - update +- apiGroups: + - rbac.authorization.k8s.io + resources: + - rolebindings + - roles + verbs: + - create + - get + - list + - patch + - update + - watch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + labels: + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/name: plugin-barman-cloud + name: barman-plugin-leader-election-rolebinding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: barman-plugin-leader-election-role +subjects: +- kind: ServiceAccount + name: plugin-barman-cloud + namespace: cnpg-system +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: barman-plugin-metrics-auth-rolebinding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: barman-plugin-metrics-auth-role +subjects: +- kind: ServiceAccount + name: plugin-barman-cloud + namespace: cnpg-system +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + labels: + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/name: plugin-barman-cloud + name: plugin-barman-cloud-binding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: plugin-barman-cloud +subjects: +- kind: ServiceAccount + name: plugin-barman-cloud + namespace: cnpg-system From 78b650417fedc2f735c8dd55bd3dd176d00c43dd Mon Sep 17 00:00:00 2001 From: Armando Ruocco Date: Tue, 14 Oct 2025 12:25:59 +0200 Subject: [PATCH 2/8] doc: review Signed-off-by: Armando Ruocco --- web/docs/resource-name-migration.md | 117 +++++++++++++++------------- web/static/migration-rbac.yaml | 13 ++-- 2 files changed, 71 insertions(+), 59 deletions(-) diff --git a/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md index 7965948f..d6771b1a 100644 --- a/web/docs/resource-name-migration.md +++ b/web/docs/resource-name-migration.md @@ -8,12 +8,13 @@ sidebar_position: 41 :::warning Before running the migration script or applying the manifest, please: -1. **Review the complete manifest** on the [Migration Manifest](migration-manifest.md) page to understand what changes will be made +1. **Review the complete manifest** at [migration-rbac.yaml](/migration-rbac.yaml) 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 -4. **Verify the resource names match** your current installation (default namespace is `cnpg-system`) This migration will delete old RBAC resources and create new ones. 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 @@ -50,26 +51,16 @@ Using generic names for cluster-wide resources is discouraged as they may confli The migration process is straightforward and can be completed with a few kubectl commands. :::danger Verify Resources Before Deletion -**IMPORTANT**: The old resource names are generic and could potentially belong to other components in your cluster. Before deleting, verify they belong to the barman plugin by checking their labels: +**IMPORTANT**: The old resource names are generic and could potentially belong to other components in your cluster. -```bash -# Check if the resources have the barman plugin labels -kubectl get clusterrole metrics-auth-role -o yaml | grep -A 5 "labels:" -kubectl get clusterrole metrics-reader -o yaml | grep -A 5 "labels:" -kubectl get clusterrole objectstore-viewer-role -o yaml | grep -A 5 "labels:" -kubectl get clusterrole objectstore-editor-role -o yaml | grep -A 5 "labels:" -kubectl get clusterrolebinding metrics-auth-rolebinding -o yaml | grep -A 5 "labels:" -``` +**Before deleting each resource, verify it belongs to the barman 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` -Look for labels like `app.kubernetes.io/name: plugin-barman-cloud` or references to `barmancloud.cnpg.io` in the rules. If the resources don't have these indicators, **DO NOT DELETE THEM** as they may belong to another application. +If a resource doesn't have these indicators, **DO NOT DELETE IT** as it may belong to another application. -If you're unsure, you can also check what the resources manage: -```bash -kubectl get clusterrole objectstore-viewer-role -o yaml -kubectl get clusterrole objectstore-editor-role -o yaml -``` - -These should reference `barmancloud.cnpg.io` API groups. If they don't, they are not barman plugin resources. +In Step 1 below, carefully review the output of each verification command before proceeding with the delete. ::: :::tip Dry Run First @@ -80,55 +71,91 @@ You can add `--dry-run=client` to any `kubectl delete` command to preview what w **Only proceed if you've verified these resources belong to the barman plugin (see warning above).** +For each resource below, first verify it belongs to barman, then delete it: + ```bash -# Only delete if this belongs to barman plugin (check labels first) -kubectl delete clusterrole metrics-auth-role +# 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 -# Only delete if this belongs to barman plugin (check labels first) -kubectl delete clusterrole metrics-reader +# 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 one, delete it (see warnings section): +kubectl delete clusterrole metrics-auth-role -# Only delete if this belongs to barman plugin (check labels first) +# 3. Check objectstore-viewer-role +# Look for barmancloud.cnpg.io API group or 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 -# Only delete if this belongs to barman plugin (check labels first) +# 4. Check objectstore-editor-role +# Look for barmancloud.cnpg.io API group or 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 -# Only delete if this belongs to barman plugin (check labels first) -kubectl delete clusterrolebinding metrics-auth-rolebinding +# 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 ``` -If any resource is not found, that's okay - it means it was never created or already deleted. +:::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 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 2: Delete Old Namespace-scoped Resources -These are less likely to conflict, but you should still verify they're in the correct namespace. Replace `cnpg-system` with your namespace if different: +Delete the old namespace-scoped resources in the `cnpg-system` namespace: ```bash -# First, verify these exist in your namespace -kubectl get role leader-election-role -n cnpg-system -kubectl get rolebinding leader-election-rolebinding -n cnpg-system - -# Then delete them +# 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. + ### Step 3: Apply the New RBAC Manifest Download and apply the new manifest with the updated resource names: ```bash -kubectl apply -f https://cloudnative-pg.io/plugin-barman-cloud/migration-rbac.yaml -n cnpg-system +kubectl apply -f https://cloudnative-pg.io/plugin-barman-cloud/migration-rbac.yaml ``` -Alternatively, you can copy the complete YAML from the [Migration Manifest](migration-manifest.md) page, save it to a file, and apply it locally: +Alternatively, you can download the [migration-rbac.yaml](/migration-rbac.yaml) file and review it locally before applying: ```bash -kubectl apply -f barman-rbac-new.yaml -n cnpg-system +# Download the file +curl -O https://cloudnative-pg.io/plugin-barman-cloud/migration-rbac.yaml + +# Review it +cat migration-rbac.yaml + +# Apply it +kubectl apply -f migration-rbac.yaml ``` :::info -The new manifest will create all RBAC resources with the `barman-plugin-` prefix. Review the [Migration Manifest](migration-manifest.md) page to see exactly what will be created. +The new manifest will create all RBAC resources with the `barman-plugin-` prefix in the `cnpg-system` namespace. You can review the complete YAML at [migration-rbac.yaml](/migration-rbac.yaml). ::: ## Impact @@ -170,20 +197,6 @@ If the plugin fails to start after migration, check: kubectl describe clusterrolebinding barman-plugin-metrics-auth-rolebinding ``` -### Old Resources Still Present - -If old resources weren't deleted properly, you can force delete them: - -```bash -kubectl delete clusterrole metrics-auth-role --ignore-not-found -kubectl delete clusterrole metrics-reader --ignore-not-found -kubectl delete clusterrole objectstore-viewer-role --ignore-not-found -kubectl delete clusterrole objectstore-editor-role --ignore-not-found -kubectl delete clusterrolebinding metrics-auth-rolebinding --ignore-not-found -kubectl delete role leader-election-role -n cnpg-system --ignore-not-found -kubectl delete rolebinding leader-election-rolebinding -n cnpg-system --ignore-not-found -``` - ## 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/static/migration-rbac.yaml b/web/static/migration-rbac.yaml index ede9bacd..be68513a 100644 --- a/web/static/migration-rbac.yaml +++ b/web/static/migration-rbac.yaml @@ -1,12 +1,8 @@ # This manifest contains the RBAC resources for the plugin-barman-cloud migration. # -# IMPORTANT: This manifest should be applied with the namespace flag: -# kubectl apply -f migration-rbac.yaml -n cnpg-system -# -# If you are using a different namespace, replace 'cnpg-system' with your namespace. -# The namespace-scoped resources (ServiceAccount, Role, RoleBinding) will be created -# in the namespace you specify, while cluster-scoped resources (ClusterRole, ClusterRoleBinding) -# will be created globally but will reference the ServiceAccount in your specified namespace. +# This manifest is configured for the 'cnpg-system' namespace. +# Simply apply it with: +# kubectl apply -f migration-rbac.yaml # apiVersion: v1 kind: ServiceAccount @@ -15,6 +11,7 @@ metadata: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: plugin-barman-cloud name: plugin-barman-cloud + namespace: cnpg-system --- apiVersion: rbac.authorization.k8s.io/v1 kind: Role @@ -23,6 +20,7 @@ metadata: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: plugin-barman-cloud name: barman-plugin-leader-election-role + namespace: cnpg-system rules: - apiGroups: - "" @@ -209,6 +207,7 @@ metadata: app.kubernetes.io/managed-by: kustomize app.kubernetes.io/name: plugin-barman-cloud name: barman-plugin-leader-election-rolebinding + namespace: cnpg-system roleRef: apiGroup: rbac.authorization.k8s.io kind: Role From ef4d26d83c0be553d9b181245f791b4bbc1a0222 Mon Sep 17 00:00:00 2001 From: Jonathan Battiato Date: Thu, 16 Oct 2025 19:54:12 +0200 Subject: [PATCH 3/8] docs(rbac): review procedure Signed-off-by: Jonathan Battiato --- web/docs/resource-name-migration.md | 60 +++---- web/static/migration-rbac.yaml | 247 ---------------------------- 2 files changed, 22 insertions(+), 285 deletions(-) delete mode 100644 web/static/migration-rbac.yaml diff --git a/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md index d6771b1a..196396eb 100644 --- a/web/docs/resource-name-migration.md +++ b/web/docs/resource-name-migration.md @@ -7,19 +7,22 @@ sidebar_position: 41 :::warning -Before running the migration script or applying the manifest, please: -1. **Review the complete manifest** at [migration-rbac.yaml](/migration-rbac.yaml) to understand what changes will be made +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 and create new ones. 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. +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. +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 @@ -44,14 +47,22 @@ The following resources have been renamed to use proper prefixes: ## 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. +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 -The migration process is straightforward and can be completed with a few kubectl commands. +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. +**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 plugin by checking:** - For `objectstore-*` roles: Look for `barmancloud.cnpg.io` in the API groups @@ -60,15 +71,14 @@ The migration process is straightforward and can be completed with a few kubectl If a resource doesn't have these indicators, **DO NOT DELETE IT** as it may belong to another application. -In Step 1 below, carefully review the output of each verification command before proceeding with the delete. +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. +You can add `--dry-run=client` to any `kubectl delete` command to preview what would be deleted without actually +removing anything. ::: -### Step 1: Delete Old Cluster-scoped Resources - **Only proceed if you've verified these resources belong to the barman plugin (see warning above).** For each resource below, first verify it belongs to barman, then delete it: @@ -121,7 +131,7 @@ If you're unsure, it's safer to leave it and let the new `barman-plugin-metrics- 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 2: Delete Old Namespace-scoped Resources +### Step 3: Delete Old Namespace-scoped Resources Delete the old namespace-scoped resources in the `cnpg-system` namespace: @@ -133,34 +143,8 @@ 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. -### Step 3: Apply the New RBAC Manifest - -Download and apply the new manifest with the updated resource names: - -```bash -kubectl apply -f https://cloudnative-pg.io/plugin-barman-cloud/migration-rbac.yaml -``` - -Alternatively, you can download the [migration-rbac.yaml](/migration-rbac.yaml) file and review it locally before applying: - -```bash -# Download the file -curl -O https://cloudnative-pg.io/plugin-barman-cloud/migration-rbac.yaml - -# Review it -cat migration-rbac.yaml - -# Apply it -kubectl apply -f migration-rbac.yaml -``` - -:::info -The new manifest will create all RBAC resources with the `barman-plugin-` prefix in the `cnpg-system` namespace. You can review the complete YAML at [migration-rbac.yaml](/migration-rbac.yaml). -::: - ## Impact -- **Downtime:** The migration requires a brief interruption as the old resources are deleted and new ones are created. The plugin controller may need to restart. - **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`). diff --git a/web/static/migration-rbac.yaml b/web/static/migration-rbac.yaml deleted file mode 100644 index be68513a..00000000 --- a/web/static/migration-rbac.yaml +++ /dev/null @@ -1,247 +0,0 @@ -# This manifest contains the RBAC resources for the plugin-barman-cloud migration. -# -# This manifest is configured for the 'cnpg-system' namespace. -# Simply apply it with: -# kubectl apply -f migration-rbac.yaml -# -apiVersion: v1 -kind: ServiceAccount -metadata: - labels: - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: plugin-barman-cloud - name: plugin-barman-cloud - namespace: cnpg-system ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - labels: - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: plugin-barman-cloud - name: barman-plugin-leader-election-role - namespace: cnpg-system -rules: -- apiGroups: - - "" - resources: - - configmaps - verbs: - - get - - list - - watch - - create - - update - - patch - - delete -- apiGroups: - - coordination.k8s.io - resources: - - leases - verbs: - - get - - list - - watch - - create - - update - - patch - - delete -- apiGroups: - - "" - resources: - - events - verbs: - - create - - patch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: barman-plugin-metrics-auth-role -rules: -- apiGroups: - - authentication.k8s.io - resources: - - tokenreviews - verbs: - - create -- apiGroups: - - authorization.k8s.io - resources: - - subjectaccessreviews - verbs: - - create ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: barman-plugin-metrics-reader -rules: -- nonResourceURLs: - - /metrics - verbs: - - get ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - labels: - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: plugin-barman-cloud - name: barman-plugin-objectstore-editor-role -rules: -- apiGroups: - - barmancloud.cnpg.io - resources: - - objectstores - verbs: - - create - - delete - - get - - list - - patch - - update - - watch -- apiGroups: - - barmancloud.cnpg.io - resources: - - objectstores/status - verbs: - - get ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - labels: - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: plugin-barman-cloud - name: barman-plugin-objectstore-viewer-role -rules: -- apiGroups: - - barmancloud.cnpg.io - resources: - - objectstores - verbs: - - get - - list - - watch -- apiGroups: - - barmancloud.cnpg.io - resources: - - objectstores/status - verbs: - - get ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: plugin-barman-cloud -rules: -- apiGroups: - - "" - resources: - - secrets - verbs: - - create - - delete - - get - - list - - watch -- apiGroups: - - barmancloud.cnpg.io - resources: - - objectstores - verbs: - - create - - delete - - get - - list - - patch - - update - - watch -- apiGroups: - - barmancloud.cnpg.io - resources: - - objectstores/finalizers - verbs: - - update -- apiGroups: - - barmancloud.cnpg.io - resources: - - objectstores/status - verbs: - - get - - patch - - update -- apiGroups: - - postgresql.cnpg.io - resources: - - backups - verbs: - - get - - list - - watch -- apiGroups: - - postgresql.cnpg.io - resources: - - clusters/finalizers - verbs: - - update -- apiGroups: - - rbac.authorization.k8s.io - resources: - - rolebindings - - roles - verbs: - - create - - get - - list - - patch - - update - - watch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - labels: - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: plugin-barman-cloud - name: barman-plugin-leader-election-rolebinding - namespace: cnpg-system -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: barman-plugin-leader-election-role -subjects: -- kind: ServiceAccount - name: plugin-barman-cloud - namespace: cnpg-system ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: barman-plugin-metrics-auth-rolebinding -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: barman-plugin-metrics-auth-role -subjects: -- kind: ServiceAccount - name: plugin-barman-cloud - namespace: cnpg-system ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - labels: - app.kubernetes.io/managed-by: kustomize - app.kubernetes.io/name: plugin-barman-cloud - name: plugin-barman-cloud-binding -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: plugin-barman-cloud -subjects: -- kind: ServiceAccount - name: plugin-barman-cloud - namespace: cnpg-system From 1ea72438b3aee3e339d2713876cb025a30b80cdc Mon Sep 17 00:00:00 2001 From: Gabriele Bartolini Date: Fri, 24 Oct 2025 16:42:10 +0300 Subject: [PATCH 4/8] docs: add upgrades page Signed-off-by: Gabriele Bartolini --- .wordlist.txt | 5 +++++ web/docs/resource-name-migration.md | 11 ++++++----- web/docs/upgrades.mdx | 16 ++++++++++++++++ 3 files changed, 27 insertions(+), 5 deletions(-) create mode 100644 web/docs/upgrades.mdx diff --git a/.wordlist.txt b/.wordlist.txt index e872a386..0569592b 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,3 +1,4 @@ +nonResourceURLs AccessDenied AdditionalContainerArgs Akamai @@ -49,6 +50,7 @@ SPDX SPDX SSL ServerRecoveryWindow +ServiceAccount Slonik TLS TODO @@ -106,6 +108,7 @@ involvedObject io isWALArchiver jq +json jsonpath kb krew @@ -131,7 +134,9 @@ recoverability repos retentionCheckInterval retentionPolicy +roleRef rolebinding +rolebindings rollout rpc sc diff --git a/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md index 196396eb..b5cd1b90 100644 --- a/web/docs/resource-name-migration.md +++ b/web/docs/resource-name-migration.md @@ -1,8 +1,8 @@ --- -sidebar_position: 41 +sidebar_position: 90 --- -# Resource Name Migration Guide +# Resource name migration guide @@ -64,7 +64,7 @@ Please refer to the [Installation](installation.mdx) section to deploy the new p :::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 plugin by checking:** +**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` @@ -79,7 +79,8 @@ You can add `--dry-run=client` to any `kubectl delete` command to preview what w removing anything. ::: -**Only proceed if you've verified these resources belong to the barman plugin (see warning above).** +**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, then delete it: @@ -124,7 +125,7 @@ kubectl delete clusterrole metrics-reader 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 plugin +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. ::: diff --git a/web/docs/upgrades.mdx b/web/docs/upgrades.mdx new file mode 100644 index 00000000..0ab9ddbe --- /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). From 141e49c218704f7782d28b1b64ee6a512f7865c4 Mon Sep 17 00:00:00 2001 From: Gabriele Bartolini Date: Mon, 27 Oct 2025 13:17:35 +0100 Subject: [PATCH 5/8] fix: spellcheck Signed-off-by: Gabriele Bartolini --- .wordlist.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.wordlist.txt b/.wordlist.txt index 0569592b..d5fa7825 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,4 +1,3 @@ -nonResourceURLs AccessDenied AdditionalContainerArgs Akamai @@ -121,6 +120,7 @@ md minio namespace namespaces +nonResourceURLs objectstore objectstores pluginConfiguration From 7f25cec7163033f9ac93ca88f24e24a9836b4f2c Mon Sep 17 00:00:00 2001 From: Marco Nenciarini Date: Mon, 27 Oct 2025 14:14:31 +0100 Subject: [PATCH 6/8] chore: generate manifest Signed-off-by: Marco Nenciarini --- manifest.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/manifest.yaml b/manifest.yaml index 27ab676e..95ed059a 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 From 5bcc1184cfc0711c75de5d4c48b502467ef64b55 Mon Sep 17 00:00:00 2001 From: Gabriele Bartolini Date: Mon, 27 Oct 2025 14:24:44 +0100 Subject: [PATCH 7/8] docs: fixes Signed-off-by: Gabriele Bartolini --- web/docs/resource-name-migration.md | 118 ++++++++++++++++++---------- 1 file changed, 75 insertions(+), 43 deletions(-) diff --git a/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md index b5cd1b90..f5c1cc39 100644 --- a/web/docs/resource-name-migration.md +++ b/web/docs/resource-name-migration.md @@ -12,125 +12,151 @@ Before proceeding with the migration process, please: 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. +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. +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: +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` | +| 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` | +| `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` | +| 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 +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. +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. +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. +**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:** +**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 `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. +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`. +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. +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, then delete it: +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: +# 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 one, delete it (see warnings section): +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 app.kubernetes.io/name: plugin-barman-cloud label +# 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 app.kubernetes.io/name: plugin-barman-cloud label +# 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 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: +# 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: +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 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. +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 @@ -142,12 +168,17 @@ 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. +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`). +- **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 @@ -184,4 +215,5 @@ If the plugin fails to start after migration, check: ## Support -If you encounter issues during migration, please open an issue on the [GitHub repository](https://github.com/cloudnative-pg/plugin-barman-cloud/issues). +If you encounter issues during migration, please open an issue on the [GitHub +repository](https://github.com/cloudnative-pg/plugin-barman-cloud/issues). From 4fbcf2fcff0d828a8be64bf83844566f7e0c42a0 Mon Sep 17 00:00:00 2001 From: Marco Nenciarini Date: Mon, 27 Oct 2025 14:26:17 +0100 Subject: [PATCH 8/8] chore: update default kustomization Signed-off-by: Marco Nenciarini --- config/default/kustomization.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/default/kustomization.yaml b/config/default/kustomization.yaml index 93664f3d..55202da5 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: