Skip to content

Commit 2039cb7

Browse files
laveryalaverya
authored
Merge pull request #3323 from replicatedhq/laverya/sc-124993/reduce-permissions-for-the-replicated-sdk
Document the actual RBAC permissions required and the minimalRBAC helm chart value
2 parents eb0f17a + d24a1fc commit 2039cb7

File tree

1 file changed

+285
-31
lines changed

1 file changed

+285
-31
lines changed

‎docs/vendor/replicated-sdk-customizing.md

Lines changed: 285 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,16 @@ For information about how to use a custom domain for the Replicated SDK image, s
66

77
## Customize RBAC for the SDK
88

9-
This section describes role-based access control (RBAC) for the Replicated SDK, including the default RBAC, minimum RBAC requirements, and how to install the SDK with custom RBAC.
9+
This section describes role-based access control (RBAC) for the Replicated SDK, including the default RBAC, minimal RBAC, and how to install the SDK with custom RBAC.
1010

1111
### Default RBAC
1212

13-
The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. The default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated` and `replicated-instance-report` Secrets:
13+
The SDK creates default Role, RoleBinding, and ServiceAccount objects during installation. When `replicated.minimalRBAC` is false, the default Role allows the SDK to get, list, and watch all resources in the namespace, to create Secrets, and to update the `replicated`, `replicated-instance-report`, `replicated-custom-app-metrics-report`, and `replicated-meta-data` Secrets:
1414

1515
```yaml
1616
apiVersion: rbac.authorization.k8s.io/v1
1717
kind: Role
1818
metadata:
19-
labels:
20-
{{- include "replicated.labels" . | nindent 4 }}
2119
name: replicated-role
2220
rules:
2321
- apiGroups:
@@ -44,30 +42,286 @@ rules:
4442
- replicated
4543
- replicated-instance-report
4644
- replicated-custom-app-metrics-report
45+
- replicated-meta-data
4746
```
4847
49-
### Minimum RBAC Requirements
48+
### Minimal RBAC
5049
51-
The SDK requires the following minimum RBAC permissions:
50+
With the Replicated SDK version 1.7.0 and later, you can enable a fully-featured but less permissive RBAC role by setting `minimalRBAC` to true in your Helm chart values, as shown below:
51+
52+
```yaml
53+
# Helm chart values.yaml
54+
55+
replicated:
56+
minimalRBAC: true
57+
```
58+
59+
The permissions included in the Minimal RBAC role vary depending on if you defined custom _status informers_ for your application. See one of the following sections for more information:
60+
* [Default Minimal RBAC Role Without Custom Status Informers](#default-no-status-informers)
61+
* [Default Minimal RBAC Role With Custom Status Informers](#default-status-informers)
62+
63+
<details>
64+
<summary>What are status informers?</summary>
65+
66+
The Replicated Vendor Portal uses status informers to provide application status data. For more information about status informers, see [Helm Installations](/vendor/insights-app-status#helm-installations) in _Enabling and Understanding Application Status_.
67+
</details>
68+
69+
#### Default Minimal RBAC Role Without Custom Status Informers {#default-no-status-informers}
70+
71+
If you did _not_ define custom status informers for your application, then the default minimal RBAC Role includes permissions for the SDK to `get`, `list`, and `watch` the following resources in the namespace:
72+
* Secrets
73+
* Deployments
74+
* StatefulSets
75+
* DaemonSets
76+
* Services
77+
* Ingresses
78+
* PVCs
79+
* Pods
80+
* ReplicaSets
81+
* Endpoints
82+
83+
These permissions allow the SDK to discover the Helm chart secret for your application, parse it to determine what resources to monitor, and then monitor those resources.
84+
85+
The following shows the default RBAC role for the SDK when Minimal RBAC is enabled and no customer status informers are defined:
86+
87+
```yaml
88+
# Generated RBAC role with no statusInformers
89+
90+
apiVersion: rbac.authorization.k8s.io/v1
91+
kind: Role
92+
metadata:
93+
name: replicated-role
94+
rules:
95+
- apiGroups:
96+
- ""
97+
resources:
98+
- secrets
99+
verbs:
100+
- create
101+
- apiGroups:
102+
- ""
103+
resourceNames:
104+
- replicated
105+
- replicated-instance-report
106+
- replicated-custom-app-metrics-report
107+
- replicated-meta-data
108+
resources:
109+
- secrets
110+
verbs:
111+
- update
112+
- apiGroups:
113+
- apps
114+
resourceNames:
115+
- replicated
116+
resources:
117+
- deployments
118+
verbs:
119+
- get
120+
- apiGroups:
121+
- apps
122+
resources:
123+
- replicasets
124+
verbs:
125+
- get
126+
- apiGroups:
127+
- ""
128+
resources:
129+
- pods
130+
verbs:
131+
- get
132+
- apiGroups:
133+
- ""
134+
resourceNames:
135+
- replicated
136+
resources:
137+
- secrets
138+
verbs:
139+
- get
140+
- apiGroups:
141+
- ""
142+
resources:
143+
- secrets
144+
verbs:
145+
- get
146+
- list
147+
- apiGroups:
148+
- apps
149+
resources:
150+
- deployments
151+
- replicasets
152+
- statefulsets
153+
- daemonsets
154+
verbs:
155+
- get
156+
- list
157+
- watch
158+
- apiGroups:
159+
- ""
160+
resources:
161+
- services
162+
- endpoints
163+
- persistentvolumeclaims
164+
verbs:
165+
- get
166+
- list
167+
- watch
168+
- apiGroups:
169+
- networking.k8s.io
170+
resources:
171+
- ingresses
172+
verbs:
173+
- get
174+
- list
175+
- watch
176+
- apiGroups:
177+
- ""
178+
resources:
179+
- pods
180+
verbs:
181+
- list
182+
```
183+
184+
#### Default Minimal RBAC Role With Custom Status Informers {#default-status-informers}
185+
186+
If you defined custom status informers for your application, then the default Minimal RBAC role is _not_ created with the ability to access all secrets, and other resources are specified by name when possible.
187+
188+
For example, the following custom `statusInformer` configuration defines specific Deployment and Service resources as status informers for the application:
189+
190+
```yaml
191+
# Helm chart values.yaml
192+
193+
replicated:
194+
minimalRBAC: true
195+
statusInformers:
196+
- deployment/replicated
197+
- deployment/myapp
198+
- service/replicated
199+
- service/myapp
200+
```
201+
202+
Given the custom `statusInformer` configuration above, the following Minimal RBAC role is created:
203+
204+
```yaml
205+
# Generated RBAC role with deployment/replicated, deployment/myapp, service/replicated and service/myapp statusinformers
206+
207+
apiVersion: rbac.authorization.k8s.io/v1
208+
kind: Role
209+
metadata:
210+
name: replicated-role
211+
rules:
212+
- apiGroups:
213+
- ""
214+
resources:
215+
- secrets
216+
verbs:
217+
- create
218+
- apiGroups:
219+
- ""
220+
resourceNames:
221+
- replicated
222+
- replicated-instance-report
223+
- replicated-custom-app-metrics-report
224+
- replicated-meta-data
225+
resources:
226+
- secrets
227+
verbs:
228+
- update
229+
- apiGroups:
230+
- apps
231+
resourceNames:
232+
- replicated
233+
resources:
234+
- deployments
235+
verbs:
236+
- get
237+
- apiGroups:
238+
- apps
239+
resources:
240+
- replicasets
241+
verbs:
242+
- get
243+
- apiGroups:
244+
- ""
245+
resources:
246+
- pods
247+
verbs:
248+
- get
249+
- apiGroups:
250+
- ""
251+
resourceNames:
252+
- replicated
253+
resources:
254+
- secrets
255+
verbs:
256+
- get
257+
- apiGroups:
258+
- apps
259+
resources:
260+
- deployments
261+
verbs:
262+
- list
263+
- watch
264+
- apiGroups:
265+
- apps
266+
resourceNames:
267+
- replicated
268+
- myapp
269+
resources:
270+
- deployments
271+
verbs:
272+
- get
273+
- apiGroups:
274+
- ""
275+
resources:
276+
- services
277+
- endpoints
278+
verbs:
279+
- list
280+
- watch
281+
- apiGroups:
282+
- ""
283+
resourceNames:
284+
- replicated
285+
- myapp
286+
resources:
287+
- services
288+
- endpoints
289+
verbs:
290+
- get
291+
```
292+
293+
### Install the SDK with Custom RBAC
294+
295+
To install with custom RBAC, you can use a custom ServiceAccount or a custom ClusterRole. See the sections below for more information.
296+
297+
#### Minimum RBAC Requirements
298+
299+
Any custom RBAC role that you create must include these permissions.
300+
301+
The SDK requires the following minimum RBAC permissions to start:
52302
* Create Secrets.
53-
* Get and update Secrets named `replicated`, `replicated-instance-report`, and `replicated-custom-app-metrics-report`.
54-
* The SDK requires the following minimum RBAC permissions for status informers:
55-
* If you defined custom status informers, then the SDK must have permissions to get, list, and watch all the resources listed in the `replicated.statusInformers` array in your Helm chart `values.yaml` file.
56-
* If you did _not_ define custom status informers, then the SDK must have permissions to get, list, and watch the following resources:
303+
* Get and update Secrets named `replicated`, `replicated-instance-report`, `replicated-meta-data`, and `replicated-custom-app-metrics-report`.
304+
* Get the `replicated` deployment.
305+
* Get the `replicaset` and `pods` corresponding to the `replicated` deployment.
306+
307+
The SDK requires the following minimum RBAC permissions for status informers:
308+
* If you defined custom status informers, then the SDK must have permissions to `list` and `watch` all the types of resources listed in the `replicated.statusInformers` array in your Helm chart `values.yaml` file, as well as the ability to `get` the named resource.
309+
310+
For example, if you have a single status informer `deployment/myapp`, then the SDK requires permissions to `list` and `watch` all deployments as well as `get` the `myapp` deployment.
311+
* If you did _not_ define custom status informers, then the SDK must:
312+
* Have permissions to `get`, and `list` all secrets within the namespace in order to discover the Helm Chart secret for your app.
313+
* Have permissions to `get`, `list`, and `watch` the following resources:
57314
* Deployments
58-
* Daemonsets
315+
* DaemonSets
59316
* Ingresses
60317
* PersistentVolumeClaims
61-
* Statefulsets
62-
* Services
63-
* For any Ingress resources used as status informers, the SDK requires `get` permissions for the Service resources listed in the `backend.Service.Name` field of the Ingress resource.
64-
* For any Daemonset and Statefulset resources used as status informers, the SDK requires `list` permissions for pods in the namespace.
65-
* For any Service resources used as status informers, the SDK requires `get` permissions for Endpoint resources with the same name as the service.
66-
67-
The Replicated Vendor Portal uses status informers to provide application status data. For more information, see [Helm Installations](/vendor/insights-app-status#helm-installations) in _Enabling and Understanding Application Status_.
68-
### Install the SDK with Custom RBAC
318+
* StatefulSets
319+
* Services
320+
* For any Ingress resources used as status informers, the SDK requires `get` permissions for the Service resources listed in the `backend.Service.Name` field of the Ingress resource.
321+
* For any DaemonSet and StatefulSet resources used as status informers, the SDK requires `list` permissions for pods in the namespace.
322+
* For any Service resources used as status informers, the SDK requires `get` permissions for Endpoint resources with the same name as the service.
69323

70-
#### Custom ServiceAccount
324+
#### Use a Custom ServiceAccount
71325

72326
To use the SDK with custom RBAC permissions, provide the name for a custom ServiceAccount object during installation. When a service account is provided, the SDK uses the RBAC permissions granted to the service account and does not create the default Role, RoleBinding, or ServiceAccount objects.
73327

@@ -76,15 +330,15 @@ To install the SDK with custom RBAC:
76330
1. Create custom Role, RoleBinding, and ServiceAccount objects. The Role must meet the minimum requirements described in [Minimum RBAC Requirements](#minimum-rbac-requirements) above.
77331
1. During installation, provide the name of the service account that you created by including `--set replicated.serviceAccountName=CUSTOM_SERVICEACCOUNT_NAME`.
78332

79-
**Example**:
333+
**Example**:
80334

81-
```
82-
helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.serviceAccountName=mycustomserviceaccount
83-
```
335+
```
336+
helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.serviceAccountName=mycustomserviceaccount
337+
```
84338
85-
For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm).
339+
For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm).
86340
87-
#### Custom ClusterRole
341+
#### Use a Custom ClusterRole
88342
89343
To use the SDK with an existing ClusterRole, provide the name for a custom ClusterRole object during installation. When a cluster role is provided, the SDK uses the RBAC permissions granted to the cluster role and does not create the default RoleBinding. Instead, the SDK creates a ClusterRoleBinding as well as a ServiceAccount object.
90344
@@ -93,13 +347,13 @@ To install the SDK with a custom ClusterRole:
93347
1. Create a custom ClusterRole object. The ClusterRole must meet at least the minimum requirements described in [Minimum RBAC Requirements](#minimum-rbac-requirements) above. However, it can also provide additional permissions that can be used by the SDK, such as listing cluster Nodes.
94348
1. During installation, provide the name of the cluster role that you created by including `--set replicated.clusterRole=CUSTOM_CLUSTERROLE_NAME`.
95349
96-
**Example**:
350+
**Example**:
97351
98-
```
99-
helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.clusterRole=mycustomclusterrole
100-
```
352+
```
353+
helm install wordpress oci://registry.replicated.com/my-app/beta/wordpress --set replicated.clusterRole=mycustomclusterrole
354+
```
101355
102-
For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm).
356+
For more information about installing with Helm, see [Install with Helm](/vendor/install-with-helm).
103357
104358
## Set Environment Variables {#env-var}
105359

0 commit comments

Comments
 (0)