Skip to content

Commit 82c4b80

Browse files
ammarioammario
authored
Docs touchups (#2421)
* Make secrets docs louder * docs: a bunch of small touchups
1 parent c9691ea commit 82c4b80

File tree

7 files changed

+52
-54
lines changed

7 files changed

+52
-54
lines changed

‎docs/CONTRIBUTORS.md

-14
This file was deleted.

‎docs/CODE_OF_CONDUCT.md renamed to ‎docs/contributing/CODE_OF_CONDUCT.md

File renamed without changes.

‎docs/SECURITY.md renamed to ‎docs/contributing/SECURITY.md

File renamed without changes.

‎docs/manifest.json

+10-3
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,14 @@
2323
"title": "Templates",
2424
"description": "Learn about templates, which define the infrastructure underlying workspaces.",
2525
"path": "./templates.md",
26-
"icon": "<svg viewBox=\"0 0 16 16\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M15.0017 4.0017H1.0017C0.868289 3.99368 0.734692 4.01405 0.609732 4.06147C0.484772 4.10889 0.371292 4.18228 0.276784 4.27678C0.182276 4.37129 0.108891 4.48477 0.0614728 4.60973C0.0140548 4.73469 -0.00631686 4.86829 0.00170278 5.0017V15.0017C-0.00631686 15.1351 0.0140548 15.2687 0.0614728 15.3937C0.108891 15.5186 0.182276 15.6321 0.276784 15.7266C0.371292 15.8211 0.484772 15.8945 0.609732 15.9419C0.734692 15.9894 0.868289 16.0097 1.0017 16.0017H15.0017C15.1351 16.0097 15.2687 15.9894 15.3937 15.9419C15.5186 15.8945 15.6321 15.8211 15.7266 15.7266C15.8211 15.6321 15.8945 15.5186 15.9419 15.3937C15.9894 15.2687 16.0097 15.1351 16.0017 15.0017V5.0017C16.0097 4.86829 15.9894 4.73469 15.9419 4.60973C15.8945 4.48477 15.8211 4.37129 15.7266 4.27678C15.6321 4.18228 15.5186 4.10889 15.3937 4.06147C15.2687 4.01405 15.1351 3.99368 15.0017 4.0017ZM14.0017 14.0017H2.0017V6.0017H14.0017V14.0017Z\" /> <path d=\"M14 0H2V2H14V0Z\" fill=\"#333333\"/> <path d=\"M5 13L10 8L13 13H5Z\" /> <path d=\"M5 10C5.55228 10 6 9.55228 6 9C6 8.44772 5.55228 8 5 8C4.44772 8 4 8.44772 4 9C4 9.55228 4.44772 10 5 10Z\" /> </svg>"
26+
"icon": "<svg viewBox=\"0 0 16 16\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M15.0017 4.0017H1.0017C0.868289 3.99368 0.734692 4.01405 0.609732 4.06147C0.484772 4.10889 0.371292 4.18228 0.276784 4.27678C0.182276 4.37129 0.108891 4.48477 0.0614728 4.60973C0.0140548 4.73469 -0.00631686 4.86829 0.00170278 5.0017V15.0017C-0.00631686 15.1351 0.0140548 15.2687 0.0614728 15.3937C0.108891 15.5186 0.182276 15.6321 0.276784 15.7266C0.371292 15.8211 0.484772 15.8945 0.609732 15.9419C0.734692 15.9894 0.868289 16.0097 1.0017 16.0017H15.0017C15.1351 16.0097 15.2687 15.9894 15.3937 15.9419C15.5186 15.8945 15.6321 15.8211 15.7266 15.7266C15.8211 15.6321 15.8945 15.5186 15.9419 15.3937C15.9894 15.2687 16.0097 15.1351 16.0017 15.0017V5.0017C16.0097 4.86829 15.9894 4.73469 15.9419 4.60973C15.8945 4.48477 15.8211 4.37129 15.7266 4.27678C15.6321 4.18228 15.5186 4.10889 15.3937 4.06147C15.2687 4.01405 15.1351 3.99368 15.0017 4.0017ZM14.0017 14.0017H2.0017V6.0017H14.0017V14.0017Z\" /> <path d=\"M14 0H2V2H14V0Z\" fill=\"#333333\"/> <path d=\"M5 13L10 8L13 13H5Z\" /> <path d=\"M5 10C5.55228 10 6 9.55228 6 9C6 8.44772 5.55228 8 5 8C4.44772 8 4 8.44772 4 9C4 9.55228 4.44772 10 5 10Z\" /> </svg>",
27+
"children": [
28+
{
29+
"title": "Authentication & Secrets",
30+
"description": "Learn how to authenticate the provisioner",
31+
"path": "./templates/authentication.md"
32+
}
33+
]
2734
},
2835
{
2936
"title": "Workspaces",
@@ -40,12 +47,12 @@
4047
{
4148
"title": "Code of Conduct",
4249
"description": "See the code of conduct for contributing to Coder.",
43-
"path": "./CODE_OF_CONDUCT.md"
50+
"path": "./contributing/CODE_OF_CONDUCT.md"
4451
},
4552
{
4653
"title": "Security",
4754
"description": "How to report vulnerabilities in Coder",
48-
"path": "./SECURITY.md"
55+
"path": "./contributing/SECURITY.md"
4956
}
5057
]
5158
}

