Skip to content

Commit 39510f4

Browse files
ericpaulsenjohnstcn
ericpaulsen
and
johnstcn
authored
docs: add openshift install (#6165)
* docs: add openshift install * make: fmt * Apply suggestions from code review Update securityContext: set project-specific uid/gid, set readOnlyRootFilesystem=false * add steps for creating compatible image and template * Update docs/install/openshift.md * make fmt * docs: make changes on feedback * combine helm steps --------- Co-authored-by: Cian Johnston <cian@coder.com>
1 parent fadeb2b commit 39510f4

File tree

2 files changed

+250
-0
lines changed

2 files changed

+250
-0
lines changed

‎docs/install/openshift.md

+245
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
## Requirements
2+
3+
Before proceeding, please ensure that you have an OpenShift cluster running K8s
4+
1.19+ (OpenShift 4.7+) and have Helm 3.5+ installed. In addition, you'll need to
5+
install the OpenShift CLI (`oc`) to authenticate to your cluster and create OpenShift
6+
resources.
7+
8+
You'll also want to install the [latest version of Coder](https://github.com/coder/coder/releases/latest)
9+
locally in order to log in and manage templates.
10+
11+
## Install Coder with OpenShift
12+
13+
### 1. Authenticate to OpenShift and create a Coder project
14+
15+
Run the following command to login to your OpenShift cluster:
16+
17+
```console
18+
oc login --token=w4r...04s --server=<cluster-url>
19+
```
20+
21+
Next, you will run the below command to create a project for Coder:
22+
23+
```console
24+
oc new-project coder
25+
```
26+
27+
### 2. Configure SecurityContext values
28+
29+
Depending upon your configured Security Context Constraints (SCC), you'll need to set
30+
the following `securityContext` values in the Coder Helm chart:
31+
32+
```yaml
33+
coder:
34+
securityContext:
35+
runAsNonRoot: true
36+
runAsUser: <project-specific UID>
37+
runAsGroup: <project-specific GID>
38+
readOnlyRootFilesystem: false
39+
```
40+
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:
44+
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+
52+
### 3. Configure the Coder service, connection URLs, and cache values
53+
54+
To establish a connection to PostgreSQL, set the `CODER_PG_CONNECTION_URL` value.
55+
[See our Helm documentation](./kubernetes.md) on configuring the PostgreSQL connection
56+
URL as a secret. Additionally, if accessing Coder over a hostname, set the `CODER_ACCESS_URL`
57+
value.
58+
59+
By default, Coder creates the cache directory in `/home/coder/.cache`. Given the
60+
OpenShift-provided UID, the Coder container does not have permission to write to
61+
this directory. To fix this, set the `CODER_CACHE_DIRECTORY` environment variable
62+
to `/tmp/coder-cache`.
63+
64+
Additionally, create the Coder service as a `ClusterIP`. In the next step,
65+
you will create an OpenShift route that points to the service HTTP target port.
66+
67+
```yaml
68+
coder:
69+
service:
70+
type: ClusterIP
71+
env:
72+
- name: CODER_CACHE_DIRECTORY
73+
value: /tmp/coder-cache
74+
- name: CODER_PG_CONNECTION_URL
75+
valueFrom:
76+
secretKeyRef:
77+
key: url
78+
name: coder-db-url
79+
- name: CODER_ACCESS_URL
80+
value: "https://coder-example.apps.openshiftapps.com"
81+
securityContext:
82+
runAsNonRoot: true
83+
runAsUser: <project-specific UID>
84+
runAsGroup: <project-specific GID>
85+
readOnlyRootFilesystem: false
86+
```
87+
88+
> Note: OpenShift provides a Developer Catalog offering you can use to
89+
> install PostgreSQL into your cluster.
90+
91+
### 4. Create the OpenShift route
92+
93+
Below is the YAML spec for creating an OpenShift route that sends traffic to the
94+
HTTP port of the Coder service:
95+
96+
```yaml
97+
kind: Route
98+
apiVersion: route.openshift.io/v1
99+
metadata:
100+
namespace: coder
101+
spec:
102+
host: https://coder-example.apps.openshiftapps.com
103+
to:
104+
kind: Service
105+
name: coder
106+
tls:
107+
# if set to edge, OpenShift will terminate TLS prior to the traffic reaching
108+
# the service.
109+
termination: edge
110+
# if set to Redirect, insecure client connections are redirected to the secure
111+
# port
112+
insecureEdgeTerminationPolicy: Redirect
113+
port:
114+
targetPort: http
115+
```
116+
117+
Once complete, you can create this route in OpenShift via:
118+
119+
```console
120+
oc apply -f route.yaml
121+
```
122+
123+
### 5. Install Coder
124+
125+
You can now install Coder using the values you've set from the above steps. To do
126+
so, run the series of `helm` commands below:
127+
128+
```console
129+
helm repo add coder-v2 https://helm.coder.com/v2
130+
helm repo update
131+
helm install coder coder-v2/coder \
132+
--namespace coder \
133+
--values values.yaml
134+
```
135+
136+
### 6. Create an OpenShift-compatible image
137+
138+
While the deployment is spinning up, we will need to create some images that
139+
are compatible with OpenShift. These images can then be run without modifying
140+
the Security Context Constraints (SCCs) in OpenShift.
141+
142+
1. Determine the UID range for the project:
143+
144+
```console
145+
oc get project coder -o json | jq -r '.metadata.annotations'
146+
{
147+
"openshift.io/description": "",
148+
"openshift.io/display-name": "coder",
149+
"openshift.io/requester": "kube:admin",
150+
"openshift.io/sa.scc.mcs": "s0:c26,c15",
151+
"openshift.io/sa.scc.supplemental-groups": "1000680000/10000",
152+
"openshift.io/sa.scc.uid-range": "1000680000/10000"
153+
}
154+
```
155+
156+
Note the `uid-range` and `supplemental-groups`. In this case, the project `coder`
157+
has been allocated 10,000 UIDs starting at 1000680000, and 10,000 GIDs starting
158+
at 1000680000. In this example, we will pick UID and GID 1000680000.
159+
160+
1. Create a `BuildConfig` referencing the source image you want to customize.
161+
This will automatically kick off a `Build` that will remain pending until step 3.
162+
163+
> For more information, please consult the [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html).
164+
165+
```console
166+
oc create -f - <<EOF
167+
kind: BuildConfig
168+
apiVersion: build.openshift.io/v1
169+
metadata:
170+
name: enterprise-base
171+
namespace: coder
172+
spec:
173+
output:
174+
to:
175+
kind: ImageStreamTag
176+
name: 'enterprise-base:latest'
177+
strategy:
178+
type: Docker
179+
dockerStrategy:
180+
imageOptimizationPolicy: SkipLayers
181+
source:
182+
type: Dockerfile
183+
dockerfile: |
184+
# Specify the source image.
185+
FROM docker.io/codercom/enterprise-base:ubuntu
186+
187+
# Switch to root
188+
USER root
189+
190+
# As root:
191+
# 1) Remove the original coder user with UID 1000
192+
# 2) Add a coder group with an allowed UID
193+
# 3) Add a coder user as a member of the above group
194+
# 4) Fix ownership on the user's home directory
195+
RUN userdel coder && \
196+
groupadd coder -g 1000680000 && \
197+
useradd -l -u 1000680000 coder -g 1000680000 && \
198+
chown -R coder:coder /home/coder
199+
200+
# Go back to the user 'coder'
201+
USER coder
202+
triggers:
203+
- type: ConfigChange
204+
runPolicy: Serial
205+
EOF
206+
```
207+
208+
1. Create an `ImageStream` as a target for the previous step:
209+
210+
```console
211+
oc create imagestream enterprise-base
212+
```
213+
214+
The `Build` created in the previous step should now begin.
215+
Once completed, you should see output similar to the following:
216+
217+
```console
218+
oc get imagestreamtag
219+
NAME IMAGE REFERENCE UPDATED
220+
enterprise-base:latest image-registry.openshift-image-registry.svc:5000/coder/enterprise-base@sha256:1dbbe4ee11be9218e1e4741264135a4f57501fe592d94d20db6bfe11692accd1 55 minutes ago
221+
```
222+
223+
### 7. Create an OpenShift-compatible template
224+
225+
Start from the default "Kubernetes" template:
226+
227+
```console
228+
echo kubernetes | coderv2 templates init ./openshift-k8s
229+
cd ./openshift-k8s
230+
```
231+
232+
Edit `main.tf` and update the following fields of the Kubernetes pod resource:
233+
234+
- `spec.security_context`: remove this field.
235+
- `spec.container.image`: update this field to the newly built image hosted
236+
on the OpenShift image registry from the previous step.
237+
- `spec.container.security_context`: remove this field.
238+
239+
Finally, create the template:
240+
241+
```console
242+
coder template create kubernetes -d .
243+
```
244+
245+
This template should be ready to use straight away.

‎docs/manifest.json

+5
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,11 @@
3636
"description": "Install Coder with Kubernetes via Helm",
3737
"path": "./install/kubernetes.md"
3838
},
39+
{
40+
"title": "OpenShift",
41+
"description": "Install Coder on OpenShift",
42+
"path": "./install/openshift.md"
43+
},
3944
{
4045
"title": "Docker",
4146
"description": "Install Coder with Docker / docker-compose",

0 commit comments

Comments
 (0)