Skip to content

Commit 80c7349

Browse files
johnstcnpull[bot]
johnstcn
authored and
pull[bot]
committed
chore(docs): update openshift documentation re psp (#7432)
1 parent 474e893 commit 80c7349

File tree

1 file changed

+89
-20
lines changed

1 file changed

+89
-20
lines changed

‎docs/install/openshift.md

Lines changed: 89 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -26,28 +26,55 @@ oc new-project coder
2626

2727
### 2. Configure SecurityContext values
2828

29-
Depending upon your configured Security Context Constraints (SCC), you'll need to set
30-
the following `securityContext` values in the Coder Helm chart:
29+
Depending upon your configured Security Context Constraints (SCC), you'll need to modify
30+
some or all of the following `securityContext` values from the default values:
31+
32+
The below values are modified from Coder defaults and allow the Coder deployment to run
33+
under the SCC `restricted-v2`.
34+
35+
> Note: `readOnlyRootFilesystem: true` is not technically required under
36+
> `restricted-v2`, but is often mandated in OpenShift environments.
3137
3238
```yaml
3339
coder:
3440
securityContext:
35-
runAsNonRoot: true
36-
runAsUser: <project-specific UID>
37-
runAsGroup: <project-specific GID>
38-
readOnlyRootFilesystem: false
41+
runAsNonRoot: true # Unchanged from default
42+
runAsUser: <project-specific UID> # Default: 1000, replace this with the correct UID for your project.
43+
runAsGroup: <project-specific GID> # Default: 1000, replace this with the correct GID for your project.
44+
readOnlyRootFilesystem: true # Default: false, this is often required in OpenShift environments.
45+
seccompProfile: RuntimeDefault # Unchanged from default
3946
```
4047
41-
The above values are the Coder defaults. You will need to change these values in
42-
accordance with the applied SCC. Retrieve the project UID range with the following
43-
command:
48+
- For `runAsUser` / `runAsGroup`, you can retrieve the correct values for project UID and project GID with the following
49+
command:
4450

45-
```console
46-
oc get project coder -o json | jq -r '.metadata.annotations'
47-
{
48-
"openshift.io/sa.scc.uid-range": "1000680000/10000"
49-
}
50-
```
51+
```console
52+
oc get project coder -o json | jq -r '.metadata.annotations'
53+
{
54+
"openshift.io/sa.scc.supplemental-groups": "1000680000/10000",
55+
"openshift.io/sa.scc.uid-range": "1000680000/10000"
56+
}
57+
```
58+
59+
Alternatively, you can set these values to `null` to allow OpenShift to automatically select
60+
the correct value for the project.
61+
62+
- For `readOnlyRootFilesystem`, consult the SCC under which Coder needs to run.
63+
In the below example, the `restricted-v2` SCC does not require a read-only root filesystem,
64+
while `restricted-custom` does:
65+
66+
```console
67+
oc get scc -o wide
68+
NAME PRIV CAPS SELINUX RUNASUSER FSGROUP SUPGROUP PRIORITY READONLYROOTFS VOLUMES
69+
restricted-custom false ["NET_BIND_SERVICE"] MustRunAs MustRunAsRange MustRunAs RunAsAny <no value> true ["configMap","downwardAPI","emptyDir","ephemeral","persistentVolumeClaim","projected","secret"]
70+
restricted-v2 false ["NET_BIND_SERVICE"] MustRunAs MustRunAsRange MustRunAs RunAsAny <no value> false ["configMap","downwardAPI","emptyDir","ephemeral","persistentVolumeClaim","projected","secret"]
71+
```
72+
73+
If you are unsure, we recommend setting `readOnlyRootFilesystem` to `true` in an OpenShift
74+
environment.
75+
76+
- For `seccompProfile`: in some environments, you may need to set this to `null` to allow OpenShift
77+
to pick its preferred value.
5178

5279
### 3. Configure the Coder service, connection URLs, and cache values
5380

@@ -59,8 +86,15 @@ value.
5986
By default, Coder creates the cache directory in `/home/coder/.cache`. Given the
6087
OpenShift-provided UID and `readOnlyRootFS` security context constraint, the Coder
6188
container does not have permission to write to this directory.
89+
6290
To fix this, you can mount a temporary volume in the pod and set
6391
the `CODER_CACHE_DIRECTORY` environment variable to that location.
92+
In the below example, we mount this under `/tmp` and set the cache location to
93+
`/tmp/coder`. This enables Coder to run with `readOnlyRootFilesystem: true`.
94+
95+
> Note: Depending on the number of templates and provisioners you use, you may
96+
> need to increase the size of the volume, as the `coder` pod will be automatically
97+
> restarted when this volume fills up.
6498

6599
Additionally, create the Coder service as a `ClusterIP`. In the next step,
66100
you will create an OpenShift route that points to the service HTTP target port.
@@ -71,7 +105,7 @@ coder:
71105
type: ClusterIP
72106
env:
73107
- name: CODER_CACHE_DIRECTORY
74-
value: /cache
108+
value: /tmp/coder
75109
- name: CODER_PG_CONNECTION_URL
76110
valueFrom:
77111
secretKeyRef:
@@ -87,10 +121,10 @@ coder:
87121
volumes:
88122
- name: "cache"
89123
emptyDir:
90-
sizeLimit: 500Mi
124+
sizeLimit: 1Gi
91125
volumeMounts:
92126
- name: "cache"
93-
mountPath: "/cache"
127+
mountPath: "/tmp"
94128
readOnly: false
95129
```
96130

@@ -142,6 +176,40 @@ helm install coder coder-v2/coder \
142176
--values values.yaml
143177
```
144178

179+
> Note: If the Helm installation fails with a Kubernetes RBAC error, check the permissions
180+
> of your OpenShift user using the `oc auth can-i` command.
181+
>
182+
> The below permissions are the minimum required:
183+
>
184+
> ```console
185+
> oc auth can-i --list
186+
> Resources Non-Resource URLs Resource Names Verbs
187+
> selfsubjectaccessreviews.authorization.k8s.io [] [] [create]
188+
> selfsubjectrulesreviews.authorization.k8s.io [] [] [create]
189+
> * [] [] [get list watch create update patch delete deletecollection]
190+
> *.apps [] [] [get list watch create update patch delete deletecollection]
191+
> *.rbac.authorization.k8s.io [] [] [get list watch create update patch delete deletecollection]
192+
> [/.well-known/*] [] [get]
193+
> [/.well-known] [] [get]
194+
> [/api/*] [] [get]
195+
> [/api] [] [get]
196+
> [/apis/*] [] [get]
197+
> [/apis] [] [get]
198+
> [/healthz] [] [get]
199+
> [/healthz] [] [get]
200+
> [/livez] [] [get]
201+
> [/livez] [] [get]
202+
> [/openapi/*] [] [get]
203+
> [/openapi] [] [get]
204+
> [/readyz] [] [get]
205+
> [/readyz] [] [get]
206+
> [/version/] [] [get]
207+
> [/version/] [] [get]
208+
> [/version] [] [get]
209+
> [/version] [] [get]
210+
> securitycontextconstraints.security.openshift.io [] [restricted-v2] [use]
211+
> ```
212+
145213
### 6. Create an OpenShift-compatible image
146214

147215
While the deployment is spinning up, we will need to create some images that
@@ -163,8 +231,9 @@ the Security Context Constraints (SCCs) in OpenShift.
163231
```
164232

165233
Note the `uid-range` and `supplemental-groups`. In this case, the project `coder`
166-
has been allocated 10,000 UIDs starting at 1000680000, and 10,000 GIDs starting
167-
at 1000680000. In this example, we will pick UID and GID 1000680000.
234+
has been allocated 10,000 UIDs and GIDs, both starting at `1000680000`.
235+
236+
In this example, we will pick both UID and GID `1000680000`.
168237

169238
1. Create a `BuildConfig` referencing the source image you want to customize.
170239
This will automatically kick off a `Build` that will remain pending until step 3.

0 commit comments

Comments
 (0)