Skip to content

Commit 5e1a1ce

Browse files
bpmctbpmct
committed
docs: custom API use cases
1 parent 700ec96 commit 5e1a1ce

File tree

7 files changed

+242
-35
lines changed

7 files changed

+242
-35
lines changed

‎coderd/apidoc/docs.go

Lines changed: 0 additions & 6 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎coderd/apidoc/swagger.json

Lines changed: 0 additions & 6 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎coderd/workspaceagents.go

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,6 @@ func (api *API) postWorkspaceAgentStartup(rw http.ResponseWriter, r *http.Reques
242242
// @Param request body agentsdk.PatchStartupLogs true "Startup logs"
243243
// @Success 200 {object} codersdk.Response
244244
// @Router /workspaceagents/me/startup-logs [patch]
245-
// @x-apidocgen {"skip": true}
246245
func (api *API) patchWorkspaceAgentStartupLogs(rw http.ResponseWriter, r *http.Request) {
247246
ctx := r.Context()
248247
workspaceAgent := httpmw.WorkspaceAgent(r)
@@ -1292,7 +1291,6 @@ func convertWorkspaceAgent(derpMap *tailcfg.DERPMap, coordinator tailnet.Coordin
12921291
// @Param request body agentsdk.Stats true "Stats request"
12931292
// @Success 200 {object} agentsdk.StatsResponse
12941293
// @Router /workspaceagents/me/report-stats [post]
1295-
// @x-apidocgen {"skip": true}
12961294
func (api *API) workspaceAgentReportStats(rw http.ResponseWriter, r *http.Request) {
12971295
ctx := r.Context()
12981296

‎docs/admin/automation.md

Lines changed: 72 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,86 @@
11
# Automation
22

3-
We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md).
3+
All actions possible through the Coder dashboard can also be automated as it utilizes the same public REST API. There are several ways to extend/automate Coder:
44

5-
## Authentication
5+
- [CLI](../cli.md)
6+
- [REST API](../api/)
7+
- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/codersdk)
68

7-
Coder uses authentication tokens to grant machine users access to the REST API. Follow the [Authentication](../api/authentication.md) page to learn how to generate long-lived tokens.
9+
## Quickstart
810

9-
## CLI
11+
Generate a token on your Coder deployment by visiting:
1012

11-
You can use tokens with the CLI by setting the `--token` CLI flag or the `CODER_SESSION_TOKEN`
12-
environment variable.
13-
14-
```console
15-
export CODER_URL=https://coder.example.com
16-
export CODER_SESSION_TOKEN=*****
17-
coder workspaces ls
13+
```sh
14+
https://coder.example.com/settings/tokens
1815
```
1916

20-
## REST API
17+
List your workspaces
2118

22-
You can review the [API reference](../api/index.md) to find the necessary routes and payload. Alternatively, you can enable the [Swagger](https://swagger.io/) endpoint to read the documentation and do requests against the API:
19+
```sh
20+
# CLI
21+
coder ls \
22+
--url https://coder.example.com \
23+
--token <your-token> \
24+
--output json
2325

24-
```console
25-
coder server --swagger-enable
26+
# REST API (with curl)
27+
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
28+
-H "Coder-Session-Token: <your-token>"
2629
```
2730

28-
By default, the local Swagger endpoint is http://localhost:3000/swagger.
31+
## Documentation
32+
33+
We publish an [API reference](../api/index.md) in our documentation. You can also enable a [Swagger endpoint](../cli/server#--swagger-enable) on your Coder deployment.
34+
35+
## Use cases
36+
37+
We strive to keep the following use cases up to date, but please note that changes to API queries and routes can occur. For the most recent queries and payloads, we recommend checking the CLI and API documentation.
38+
39+
### Templates
40+
41+
- [Update templates in CI](../templates/change-management.md): Store all templates and git and update templates in CI/CD pipelines.
42+
43+
### Workspace agents
44+
45+
Workspace agents have a special token that can send logs, metrics, and workspace activity.
46+
47+
- [Custom workspace logs](../api/agents.md#patch-workspace-agent-startup-logs): Expose messages prior to the Coder init script running (e.g. pulling image, VM starting, restoring snapshot). [coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses this to show Kubernetes events, such as image pulls or ResourceQuota restrictions.
48+
49+
```sh
50+
curl -X PATCH https://dev.coder.com/api/v2/workspaceagents/me/startup-logs \
51+
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
52+
-d "{
53+
\"logs\": [
54+
{
55+
\"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
56+
\"level\": \"info\",
57+
\"output\": \"Restoring workspace from snapshot: 05%...\"
58+
}
59+
]
60+
}"
61+
```
62+
63+
- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats): Keep a workspace "active," even if there is not an open connection (e.g. for a long-running machine learning job).
64+
65+
```sh
66+
#!/bin/bash
67+
# Send workspace activity as long as the job is still running
2968

30-
## Golang SDK
69+
while true
70+
do
71+
if pgrep -f "my_training_script.py" > /dev/null
72+
then
73+
curl -X POST "https://coder.example.com/api/v2/workspaceagents/me/report-stats" \
74+
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
75+
-d '{
76+
"connection_count": 1
77+
}'
3178

32-
Coder publishes a public [Golang SDK](https://pkg.go.dev/github.com/coder/coder/codersdk) for Coder. This is consumed by the [CLI package](https://github.com/coder/coder/tree/main/cli).
79+
# Sleep for 30 minutes (1800 seconds) if the job is running
80+
sleep 1800
81+
else
82+
# Sleep for 1 minute (60 seconds) if the job is not running
83+
sleep 60
84+
fi
85+
done
86+
```

‎docs/api/agents.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -395,6 +395,137 @@ curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/manifest \
395395

396396
To perform this operation, you must be authenticated. [Learn more](authentication.md).
397397

398+
## Submit workspace agent stats
399+
400+
### Code samples
401+
402+
```shell
403+
# Example request using curl
404+
curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/report-stats \
405+
-H 'Content-Type: application/json' \
406+
-H 'Accept: application/json' \
407+
-H 'Coder-Session-Token: API_KEY'
408+
```
409+
410+
`POST /workspaceagents/me/report-stats`
411+
412+
> Body parameter
413+
414+
```json
415+
{
416+
"connection_count": 0,
417+
"connection_median_latency_ms": 0,
418+
"connections_by_proto": {
419+
"property1": 0,
420+
"property2": 0
421+
},
422+
"metrics": [
423+
{
424+
"labels": [
425+
{
426+
"name": "string",
427+
"value": "string"
428+
}
429+
],
430+
"name": "string",
431+
"type": "counter",
432+
"value": 0
433+
}
434+
],
435+
"rx_bytes": 0,
436+
"rx_packets": 0,
437+
"session_count_jetbrains": 0,
438+
"session_count_reconnecting_pty": 0,
439+
"session_count_ssh": 0,
440+
"session_count_vscode": 0,
441+
"tx_bytes": 0,
442+
"tx_packets": 0
443+
}
444+
```
445+
446+
### Parameters
447+
448+
| Name | In | Type | Required | Description |
449+
| ------ | ---- | ------------------------------------------ | -------- | ------------- |
450+
| `body` | body | [agentsdk.Stats](schemas.md#agentsdkstats) | true | Stats request |
451+
452+
### Example responses
453+
454+
> 200 Response
455+
456+
```json
457+
{
458+
"report_interval": 0
459+
}
460+
```
461+
462+
### Responses
463+
464+
| Status | Meaning | Description | Schema |
465+
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
466+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.StatsResponse](schemas.md#agentsdkstatsresponse) |
467+
468+
To perform this operation, you must be authenticated. [Learn more](authentication.md).
469+
470+
## Patch workspace agent startup logs
471+
472+
### Code samples
473+
474+
```shell
475+
# Example request using curl
476+
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/startup-logs \
477+
-H 'Content-Type: application/json' \
478+
-H 'Accept: application/json' \
479+
-H 'Coder-Session-Token: API_KEY'
480+
```
481+
482+
`PATCH /workspaceagents/me/startup-logs`
483+
484+
> Body parameter
485+
486+
```json
487+
{
488+
"logs": [
489+
{
490+
"created_at": "string",
491+
"level": "trace",
492+
"output": "string"
493+
}
494+
]
495+
}
496+
```
497+
498+
### Parameters
499+
500+
| Name | In | Type | Required | Description |
501+
| ------ | ---- | ---------------------------------------------------------------- | -------- | ------------ |
502+
| `body` | body | [agentsdk.PatchStartupLogs](schemas.md#agentsdkpatchstartuplogs) | true | Startup logs |
503+
504+
### Example responses
505+
506+
> 200 Response
507+
508+
```json
509+
{
510+
"detail": "string",
511+
"message": "string",
512+
"validations": [
513+
{
514+
"detail": "string",
515+
"field": "string"
516+
}
517+
]
518+
}
519+
```
520+
521+
### Responses
522+
523+
| Status | Meaning | Description | Schema |
524+
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ |
525+
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](schemas.md#codersdkresponse) |
526+
527+
To perform this operation, you must be authenticated. [Learn more](authentication.md).
528+
398529
## Get workspace agent by ID
399530

400531
### Code samples

‎docs/api/index.md

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,22 @@
1-
Get started with Coder API:
1+
Get started with the Coder API:
2+
3+
## Quickstart
4+
5+
Generate a token on your Coder deployment by visiting:
6+
7+
```sh
8+
https://coder.example.com/settings/tokens
9+
```
10+
11+
List your workspaces
12+
13+
```sh
14+
# CLI
15+
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
16+
-H "Coder-Session-Token: <your-token>"
17+
```
18+
19+
## Sections
220

321
<children>
422
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the `api/` directory.

‎scripts/apidocgen/postprocess/main.go

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,28 @@ import (
1818
const (
1919
apiSubdir = "api"
2020
apiIndexFile = "index.md"
21-
apiIndexContent = `Get started with Coder API:
21+
apiIndexContent = `Get started with the Coder API:
22+
23+
## Quickstart
24+
25+
Generate a token on your Coder deployment by visiting:
26+
27+
` + "````sh" + `
28+
https://coder.example.com/settings/tokens
29+
` + "````" + `
30+
31+
List your workspaces
32+
33+
` + "````sh" + `
34+
# CLI
35+
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
36+
-H "Coder-Session-Token: <your-token>"
37+
` + "````" + `
38+
39+
## Sections
2240
2341
<children>
24-
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`" + `api/` + "`" + ` directory.
42+
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`api/`" + ` directory.
2543
</children>
2644
`
2745
)

0 commit comments

Comments
 (0)