marco/plugin-barman-cloud
1
0
Fork 0
mirror of https://github.com/cloudnative-pg/plugin-barman-cloud.git synced 2026-01-11 21:23:12 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: fixes

Browse Source 
Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
This commit is contained in:
Gabriele Bartolini 2025-10-27 14:24:44 +01:00
parent 7f25cec716
commit 5bcc1184cf
1 changed files with 75 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
web/docs/resource-name-migration.md
View File

@ -12,26 +12,29 @@ 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` |
| `metrics-auth-rolebinding` | `barman-plugin-metrics-auth-rolebinding` |
| `metrics-reader` | `barman-plugin-metrics-reader` |
@ -41,96 +44,119 @@ The following resources have been renamed to use proper prefixes:
### 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
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).