Nov 1, 2024 · Oct 30, 2024 · Oct 30, 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
 # 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
 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.
  -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
 "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
 # 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
 # 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 or on an existing
 Prometheus or Grafana stack 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: "1Gi"
    requests:
      cpu: "0.25"
      memory: "1Gi"
 …
 ```

 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
   ```
Original file line number	Diff line number	Diff line change
		@@ -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
Expand DownExpand Up		@@ -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.
Expand All		@@ -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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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",
EdwardAngert marked this conversation as resolved. Show resolvedHide resolved
		"children": [
		{
		"title": "Speed up your workspaces",
		"description": "Speed up your Coder templates and workspaces",
		"path": "./tutorials/best-practices/speed-up-templates.md"
		}
		]
		}
		]
		},
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,5 @@
		# Best practices

EdwardAngert marked this conversation as resolved. Show resolvedHide resolved
		Guides to help you make the most of your Coder experience.

		<children></children>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,143 @@
		# Speed up your Coder templates and workspaces

		October 31, 2024
EdwardAngert marked this conversation as resolved. Show resolvedHide resolved

		---

		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 or on an existing
		Prometheus or Grafana stack 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: "1Gi"
		requests:
		cpu: "0.25"
		memory: "1Gi"
		…
		```

		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
		```