doc: review

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

Author: armru

web/docs/resource-name-migration.md

@@ -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:"
-```
-
-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.
+**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`
 
-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:
+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
 
@@ -170,20 +191,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).