From d04a93e8bb0c7c4d6fba4ee38efc119e7200ad05 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Thu, 2 Jun 2022 16:09:02 -0500 Subject: [PATCH 1/5] add: install formatting & proxy config --- setup/installation.md | 49 ++++++++++++++++++++++++++---------------- setup/upgrade/index.md | 6 ++++++ 2 files changed, 36 insertions(+), 19 deletions(-) diff --git a/setup/installation.md b/setup/installation.md index 227a589f6..2af1efa39 100644 --- a/setup/installation.md +++ b/setup/installation.md @@ -29,25 +29,16 @@ resources from > Both the Big Bang and Ironbank repositories are one release behind the latest > version of Coder. -## Create the Coder namespace (optional) +## Install Coder -We recommend running Coder in a separate -[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/); -to do so, run +1. Create the Coder namespace +[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/): ```console kubectl create namespace coder ``` -Next, change the kubectl context to point to your newly created namespace: - -```console -kubectl config set-context --current --namespace=coder -``` - -## Install Coder - -1. Add the Coder Helm repo +1. Add the Coder Helm repo: ```console helm repo add coder https://helm.coder.com @@ -59,7 +50,7 @@ kubectl config set-context --current --namespace=coder > This step will install Coder with the default configuration. This does not > set up dev URLs, TLS, ingress controllers, or an external database. To - > configure these recommended features, please go to step 4. + > configure these recommended features, please see the following sections. ```console helm install coder coder/coder --namespace coder --version= @@ -91,13 +82,15 @@ kubectl config set-context --current --namespace=coder 1. Create a `values.yaml` file to configure Coder: ```console - helm show values coder/coder --version= > values.yaml + helm show values coder/coder --namespace coder --version= > values.yaml ``` > View the > [configuration options available in the `values.yaml` file.](https://github.com/coder/enterprise-helm#values) -1. **Optional**: change the admin user password by updating `values.yaml` as +## Set the super admin password + +**Optional**: change the admin user password by updating `values.yaml` as follows: ```yaml @@ -115,7 +108,9 @@ kubectl config set-context --current --namespace=coder key: "password" ``` -1. **Optional**: To configure an externally hosted database, set the following +## Connect an external database + +**Optional**: To configure an externally hosted database, set the following in `values.yaml`: > Ensure that you have superuser privileges to your PostgreSQL database. @@ -159,7 +154,9 @@ kubectl config set-context --current --namespace=coder devurlsHost: "*.my-custom-domain.io" ``` -1. **Optional:** To set up TLS: +## Enable TLS + +**Optional:** To set up TLS: a. You will need to create a TLS secret. To do so, run the following with the `.pem` files provided by your certificate: @@ -180,7 +177,9 @@ kubectl config set-context --current --namespace=coder devurlsHostSecretName: ``` -1. **Optional:** If you cannot use a load balancer, you may need an ingress +## Set up an ingress controller + +**Optional:** If you cannot use a load balancer, you may need an ingress controller. To configure one with Coder, set the following in `values.yaml`: > We assume that you already have an ingress controller installed in your @@ -206,6 +205,18 @@ kubectl config set-context --current --namespace=coder annotations: {} ``` +## Proxy Configuration + +**Optional:** To have Coder initiate outbound connections via a proxy, set + the following (applicable) values: + + ```yaml + coderd: + proxy: + http: "" + https: "" + exempt: "cluster.local" + 1. Once you've implemented all of the changes in `values.yaml`, install Coder with the following command: diff --git a/setup/upgrade/index.md b/setup/upgrade/index.md index 43df5ab79..2c3f20e69 100644 --- a/setup/upgrade/index.md +++ b/setup/upgrade/index.md @@ -72,3 +72,9 @@ resources from ```console helm upgrade coder coder/coder -n coder --version= --values current-values.yaml ``` + +## Downgrading + +When attempting to troubleshoot Coder, you may want to roll back to an older +version of Coder. This is not supported nor recommended, as the database schema +is updated with every Coder upgrade. From 417382c2e62aca6eaf9ed1dd73b62a0f7e102890 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Thu, 2 Jun 2022 16:15:00 -0500 Subject: [PATCH 2/5] update: wording --- setup/upgrade/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup/upgrade/index.md b/setup/upgrade/index.md index 2c3f20e69..50466cc76 100644 --- a/setup/upgrade/index.md +++ b/setup/upgrade/index.md @@ -76,5 +76,5 @@ resources from ## Downgrading When attempting to troubleshoot Coder, you may want to roll back to an older -version of Coder. This is not supported nor recommended, as the database schema -is updated with every Coder upgrade. +version of Coder. This is not supported without using a database snapshot, as +the database schema will be out of date. From 4a0f9d8396aa757417f7ec21cd9644d47c00065a Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Fri, 3 Jun 2022 09:13:52 -0500 Subject: [PATCH 3/5] chore: edit text --- setup/upgrade/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup/upgrade/index.md b/setup/upgrade/index.md index 50466cc76..31c3f2769 100644 --- a/setup/upgrade/index.md +++ b/setup/upgrade/index.md @@ -76,5 +76,5 @@ resources from ## Downgrading When attempting to troubleshoot Coder, you may want to roll back to an older -version of Coder. This is not supported without using a database snapshot, as -the database schema will be out of date. +version of Coder. Doing so requires you to make and use a database snapshot +since the database schema will be out of date. From 5c7d8b9ef68308b76f56dd03dcdae5ae94640ab3 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Fri, 3 Jun 2022 09:23:33 -0500 Subject: [PATCH 4/5] chore: edit text --- setup/installation.md | 240 ++++++++++++++++++++++-------------------- 1 file changed, 124 insertions(+), 116 deletions(-) diff --git a/setup/installation.md b/setup/installation.md index 2af1efa39..54445f510 100644 --- a/setup/installation.md +++ b/setup/installation.md @@ -32,11 +32,11 @@ resources from ## Install Coder 1. Create the Coder namespace -[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/): + [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/): -```console -kubectl create namespace coder -``` + ```console + kubectl create namespace coder + ``` 1. Add the Coder Helm repo: @@ -88,141 +88,149 @@ kubectl create namespace coder > View the > [configuration options available in the `values.yaml` file.](https://github.com/coder/enterprise-helm#values) -## Set the super admin password +## Optional configuration + +The following sections walk you through optional confirmation steps; once you've +updated the configuration, you'll need to (re)install Coder. + +### Set the super admin password **Optional**: change the admin user password by updating `values.yaml` as - follows: - - ```yaml - superAdmin: - # Options for configuring the secret used to specify the password for the - # built-in super admin account. - passwordSecret: - # coderd.superAdmin.passwordSecret.name -- Name of a secret that should - # be used to determine the password for the super admin account. The - # password should be contained in the field `password`, or the manually - # specified one. - name: "" - # coderd.superAdmin.passwordSecret.key -- The key of the secret that - # contains the super admin password. - key: "password" - ``` +follows: + +```yaml +superAdmin: + # Options for configuring the secret used to specify the password for the + # built-in super admin account. + passwordSecret: + # coderd.superAdmin.passwordSecret.name -- Name of a secret that should + # be used to determine the password for the super admin account. The + # password should be contained in the field `password`, or the manually + # specified one. + name: "" + # coderd.superAdmin.passwordSecret.key -- The key of the secret that + # contains the super admin password. + key: "password" +``` -## Connect an external database +### Connect an external database -**Optional**: To configure an externally hosted database, set the following - in `values.yaml`: +**Optional**: To configure an externally hosted database, set the following in +`values.yaml`: - > Ensure that you have superuser privileges to your PostgreSQL database. +> Ensure that you have superuser privileges to your PostgreSQL database. - ```yaml - postgres: - default: - enable: false - host: HOST_ADDRESS - port: PORT_NUMBER - user: YOUR_USER_NAME - database: YOUR_DATABASE - passwordSecret: secret-name - sslMode: require - ``` +```yaml +postgres: + default: + enable: false + host: HOST_ADDRESS + port: PORT_NUMBER + user: YOUR_USER_NAME + database: YOUR_DATABASE + passwordSecret: secret-name + sslMode: require +``` - a. To create the `passwordSecret`, run: +To create the `passwordSecret`, run: - ```console - kubectl create secret generic --from-literal="password=UserDefinedPassword" - ``` +```console +kubectl create secret generic --from-literal="password=UserDefinedPassword" +``` - > Put a space before the command to prevent it from being saved in your shell - > history. - > - > Running this command could potentially expose your database password to - > other users on your system through `/proc`. If this is a concern, you can - > use `--from-file=password=/dev/stdin` instead of `--from-literal=...` to - > enter your password and press `Ctrl+D` when you're done to submit it. - > - > Ensure that there are no trailing white spaces in your password secret. - - For more detailed configuration instructions, - [see our PostgreSQL setup guide](../guides/deployments/postgres.md). - -1. **Optional**: Enable dev URL usage. - [You must provide a wildcard domain in the Helm chart](../admin/devurls.md). - - ```yaml - coderd: - devurlsHost: "*.my-custom-domain.io" - ``` +> Put a space before the command to prevent it from being saved in your shell +> history. +> +> Running this command could potentially expose your database password to other +> users on your system through `/proc`. If this is a concern, you can use +> `--from-file=password=/dev/stdin` instead of `--from-literal=...` to enter +> your password and press `Ctrl+D` when you're done to submit it. +> +> Ensure that there are no trailing white spaces in your password secret. + +For more detailed configuration instructions, +[see our PostgreSQL setup guide](../guides/deployments/postgres.md). + +### Enable dev URLs -## Enable TLS +**Optional**: Enable dev URL usage. +[You must provide a wildcard domain in the Helm chart](../admin/devurls.md). + +```yaml +coderd: + devurlsHost: "*.my-custom-domain.io" +``` + +### Enable TLS **Optional:** To set up TLS: - a. You will need to create a TLS secret. To do so, run the following with the - `.pem` files provided by your certificate: +a. You will need to create a TLS secret. To do so, run the following with the +`.pem` files provided by your certificate: - ```console - kubectl create secret tls tls-secret --key key.pem --cert cert.pem - ``` +```console +kubectl create secret tls tls-secret --key key.pem --cert cert.pem +``` - > If your certificate provider does not provide `.pem` files, then you may - > need to attach the certificate to the LoadBalancer manually. +> If your certificate provider does not provide `.pem` files, then you may need +> to attach the certificate to the LoadBalancer manually. - b. Attach the secret to the `coderd` service by setting the following values: +b. Attach the secret to the `coderd` service by setting the following values: - ```yaml - coderd: - tls: - hostSecretName: - devurlsHostSecretName: - ``` +```yaml +coderd: + tls: + hostSecretName: + devurlsHostSecretName: +``` -## Set up an ingress controller +### Set up an ingress controller **Optional:** If you cannot use a load balancer, you may need an ingress - controller. To configure one with Coder, set the following in `values.yaml`: - - > We assume that you already have an ingress controller installed in your - > cluster. - - ```yaml - coderd: - devurlsHost: "*.devurls.coderhost.com" - serviceSpec: - # The Ingress will route traffic to the internal ClusterIP. - type: ClusterIP - externalTrafficPolicy: "" - tls: - hostSecretName: - devurlsHostSecretName: - ingress: - enable: true - # Hostname to use for routing decisions - host: "coder.coderhost.com" - # Custom annotations to apply to the resulting Ingress object - # This is useful for configuring other controllers in the cluster - # such as cert-manager or the ingress controller - annotations: {} - ``` +controller. To configure one with Coder, set the following in `values.yaml`: + +> We assume that you already have an ingress controller installed in your +> cluster. + +```yaml +coderd: + devurlsHost: "*.devurls.coderhost.com" + serviceSpec: + # The Ingress will route traffic to the internal ClusterIP. + type: ClusterIP + externalTrafficPolicy: "" + tls: + hostSecretName: + devurlsHostSecretName: +ingress: + enable: true + # Hostname to use for routing decisions + host: "coder.coderhost.com" + # Custom annotations to apply to the resulting Ingress object + # This is useful for configuring other controllers in the cluster + # such as cert-manager or the ingress controller + annotations: {} +``` -## Proxy Configuration +### Configure your proxy -**Optional:** To have Coder initiate outbound connections via a proxy, set - the following (applicable) values: +**Optional:** To have Coder initiate outbound connections via a proxy, set the +following (applicable) values: - ```yaml - coderd: - proxy: - http: "" - https: "" - exempt: "cluster.local" +```yaml +coderd: + proxy: + http: "" + https: "" + exempt: "cluster.local" +``` -1. Once you've implemented all of the changes in `values.yaml`, install Coder - with the following command: +Once you've implemented all of the changes in `values.yaml`, install Coder with +the following command: - ```console - helm install coder coder/coder --namespace coder --version= -f values.yaml - ``` +```console +helm install coder coder/coder --namespace coder --version= -f values.yaml +``` ## Logging @@ -231,7 +239,7 @@ At this time, we recommend reviewing Coder's default your cluster and troubleshooting, and Coder offers you several options for obtaining these. -## Accessing Coder +## Access Coder 1. To access Coder's web UI, you'll need to get its IP address by running the following in the terminal to list the Kubernetes services running: @@ -251,7 +259,7 @@ obtaining these. At this point, you're ready to proceed to [configuring Coder](configuration.md). -## EKS troubleshooting +## Troubleshoot EKS If you're unable to access your Coder deployment via the external IP generated by EKS, this is likely due to `coderd` being scheduled onto the incorrect node From f57eee13c62930ea8990cd75858a08afcb8322c3 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Fri, 3 Jun 2022 11:07:11 -0500 Subject: [PATCH 5/5] fix: typo --- setup/installation.md | 234 ++++++++++++++++++++---------------------- 1 file changed, 114 insertions(+), 120 deletions(-) diff --git a/setup/installation.md b/setup/installation.md index 54445f510..c4cb73f73 100644 --- a/setup/installation.md +++ b/setup/installation.md @@ -31,12 +31,11 @@ resources from ## Install Coder -1. Create the Coder namespace - [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/): +1. Create the Coder [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/): - ```console - kubectl create namespace coder - ``` +```console +kubectl create namespace coder +``` 1. Add the Coder Helm repo: @@ -88,149 +87,144 @@ resources from > View the > [configuration options available in the `values.yaml` file.](https://github.com/coder/enterprise-helm#values) -## Optional configuration - -The following sections walk you through optional confirmation steps; once you've -updated the configuration, you'll need to (re)install Coder. - -### Set the super admin password +## Set the super admin password **Optional**: change the admin user password by updating `values.yaml` as -follows: - -```yaml -superAdmin: - # Options for configuring the secret used to specify the password for the - # built-in super admin account. - passwordSecret: - # coderd.superAdmin.passwordSecret.name -- Name of a secret that should - # be used to determine the password for the super admin account. The - # password should be contained in the field `password`, or the manually - # specified one. - name: "" - # coderd.superAdmin.passwordSecret.key -- The key of the secret that - # contains the super admin password. - key: "password" -``` + follows: + + ```yaml + superAdmin: + # Options for configuring the secret used to specify the password for the + # built-in super admin account. + passwordSecret: + # coderd.superAdmin.passwordSecret.name -- Name of a secret that should + # be used to determine the password for the super admin account. The + # password should be contained in the field `password`, or the manually + # specified one. + name: "" + # coderd.superAdmin.passwordSecret.key -- The key of the secret that + # contains the super admin password. + key: "password" + ``` -### Connect an external database +## Connect an external database -**Optional**: To configure an externally hosted database, set the following in -`values.yaml`: +**Optional**: To configure an externally hosted database, set the following + in `values.yaml`: -> Ensure that you have superuser privileges to your PostgreSQL database. + > Ensure that you have superuser privileges to your PostgreSQL database. -```yaml -postgres: - default: - enable: false - host: HOST_ADDRESS - port: PORT_NUMBER - user: YOUR_USER_NAME - database: YOUR_DATABASE - passwordSecret: secret-name - sslMode: require -``` + ```yaml + postgres: + default: + enable: false + host: HOST_ADDRESS + port: PORT_NUMBER + user: YOUR_USER_NAME + database: YOUR_DATABASE + passwordSecret: secret-name + sslMode: require + ``` -To create the `passwordSecret`, run: + a. To create the `passwordSecret`, run: -```console -kubectl create secret generic --from-literal="password=UserDefinedPassword" -``` + ```console + kubectl create secret generic --from-literal="password=UserDefinedPassword" + ``` -> Put a space before the command to prevent it from being saved in your shell -> history. -> -> Running this command could potentially expose your database password to other -> users on your system through `/proc`. If this is a concern, you can use -> `--from-file=password=/dev/stdin` instead of `--from-literal=...` to enter -> your password and press `Ctrl+D` when you're done to submit it. -> -> Ensure that there are no trailing white spaces in your password secret. + > Put a space before the command to prevent it from being saved in your shell + > history. + > + > Running this command could potentially expose your database password to + > other users on your system through `/proc`. If this is a concern, you can + > use `--from-file=password=/dev/stdin` instead of `--from-literal=...` to + > enter your password and press `Ctrl+D` when you're done to submit it. + > + > Ensure that there are no trailing white spaces in your password secret. -For more detailed configuration instructions, -[see our PostgreSQL setup guide](../guides/deployments/postgres.md). + For more detailed configuration instructions, + [see our PostgreSQL setup guide](../guides/deployments/postgres.md). -### Enable dev URLs +## Enable dev URLs **Optional**: Enable dev URL usage. -[You must provide a wildcard domain in the Helm chart](../admin/devurls.md). + [You must provide a wildcard domain in the Helm chart](../admin/devurls.md). -```yaml -coderd: - devurlsHost: "*.my-custom-domain.io" -``` + ```yaml + coderd: + devurlsHost: "*.my-custom-domain.io" + ``` -### Enable TLS +## Enable TLS **Optional:** To set up TLS: -a. You will need to create a TLS secret. To do so, run the following with the -`.pem` files provided by your certificate: + a. You will need to create a TLS secret. To do so, run the following with the + `.pem` files provided by your certificate: -```console -kubectl create secret tls tls-secret --key key.pem --cert cert.pem -``` + ```console + kubectl create secret tls tls-secret --key key.pem --cert cert.pem + ``` -> If your certificate provider does not provide `.pem` files, then you may need -> to attach the certificate to the LoadBalancer manually. + > If your certificate provider does not provide `.pem` files, then you may + > need to attach the certificate to the LoadBalancer manually. -b. Attach the secret to the `coderd` service by setting the following values: + b. Attach the secret to the `coderd` service by setting the following values: -```yaml -coderd: - tls: - hostSecretName: - devurlsHostSecretName: -``` + ```yaml + coderd: + tls: + hostSecretName: + devurlsHostSecretName: + ``` -### Set up an ingress controller +## Set up an ingress controller **Optional:** If you cannot use a load balancer, you may need an ingress -controller. To configure one with Coder, set the following in `values.yaml`: - -> We assume that you already have an ingress controller installed in your -> cluster. - -```yaml -coderd: - devurlsHost: "*.devurls.coderhost.com" - serviceSpec: - # The Ingress will route traffic to the internal ClusterIP. - type: ClusterIP - externalTrafficPolicy: "" - tls: - hostSecretName: - devurlsHostSecretName: -ingress: - enable: true - # Hostname to use for routing decisions - host: "coder.coderhost.com" - # Custom annotations to apply to the resulting Ingress object - # This is useful for configuring other controllers in the cluster - # such as cert-manager or the ingress controller - annotations: {} -``` + controller. To configure one with Coder, set the following in `values.yaml`: + + > We assume that you already have an ingress controller installed in your + > cluster. + + ```yaml + coderd: + devurlsHost: "*.devurls.coderhost.com" + serviceSpec: + # The Ingress will route traffic to the internal ClusterIP. + type: ClusterIP + externalTrafficPolicy: "" + tls: + hostSecretName: + devurlsHostSecretName: + ingress: + enable: true + # Hostname to use for routing decisions + host: "coder.coderhost.com" + # Custom annotations to apply to the resulting Ingress object + # This is useful for configuring other controllers in the cluster + # such as cert-manager or the ingress controller + annotations: {} + ``` -### Configure your proxy +## Configure a proxy -**Optional:** To have Coder initiate outbound connections via a proxy, set the -following (applicable) values: +**Optional:** To have Coder initiate outbound connections via a proxy, set + the following (applicable) values: -```yaml -coderd: - proxy: - http: "" - https: "" - exempt: "cluster.local" -``` + ```yaml + coderd: + proxy: + http: "" + https: "" + exempt: "cluster.local" + ``` -Once you've implemented all of the changes in `values.yaml`, install Coder with -the following command: +Once you've implemented all of the changes in `values.yaml`, upgrade Coder +with the following command: -```console -helm install coder coder/coder --namespace coder --version= -f values.yaml -``` + ```console + helm upgrade coder coder/coder --namespace coder --version= -f values.yaml + ``` ## Logging @@ -239,7 +233,7 @@ At this time, we recommend reviewing Coder's default your cluster and troubleshooting, and Coder offers you several options for obtaining these. -## Access Coder +## Accessing Coder 1. To access Coder's web UI, you'll need to get its IP address by running the following in the terminal to list the Kubernetes services running: @@ -259,7 +253,7 @@ obtaining these. At this point, you're ready to proceed to [configuring Coder](configuration.md). -## Troubleshoot EKS +## EKS troubleshooting If you're unable to access your Coder deployment via the external IP generated by EKS, this is likely due to `coderd` being scheduled onto the incorrect node