Skip to content

Commit dd86fd4

Browse files
adellapeadellape
committed
Granting user access to OLMv1 extension resources
1 parent dab6efe commit dd86fd4

6 files changed

+314
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2100,6 +2100,8 @@ Topics:
21002100
Topics:
21012101
- Name: Managing extensions
21022102
File: managing-ce
2103+
- Name: User access to extension resources
2104+
File: user-access-resources
21032105
- Name: Update paths
21042106
File: update-paths
21052107
- Name: CRD upgrade safety

‎extensions/ce/user-access-resources.adoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="user-access-resources"]
3+
= User access to extension resources
4+
include::_attributes/common-attributes.adoc[]
5+
:context: user-access-resources
6+
7+
toc::[]
8+
9+
After a cluster extension has been installed and is being managed by {olmv1-first}, the extension can often provide `CustomResourceDefinition` objects (CRDs) that expose new API resources on the cluster. Cluster administrators typically have full management access to these resources by default, whereas non-cluster administrator users, or _regular users_, might lack sufficient permissions.
10+
11+
{olmv1} does not automatically configure or manage role-based access control (RBAC) for regular users to interact with the APIs provided by installed extensions. Cluster administrators must define the required RBAC policy to create, view, or edit these custom resources (CRs) for such users.
12+
13+
[NOTE]
14+
====
15+
The RBAC permissions described for user access to extension resources are different from the permissions that must be added to a service account to enable {olmv1}-based initial installation of a cluster extension itself. For more on RBAC requirements while installing an extension, see "Cluster extension permissions" in "Managing extensions".
16+
====
17+
18+
[role="_additional-resources"]
19+
.Additional resources
20+
* xref:../../extensions/ce/managing-ce.adoc#managing-ce["Managing extensions" -> "Cluster extension permissions"]
21+
22+
include::modules/olmv1-default-cluster-roles-users.adoc[leveloffset=+1]
23+
24+
[role="_additional-resources"]
25+
.Additional resources
26+
* link:https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles[User-facing roles] (Kubernetes documentation)
27+
28+
include::modules/olmv1-finding-ce-resources.adoc[leveloffset=+1]
29+
include::modules/olmv1-granting-user-access-binding.adoc[leveloffset=+1]
30+
include::modules/olmv1-granting-user-access-aggregated.adoc[leveloffset=+1]
31+
32+
[role="_additional-resources"]
33+
.Additional resources
34+
* link:https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles[Aggregated ClusterRoles] (Kubernetes documentation)
35+

‎modules/olmv1-default-cluster-roles-users.adoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * extensions/ce/user-access-resources.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
7+
[id="olmv1-default-cluster-roles-users_{context}"]
8+
= Common default cluster roles for users
9+
10+
An installed cluster extension might include default cluster roles to determine role-based access control (RBAC) for regular users to API resources provided by the extension. A common set of cluster roles can resemble the following policies:
11+
12+
`view` cluster role:: Grants read-only access to all custom resource (CR) objects of specified API resources across the cluster. Intended for regular users who require visibility into the resources without any permissions to modify them. Ideal for monitoring purposes and limited access viewing.
13+
`edit` cluster role:: Allows users to modify all CR objects within the cluster. Enables users to create, update, and delete resources, making it suitable for team members who must manage resources but should not control RBAC or manage permissions for others.
14+
`admin` cluster role:: Provides full permissions, including `create`, `update`, and `delete` verbs, over all custom resource objects for the specified API resources across the cluster.

