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/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/web/docs/resource-name-migration.md b/web/docs/resource-name-migration.md new file mode 100644 index 0000000..7965948 --- /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 0000000..ede9bac --- /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