From e26455704044e01e54fd35657630d1f37b2b5dc6 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Fri, 10 Feb 2023 18:28:59 -0500 Subject: [PATCH 1/8] docs: add openshift install --- docs/install/openshift.md | 148 ++++++++++++++++++++++++++++++++++++++ docs/manifest.json | 5 ++ 2 files changed, 153 insertions(+) create mode 100644 docs/install/openshift.md diff --git a/docs/install/openshift.md b/docs/install/openshift.md new file mode 100644 index 0000000000000..fac1815b66793 --- /dev/null +++ b/docs/install/openshift.md @@ -0,0 +1,148 @@ +## Requirements + +Before proceeding, please ensure that you have an OpenShift cluster running K8s +1.19+ (OpenShift 4.7+) and have Helm 3.5+ installed. In addition, you'll need to +install the OpenShift CLI (`oc`) to authenticate to your cluster and create OpenShift +resources. + +You'll also want to install the [latest version of Coder](https://github.com/coder/coder/releases/latest) +locally in order to log in and manage templates. + +## Install Coder with OpenShift + +### 1. Authenticate to OpenShift and create a Coder project + +Run the following command to login to your OpenShift cluster: + +```console +oc login +``` + +This will configure your local `~/.kube/config` file with the cluster credentials +needed when installing Coder via `helm`. + +Next, you will run the below command to create a project for Coder: + +```console +oc new-project coder +``` + +### 2. Configure SecurityContext values + +Depending upon your configured Security Context Constraints (SCC), you'll need to set +the following `securityContext` values in the Coder Helm chart: + +```yaml +coder: + securityContext: + runAsNonRoot: true + runAsUser: 1000 + runAsGroup: 1000 + readOnlyRootFilesystem: true + seccompProfile: + type: RuntimeDefault + allowPrivilegeEscalation: false +``` + +The above values are the Coder defaults. You will need to change these values in +accordance with the applied SCC. To get a current list of SCCs, run the below command: + +```console +oc get scc +``` + +> Note: you must have cluster-admin privileges to manage SCCs + +### 3. Set the `CODER_CACHE_DIRECTORY` environment variable + +By default, Coder creates the cache directory in `/home/coder/.cache`. Given the +OpenShift-provided UID, the Coder container does not have permission to write to +this directory. + +To address this issue, you will need to set the `CODER_CACHE_DIRECTORY` environment +variable in your Helm values to the following: + +```yaml +coder: + env: + - name: CODER_CACHE_DIRECTORY + value: /tmp/coder-cache +``` + +### 4. Set access URL, PostgreSQL connection values + +Set the `CODER_PG_CONNECTION_URL` value to enable Coder to establish a connection +to a PostgreSQL instance. [See our Helm documentation](./kubernetes.md) on configuring +the PostgreSQL connection URL as a secret. Additionally, if accessing Coder over a hostname, set +the `CODER_ACCESS_URL` value. + +```yaml +coder: + env: + - name: CODER_PG_CONNECTION_URL + valueFrom: + secretKeyRef: + key: url + name: coder-db-url + - name: CODER_ACCESS_URL + value: 'https://coder-example.apps.openshiftapps.com' +``` + +### 5. Configure the Coder service + +In this step, we will configure the Coder service as a `ClusterIP`, and create an +OpenShift route that points to the service HTTP target port. + +> Note that setting the `ClusterIP` service type for Coder is not required. +> `LoadBalancer` and `NodePort` services types can be used. + +Below are the Helm chart values for configuring the Coder service as a `ClusterIP`: + +```yaml +coder: + service: + type: ClusterIP +``` + +Below is the YAML spec for creating an OpenShift route that sends traffic to the +HTTP port of the Coder service: + +```yaml +kind: Route +apiVersion: route.openshift.io/v1 +metadata: + namespace: coder +spec: + host: https://coder-example.apps.openshiftapps.com + to: + kind: Service + name: coder + tls: + # if set to edge, OpenShift will terminate TLS prior to the traffic reaching + # the service. + termination: edge + # if set to Redirect, insecure client connections are redirected to the secure + # port + insecureEdgeTerminationPolicy: Redirect + port: + targetPort: http +``` + +Once complete, you can create this route in OpenShift via: + +```console +oc apply -f route.yaml +``` + +### 6. Install Coder + +You can now install Coder using the values you've set from the above steps. To do +so, run the series of `helm` commands below: + +```console +helm repo add coder-v2 https://helm.coder.com/v2 +helm repo update +helm install coder coder-v2/coder \ + --namespace coder \ + --values values.yaml +``` diff --git a/docs/manifest.json b/docs/manifest.json index ecfff14d19bb5..fa23797e77057 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -36,6 +36,11 @@ "description": "Install Coder with Kubernetes via Helm", "path": "./install/kubernetes.md" }, + { + "title": "OpenShift", + "description": "Install Coder on OpenShift", + "path": "./install/openshift.md" + }, { "title": "Docker", "description": "Install Coder with Docker / docker-compose", From 21e8bb4f4b4db554d06d36b1698ffffa10d60539 Mon Sep 17 00:00:00 2001 From: Eric Date: Mon, 13 Feb 2023 13:43:18 +0000 Subject: [PATCH 2/8] make: fmt --- docs/install/openshift.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/openshift.md b/docs/install/openshift.md index fac1815b66793..2bec8b5e57957 100644 --- a/docs/install/openshift.md +++ b/docs/install/openshift.md @@ -85,7 +85,7 @@ coder: key: url name: coder-db-url - name: CODER_ACCESS_URL - value: 'https://coder-example.apps.openshiftapps.com' + value: "https://coder-example.apps.openshiftapps.com" ``` ### 5. Configure the Coder service From aa8add4982705343e84d373c402a3f7c5ea28bba Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 17 Feb 2023 12:56:52 +0000 Subject: [PATCH 3/8] Apply suggestions from code review Update securityContext: set project-specific uid/gid, set readOnlyRootFilesystem=false --- docs/install/openshift.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/install/openshift.md b/docs/install/openshift.md index 2bec8b5e57957..f2542c7bb0972 100644 --- a/docs/install/openshift.md +++ b/docs/install/openshift.md @@ -36,9 +36,9 @@ the following `securityContext` values in the Coder Helm chart: coder: securityContext: runAsNonRoot: true - runAsUser: 1000 - runAsGroup: 1000 - readOnlyRootFilesystem: true + runAsUser: + runAsGroup: + readOnlyRootFilesystem: false seccompProfile: type: RuntimeDefault allowPrivilegeEscalation: false From 6f9d55f94a2fc949195545abedd38d3d43baedfc Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 17 Feb 2023 14:00:01 +0000 Subject: [PATCH 4/8] add steps for creating compatible image and template --- docs/install/openshift.md | 112 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/docs/install/openshift.md b/docs/install/openshift.md index f2542c7bb0972..49c585e744e86 100644 --- a/docs/install/openshift.md +++ b/docs/install/openshift.md @@ -146,3 +146,115 @@ helm install coder coder-v2/coder \ --namespace coder \ --values values.yaml ``` + +### 7. Create an OpenShift-compatible image + +While the deployment is spinning up, we will need to create some images that +are compatible with OpenShift. These images can then be run without modifying +the Security Context Constraints (SCCs) in OpenShift. + +1. Determine the UID range for the project: + + ```console + oc get project coder -o json | jq -r '.metadata.annotations' + { + "openshift.io/description": "", + "openshift.io/display-name": "coder", + "openshift.io/requester": "kube:admin", + "openshift.io/sa.scc.mcs": "s0:c26,c15", + "openshift.io/sa.scc.supplemental-groups": "1000680000/10000", + "openshift.io/sa.scc.uid-range": "1000680000/10000" + } + ``` + + Note the `uid-range` and `supplemental-groups`. In this case, the project `coder` + has been allocated 10,000 UIDs starting at 1000680000, and 10,000 GIDs starting + at 1000680000. In this example, we will pick UID and GID 1000680000. + +1. Create a `BuildConfig` referencing the source image you want to customize. + This will automatically kick off a `Build` that will remain pending until step 3. + + > For more information, please consult the [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html). + + ```console + oc create -f - < Date: Fri, 17 Feb 2023 17:11:18 +0000 Subject: [PATCH 5/8] Update docs/install/openshift.md --- docs/install/openshift.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/install/openshift.md b/docs/install/openshift.md index 49c585e744e86..a465c35aa8b88 100644 --- a/docs/install/openshift.md +++ b/docs/install/openshift.md @@ -42,6 +42,9 @@ coder: seccompProfile: type: RuntimeDefault allowPrivilegeEscalation: false + capabilities: + drop: + - ALL ``` The above values are the Coder defaults. You will need to change these values in From b91ae3bb9dbe63fb924e552d8d12d047b68ae3ed Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Mon, 13 Mar 2023 13:35:08 +0000 Subject: [PATCH 6/8] make fmt --- docs/install/openshift.md | 145 +++++++++++++++++++------------------- 1 file changed, 72 insertions(+), 73 deletions(-) diff --git a/docs/install/openshift.md b/docs/install/openshift.md index a465c35aa8b88..9e535ce0740e8 100644 --- a/docs/install/openshift.md +++ b/docs/install/openshift.md @@ -158,85 +158,84 @@ the Security Context Constraints (SCCs) in OpenShift. 1. Determine the UID range for the project: - ```console - oc get project coder -o json | jq -r '.metadata.annotations' - { - "openshift.io/description": "", - "openshift.io/display-name": "coder", - "openshift.io/requester": "kube:admin", - "openshift.io/sa.scc.mcs": "s0:c26,c15", - "openshift.io/sa.scc.supplemental-groups": "1000680000/10000", - "openshift.io/sa.scc.uid-range": "1000680000/10000" - } - ``` - - Note the `uid-range` and `supplemental-groups`. In this case, the project `coder` - has been allocated 10,000 UIDs starting at 1000680000, and 10,000 GIDs starting - at 1000680000. In this example, we will pick UID and GID 1000680000. + ```console + oc get project coder -o json | jq -r '.metadata.annotations' + { + "openshift.io/description": "", + "openshift.io/display-name": "coder", + "openshift.io/requester": "kube:admin", + "openshift.io/sa.scc.mcs": "s0:c26,c15", + "openshift.io/sa.scc.supplemental-groups": "1000680000/10000", + "openshift.io/sa.scc.uid-range": "1000680000/10000" + } + ``` + + Note the `uid-range` and `supplemental-groups`. In this case, the project `coder` + has been allocated 10,000 UIDs starting at 1000680000, and 10,000 GIDs starting + at 1000680000. In this example, we will pick UID and GID 1000680000. 1. Create a `BuildConfig` referencing the source image you want to customize. - This will automatically kick off a `Build` that will remain pending until step 3. - - > For more information, please consult the [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html). - - ```console - oc create -f - < For more information, please consult the [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html). + + ```console + oc create -f - < Date: Sun, 19 Mar 2023 22:40:38 +0000 Subject: [PATCH 7/8] docs: make changes on feedback --- docs/install/openshift.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/install/openshift.md b/docs/install/openshift.md index 9e535ce0740e8..9c30797d32ab3 100644 --- a/docs/install/openshift.md +++ b/docs/install/openshift.md @@ -15,12 +15,9 @@ locally in order to log in and manage templates. Run the following command to login to your OpenShift cluster: ```console -oc login +oc login --token=w4r...04s --server= ``` -This will configure your local `~/.kube/config` file with the cluster credentials -needed when installing Coder via `helm`. - Next, you will run the below command to create a project for Coder: ```console From 269a2e618fbc4e22848ef3d09194366fb4f650dd Mon Sep 17 00:00:00 2001 From: Eric Date: Mon, 20 Mar 2023 00:32:20 +0000 Subject: [PATCH 8/8] combine helm steps --- docs/install/openshift.md | 70 ++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 42 deletions(-) diff --git a/docs/install/openshift.md b/docs/install/openshift.md index 9c30797d32ab3..e9081004e398f 100644 --- a/docs/install/openshift.md +++ b/docs/install/openshift.md @@ -36,49 +36,41 @@ coder: runAsUser: runAsGroup: readOnlyRootFilesystem: false - seccompProfile: - type: RuntimeDefault - allowPrivilegeEscalation: false - capabilities: - drop: - - ALL ``` The above values are the Coder defaults. You will need to change these values in -accordance with the applied SCC. To get a current list of SCCs, run the below command: +accordance with the applied SCC. Retrieve the project UID range with the following +command: ```console -oc get scc +oc get project coder -o json | jq -r '.metadata.annotations' +{ + "openshift.io/sa.scc.uid-range": "1000680000/10000" +} ``` -> Note: you must have cluster-admin privileges to manage SCCs +### 3. Configure the Coder service, connection URLs, and cache values -### 3. Set the `CODER_CACHE_DIRECTORY` environment variable +To establish a connection to PostgreSQL, set the `CODER_PG_CONNECTION_URL` value. +[See our Helm documentation](./kubernetes.md) on configuring the PostgreSQL connection +URL as a secret. Additionally, if accessing Coder over a hostname, set the `CODER_ACCESS_URL` +value. By default, Coder creates the cache directory in `/home/coder/.cache`. Given the OpenShift-provided UID, the Coder container does not have permission to write to -this directory. +this directory. To fix this, set the `CODER_CACHE_DIRECTORY` environment variable +to `/tmp/coder-cache`. -To address this issue, you will need to set the `CODER_CACHE_DIRECTORY` environment -variable in your Helm values to the following: +Additionally, create the Coder service as a `ClusterIP`. In the next step, +you will create an OpenShift route that points to the service HTTP target port. ```yaml coder: + service: + type: ClusterIP env: - name: CODER_CACHE_DIRECTORY value: /tmp/coder-cache -``` - -### 4. Set access URL, PostgreSQL connection values - -Set the `CODER_PG_CONNECTION_URL` value to enable Coder to establish a connection -to a PostgreSQL instance. [See our Helm documentation](./kubernetes.md) on configuring -the PostgreSQL connection URL as a secret. Additionally, if accessing Coder over a hostname, set -the `CODER_ACCESS_URL` value. - -```yaml -coder: - env: - name: CODER_PG_CONNECTION_URL valueFrom: secretKeyRef: @@ -86,23 +78,17 @@ coder: name: coder-db-url - name: CODER_ACCESS_URL value: "https://coder-example.apps.openshiftapps.com" + securityContext: + runAsNonRoot: true + runAsUser: + runAsGroup: + readOnlyRootFilesystem: false ``` -### 5. Configure the Coder service - -In this step, we will configure the Coder service as a `ClusterIP`, and create an -OpenShift route that points to the service HTTP target port. - -> Note that setting the `ClusterIP` service type for Coder is not required. -> `LoadBalancer` and `NodePort` services types can be used. - -Below are the Helm chart values for configuring the Coder service as a `ClusterIP`: +> Note: OpenShift provides a Developer Catalog offering you can use to +> install PostgreSQL into your cluster. -```yaml -coder: - service: - type: ClusterIP -``` +### 4. Create the OpenShift route Below is the YAML spec for creating an OpenShift route that sends traffic to the HTTP port of the Coder service: @@ -134,7 +120,7 @@ Once complete, you can create this route in OpenShift via: oc apply -f route.yaml ``` -### 6. Install Coder +### 5. Install Coder You can now install Coder using the values you've set from the above steps. To do so, run the series of `helm` commands below: @@ -147,7 +133,7 @@ helm install coder coder-v2/coder \ --values values.yaml ``` -### 7. Create an OpenShift-compatible image +### 6. Create an OpenShift-compatible image While the deployment is spinning up, we will need to create some images that are compatible with OpenShift. These images can then be run without modifying @@ -234,7 +220,7 @@ the Security Context Constraints (SCCs) in OpenShift. enterprise-base:latest image-registry.openshift-image-registry.svc:5000/coder/enterprise-base@sha256:1dbbe4ee11be9218e1e4741264135a4f57501fe592d94d20db6bfe11692accd1 55 minutes ago ``` -### 8. Create an OpenShift-compatible template +### 7. Create an OpenShift-compatible template Start from the default "Kubernetes" template: