Skip to content

Commit d4bd7ed

Browse files
ammarioammario
committed
docs: a bunch of small touchups
1 parent a85b343 commit d4bd7ed

File tree

6 files changed

+50
-55
lines changed

6 files changed

+50
-55
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/templates.md

+6-38
Original file line numberDiff line numberDiff line change
@@ -34,47 +34,15 @@ Templates often contain _parameters_. In Coder, there are two types of parameter
3434
to each workspace, often personalization settings such as "preferred region"
3535
or "workspace image".
3636

37-
## Best Practices
37+
## Change Management
3838

39-
### Template Changes
39+
We recommend source controlling your templates as you would other code.
4040

41-
We recommend source controlling your templates.
42-
43-
### Authentication & Secrets
44-
45-
<blockquote class="danger">
46-
<p>
47-
Do not store secrets in templates. Assume every user has cleartext access
48-
to every template.
49-
</p>
50-
</blockquote>
51-
52-
Coder's provisioner process needs to authenticate with cloud provider APIs to provision
53-
workspaces. You can either pass credentials to the provisioner as parameters or execute Coder
54-
in an environment that is authenticated with the cloud provider.
55-
56-
We encourage the latter where supported. This approach simplifies the template, keeps cloud
57-
provider credentials out of Coder's database (making it a less valuable target for attackers),
58-
and is compatible with agent-based authentication schemes (that handle credential rotation
59-
and/or ensure the credentials are not written to disk).
60-
61-
Cloud providers for which the Terraform provider supports authenticated environments include:
62-
63-
- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
64-
- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
65-
- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
66-
- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
67-
68-
Additional providers may be supported; check the
69-
[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for
70-
details.
71-
72-
The way these generally work is via the credentials being available to Coder either in some
73-
well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via
74-
environment variables. It is usually sufficient to authenticate using the CLI or SDK for the
75-
cloud provider before running Coder for this to work, but check the Terraform provider
76-
documentation for details.
41+
CI is as simple as running `coder templates update` with the appropriate
42+
credentials.
7743

7844
---
7945

8046
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)