Files
coder/docs/reference/index.md
T

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

110 lines
3.2 KiB
Markdown
Raw Normal View History

2024-10-05 08:52:04 -07:00
# Reference
## Automation
2022-10-12 10:43:59 -05:00
2024-10-05 08:52:04 -07:00
All actions possible through the Coder dashboard can also be automated. There
are several ways to extend/automate Coder:
2022-10-12 10:43:59 -05:00
- [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
2024-10-05 08:52:04 -07:00
- [CLI](../reference/cli/index.md)
- [REST API](../reference/api/index.md)
- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
2024-10-05 08:52:04 -07:00
- [Agent API](../reference/agent-api/index.md)
2022-10-12 10:43:59 -05:00
2023-07-13 09:24:09 -04:00
## Quickstart
2022-10-12 10:43:59 -05:00
2023-07-13 09:24:09 -04:00
Generate a token on your Coder deployment by visiting:
2022-10-12 10:43:59 -05:00
```shell
2023-07-13 09:24:09 -04:00
https://coder.example.com/settings/tokens
2022-10-12 10:43:59 -05:00
```
2023-07-13 09:24:09 -04:00
List your workspaces
2022-10-12 10:43:59 -05:00
```shell
2023-07-13 09:24:09 -04:00
# CLI
coder ls \
--url https://coder.example.com \
--token <your-token> \
--output json
2022-10-12 10:43:59 -05:00
2023-07-13 09:24:09 -04:00
# REST API (with curl)
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
-H "Coder-Session-Token: <your-token>"
2022-10-12 10:43:59 -05:00
```
2023-07-13 09:24:09 -04:00
## Documentation
2022-10-12 10:43:59 -05:00
2024-10-05 08:52:04 -07:00
We publish an [API reference](../reference/api/index.md) in our documentation.
You can also enable a
[Swagger endpoint](../reference/cli/server.md#--swagger-enable) on your Coder
deployment.
2022-10-12 10:43:59 -05:00
2023-07-13 09:24:09 -04:00
## Use cases
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 relevant documentation.
### Users & Groups
- [Manage Users via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/user)
- [Manage Groups via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/group)
2023-07-13 09:24:09 -04:00
### Templates
2024-10-05 08:52:04 -07:00
- [Manage templates via Terraform or CLI](../admin/templates/managing-templates/change-management.md):
Store all templates in git and update them in CI/CD pipelines.
2023-07-13 09:24:09 -04:00
### Workspace agents
Workspace agents have a special token that can send logs, metrics, and workspace
activity.
2023-07-13 09:24:09 -04:00
- [Custom workspace logs](../reference/api/agents.md#patch-workspace-agent-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.
2023-07-13 09:24:09 -04:00
```shell
curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/logs \
2023-07-13 09:24:09 -04:00
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
-d "{
2024-10-05 08:52:04 -07:00
\"logs\": [
{
\"created_at\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
\"level\": \"info\",
\"output\": \"Restoring workspace from snapshot: 05%...\"
2024-10-05 08:52:04 -07:00
}
]
2023-07-13 09:24:09 -04:00
}"
```
- [Manually send workspace activity](../reference/api/workspaces.md#extend-workspace-deadline-by-id):
Keep a workspace "active," even if there is not an open connection (e.g. for a
long-running machine learning job).
2023-07-13 09:24:09 -04:00
```shell
2023-07-13 09:24:09 -04:00
#!/bin/bash
# Send workspace activity as long as the job is still running
while true
do
2024-10-05 08:52:04 -07:00
if pgrep -f "my_training_script.py" > /dev/null
then
curl -X PUT "https://coder.example.com/api/v2/workspaces/$WORKSPACE_ID/extend" \
2024-10-05 08:52:04 -07:00
-H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
-d '{
"deadline": "2019-08-24T14:15:22Z"
2024-10-05 08:52:04 -07:00
}'
2023-07-13 09:24:09 -04:00
2024-10-05 08:52:04 -07:00
# Sleep for 30 minutes (1800 seconds) if the job is running
sleep 1800
else
# Sleep for 1 minute (60 seconds) if the job is not running
sleep 60
fi
2023-07-13 09:24:09 -04:00
done
```