‎modules/olmv1-finding-ce-resources.adoc

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * extensions/ce/user-access-resources.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
7+
[id="olmv1-finding-ce-resources_{context}"]
8+
= Finding API groups and resources exposed by a cluster extension
9+
10+
To create appropriate RBAC policies for granting user access to cluster extension resources, you must know which API groups and resources are exposed by the installed extension. As an administrator, you can inspect custom resource definitions (CRDs) installed on the cluster by using {oc-first}.
11+
12+
.Prerequisites
13+
14+
* A cluster extension has been installed on your cluster.
15+
16+
.Procedure
17+
18+
* To list installed CRDs while specifying a label selector targeting a specific cluster extension by name to find only CRDs owned by that extension, run the following command:
19+
+
20+
[source,terminal]
21+
----
22+
$ oc get crds -l 'olm.operatorframework.io/owner-kind=ClusterExtension,olm.operatorframework.io/owner-name=<cluster_extension_name>'
23+
----
24+
25+
* Alternatively, you can search through all installed CRDs and individually inspect them by CRD name:
26+
27+
.. List all available custom resource definitions (CRDs) currently installed on the cluster by running the following command:
28+
+
29+
[source,terminal]
30+
----
31+
$ oc get crds
32+
----
33+
+
34+
Find the CRD you are looking for in the output.
35+
36+
.. Inspect the individual CRD further to find its API groups by running the following command:
37+
+
38+
[source,terminal]
39+
----
40+
$ oc get crd <crd_name> -o yaml
41+
----
42+

‎modules/olmv1-granting-user-access-aggregated.adoc

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * extensions/ce/user-access-resources.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
7+
[id="olmv1-granting-user-access-aggregated_{context}"]
8+
= Granting user access to extension resources by using aggregated cluster roles
9+
10+
As a cluster administrator, you can configure role-based access control (RBAC) policies to grant user access to extension resources by using aggregated cluster roles.
11+
12+
To automatically extend existing default cluster roles, you can add _aggregation labels_ by adding one or more of the following labels to a `ClusterRole` object:
13+
14+
.Aggregation labels in a `ClusterRole` object
15+
[source,yaml]
16+
----
17+
# ..
18+
metadata:
19+
labels:
20+
rbac.authorization.k8s.io/aggregate-to-admin: "true"
21+
rbac.authorization.k8s.io/aggregate-to-edit: "true"
22+
rbac.authorization.k8s.io/aggregate-to-view: "true"
23+
# ..
24+
----
25+
26+
This allows users who already have `view`, `edit`, or `admin` roles to interact with the custom resource specified by the `ClusterRole` object without requiring additional role or cluster role bindings to specific users or groups.
27+
28+
.Prerequisites
29+
30+
* A cluster extension has been installed on your cluster.
31+
* You have a list of API groups and resource names, as described in "Finding API groups and resources exposed by a cluster extension".
32+
33+
.Procedure
34+
35+
. Create an object definition for a cluster role that specifies the API groups and resources provided by the cluster extension and add an aggregation label to extend one or more existing default cluster roles:
36+
+
37+
.Example `ClusterRole` object with an aggregation label
38+
[source,yaml]
39+
----
40+
apiVersion: rbac.authorization.k8s.io/v1
41+
kind: ClusterRole
42+
metadata:
43+
name: view-custom-resource-aggregated
44+
labels:
45+
rbac.authorization.k8s.io/aggregate-to-view: "true"
46+
rules:
47+
- apiGroups:
48+
- <cluster_extension_api_group>
49+
resources:
50+
- <cluster_extension_custom_resource>
51+
verbs:
52+
- get
53+
- list
54+
- watch
55+
----
56+
+
57+
You can create similar `ClusterRole` objects for `edit` and `admin` with appropriate verbs, such as `create`, `update`, and `delete`. By using aggregation labels, the permissions for the custom resources are added to the default roles.
58+
59+
. Save your object definition to a YAML file.
60+
61+
. Create the object by running the following command:
62+
+
63+
[source,terminal]
64+
----
65+
$ oc create -f <filename>.yaml
66+
----

