diff --git a/docs/install/openshift.md b/docs/install/openshift.md new file mode 100644 index 0000000000000..e9081004e398f --- /dev/null +++ b/docs/install/openshift.md @@ -0,0 +1,245 @@ +## 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 --token=w4r...04s --server= +``` + +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: + runAsGroup: + readOnlyRootFilesystem: false +``` + +The above values are the Coder defaults. You will need to change these values in +accordance with the applied SCC. Retrieve the project UID range with the following +command: + +```console +oc get project coder -o json | jq -r '.metadata.annotations' +{ + "openshift.io/sa.scc.uid-range": "1000680000/10000" +} +``` + +### 3. Configure the Coder service, connection URLs, and cache values + +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. To fix this, set the `CODER_CACHE_DIRECTORY` environment variable +to `/tmp/coder-cache`. + +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 + - name: CODER_PG_CONNECTION_URL + valueFrom: + secretKeyRef: + key: url + name: coder-db-url + - name: CODER_ACCESS_URL + value: "https://coder-example.apps.openshiftapps.com" + securityContext: + runAsNonRoot: true + runAsUser: + runAsGroup: + readOnlyRootFilesystem: false +``` + +> Note: OpenShift provides a Developer Catalog offering you can use to +> install PostgreSQL into your cluster. + +### 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: + +```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 +``` + +### 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: + +```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 +``` + +### 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 +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 - <