‎docs/quickstart.md

-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# Quickstart
22

3-
This guide will walk you through creating your first template and workspace.
4-
53
## Prerequisites
64

75
Please [install Coder](./install.md) before proceeding with the steps outlined in this article.

‎docs/templates.md

+8-35
Original file line numberDiff line numberDiff line change
@@ -25,51 +25,24 @@ coder templates <create/update> <template-name>
2525

2626
## Parameters
2727

28-
Templates often contain *parameters*. In Coder, there are two types of parameters:
28+
Templates often contain _parameters_. In Coder, there are two types of parameters:
2929

3030
- **Admin parameters** are set when a template is created/updated. These values
3131
are often cloud secrets, such as a `ServiceAccount` token, and are annotated
32-
with `sensitive = true` in the template code.
33-
32+
with `sensitive = true` in the template code.
3433
- **User parameters** are set when a user creates a workspace. They are unique
3534
to each workspace, often personalization settings such as "preferred region"
3635
or "workspace image".
3736

38-
## Best Practices
39-
40-
### Template Changes
41-
42-
We recommend source controlling your templates.
43-
44-
### Authenticating with Cloud Providers
45-
46-
Coder's provisioner process needs to authenticate with cloud provider APIs to provision
47-
workspaces. We strongly advise against including credentials directly in your templates. You
48-
can either pass credentials to the provisioner as parameters, or execute Coder
49-
in an environment that is authenticated with the cloud provider.
37+
## Change Management
5038

51-
We encourage the latter where supported. This approach simplifies the template, keeps cloud
52-
provider credentials out of Coder's database (making it a less valuable target for attackers),
53-
and is compatible with agent-based authentication schemes (that handle credential rotation
54-
and/or ensure the credentials are not written to disk).
39+
We recommend source controlling your templates as you would other code.
5540

56-
Cloud providers for which the Terraform provider supports authenticated environments include:
57-
58-
- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
59-
- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
60-
- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
61-
- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
62-
63-
Additional providers may be supported; check the
64-
[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for
65-
details.
66-
67-
The way these generally work is via the credentials being available to Coder either in some
68-
well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via
69-
environment variables. It is usually sufficient to authenticate using the CLI or SDK for the
70-
cloud provider before running Coder for this to work, but check the Terraform provider
71-
documentation for details.
41+
CI is as simple as running `coder templates update` with the appropriate
42+
credentials.
7243

7344
---
7445

7546
Next: [Workspaces](./workspaces.md)
47+
48+
Next: [Authentication & Secrets](./authentication.md)

‎docs/templates/authentication.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Authentication & Secrets
2+
3+
<blockquote class="danger">
4+
<p>
5+
Do not store secrets in templates. Assume every user has cleartext access
6+
to every template.
7+
</p>
8+
</blockquote>
9+
10+
Coder's provisioner process needs to authenticate with cloud provider APIs to provision
11+
workspaces. You can either pass credentials to the provisioner as parameters or execute Coder
12+
in an environment that is authenticated with the cloud provider.
13+
14+
We encourage the latter where supported. This approach simplifies the template, keeps cloud
15+
provider credentials out of Coder's database (making it a less valuable target for attackers),
16+
and is compatible with agent-based authentication schemes (that handle credential rotation
17+
and/or ensure the credentials are not written to disk).
18+
19+
Cloud providers for which the Terraform provider supports authenticated environments include
20+
21+
- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
22+
- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
23+
- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
24+
- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
25+
26+
Additional providers may be supported; check the
27+
[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for
28+
details.
29+
30+
The way these generally work is via the credentials being available to Coder either in some
31+
well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via
32+
environment variables. It is usually sufficient to authenticate using the CLI or SDK for the
33+
cloud provider before running Coder for this to work, but check the Terraform provider
34+
documentation for details.

0 commit comments

Comments
 (0)