Skip to content

Commit 131cb0d

Browse files
EdwardAngertmatifalibpmct
authored and
stirby
committed
docs: add new best practice doc to speed up templates and workspaces (#15296)
closes #14858 - [x] TODO: update `build-timeline.png` - [x] TODO: `Best practices` doesn't show up in the sidebar until you're actually in the doc 🤔 [preview](https://coder.com/docs/@bp-speed-up-templates/tutorials/best-practices/speed-up-templates) --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Muhammad Atif Ali <atif@coder.com> Co-authored-by: Ben Potter <ben@coder.com> (cherry picked from commit 18ef954)
1 parent 920c275 commit 131cb0d

File tree

5 files changed

+189
-17
lines changed

5 files changed

+189
-17
lines changed

‎docs/images/best-practice/build-timeline.png

110 KB
Loading

‎docs/install/kubernetes.md

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Install Coder on Kubernetes
22

3-
You can install Coder on Kubernetes using Helm. We run on most Kubernetes
3+
You can install Coder on Kubernetes (K8s) using Helm. We run on most Kubernetes
44
distributions, including [OpenShift](./openshift.md).
55

66
## Requirements
@@ -121,27 +121,27 @@ coder:
121121
We support two release channels: mainline and stable - read the
122122
[Releases](./releases.md) page to learn more about which best suits your team.
123123

124-
For the **mainline** Coder release:
124+
- **Mainline** Coder release:
125125

126-
<!-- autoversion(mainline): "--version [version]" -->
126+
<!-- autoversion(mainline): "--version [version]" -->
127127

128-
```shell
129-
helm install coder coder-v2/coder \
130-
--namespace coder \
131-
--values values.yaml \
132-
--version 2.15.0
133-
```
128+
```shell
129+
helm install coder coder-v2/coder \
130+
--namespace coder \
131+
--values values.yaml \
132+
--version 2.15.0
133+
```
134134

135-
For the **stable** Coder release:
135+
- **Stable** Coder release:
136136

137-
<!-- autoversion(stable): "--version [version]" -->
137+
<!-- autoversion(stable): "--version [version]" -->
138138

139-
```shell
140-
helm install coder coder-v2/coder \
141-
--namespace coder \
142-
--values values.yaml \
143-
--version 2.15.1
144-
```
139+
```shell
140+
helm install coder coder-v2/coder \
141+
--namespace coder \
142+
--values values.yaml \
143+
--version 2.15.1
144+
```
145145

146146
You can watch Coder start up by running `kubectl get pods -n coder`. Once Coder
147147
has started, the `coder-*` pods should enter the `Running` state.
@@ -167,6 +167,18 @@ helm upgrade coder coder-v2/coder \
167167
-f values.yaml
168168
```
169169

170+
## Coder Observability Chart
171+
172+
Use the [Observability Helm chart](https://github.com/coder/observability) for a
173+
pre-built set of dashboards to monitor your control plane over time. It includes
174+
Grafana, Prometheus, Loki, and Alert Manager out-of-the-box, and can be deployed
175+
on your existing Grafana instance.
176+
177+
We recommend that all administrators deploying on Kubernetes set the
178+
observability bundle up with the control plane from the start. For installation
179+
instructions, visit the
180+
[observability repository](https://github.com/coder/observability?tab=readme-ov-file#installation).
181+
170182
## Kubernetes Security Reference
171183

172184
Below are common requirements we see from our enterprise customers when

‎docs/manifest.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -723,6 +723,18 @@
723723
"title": "FAQs",
724724
"description": "Miscellaneous FAQs from our community",
725725
"path": "./tutorials/faqs.md"
726+
},
727+
{
728+
"title": "Best practices",
729+
"description": "Guides to help you make the most of your Coder experience",
730+
"path": "./tutorials/best-practices/index.md",
731+
"children": [
732+
{
733+
"title": "Speed up your workspaces",
734+
"description": "Speed up your Coder templates and workspaces",
735+
"path": "./tutorials/best-practices/speed-up-templates.md"
736+
}
737+
]
726738
}
727739
]
728740
},

‎docs/tutorials/best-practices/index.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Best practices
2+
3+
Guides to help you make the most of your Coder experience.
4+
5+
<children></children>

‎docs/tutorials/best-practices/speed-up-templates.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Speed up your Coder templates and workspaces
2+
3+
October 31, 2024
4+
5+
---
6+
7+
If it takes your workspace a long time to start, find out why and make some
8+
changes to your Coder templates to help speed things up.
9+
10+
## Monitoring
11+
12+
You can monitor [Coder logs](../../admin/monitoring/logs.md) through the
13+
system-native tools on your deployment platform, or stream logs to tools like
14+
Splunk, Datadog, Grafana Loki, and others.
15+
16+
### Workspace build timeline
17+
18+
Use the **Build timeline** to monitor the time it takes to start specific
19+
workspaces. Identify long scripts, resources, and other things you can
20+
potentially optimize within the template.
21+
22+
![Screenshot of a workspace and its build timeline](../../images/best-practice/build-timeline.png)
23+
24+
Adjust this request to match your Coder access URL and workspace:
25+
26+
```shell
27+
curl -X GET https://coder.example.com/api/v2/workspacebuilds/{workspacebuild}/timings \
28+
-H 'Accept: application/json' \
29+
-H 'Coder-Session-Token: API_KEY'
30+
```
31+
32+
Visit the
33+
[API documentation](../../reference/api/builds.md#get-workspace-build-timings-by-id)
34+
for more information.
35+
36+
### Coder Observability Chart
37+
38+
Use the [Observability Helm chart](https://github.com/coder/observability) for a
39+
pre-built set of dashboards to monitor your control plane over time. It includes
40+
Grafana, Prometheus, Loki, and Alert Manager out-of-the-box, and can be deployed
41+
on your existing Grafana instance.
42+
43+
We recommend that all administrators deploying on Kubernetes or on an existing
44+
Prometheus or Grafana stack set the observability bundle up with the control
45+
plane from the start. For installation instructions, visit the
46+
[observability repository](https://github.com/coder/observability?tab=readme-ov-file#installation),
47+
or our [Kubernetes installation guide](../../install/kubernetes.md).
48+
49+
### Enable Prometheus metrics for Coder
50+
51+
[Prometheus.io](https://prometheus.io/docs/introduction/overview/#what-is-prometheus)
52+
is included as part of the [observability chart](#coder-observability-chart). It
53+
offers a variety of
54+
[available metrics](../../admin/integrations/prometheus.md#available-metrics),
55+
such as `coderd_provisionerd_job_timings_seconds` and
56+
`coderd_agentstats_startup_script_seconds`, which measure how long the workspace
57+
takes to provision and how long the startup script takes.
58+
59+
You can
60+
[install it separately](https://prometheus.io/docs/prometheus/latest/getting_started/)
61+
if you prefer.
62+
63+
## Provisioners
64+
65+
`coder server` defaults to three provisioner daemons. Each provisioner daemon
66+
can handle one single job, such as start, stop, or delete at a time and can be
67+
resource intensive. When all provisioners are busy, workspaces enter a "pending"
68+
state until a provisioner becomes available.
69+
70+
### Increase provisioner daemons
71+
72+
Provisioners are queue-based to reduce unpredictable load to the Coder server.
73+
However, they can be scaled up to allow more concurrent provisioners. You risk
74+
overloading the central Coder server if you use too many built-in provisioners,
75+
so we recommend a maximum of five provisioners. For more than five provisioners,
76+
we recommend that you move to
77+
[external provisioners](../../admin/provisioners.md).
78+
79+
If you can’t move to external provisioners, use the `provisioner-daemons` flag
80+
to increase the number of provisioner daemons to five:
81+
82+
```shell
83+
coder server --provisioner-daemons=5
84+
```
85+
86+
Visit the
87+
[CLI documentation](../../reference/cli/server.md#--provisioner-daemons) for
88+
more information about increasing provisioner daemons, configuring external
89+
provisioners, and other options.
90+
91+
### Adjust provisioner CPU/memory
92+
93+
We recommend that you deploy Coder to its own respective Kubernetes cluster,
94+
separate from production applications. Keep in mind that Coder runs development
95+
workloads, so the cluster should be deployed as such, without production-level
96+
configurations.
97+
98+
Adjust the CPU and memory values as shown in
99+
[Helm provisioner values.yaml](https://github.com/coder/coder/blob/main/helm/provisioner/values.yaml#L134-L141):
100+
101+
```yaml
102+
…
103+
resources:
104+
limits:
105+
cpu: "0.25"
106+
memory: "1Gi"
107+
requests:
108+
cpu: "0.25"
109+
memory: "1Gi"
110+
…
111+
```
112+
113+
Visit the
114+
[validated architecture documentation](../../admin/infrastructure/validated-architectures/index.md#workspace-nodes)
115+
for more information.
116+
117+
## Set up Terraform provider caching
118+
119+
By default, Coder downloads each Terraform provider when a workspace starts.
120+
This can create unnecessary network and disk I/O.
121+
122+
`terraform init` generates a `.terraform.lock.hcl` which instructs Coder
123+
provisioners to cache specific versions of your providers.
124+
125+
To use `terraform init` to cache providers:
126+
127+
1. Pull the templates to your local device:
128+
129+
```shell
130+
coder templates pull
131+
```
132+
133+
1. Run `terraform init` to initialize the directory:
134+
135+
```shell
136+
terraform init
137+
```
138+
139+
1. Push the templates back to your Coder deployment:
140+
141+
```shell
142+
coder templates push
143+
```

0 commit comments

Comments
 (0)