Skip to content

Commit c5408d0

Browse files
mikeshngmikeshng
authored
docs: polish readme (#63)
Signed-off-by: Mike Ng <ming@redhat.com>
1 parent c8c8afe commit c5408d0

1 file changed

Lines changed: 225 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 225 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,250 @@
11
# ClusterPermission
2-
`ClusterPermission` is an OCM custom resource that enables administrators to automatically distribute RBAC resources to managed clusters and manage the lifecycle of those resources. It provides functionality for handling Roles, ClusterRoles, RoleBindings, and ClusterRoleBindings.
32

4-
This project aims to improve the usability of `ManagedServiceAccount` ([GitHub link](https://github.com/open-cluster-management-io/managed-serviceaccount)). `ManagedServiceAccount` facilitates authentication fleet management, while `ClusterPermission` addresses the authorization aspects of fleet management.
3+
`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.
54

6-
## Description
7-
This repository contains the API definition and controller for `ClusterPermission`.
5+
## Overview
86

9-
A valid `ClusterPermission` resource should reside in an OCM "managed cluster namespace" and the associated RBAC resources will be deployed to the managed cluster associated with that managed cluster namespace. The `ClusterPermission` controller utilizes the `ManifestWork` API to ensure the creation, update, and removal of RBAC resources on each managed cluster. The `ClusterPermission` API safeguards these distributed RBAC resources against unintended modifications and removal.
7+
This project complements [ManagedServiceAccount](https://github.com/open-cluster-management-io/managed-serviceaccount) by addressing the authorization aspects of fleet management. While `ManagedServiceAccount` handles authentication across clusters, `ClusterPermission` manages authorization by distributing and maintaining RBAC resources.
108

11-
Apart from the typical RBAC binding subject resources (Group, ServiceAccount, and User), `ManagedServiceAccount` can also serve as a subject. When the binding subject is a `ManagedServiceAccount`, the controller computes and generates RBAC resources based on the ServiceAccount managed by the `ManagedServiceAccount`.
9+
### Key Features
1210

13-
## Dependencies
14-
- The Open Cluster Management (OCM) multi-cluster environment needs to be setup. See [OCM website](https://open-cluster-management.io/) on how to setup the environment.
15-
- Optional: [ManagedServiceAccount](https://github.com/open-cluster-management-io/managed-serviceaccount) add-on installed if you want to leverage `ManagedServiceAccount` resource as RBAC subject.
11+
- **Automated RBAC Distribution**: Automatically deploys RBAC resources to managed clusters
12+
- **Lifecycle Management**: Uses OCM's ManifestWork API for creation, updates, and deletion
13+
- **ManagedServiceAccount Integration**: Supports ManagedServiceAccount as a binding subject
14+
- **Multi-cluster Authorization**: Centralized authorization management across OCM fleet
15+
- **Resource Protection**: Safeguards distributed RBAC resources against unintended modifications
1616

17-
## Getting Started
18-
1. Setup an OCM Hub cluster and registered an OCM Managed cluster. See [Open Cluster Management Quick Start](https://open-cluster-management.io/getting-started/quick-start/) for more details.
17+
## Architecture
1918

20-
2. On the Hub cluster, install the `ClusterPermission` API and run the controller,
21-
```
19+
A `ClusterPermission` resource must reside in an OCM managed cluster namespace on the Hub cluster. The controller:
20+
21+
1. Validates the ClusterPermission specification
22+
2. Generates appropriate RBAC manifests
23+
3. Creates ManifestWork resources to deploy RBAC to target managed clusters
24+
4. Monitors and maintains the lifecycle of distributed resources
25+
26+
Supported RBAC resources:
27+
- **ClusterRole** and **ClusterRoleBinding**
28+
- **Role** and **RoleBinding** (with namespace targeting)
29+
- **Standard subjects**: User, Group, ServiceAccount
30+
- **Enhanced subjects**: ManagedServiceAccount (requires ManagedServiceAccount addon)
31+
32+
## Prerequisites
33+
34+
- **Open Cluster Management (OCM)** environment with Hub and managed clusters
35+
- See [OCM Quick Start](https://open-cluster-management.io/getting-started/quick-start/) for setup instructions
36+
- **Optional**: [ManagedServiceAccount addon](https://github.com/open-cluster-management-io/managed-serviceaccount) for enhanced authentication features
37+
38+
## Installation
39+
40+
### Option 1: Development Installation
41+
42+
1. Clone the repository and install CRDs:
43+
```bash
44+
git clone https://github.com/open-cluster-management-io/cluster-permission.git
2245
cd cluster-permission/
2346
make install
47+
```
48+
49+
2. Run the controller locally:
50+
```bash
2451
make run
2552
```
2653

27-
3. On the Hub cluster, apply the sample (modify the cluster1 namespace to your managed cluster name):
54+
### Option 2: Helm Chart Installation
55+
56+
Deploy using the provided Helm chart:
57+
```bash
58+
helm install cluster-permission ./chart/
2859
```
29-
kubectl -n cluster1 apply -f config/samples/rbac.open-cluster-management.io_v1alpha1_clusterpermission
30-
kubectl -n cluster1 get clusterpermission -o yaml
31-
...
32-
status:
33-
conditions:
34-
- lastTransitionTime: "2023-04-12T15:19:04Z"
35-
message: |-
36-
Run the following command to check the ManifestWork status:
37-
kubectl -n cluster1 get ManifestWork clusterpermission-sample-f15f0 -o yaml
38-
reason: AppliedRBACManifestWork
39-
status: "True"
40-
type: AppliedRBACManifestWork
60+
61+
### Option 3: Direct Deployment
62+
63+
Apply the deployment manifests:
64+
```bash
65+
kubectl apply -f config/deploy/
4166
```
4267

43-
4. On the Managed cluster, check the RBAC resources
68+
## Quick Start
69+
70+
### 1. Basic ClusterPermission Example
71+
72+
Create a ClusterPermission in your managed cluster namespace (replace `cluster1` with your managed cluster name):
73+
74+
```bash
75+
kubectl apply -f - <<EOF
76+
apiVersion: rbac.open-cluster-management.io/v1alpha1
77+
kind: ClusterPermission
78+
metadata:
79+
name: example-permissions
80+
namespace: cluster1
81+
spec:
82+
clusterRole:
83+
rules:
84+
- apiGroups: ["apps"]
85+
resources: ["deployments"]
86+
verbs: ["get", "list", "watch"]
87+
clusterRoleBinding:
88+
subject:
89+
kind: ServiceAccount
90+
name: my-service-account
91+
namespace: default
92+
EOF
4493
```
45-
kubectl -n default get role
46-
NAME CREATED AT
47-
clusterpermission-sample 2023-04-12T15:19:04Z
94+
95+
### 2. Verify Deployment
96+
97+
Check the ClusterPermission status:
98+
```bash
99+
kubectl -n cluster1 get clusterpermission example-permissions -o yaml
100+
```
101+
102+
Expected status:
103+
```yaml
104+
status:
105+
conditions:
106+
- lastTransitionTime: "2023-04-12T15:19:04Z"
107+
message: |-
108+
Run the following command to check the ManifestWork status:
109+
kubectl -n cluster1 get ManifestWork example-permissions-xxxxx -o yaml
110+
reason: AppliedRBACManifestWork
111+
status: "True"
112+
type: AppliedRBACManifestWork
113+
```
114+
115+
### 3. Verify RBAC Resources on Managed Cluster
116+
117+
On the managed cluster, verify the RBAC resources were created:
118+
```bash
119+
kubectl get clusterrole | grep example-permissions
120+
kubectl get clusterrolebinding | grep example-permissions
121+
```
122+
123+
## Usage Examples
124+
125+
### Standard RBAC Subjects
126+
127+
Apply the basic sample:
128+
```bash
129+
kubectl -n cluster1 apply -f config/samples/rbac.open-cluster-management.io_v1alpha1_clusterpermission.yaml
130+
```
131+
132+
### Users and Groups
133+
134+
For user and group-based permissions:
135+
```bash
136+
kubectl -n cluster1 apply -f config/samples/clusterpermission_users_groups.yaml
137+
```
138+
139+
### ManagedServiceAccount Integration
140+
141+
To use ManagedServiceAccount as a subject:
142+
```bash
143+
kubectl -n cluster1 apply -f config/samples/clusterpermission_subject_msa.yaml
48144
```
49145

50-
## Community, discussion, contribution, and support
146+
### Multiple ClusterRoleBindings
147+
148+
For complex permission scenarios:
149+
```bash
150+
kubectl -n cluster1 apply -f config/samples/clusterpermission_multiple_clusterrolebindings.yaml
151+
```
152+
153+
## Configuration Reference
154+
155+
### ClusterPermissionSpec
156+
157+
| Field | Type | Description |
158+
|-------|------|-------------|
159+
| `clusterRole` | `ClusterRole` | ClusterRole to create on managed cluster |
160+
| `clusterRoleBinding` | `ClusterRoleBinding` | ClusterRoleBinding to create |
161+
| `clusterRoleBindings` | `[]ClusterRoleBinding` | Multiple ClusterRoleBindings |
162+
| `roles` | `[]Role` | Roles to create with namespace targeting |
163+
| `roleBindings` | `[]RoleBinding` | RoleBindings with namespace support |
164+
165+
### Subject Types
166+
167+
- **ServiceAccount**: `kind: ServiceAccount`
168+
- **User**: `kind: User`
169+
- **Group**: `kind: Group`
170+
- **ManagedServiceAccount**: `kind: ManagedServiceAccount` (requires addon)
171+
172+
## Troubleshooting
173+
174+
### Common Issues
175+
176+
1. **ClusterPermission not applying**
177+
- Verify the namespace is a valid managed cluster namespace
178+
- Check OCM hub cluster connectivity
179+
180+
2. **RBAC resources not appearing on managed cluster**
181+
- Check ManifestWork status: `kubectl -n <cluster-ns> get manifestwork`
182+
- Verify managed cluster agent connectivity
183+
184+
3. **ManagedServiceAccount subjects not working**
185+
- Ensure ManagedServiceAccount addon is installed
186+
- Verify the referenced ManagedServiceAccount exists
187+
188+
### Debugging Commands
189+
190+
```bash
191+
# Check ClusterPermission status
192+
kubectl -n <cluster-namespace> get clusterpermission <name> -o yaml
193+
194+
# Check associated ManifestWork
195+
kubectl -n <cluster-namespace> get manifestwork
196+
197+
# View controller logs
198+
kubectl logs -n cluster-permission-system deployment/cluster-permission-controller-manager
199+
```
200+
201+
## Development
202+
203+
### Building from Source
204+
205+
```bash
206+
# Build the binary
207+
make build
208+
209+
# Build Docker image
210+
make docker-build
211+
212+
# Run tests
213+
make test
214+
215+
# Generate CRDs
216+
make manifests
217+
218+
# Update generated code
219+
make generate
220+
```
221+
222+
### Code Generation
223+
224+
After modifying API types, regenerate code:
225+
```bash
226+
make generate
227+
make manifests
228+
```
229+
230+
## Community and Support
231+
232+
### Contributing
233+
234+
Check the [CONTRIBUTING Doc](CONTRIBUTING.md) for contribution guidelines.
235+
236+
### Communication
51237

52-
Check the [CONTRIBUTING Doc](CONTRIBUTING.md) for how to contribute to the repo.
238+
- **Slack**: [#open-cluster-mgmt](https://kubernetes.slack.com/channels/open-cluster-mgmt)
239+
- **GitHub Issues**: Report bugs and feature requests
240+
- **GitHub Discussions**: Community questions and discussions
53241

54-
### Communication channels
242+
### Related Projects
55243

56-
Slack channel: [#open-cluster-mgmt](https://kubernetes.slack.com/channels/open-cluster-mgmt)
244+
- [Open Cluster Management](https://open-cluster-management.io/)
245+
- [ManagedServiceAccount](https://github.com/open-cluster-management-io/managed-serviceaccount)
246+
- [ManifestWork](https://open-cluster-management.io/concepts/manifestwork/)
57247

58248
## License
59249

60-
This code is released under the Apache 2.0 license. See the file [LICENSE](LICENSE) for more information.
250+
This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)