Skip to content

Commit

Permalink
📖 [Docs] Document the granting of API access (#1407)
Browse files Browse the repository at this point in the history 
* Document granting API access

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Addressing PR comments

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Addressing PR comments 2

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Reorders document

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Improve wording on explanation around access needs

Co-authored-by: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>

* Improved wording on OLM not managing RBAC

Co-authored-by: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>

* Clarify admin and edit roles

Co-authored-by: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>

* Draw attention to RBAC all verbs grant

Co-authored-by: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>

* Clarify role vs. binding recommendations in notes

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Cluster extension everywhere we had operator ref

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Improved wordigin on rbac mention

Co-authored-by: Michael Peter <mipeter@redhat.com>

* Improve wording around who the users are

Co-authored-by: Michael Peter <mipeter@redhat.com>

* Add mkdocs ref and move to howto

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Clarify what admin clusterrole does

Co-authored-by: Joe Lanford <joe.lanford@gmail.com>

* Clean up what * verb allows

Co-authored-by: Joe Lanford <joe.lanford@gmail.com>

* Removes Notes section - covered in intro

Signed-off-by: Brett Tofel <btofel@redhat.com>

* Reword mkdocs link text

Signed-off-by: Brett Tofel <btofel@redhat.com>

* ReReword mkdocs link text

Signed-off-by: Brett Tofel <btofel@redhat.com>

---------

Signed-off-by: Brett Tofel <btofel@redhat.com>
Co-authored-by: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>
Co-authored-by: Michael Peter <mipeter@redhat.com>
Co-authored-by: Joe Lanford <joe.lanford@gmail.com>
  • Loading branch information
@bentito @camilamacedo86
@michaelryanpeter @joelanford
4 people authored Nov 7, 2024
1 parent bb80643 commit 8d535a6
Show file tree
Hide file tree
Showing 2 changed files with 175 additions and 0 deletions.
174 changes: 174 additions & 0 deletions docs/howto/how-to-grant-api-access.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@

# Granting Users Access to API Resources in OLM

When cluster extensions are managed via OLM, they often provide Custom Resource Definitions (CRDs) that expose new API resources. Typically, cluster administrators have full management access to these resources by default, whereas non-administrative users might lack sufficient permissions. Cluster administrators must create the needed permissions to create, view, or edit these Custom Resources for these users.

OLM v1 does **not** automatically configure or manage role-based access control (RBAC) for users to interact with the APIs provided by installed packages. Cluster administrators must manage RBAC to grant appropriate permissions to non-administrative users. This guide outlines the steps to manually configure RBAC, with a focus on creating ClusterRoles and binding them to specific users or groups.

---

## 1. Finding API Groups and Resources Provided by a ClusterExtension

To create appropriate RBAC policies, you need to know which API groups and resources are exposed by the installed cluster extension. You can inspect the installed CRDs and resources by running:

```bash
kubectl get crds
```

This will list all available CRDs, and you can inspect individual CRDs for their API groups:

```bash
kubectl get crd <crd-name> -o yaml
```

A user can use label selectors to find CRDs owned by a specific cluster extension:

```bash
kubectl get crds -l 'olm.operatorframework.io/owner-kind=ClusterExtension,olm.operatorframework.io/owner-name=<clusterExtensionName>'
```

---

## 2. Creating Default ClusterRoles for API/CRD Access

Administrators can define standard roles to control access to the API resources provided by installed cluster extensions. If the cluster extension does not provide default roles, you can create them yourself.

### Default Roles

- **View ClusterRole**: Grants read-only access to all custom resource objects of specified API resources across the cluster. This role is intended for users who need visibility into the resources without any permissions to modify them. It’s ideal for monitoring purposes and limited access viewing.
- **Edit ClusterRole**: Allows users to modify all custom resource objects within the cluster. This role enables users to create, update, and delete resources, making it suitable for team members who need to manage resources but should not control RBAC or manage permissions for others.
- **Admin ClusterRole**: Provides full permissions (create, update, delete) over all custom resource objects for the specified API resources across the cluster.

### Example: Defining a Custom "View" ClusterRole

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: custom-resource-view
rules:
- apiGroups:
- <your-api-group>
resources:
- <your-custom-resources>
verbs:
- get
- list
- watch
```
### Example: Defining a Custom "Edit" ClusterRole
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: custom-resource-edit
rules:
- apiGroups:
- <your-api-group>
resources:
- <your-custom-resources>
verbs:
- get
- list
- watch
- create
- update
- patch
- delete
```
### Example: Defining a Custom "Admin" ClusterRole
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: custom-resource-admin
rules:
- apiGroups:
- <your-api-group>
resources:
- <your-custom-resources>
verbs:
- '*'
```
**Note**: The `'*'` in verbs allows all actions on the specified resources
In each case, replace `<your-api-group>` and `<your-custom-resources>` with the actual API group and resource names provided by the installed cluster extension.

---

## 3. Granting User Access to API Resources

Once the roles are created, you can bind them to specific users or groups to grant them the necessary permissions. There are two main ways to do this:

### Option 1: Binding Default ClusterRoles to Users

- **ClusterRoleBinding**: Use this to grant access across all namespaces.
- **RoleBinding**: Use this to grant access within a specific namespace.

#### Example: ClusterRoleBinding

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: custom-resource-view-binding
subjects:
- kind: User
name: <username> # Or use Group for group-based binding
roleRef:
kind: ClusterRole
name: custom-resource-view
apiGroup: rbac.authorization.k8s.io
```

This binding grants `<username>` read-only access to the custom resource across all namespaces.

#### Example: RoleBinding

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: custom-resource-edit-binding
namespace: <namespace>
subjects:
- kind: User
name: <username>
roleRef:
kind: Role
name: custom-resource-edit
apiGroup: rbac.authorization.k8s.io
```

This RoleBinding restricts permissions to a specific namespace.

### Option 2: Extending Default Kubernetes Roles

To automatically extend existing Kubernetes roles (e.g., the default `view`, `edit`, and `admin` roles), you can add **aggregation labels** to **ClusterRoles**. This allows users who already have `view`, `edit`, or `admin` roles to interact with the custom resource without needing additional RoleBindings.

#### Example: Adding Aggregation Labels to a ClusterRole

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: custom-resource-aggregated-view
labels:
rbac.authorization.k8s.io/aggregate-to-view: "true"
rules:
- apiGroups:
- <your-api-group>
resources:
- <your-custom-resource>
verbs:
- get
- list
- watch
```

You can create similar ClusterRoles for `edit` and `admin` with appropriate verbs (such as `create`, `update`, `delete` for `edit` and `admin`). By using aggregation labels, the permissions for the custom resources are added to the default roles.

> **Source**: [Kubernetes RBAC Aggregation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings)
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ nav:
- Version Range Upgrades: howto/how-to-version-range-upgrades.md
- Z-Stream Upgrades: howto/how-to-z-stream-upgrades.md
- Derive Service Account Permissions: howto/derive-service-account.md
- Grant Access to Your Extension's API: howto/how-to-grant-api-access.md
- Conceptual Guides:
- Single Owner Objects: concepts/single-owner-objects.md
- Upgrade Support: concepts/upgrade-support.md
Expand Down

0 comments on commit 8d535a6

Please sign in to comment.