doc: review

Signed-off-by: Armando Ruocco <[email protected]>

Author: armru

web/docs/resource-name-migration.md

@@ -8,7 +8,7 @@ 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`)
@@ -50,26 +50,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 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
-```
+If a resource doesn't have these indicators, **DO NOT DELETE IT** as it may belong to another application.
 
-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,24 +70,55 @@ 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
 
@@ -118,17 +139,44 @@ kubectl delete rolebinding leader-election-rolebinding -n cnpg-system
 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:
+:::caution Custom Namespace Users
+If you're using a **different namespace** than `cnpg-system`, you'll need to download the manifest and modify it 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
+
+# Replace ALL occurrences of cnpg-system with your namespace
+sed -i.bak 's/cnpg-system/your-namespace/g' migration-rbac.yaml
+
+# Review the changes
+cat migration-rbac.yaml
+
+# Apply it
+kubectl apply -f migration-rbac.yaml
+```
+
+The manifest has `cnpg-system` hardcoded in multiple places (namespace metadata and ClusterRoleBinding subjects), so all occurrences need to be replaced.
+:::
+
+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 (no need to specify namespace, it's in the manifest)
+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. You can review the complete YAML at [migration-rbac.yaml](/migration-rbac.yaml).
 :::
 
 ## Impact
@@ -170,20 +218,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).

web/static/migration-rbac.yaml

@@ -1,12 +1,11 @@
 # 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
+# IMPORTANT: This manifest is configured for the 'cnpg-system' namespace.
+# Simply apply it with:
+#   kubectl apply -f migration-rbac.yaml
 #
-# 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.
+# If you are using a different namespace, you must replace all occurrences of
+# 'cnpg-system' in this file with your namespace before applying.
 #
 apiVersion: v1
 kind: ServiceAccount
@@ -15,6 +14,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 +23,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 +210,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