‎modules/olmv1-granting-user-access-binding.adoc

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * extensions/ce/user-access-resources.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
7+
[id="olmv1-granting-user-access-binding_{context}"]
8+
= Granting user access to extension resources by using custom role bindings
9+
10+
As a cluster administrator, you can manually create and configure role-based access control (RBAC) policies to grant user access to extension resources by using custom role bindings.
11+
12+
.Prerequisites
13+
14+
* A cluster extension has been installed on your cluster.
15+
* You have a list of API groups and resource names, as described in "Finding API groups and resources exposed by a cluster extension".
16+
17+
.Procedure
18+
19+
. If the installed cluster extension does not provide default cluster roles, manually create one or more roles:
20+
21+
.. Consider the use cases for the set of roles described in "Common default cluster roles for users".
22+
+
23+
For example, create one or more of the following `ClusterRole` object definitions, replacing `<cluster_extension_api_group>` and `<cluster_extension_custom_resource>` with the actual API group and resource names provided by the installed cluster extension:
24+
+
25+
.Example `view-custom-resource.yaml` file
26+
[source,yaml]
27+
----
28+
apiVersion: rbac.authorization.k8s.io/v1
29+
kind: ClusterRole
30+
metadata:
31+
name: view-custom-resource
32+
rules:
33+
- apiGroups:
34+
- <cluster_extension_api_group>
35+
resources:
36+
- <cluster_extension_custom_resources>
37+
verbs:
38+
- get
39+
- list
40+
- watch
41+
----
42+
+
43+
.Example `edit-custom-resource.yaml` file
44+
[source,yaml]
45+
----
46+
apiVersion: rbac.authorization.k8s.io/v1
47+
kind: ClusterRole
48+
metadata:
49+
name: edit-custom-resource
50+
rules:
51+
- apiGroups:
52+
- <cluster_extension_api_group>
53+
resources:
54+
- <cluster_extension_custom_resources>
55+
verbs:
56+
- get
57+
- list
58+
- watch
59+
- create
60+
- update
61+
- patch
62+
- delete
63+
----
64+
+
65+
.Example `admin-custom-resource.yaml` file
66+
[source,yaml]
67+
----
68+
apiVersion: rbac.authorization.k8s.io/v1
69+
kind: ClusterRole
70+
metadata:
71+
name: admin-custom-resource
72+
rules:
73+
- apiGroups:
74+
- <cluster_extension_api_group>
75+
resources:
76+
- <cluster_extension_custom_resources>
77+
verbs:
78+
- '*' <1>
79+
----
80+
<1> Setting a wildcard (`*`) in `verbs` allows all actions on the specified resources.
81+
82+
.. Create the cluster roles by running the following command for any YAML files you created:
83+
+
84+
[source,terminal]
85+
----
86+
$ oc create -f <filename>.yaml
87+
----
88+
89+
. Associate a cluster role to specific users or groups to grant them the necessary permissions for the resource by binding the cluster roles to individual user or group names:
90+
91+
.. Create an object definition for either a _cluster role binding_ to grant access across all namespaces or a _role binding_ to grant access within a specific namespace:
92+
+
93+
--
94+
*** The following example cluster role bindings grant read-only `view` access to the custom resource across all namespaces:
95+
+
96+
.Example `ClusterRoleBinding` object for a user
97+
[source,yaml]
98+
----
99+
apiVersion: rbac.authorization.k8s.io/v1
100+
kind: ClusterRoleBinding
101+
metadata:
102+
name: view-custom-resource-binding
103+
subjects:
104+
- kind: User
105+
name: <user_name>
106+
roleRef:
107+
kind: ClusterRole
108+
name: view-custom-resource
109+
apiGroup: rbac.authorization.k8s.io
110+
----
111+
+
112+
.Example `ClusterRoleBinding` object for a user
113+
[source,yaml]
114+
----
115+
apiVersion: rbac.authorization.k8s.io/v1
116+
kind: ClusterRoleBinding
117+
metadata:
118+
name: view-custom-resource-binding
119+
subjects:
120+
- kind: Group
121+
name: <group_name>
122+
roleRef:
123+
kind: ClusterRole
124+
name: view-custom-resource
125+
apiGroup: rbac.authorization.k8s.io
126+
----
127+
128+
*** The following role binding restricts `edit` permissions to a specific namespace:
129+
+
130+
.Example `RoleBinding` object for a user
131+
[source,yaml]
132+
----
133+
apiVersion: rbac.authorization.k8s.io/v1
134+
kind: RoleBinding
135+
metadata:
136+
name: edit-custom-resource-edit-binding
137+
namespace: <namespace>
138+
subjects:
139+
- kind: User
140+
name: <username>
141+
roleRef:
142+
kind: Role
143+
name: custom-resource-edit
144+
apiGroup: rbac.authorization.k8s.io
145+
----
146+
--
147+
148+
.. Save your object definition to a YAML file.
149+
150+
.. Create the object by running the following command:
151+
+
152+
[source,terminal]
153+
----
154+
$ oc create -f <filename>.yaml
155+
----

0 commit comments

Comments
 (0)