Skip to content

Commit 5a0d820

Browse files
bpmctbpmct
committed
chore: add docs for template change management
1 parent c27b289 commit 5a0d820

File tree

7 files changed

+80
-8
lines changed

7 files changed

+80
-8
lines changed

‎cli/tokens.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ func createToken() *cobra.Command {
6767
cmd.Println(cliui.Styles.Code.Render(strings.TrimSpace(res.Key)))
6868
cmd.Println()
6969
cmd.Println(cliui.Styles.Wrap.Render(
70-
fmt.Sprintf("You can use this token by setting the --%s CLI flag, the %s environment variable, or the %q HTTP header.", varToken, envSessionToken, codersdk.SessionTokenKey),
70+
fmt.Sprintf("You can use this token by setting the --%s CLI flag, the %s environment variable, or the %q HTTP header.", varToken, envSessionToken, codersdk.SessionCustomHeader),
7171
))
7272

7373
return nil

‎docs/admin/automation.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Automation
2+
3+
We recommend automating Coder deployments through the CLI.
4+
5+
## Tokens
6+
7+
Long-lived tokens can be generated to perform actions on behalf of your user account:
8+
9+
```sh
10+
coder tokens create
11+
```
12+
13+
## CLI
14+
15+
You can use tokens with the CLI by setting the `--token` CLI flag or the `CODER_SESSION_TOKEN`
16+
environment variable.
17+
18+
```sh
19+
export CODER_URL=https://coder.example.com
20+
export CODER_SESSION_TOKEN=*****
21+
coder workspaces ls
22+
```
23+
24+
## REST API
25+
26+
You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header.
27+
28+
```sh
29+
curl 'https://dev.coder.com/api/v2/workspaces' \
30+
-H 'Coder-Session-Token: *****'
31+
```
32+
33+
> At this time, we do not publish an API reference. However, [codersdk](https://github.com/coder/coder/tree/main/codersdk) can be grepped to find the necessary routes and payloads.
34+
35+
## Golang SDK
36+
37+
Coder publishes a public [Golang SDK](https://pkg.go.dev/github.com/coder/coder@main/codersdk) for Coder. This is consumed by the [CLI package](https://github.com/coder/coder/tree/main/cli).

‎docs/images/icons/git.svg

Lines changed: 4 additions & 0 deletions
Loading

‎docs/images/icons/plug.svg

Lines changed: 1 addition & 0 deletions
Loading

‎docs/manifest.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,12 @@
9595
"path": "./templates/authentication.md",
9696
"icon_path": "./images/icons/key.svg"
9797
},
98+
{
99+
"title": "Change Management",
100+
"description": "Learn how to source-control templates with git and CI",
101+
"path": "./templates/change-management.md",
102+
"icon_path": "./images/icons/git.svg"
103+
},
98104
{
99105
"title": "Resource Metadata",
100106
"description": "Learn how to expose resource data to users",
@@ -212,6 +218,12 @@
212218
"icon_path": "./images/icons/upgrade.svg",
213219
"path": "./admin/upgrade.md"
214220
},
221+
{
222+
"title": "Automation",
223+
"description": "Learn how to automate Coder with the CLI and API",
224+
"icon_path": "./images/icons/plug.svg",
225+
"path": "./admin/automation.md"
226+
},
215227
{
216228
"title": "Audit Logs",
217229
"description": "Learn how to use Audit Logs in your Coder deployment.",

‎docs/templates.md

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -314,14 +314,9 @@ practices:
314314

315315
Template permissions can be used to give users and groups access to specific templates. [Learn more about RBAC](./admin/rbac.md).
316316

317-
## Change Management
318-
319-
We recommend source controlling your templates as you would other code.
320-
321-
CI is as simple as running `coder templates push` with the appropriate
322-
credentials.
323-
324317
## Next Steps
325318

326319
- Learn about [Authentication & Secrets](templates/authentication.md)
320+
- Learn about [Change management](templates/change-management.md)
321+
- Learn about [Resource Metadata](templates/resource-metadata.md)
327322
- Learn about [Workspaces](workspaces.md)

‎docs/templates/change-management.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Template Change Management
2+
3+
We recommend source controlling your templates as you would other code. [Install Coder](../install/) in CI/CD pipelines to push new template versions.
4+
5+
```sh
6+
# Install the Coder CLI
7+
curl -L https://coder.com/install.sh | sh
8+
# curl -L https://coder.com/install.sh | sh -s -- --version=0.x
9+
10+
# To create API tokens, use `coder tokens create`.
11+
# These variables are consumed by Coder
12+
export CODER_URL=https://coder.example.com
13+
export CODER_SESSION_TOKEN=*****
14+
15+
# Template details
16+
export CODER_TEMPLATE_NAME=kubernetes
17+
export CODER_TEMPLATE_DIR=.coder/templates/kubernetes
18+
export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD)
19+
20+
coder templates push --yes $CODER_TEMPLATE_NAME \
21+
--directory $CODER_TEMPLATE_DIR \
22+
--name=$CODER_TEMPLATE_VERSION # Version name is optional
23+
```

0 commit comments

Comments
 (0)