coder · EdwardAngert · Nov 1, 2024 · Oct 30, 2024 · Oct 30, 2024 · Oct 30, 2024
diff --git a/docs/images/best-practice/build-timeline.png b/docs/images/best-practice/build-timeline.png
diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md
@@ -1,6 +1,6 @@
 # Install Coder on Kubernetes
 
-You can install Coder on Kubernetes using Helm. We run on most Kubernetes
+You can install Coder on Kubernetes (K8s) using Helm. We run on most Kubernetes
 distributions, including [OpenShift](./openshift.md).
 
 ## Requirements
@@ -121,27 +121,27 @@ coder:
 We support two release channels: mainline and stable - read the
 [Releases](./releases.md) page to learn more about which best suits your team.
 
-For the **mainline** Coder release:
+- **Mainline** Coder release:
 
-   <!-- autoversion(mainline): "--version [version]" -->
+  <!-- autoversion(mainline): "--version [version]" -->
 
-```shell
-helm install coder coder-v2/coder \
-    --namespace coder \
-    --values values.yaml \
-    --version 2.15.0
-```
+  ```shell
+  helm install coder coder-v2/coder \
+      --namespace coder \
+      --values values.yaml \
+      --version 2.15.0
+  ```
 
-    	For the **stable** Coder release:
+- **Stable** Coder release:
 
-    		<!-- autoversion(stable): "--version [version]" -->
+  <!-- autoversion(stable): "--version [version]" -->
 
-```shell
-helm install coder coder-v2/coder \
-    --namespace coder \
-    --values values.yaml \
-    --version 2.15.1
-```
+  ```shell
+  helm install coder coder-v2/coder \
+      --namespace coder \
+      --values values.yaml \
+      --version 2.15.1
+  ```
 
 You can watch Coder start up by running `kubectl get pods -n coder`. Once Coder
 has started, the `coder-*` pods should enter the `Running` state.
