chore: deprecate NetV2 upgrade steps, refactor install flow (#921)

ericpaulsen · Katie Horne · web-flow · commit b163e85ac252 · 2022-03-24T17:31:35.000-05:00
* deprecate NetV2 upgrade steps, refactor install flow

* chore: edit text

* rm: ingress routing &amp; db admin user

* fix: formatting

Co-authored-by: Katie Horne &lt;katie@coder.com&gt;
diff --git a/admin/devurls.md b/admin/devurls.md
@@ -26,23 +26,17 @@ your cluster, you'll need to modify your:
 
 ### Step 1: Modify the Helm chart
 
-Set `devurls.host` to a wildcard domain:
+Set `coderd.devurlsHost` to a wildcard domain in your `values.yaml` file:
 
-```shell
-helm upgrade coder coder/coder --set coderd.devurlsHost="*.my-custom-domain.io"
+```yaml
+coderd:
+  devurlsHost: "*.my-custom-domain.io"
 ```
 
-**Note:** If you are providing an ingress controller, then you will need to add
-the rule manually to the ingress.
+Run the `helm upgrade` command:
 
-```yaml
- - host: "*.my-custom-domain.io"
-    http:
-      paths:
-      - path: /
-        backend:
-          serviceName: coderd
-          servicePort: 8080
+```console
+helm upgrade coder coder/coder -n coder --version=<VERSION> --values values.yaml"
 ```
 
 > Beginning with Coder version `1.26.0`, you can set a constant suffix for all
diff --git a/setup/installation.md b/setup/installation.md
@@ -20,13 +20,13 @@ data, including workspace information and session tokens.
 ## Doctor
 
 Before proceeding, we strongly recommend running
-[Doctor](https://github.com/coder/coder-doctor), which is Coder-supplied
+[Doctor](https://github.com/coder/coder-doctor), which is a Coder-supplied
 command-line tool that evaluates whether your environment is ready to install
 Coder. If there are issues with your cluster that may impact the installation
-process, Doctor will return information on what the issue is and suggestions on
-how you can fix it.
+process, Doctor will return information on what the problem is and suggestions
+on how you can fix it.
 
-## Creating the Coder namespace (optional)
+## Create the Coder namespace (optional)
 
 We recommend running Coder in a separate
 [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/);
@@ -42,7 +42,7 @@ Next, change the kubectl context to point to your newly created namespace:
 kubectl config set-context --current --namespace=coder
 ```
 
-## Installing Coder
+## Install Coder
 
 1. Add the Coder Helm repo
 
@@ -54,42 +54,68 @@ kubectl config set-context --current --namespace=coder
    [changelog](../changelog/index.md) for a list of Coder versions or run
    `helm search repo coder -l`)
 
+   > 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.
+
    ```console
    helm install coder coder/coder --namespace coder --version=<VERSION>
    ```
 
-   **Steps 3-5 are optional for non-production deployments.**
+1. Once `coderd` is running, tail the logs to find the randomly generated
+   password for the admin user:
+
+   ```console
+   kubectl logs -n coder -l coder.deployment=coderd -c coderd \
+    --tail=-1 | grep -A1 -B2 Password
+   ```
+
+   When this step is done, you will see:
+
+   ```text
+   ----------------------
+   User:     admin
+   Password: kv...k3
+   ----------------------
+   ```
+
+   You will need these credentials to continue setup using Coder's web UI.
 
-1. Get a copy of your Helm config values so that you can modify it; you'll need
-   to modify these values to update your PostgreSQL databases (step 4) and
-   enable dev URLs (step 5):
+   > If you lose your admin credentials, you can use the
+   > [admin password reset](../admin/access-control/users/password-reset.md#resetting-the-site-admin-password)
+   > process to regain access.
 
-   a. Create an empty file called `values.yaml` which will contain your
-   deployment configuration options.
+1. Create a `values.yaml` file to configure Coder:
 
-   b. Edit the `values.yaml` file as needed.
+   ```console
+   helm show values coder/coder --version=<VERSION> > values.yaml
+   ```
 
    > View the
    > [configuration options available in the `values.yaml` file.](https://github.com/coder/enterprise-helm#values)
 
-   c. Upgrade/install your Coder deployment with the updated Helm chart (be sure
-   to replace the placeholder value with your Coder version). **This must be
-   done whenever you update the Helm chart:**
+1. **Optional**: change the admin user password by updating `values.yaml` as
+   follows:
 
-   ```console
-   helm upgrade coder coder/coder --namespace coder --version=<VERSION> --values values.yaml
+   ```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"
    ```
 
-   > If you omit `--version`, you'll upgrade to the latest version, excluding
-   > release candidates (RCs). To include RCs, provide the `--devel` flag.
-   >
-   > We do not provide documentation for RCs, and you should not use them unless
-   > you've been instructed to do so by Coder. You can identify RCs by the
-   > presence of `-rc` in the version number (e.g., `1.16.0-rc.1`).
+1. **Optional**: To configure an externally hosted database, set the following
+   in `values.yaml`:
 
-1. Ensure that you have superuser privileges to your PostgreSQL database. Add
-   the following to your Helm values so that Coder uses your external PostgreSQL
-   databases:
+   > Ensure that you have superuser privileges to your PostgreSQL database.
 
    ```yaml
    postgres:
@@ -103,60 +129,93 @@ kubectl config set-context --current --namespace=coder
      sslMode: require
    ```
 
-   To create the `passwordSecret`, run
-   `kubectl create secret generic <NAME> --from-literal="password=UserDefinedPassword"`
-   (be sure to replace `UserDefinedPassword` with your actual password).
+   a. To create the `passwordSecret`, run:
+
+   ```console
+   kubectl create secret generic <NAME> --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.
+   > 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.
 
-   You can find/define these values in your
-   [PostgreSQL server configuration file](https://www.postgresql.org/docs/current/config-setting.html).
+   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).
 
-   > For more information, [see our guide](../guides/deployments/postgres.md) on
-   > setting up a PostgreSQL instance.
+   ```yaml
+   coderd:
+     devurlsHost: "*.my-custom-domain.io"
+   ```
 
-1. [Enable dev URL usage](../admin/devurls.md). Dev URLs allow users to access
-   the web servers running in your workspace. To enable, provide a wildcard
-   domain and its DNS certificate and update your Helm chart accordingly. This
-   step is **optional** but recommended.
+1. **Optional:** To set up TLS:
 
-1. After you've created the pod, tail the logs to find the randomly generated
-   password for the admin user
+   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 logs -n coder -l coder.deployment=coderd -c coderd \
-    --tail=-1 | grep -A1 -B2 Password
+   kubectl create secret tls tls-secret --key key.pem --cert cert.pem
    ```
 
-   When this step is done, you will see:
+   > If your certificate provider does not provide `.pem` files, then you may
+   > need to attach the certificate to the LoadBalancer manually.
 
-   ```text
-   ----------------------
-   User:     admin
-   Password: kv...k3
-   ----------------------
+   b. Attach the secret to the `coderd` service by setting the following values:
+
+   ```yaml
+   coderd:
+     tls:
+       hostSecretName: <tls-secret>
+       devurlsHostSecretName: <tls-secret>
    ```
 
-   These are the credentials you need to continue setup using Coder's web UI.
+1. **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.
 
-> If you lose your admin credentials, you can use the
-> [admin password reset](../admin/access-control/users/password-reset.md#resetting-the-site-admin-password)
-> process to regain access.
+   ```yaml
+   coderd:
+     devurlsHost: "*.devurls.coderhost.com"
+     serviceSpec:
+       # The Ingress will route traffic to the internal ClusterIP.
+       type: ClusterIP
+       externalTrafficPolicy: ""
+     tls:
+       hostSecretName: <tls-secret>
+       devurlsHostSecretName: <tls-secret>
+   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: {}
+   ```
+
+1. 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=<VERSION> -f values.yaml
+   ```
 
 ## Logging
 
 At this time, we recommend reviewing Coder's default
-[logging](../guides/admin/logging.md) settings. Logs are helpful for monitoring
-the health of your cluster and troubleshooting, and Coder offers you several
-options for obtaining these.
+[logging](../guides/admin/logging.md) settings. Logs help monitor the health of
+your cluster and troubleshooting, and Coder offers you several options for
+obtaining these.
 
 ## Accessing Coder
 
diff --git a/setup/upgrade/index.md b/setup/upgrade/index.md
