Skip to content

Commit 2a1bfb3

Browse files
bpmctbpmct
authored
docs: API tokens & CI automation (#4510)
* reword: chore: add CI to dogfood template * use hardcoded URL * use consistent name for tokens * chore: add docs for template change management * add an example * fix case
1 parent abf14d9 commit 2a1bfb3

File tree

8 files changed

+105
-9
lines changed

8 files changed

+105
-9
lines changed

‎.github/workflows/dogfood.yaml

+25-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ on:
1212
workflow_dispatch:
1313

1414
jobs:
15-
deploy:
15+
deploy_image:
1616
runs-on: ubuntu-latest
1717
steps:
1818
- name: Get branch name
@@ -47,3 +47,27 @@ jobs:
4747
tags: "codercom/oss-dogfood:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood:latest"
4848
cache-from: type=registry,ref=codercom/oss-dogfood:latest
4949
cache-to: type=inline
50+
deploy_template:
51+
runs-on: ubuntu-latest
52+
steps:
53+
- name: Checkout
54+
uses: actions/checkout@v3
55+
- name: Get short commit SHA
56+
id: vars
57+
run: echo "::set-output name=sha_short::$(git rev-parse --short HEAD)"
58+
- name: "Install latest Coder"
59+
run: |
60+
curl -L https://coder.com/install.sh | sh
61+
# env:
62+
# VERSION: 0.x
63+
- name: "Push template"
64+
run: |
65+
coder templates push $CODER_TEMPLATE_NAME --directory $CODER_TEMPLATE_DIR --yes --name=$CODER_TEMPLATE_VERSION
66+
env:
67+
# Consumed by Coder CLI
68+
CODER_URL: https://dev.coder.com
69+
CODER_SESSION_TOKEN: ${{ secrets.CODER_SESSION_TOKEN }}
70+
# Template source & details
71+
CODER_TEMPLATE_NAME: ${{ secrets.CODER_TEMPLATE_NAME }}
72+
CODER_TEMPLATE_VERSION: ${{ steps.vars.outputs.sha_short }}
73+
CODER_TEMPLATE_DIR: ./dogfood

‎cli/tokens.go

+1-1
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

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Automation
2+
3+
We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md).
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

+4
Loading

‎docs/images/icons/plug.svg

+1
Loading

‎docs/manifest.json

+12
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

+2-7
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

+23
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)