@@ -167,6 +167,18 @@ helm upgrade coder coder-v2/coder \
   -f values.yaml
 ```
 
+## Coder Observability Chart
+
+Use the [Observability Helm chart](https://github.com/coder/observability) for a
+pre-built set of dashboards to monitor your control plane over time. It includes
+Grafana, Prometheus, Loki, and Alert Manager out-of-the-box, and can be deployed
+on your existing Grafana instance.
+
+We recommend that all administrators deploying on Kubernetes set the
+observability bundle up with the control plane from the start. For installation
+instructions, visit the
+[observability repository](https://github.com/coder/observability?tab=readme-ov-file#installation).
+
 ## Kubernetes Security Reference
 
 Below are common requirements we see from our enterprise customers when

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -723,6 +723,18 @@
 					"title": "FAQs",
 					"description": "Miscellaneous FAQs from our community",
 					"path": "./tutorials/faqs.md"
+				},
+				{
+					"title": "Best practices",
+					"description": "Guides to help you make the most of your Coder experience",
+					"path": "./tutorials/best-practices/index.md",
+					"children": [
+						{
+							"title": "Speed up your workspaces",
+							"description": "Speed up your Coder templates and workspaces",
+							"path": "./tutorials/best-practices/speed-up-templates.md"
+						}
+					]
 				}
 			]
 		},

diff --git a/docs/tutorials/best-practices/index.md b/docs/tutorials/best-practices/index.md
@@ -0,0 +1,5 @@
+# Best practices
+
+Guides to help you make the most of your Coder experience.
+
+<children></children>
diff --git a/docs/tutorials/best-practices/speed-up-templates.md b/docs/tutorials/best-practices/speed-up-templates.md
@@ -0,0 +1,143 @@
+# Speed up your Coder templates and workspaces
+
+October 31, 2024
+
+---
+
+If it takes your workspace a long time to start, find out why and make some
+changes to your Coder templates to help speed things up.
+
+## Monitoring
+
+You can monitor [Coder logs](../../admin/monitoring/logs.md) through the
+system-native tools on your deployment platform, or stream logs to tools like
+Splunk, Datadog, Grafana Loki, and others.
+
+### Workspace build timeline
+
+Use the **Build timeline** to monitor the time it takes to start specific
+workspaces. Identify long scripts, resources, and other things you can
+potentially optimize within the template.
+
+![Screenshot of a workspace and its build timeline](../../images/best-practice/build-timeline.png)
+
+Adjust this request to match your Coder access URL and workspace:
+
+```shell
+curl -X GET https://coder.example.com/api/v2/workspacebuilds/{workspacebuild}/timings \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+Visit the
+[API documentation](../../reference/api/builds.md#get-workspace-build-timings-by-id)
+for more information.
+
+### Coder Observability Chart
+
+Use the [Observability Helm chart](https://github.com/coder/observability) for a
+pre-built set of dashboards to monitor your control plane over time. It includes
+Grafana, Prometheus, Loki, and Alert Manager out-of-the-box, and can be deployed
+on your existing Grafana instance.
+
+We recommend that all administrators deploying on Kubernetes set the
+observability bundle up with the control plane from the start. For installation
+instructions, visit the
+[observability repository](https://github.com/coder/observability?tab=readme-ov-file#installation),
+or our [Kubernetes installation guide](../../install/kubernetes.md).
+
+### Enable Prometheus metrics for Coder
+
+[Prometheus.io](https://prometheus.io/docs/introduction/overview/#what-is-prometheus)
+is included as part of the [observability chart](#coder-observability-chart). It
+offers a variety of
+[available metrics](../../admin/integrations/prometheus.md#available-metrics),
+such as `coderd_provisionerd_job_timings_seconds` and
+`coderd_agentstats_startup_script_seconds`, which measure how long the workspace
+takes to provision and how long the startup script takes.
+
+You can
+[install it separately](https://prometheus.io/docs/prometheus/latest/getting_started/)
+if you prefer.
+
+## Provisioners
+
+`coder server` defaults to three provisioner daemons. Each provisioner daemon
+can handle one single job, such as start, stop, or delete at a time and can be
+resource intensive. When all provisioners are busy, workspaces enter a "pending"
+state until a provisioner becomes available.
+
+### Increase provisioner daemons
+
+Provisioners are queue-based to reduce unpredictable load to the Coder server.
+However, they can be scaled up to allow more concurrent provisioners. You risk
+overloading the central Coder server if you use too many built-in provisioners,
+so we recommend a maximum of five provisioners. For more than five provisioners,
+we recommend that you move to
+[external provisioners](../../admin/provisioners.md).
+
+If you can’t move to external provisioners, use the `provisioner-daemons` flag
+to increase the number of provisioner daemons to five:
+
+```shell
+coder server --provisioner-daemons=5
+```
+
+Visit the
+[CLI documentation](../../reference/cli/server.md#--provisioner-daemons) for
+more information about increasing provisioner daemons, configuring external
+provisioners, and other options.
+
+### Adjust provisioner CPU/memory
+
+We recommend that you deploy Coder to its own respective Kubernetes cluster,
+separate from production applications. Keep in mind that Coder runs development
+workloads, so the cluster should be deployed as such, without production-level
+configurations.
+
+Adjust the CPU and memory values as shown in
+[Helm provisioner values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml#L134-L141):
+
+```yaml
+…
+  resources:
+    limits:
+      cpu: "0.25"
+      memory: "1G"
+    requests:
+      cpu: "0.25"
+      memory: "1G"
+…
+```
+
+Visit the
+[validated architecture documentation](../../admin/infrastructure/validated-architectures/index.md#workspace-nodes)
+for more information.
+
+## Set up Terraform provider caching
+
+By default, Coder downloads each Terraform provider when a workspace starts.
+This can create unnecessary network and disk I/O.
+
+`terraform init` generates a `.terraform.lock.hcl` which instructs Coder
+provisioners to cache specific versions of your providers.
+
+To use `terraform init` to cache providers:
+
+1. Pull the templates to your local device:
+
+   ```shell
+   coder templates pull
+   ```
+
+1. Run `terraform init` to initialize the directory:
+
+   ```shell
+   terraform init
+   ```
+
+1. Push the templates back to your Coder deployment:
+
+   ```shell
+   coder templates push
+   ```