Skip to content

Commit a49e6b8

Browse files
matifalibpmctmarcpaq
authored
docs: reorganize template docs (#10297)
* docs: rework our "templates" section * wikistuff * fix formatting * add diagram * reorganize some things * docs: improve workspaces and templates doc (#9139) * Reorg, updated/new screenshots, consistent terminology * First pass * Another pass * Added integration section * New outline for template pages, small updates * Revised outline for templates, added tutorial * First pass at tutorial * Some feedback from Ben. * Update docs/workspaces.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/workspaces.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/workspaces.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Fixed typos * Expanded tutorial I have read the CLA Document and I hereby sign the CLA * New screenshots, improved tutorial, revised anatomy * Improved tutorial. Anatomy is now a guided tour. * First pass at guided tour * Updated authentication info * Reorganized the guided tour * Edited more template pages * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tutorial.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Update docs/templates/tour.md Co-authored-by: Muhammad Atif Ali <matifali@live.com> * Revised devcontainers and docker-in-workspaces * Edited and added screenshots * Prepared first draft, except docs/templates/open-in-coder.md * Fix typo * remove legacy parameters and migration guide * Use coder templates create * Added screenshot for workspace template variables * Made it prettier * Fixed minor typos and markdown problems * edits to repairing workspaces * fix broken links in product * Added troubleshooting, minor corrections. * fix terminal links * fmt --------- Co-authored-by: Muhammad Atif Ali <matifali@live.com> Co-authored-by: Ben Potter <me@bpmct.net> Co-authored-by: Atif Ali <atif@coder.com> * make fmt * fix merge conflict * make fmt * make gen * update * lint * Discard changes to coderd/database/queries.sql.go * Discard changes to cli/templates.go * Discard changes to cli/templateversionarchive.go * Discard changes to cli/templateversions.go * Update docker-in-workspaces.md * replace ```sh with ```shell * open-in-coder * fmt * mention coder_metadata in icons.md * resource_metadata * use shell * modules.md * mention coder registry module * workspace.md * resource_metadata * remove duplication * address comments * cleanup * fmt * fix broken links * fix numbering * mention module registry * add example * demote heading * remove top level entry from manifest * fmt --------- Co-authored-by: Ben <me@bpmct.net> Co-authored-by: Marc Paquette <22124737+marcpaq@users.noreply.github.com>
1 parent b5e5b39 commit a49e6b8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+1430
-1135
lines changed

‎docs/admin/provisioners.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Provisioners
1+
# External provisioners
22

33
By default, the Coder server runs
44
[built-in provisioner daemons](../cli/server.md#provisioner-daemons), which

‎docs/images/autostart.png

-30.4 KB
Loading

‎docs/images/autostop.png

-10.2 KB
Loading

‎docs/images/creating-workspace-ui.png

69.7 KB
Loading

‎docs/images/schedule.png

-12.3 KB
Loading

‎docs/images/template-variables.png

89.9 KB
Loading

‎docs/images/templates/build-template.png

54.2 KB
Loading

‎docs/images/templates/choosing-edit-template.gif

525 KB
Loading

‎docs/images/templates/coder-login-web.png

46.9 KB
Loading

‎docs/images/templates/coder-session-token.png

55.9 KB
Loading

‎docs/images/templates/create-template.png

93.4 KB
Loading

‎docs/images/templates/create-workspace.png

75.6 KB
Loading

‎docs/images/templates/develop-in-docker-template.png

96 KB
Loading

‎docs/images/templates/edit-files.png

50.1 KB
Loading

‎docs/images/templates/edit-source-code.png

32.8 KB
Loading

‎docs/images/templates/new-workspace.png

63.6 KB
Loading

‎docs/images/templates/publish.png

79.1 KB
Loading

‎docs/images/templates/select-template.png

45 KB
Loading

‎docs/images/templates/source-code.png

59.3 KB
Loading

‎docs/images/templates/starter-templates-button.png

35.3 KB
Loading

‎docs/images/templates/starter-templates.png

140 KB
Loading

‎docs/images/templates/template-architecture.png

39.6 KB
Loading

‎docs/images/templates/template-tour.png

61.5 KB
Loading

‎docs/images/templates/template-variables.png

226 KB
Loading

‎docs/images/templates/update.png

171 KB
Loading

‎docs/images/templates/use-template.png

67.5 KB
Loading

‎docs/images/templates/workspace-apps.png

497 KB
Loading

‎docs/images/templates/workspace-ready.png

110 KB
Loading

‎docs/images/workspace-update.png

33.6 KB
Loading

‎docs/manifest.json

+65-34
Original file line numberDiff line numberDiff line change
@@ -139,55 +139,86 @@
139139
},
140140
{
141141
"title": "Templates",
142-
"description": "Learn about templates, which define the infrastructure underlying workspaces",
142+
"description": "Templates define the infrastructure for workspaces",
143143
"path": "./templates/index.md",
144144
"icon_path": "./images/icons/picture.svg",
145145
"children": [
146146
{
147-
"title": "Resource Persistence",
148-
"description": "Learn how resource persistence works in Coder",
149-
"path": "./templates/resource-persistence.md",
150-
"icon_path": "./images/icons/infinity.svg"
147+
"title": "Working with templates",
148+
"description": "Creating, editing, and updating templates",
149+
"path": "./templates/creating.md"
151150
},
152151
{
153-
"title": "Provider Authentication",
154-
"description": "Learn how to authenticate the provisioner",
155-
"path": "./templates/authentication.md",
156-
"icon_path": "./images/icons/key.svg"
157-
},
158-
{
159-
"title": "Change Management",
160-
"description": "Learn how to source-control templates with git and CI",
161-
"path": "./templates/change-management.md",
162-
"icon_path": "./images/icons/git.svg"
152+
"title": "Your first template",
153+
"description": "A tutorial for creating and editing your first template",
154+
"path": "./templates/tutorial.md"
163155
},
164156
{
165-
"title": "Resource Metadata",
166-
"description": "Learn how to expose resource data to users",
167-
"path": "./templates/resource-metadata.md",
168-
"icon_path": "./images/icons/table-rows.svg"
157+
"title": "Guided tour",
158+
"description": "Create a template from scratch",
159+
"path": "./templates/tour.md"
169160
},
170161
{
171-
"title": "Agent Metadata",
172-
"description": "Learn how to expose live agent information to users",
173-
"path": "./templates/agent-metadata.md",
174-
"icon_path": "./images/icons/table-rows.svg"
162+
"title": "Setting up templates",
163+
"description": "Best practices for writing templates",
164+
"path": "./templates/best-practices.md",
165+
"children": [
166+
{
167+
"title": "Change management",
168+
"description": "Versioning templates with git and CI",
169+
"path": "./templates/change-management.md",
170+
"icon_path": "./images/icons/git.svg"
171+
},
172+
{
173+
"title": "Provider authentication",
174+
"description": "Authenticate the provisioner",
175+
"path": "./templates/authentication.md",
176+
"icon_path": "./images/icons/key.svg"
177+
},
178+
{
179+
"title": "Resource persistence",
180+
"description": "How resource persistence works in Coder",
181+
"path": "./templates/resource-persistence.md",
182+
"icon_path": "./images/icons/infinity.svg"
183+
},
184+
{
185+
"title": "Terraform modules",
186+
"description": "Reuse code across Coder templates",
187+
"path": "./templates/modules.md"
188+
}
189+
]
175190
},
176191
{
177-
"title": "Parameters",
178-
"description": "Use parameters to customize templates",
179-
"path": "./templates/parameters.md",
180-
"icon_path": "./images/icons/code.svg"
192+
"title": "Customizing templates",
193+
"description": "Give information and options to workspace users",
194+
"path": "./templates/customizing.md",
195+
"children": [
196+
{
197+
"title": "Agent metadata",
198+
"description": "Show operational metrics in the workspace",
199+
"path": "./templates/agent-metadata.md"
200+
},
201+
{
202+
"title": "Resource metadata",
203+
"description": "Show information in the workspace about template resources",
204+
"path": "./templates/resource-metadata.md"
205+
},
206+
{
207+
"title": "Parameters",
208+
"description": "Prompt the user for additional information about a workspace",
209+
"path": "./templates/parameters.md"
210+
}
211+
]
181212
},
182213
{
183214
"title": "Open in Coder",
184-
"description": "Learn how to add an \"Open in Coder\" button to your repos",
215+
"description": "Add an \"Open in Coder\" button to your repos",
185216
"path": "./templates/open-in-coder.md",
186217
"icon_path": "./images/icons/key.svg"
187218
},
188219
{
189-
"title": "Docker in Workspaces",
190-
"description": "Use docker inside containerized templates",
220+
"title": "Docker in workspaces",
221+
"description": "Use Docker inside containerized templates",
191222
"path": "./templates/docker-in-workspaces.md",
192223
"icon_path": "./images/icons/docker.svg"
193224
},
@@ -198,9 +229,9 @@
198229
"state": "alpha"
199230
},
200231
{
201-
"title": "Terraform Modules",
202-
"description": "Reuse code across Coder templates",
203-
"path": "./templates/modules.md"
232+
"title": "Troubleshooting templates",
233+
"description": "Fix common template problems",
234+
"path": "./templates/troubleshooting.md"
204235
},
205236
{
206237
"title": "Process Logging",
@@ -337,7 +368,7 @@
337368
"icon_path": "./images/icons/scale.svg"
338369
},
339370
{
340-
"title": "Provisioners",
371+
"title": "External Provisioners",
341372
"description": "Run provisioners isolated from the Coder server",
342373
"path": "./admin/provisioners.md",
343374
"icon_path": "./images/icons/queue.svg",

‎docs/platforms/jfrog.md

+4
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ The admin-level access token is used to provision user tokens and is never expos
2424
developers or stored in workspaces.
2525
</blockquote>
2626

27+
<blockquote class="info">
28+
You can skip the whole page and use [JFrog module](https://registry.coder.com/modules/jfrog) for easy JFrog Artifactory integration.
29+
</blockquote>
30+
2731
## Provisioner Authentication
2832

2933
The most straight-forward way to authenticate your template with Artifactory is

‎docs/templates/agent-metadata.md

+38-35
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
1-
# Agent Metadata
1+
# Agent metadata
22

33
![agent-metadata](../images/agent-metadata.png)
44

5-
With Agent Metadata, template admins can expose operational metrics from their
6-
workspaces to their users. It is the dynamic complement of
7-
[Resource Metadata](./resource-metadata.md).
5+
You can show live operational metrics to workspace users with agent metadata. It
6+
is the dynamic complement of [resource metadata](./resource-metadata.md).
87

9-
See the
10-
[Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
8+
You specify agent metadata in the
9+
[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
1110

1211
## Examples
1312

@@ -16,9 +15,10 @@ All of these examples use
1615
for the script declaration. With heredoc strings, you can script without messy
1716
escape codes, just as if you were working in your terminal.
1817

19-
Some of the below examples use the [`coder stat`](../cli/stat.md) command. This
20-
is useful for determining CPU/memory usage inside a container, which can be
21-
tricky otherwise.
18+
Some of the examples use the [`coder stat`](../cli/stat.md) command. This is
19+
useful for determining CPU and memory usage of the VM or container that the
20+
workspace is running in, which is more accurate than resource usage about the
21+
workspace's host.
2222

2323
Here's a standard set of metadata snippets for Linux agents:
2424

@@ -86,60 +86,63 @@ resource "coder_agent" "main" {
8686
}
8787
```
8888

89-
## Utilities
89+
## Useful utilities
9090

91-
[top](https://linux.die.net/man/1/top) is available in most Linux distributions
92-
and provides virtual memory, CPU and IO statistics. Running `top` produces
93-
output that looks like:
91+
You can also show agent metadata for information about the workspace's host.
92+
93+
[top](https://manpages.ubuntu.com/manpages/jammy/en/man1/top.1.html) is
94+
available in most Linux distributions and provides virtual memory, CPU and IO
95+
statistics. Running `top` produces output that looks like:
9496

9597
```text
9698
%Cpu(s): 65.8 us, 4.4 sy, 0.0 ni, 29.3 id, 0.3 wa, 0.0 hi, 0.2 si, 0.0 st
9799
MiB Mem : 16009.0 total, 493.7 free, 4624.8 used, 10890.5 buff/cache
98100
MiB Swap: 0.0 total, 0.0 free, 0.0 used. 11021.3 avail Mem
99101
```
100102

101-
[vmstat](https://linux.die.net/man/8/vmstat) is available in most Linux
102-
distributions and provides virtual memory, CPU and IO statistics. Running
103-
`vmstat` produces output that looks like:
103+
[vmstat](https://manpages.ubuntu.com/manpages/jammy/en/man8/vmstat.8.html) is
104+
available in most Linux distributions and provides virtual memory, CPU and IO
105+
statistics. Running `vmstat` produces output that looks like:
104106

105107
```text
106108
procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu-----
107109
r b swpd free buff cache si so bi bo in cs us sy id wa st
108110
0 0 19580 4781680 12133692 217646944 0 2 4 32 1 0 1 1 98 0 0
109111
```
110112

111-
[dstat](https://linux.die.net/man/1/dstat) is considerably more parseable than
112-
`vmstat` but often not included in base images. It is easily installed by most
113-
package managers under the name `dstat`. The output of running `dstat 1 1` looks
114-
like:
113+
[dstat](https://manpages.ubuntu.com/manpages/jammy/man1/dstat.1.html) is
114+
considerably more parseable than `vmstat` but often not included in base images.
115+
It is easily installed by most package managers under the name `dstat`. The
116+
output of running `dstat 1 1` looks like:
115117

116118
```text
117119
--total-cpu-usage-- -dsk/total- -net/total- ---paging-- ---system--
118120
usr sys idl wai stl| read writ| recv send| in out | int csw
119121
1 1 98 0 0|3422k 25M| 0 0 | 153k 904k| 123k 174k
120122
```
121123

122-
## DB Write Load
124+
## Managing the database load
123125

124-
Agent metadata can generate a significant write load and overwhelm your database
125-
if you're not careful. The approximate writes per second can be calculated using
126-
the following formula (applied once for each unique metadata interval):
126+
Agent metadata can generate a significant write load and overwhelm your Coder
127+
database if you're not careful. The approximate writes per second can be
128+
calculated using the formula:
127129

128130
```text
129-
num_running_agents * write_multiplier / metadata_interval
131+
(metadata_count * num_running_agents * 2) / metadata_avg_interval
130132
```
131133

132-
For example, let's say you have:
134+
For example, let's say you have
133135

134136
- 10 running agents
135-
- each with 4 metadata snippets
136-
- where two have an interval of 4 seconds, and the other two 6 seconds
137+
- each with 6 metadata snippets
138+
- with an average interval of 4 seconds
139+
140+
You can expect `(10 * 6 * 2) / 4`, or 30 writes per second.
141+
142+
One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table and the
143+
other to the `NOTIFY` query that enables live stats streaming in the UI.
137144

138-
You can expect at most `(10 * 2 / 4) + (10 * 2 / 6)` or ~8 writes per second.
139-
The actual writes per second may be a bit lower due to batching of metadata.
140-
Adding more metadata with the same interval will not increase writes per second,
141-
but it may still increase database load slightly.
145+
## Next Steps
142146

143-
We use a `write_multiplier` of `2` because each metadata write generates two
144-
writes. One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table
145-
and the other to the `NOTIFY` query that enables live stats streaming in the UI.
147+
- [Resource metadata](./resource-metadata.md)
148+
- [Parameters](./parameters.md)

‎docs/templates/authentication.md

+29-18
Original file line numberDiff line numberDiff line change
@@ -7,31 +7,42 @@
77
</p>
88
</blockquote>
99

10-
Coder's provisioner process needs to authenticate with cloud provider APIs to
11-
provision workspaces. You can either pass credentials to the provisioner as
12-
parameters or execute Coder in an environment that is authenticated with the
13-
cloud provider.
10+
The Coder server's
11+
[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner)
12+
process needs to authenticate with other provider APIs to provision workspaces.
13+
There are two approaches to do this:
1414

15-
We encourage the latter where supported. This approach simplifies the template,
16-
keeps cloud provider credentials out of Coder's database (making it a less
17-
valuable target for attackers), and is compatible with agent-based
18-
authentication schemes (that handle credential rotation and/or ensure the
19-
credentials are not written to disk).
15+
- Pass credentials to the provisioner as parameters.
16+
- Preferred: Execute the Coder server in an environment that is authenticated
17+
with the provider.
2018

21-
Cloud providers for which the Terraform provider supports authenticated
22-
environments include
19+
We encourage the latter approach where supported:
20+
21+
- Simplifies the template.
22+
- Keeps provider credentials out of Coder's database, making it a less valuable
23+
target for attackers.
24+
- Compatible with agent-based authentication schemes, which handle credential
25+
rotation or ensure the credentials are not written to disk.
26+
27+
Generally, you can set up an environment to provide credentials to Coder in
28+
these ways:
29+
30+
- A well-known location on disk. For example, `~/.aws/credentials` for AWS on
31+
POSIX systems.
32+
- Environment variables.
33+
34+
It is usually sufficient to authenticate using the CLI or SDK for the provider
35+
before running Coder, but check the Terraform provider's documentation for
36+
details.
37+
38+
These platforms have Terraform providers that support authenticated
39+
environments:
2340

2441
- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
2542
- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
2643
- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
2744
- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
2845

29-
Additional providers may be supported; check the
46+
Other providers might also support authenticated environments. Check the
3047
[documentation of the Terraform provider](https://registry.terraform.io/browse/providers)
3148
for details.
32-
33-
The way these generally work is via the credentials being available to Coder
34-
either in some well-known location on disk (e.g. `~/.aws/credentials` for AWS on
35-
posix systems), or via environment variables. It is usually sufficient to
36-
authenticate using the CLI or SDK for the cloud provider before running Coder
37-
for this to work, but check the Terraform provider documentation for details.

‎docs/templates/best-practices.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Template best practices
2+
3+
We recommend a few ways to manage workspace resources, authentication, and
4+
versioning.
5+
6+
<children>
7+
</children>

‎docs/templates/change-management.md

+6-8
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Template Change Management
22

3-
We recommend source controlling your templates as you would other code.
4-
[Install Coder](../install/) in CI/CD pipelines to push new template versions.
3+
We recommend source-controlling your templates as you would other code. You can
4+
[install Coder](../install/) in CI/CD pipelines to push new template versions.
55

66
```console
77
# Install the Coder CLI
@@ -21,14 +21,12 @@ export CODER_TEMPLATE_DIR=.coder/templates/kubernetes
2121
export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD)
2222

2323
# Push the new template version to Coder
24-
coder login --url $CODER_URL --token $CODER_SESSION_TOKEN
2524
coder templates push --yes $CODER_TEMPLATE_NAME \
2625
--directory $CODER_TEMPLATE_DIR \
2726
--name=$CODER_TEMPLATE_VERSION # Version name is optional
2827
```
2928

30-
> Looking for an example? See how we push our development image and template
31-
> [via GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).
32-
33-
> To cap token lifetime on creation,
34-
> [configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime)
29+
To cap token lifetime on creation,
30+
[configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime).
31+
For an example, see how we push our development image and template
32+
[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).

0 commit comments

Comments
 (0)