ClusterPermission

ClusterPermission is an Open Cluster Management (OCM) custom resource that enables administrators to automatically distribute RBAC resources to managed clusters and manage their lifecycle. It provides centralized management of Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings across multiple Kubernetes clusters.

Overview

This project complements ManagedServiceAccount by addressing the authorization aspects of fleet management. While ManagedServiceAccount handles authentication across clusters, ClusterPermission manages authorization by distributing and maintaining RBAC resources.

Key Features

Automated RBAC Distribution: Automatically deploys RBAC resources to managed clusters
Lifecycle Management: Uses OCM's ManifestWork API for creation, updates, and deletion
ManagedServiceAccount Integration: Supports ManagedServiceAccount as a binding subject
Multi-cluster Authorization: Centralized authorization management across OCM fleet
Resource Protection: Safeguards distributed RBAC resources against unintended modifications

Architecture

A ClusterPermission resource must reside in an OCM managed cluster namespace on the Hub cluster. The controller:

Validates the ClusterPermission specification
Generates appropriate RBAC manifests
Creates ManifestWork resources to deploy RBAC to target managed clusters
Monitors and maintains the lifecycle of distributed resources

Supported RBAC resources:

ClusterRole and ClusterRoleBinding
Role and RoleBinding (with namespace targeting)
Standard subjects: User, Group, ServiceAccount
Enhanced subjects: ManagedServiceAccount (requires ManagedServiceAccount addon)

Prerequisites

Open Cluster Management (OCM) environment with Hub and managed clusters
- See OCM Quick Start for setup instructions
Optional: ManagedServiceAccount addon for enhanced authentication features

Installation

Option 1: Development Installation

Clone the repository and install CRDs:

git clone https://github.com/open-cluster-management-io/cluster-permission.git
cd cluster-permission/
make install

Run the controller locally:

make run

Option 2: Helm Chart Installation

Deploy using the provided Helm chart:

helm install cluster-permission ./chart/

Option 3: Direct Deployment

Apply the deployment manifests:

kubectl apply -f config/deploy/

Quick Start

1. Basic ClusterPermission Example

Create a ClusterPermission in your managed cluster namespace (replace cluster1 with your managed cluster name):

kubectl apply -f - <<EOF
apiVersion: rbac.open-cluster-management.io/v1alpha1
kind: ClusterPermission
metadata:
  name: example-permissions
  namespace: cluster1
spec:
  clusterRole:
    rules:
    - apiGroups: ["apps"]
      resources: ["deployments"]
      verbs: ["get", "list", "watch"]
  clusterRoleBinding:
    subject:
      kind: ServiceAccount
      name: my-service-account
      namespace: default
EOF

2. Verify Deployment

Check the ClusterPermission status:

kubectl -n cluster1 get clusterpermission example-permissions -o yaml

Expected status:

status:
  conditions:
  - lastTransitionTime: "2023-04-12T15:19:04Z"
    message: |-
      Run the following command to check the ManifestWork status:
      kubectl -n cluster1 get ManifestWork example-permissions-xxxxx -o yaml
    reason: AppliedRBACManifestWork
    status: "True"
    type: AppliedRBACManifestWork

3. Verify RBAC Resources on Managed Cluster

On the managed cluster, verify the RBAC resources were created:

kubectl get clusterrole | grep example-permissions
kubectl get clusterrolebinding | grep example-permissions

Usage Examples

Standard RBAC Subjects

Apply the basic sample:

kubectl -n cluster1 apply -f config/samples/rbac.open-cluster-management.io_v1alpha1_clusterpermission.yaml

Users and Groups

For user and group-based permissions:

kubectl -n cluster1 apply -f config/samples/clusterpermission_users_groups.yaml

ManagedServiceAccount Integration

To use ManagedServiceAccount as a subject:

kubectl -n cluster1 apply -f config/samples/clusterpermission_subject_msa.yaml

Multiple ClusterRoleBindings

For complex permission scenarios:

kubectl -n cluster1 apply -f config/samples/clusterpermission_multiple_clusterrolebindings.yaml

Configuration Reference