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).