Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

docs: add custom API use cases#8445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
bpmct merged 3 commits intomainfrombpmct/apistuff
Jul 13, 2023
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletionscoderd/apidoc/docs.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more abouthow customized files appear on GitHub.

6 changes: 0 additions & 6 deletionscoderd/apidoc/swagger.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more abouthow customized files appear on GitHub.

2 changes: 0 additions & 2 deletionscoderd/workspaceagents.go
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -242,7 +242,6 @@ func (api *API) postWorkspaceAgentStartup(rw http.ResponseWriter, r *http.Reques
// @Param request body agentsdk.PatchStartupLogs true "Startup logs"
// @Success 200 {object} codersdk.Response
// @Router /workspaceagents/me/startup-logs [patch]
// @x-apidocgen {"skip": true}
func (api *API) patchWorkspaceAgentStartupLogs(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
workspaceAgent := httpmw.WorkspaceAgent(r)
Expand DownExpand Up@@ -1292,7 +1291,6 @@ func convertWorkspaceAgent(derpMap *tailcfg.DERPMap, coordinator tailnet.Coordin
// @Param request body agentsdk.Stats true "Stats request"
// @Success 200 {object} agentsdk.StatsResponse
// @Router /workspaceagents/me/report-stats [post]
// @x-apidocgen {"skip": true}
func (api *API) workspaceAgentReportStats(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()

Expand Down
90 changes: 72 additions & 18 deletionsdocs/admin/automation.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,86 @@
#Automation

We recommend automatingCoderdeployments throughtheCLI. Examples include[updating templates via CI/CD pipelines](../templates/change-management.md).
All actions possible through theCoderdashboard can also be automated as it utilizesthesame public REST API. There are several ways to extend/automate Coder:

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

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.
##Quickstart

##CLI
Generate a token on your Coder deployment by visiting:

You can use tokens with the CLI by setting the`--token` CLI flag or the`CODER_SESSION_TOKEN`
environment variable.

```console
export CODER_URL=https://coder.example.com
export CODER_SESSION_TOKEN=*****
coder workspaces ls
```sh
https://coder.example.com/settings/tokens
```

##REST API
List your workspaces

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:
```sh
# CLI
coder ls \
--url https://coder.example.com \
--token<your-token> \
--output json

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

By default, the local Swagger endpoint ishttp://localhost:3000/swagger.
##Documentation

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.

##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 CLI and API documentation.

###Templates

-[Update templates in CI](../templates/change-management.md): Store all templates and git and update templates in CI/CD pipelines.

###Workspace agents

Workspace agents have a special token that can send logs, metrics, and workspace activity.

-[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.

```sh
curl -X PATCH https://coder.example.com/api/v2/workspaceagents/me/startup-logs \
-H"Coder-Session-Token:$CODER_AGENT_TOKEN" \
-d"{
\"logs\": [
{
\"created_at\":\"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\",
\"level\":\"info\",
\"output\":\"Restoring workspace from snapshot: 05%...\"
}
]
}"
```

-[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).

```sh
#!/bin/bash
# Send workspace activity as long as the job is still running

##Golang SDK
whiletrue
do
if pgrep -f"my_training_script.py"> /dev/null
then
curl -X POST"https://coder.example.com/api/v2/workspaceagents/me/report-stats" \
-H"Coder-Session-Token:$CODER_AGENT_TOKEN" \
-d'{
"connection_count": 1
}'

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).
# 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
done
```
131 changes: 131 additions & 0 deletionsdocs/api/agents.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -395,6 +395,137 @@ curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/manifest \

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

## Submit workspace agent stats

### Code samples

```shell
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/me/report-stats \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```

`POST /workspaceagents/me/report-stats`

> Body parameter

```json
{
"connection_count": 0,
"connection_median_latency_ms": 0,
"connections_by_proto": {
"property1": 0,
"property2": 0
},
"metrics": [
{
"labels": [
{
"name": "string",
"value": "string"
}
],
"name": "string",
"type": "counter",
"value": 0
}
],
"rx_bytes": 0,
"rx_packets": 0,
"session_count_jetbrains": 0,
"session_count_reconnecting_pty": 0,
"session_count_ssh": 0,
"session_count_vscode": 0,
"tx_bytes": 0,
"tx_packets": 0
}
```

### Parameters

| Name | In | Type | Required | Description |
| ------ | ---- | ------------------------------------------ | -------- | ------------- |
| `body` | body | [agentsdk.Stats](schemas.md#agentsdkstats) | true | Stats request |

### Example responses

> 200 Response

```json
{
"report_interval": 0
}
```

### Responses

| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.StatsResponse](schemas.md#agentsdkstatsresponse) |

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

## Patch workspace agent startup logs

### Code samples

```shell
# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaceagents/me/startup-logs \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```

`PATCH /workspaceagents/me/startup-logs`

> Body parameter

```json
{
"logs": [
{
"created_at": "string",
"level": "trace",
"output": "string"
}
]
}
```

### Parameters

| Name | In | Type | Required | Description |
| ------ | ---- | ---------------------------------------------------------------- | -------- | ------------ |
| `body` | body | [agentsdk.PatchStartupLogs](schemas.md#agentsdkpatchstartuplogs) | true | Startup logs |

### Example responses

> 200 Response

```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```

### Responses

| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](schemas.md#codersdkresponse) |

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

## Get workspace agent by ID

### Code samples
Expand Down
24 changes: 23 additions & 1 deletiondocs/api/index.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,26 @@
Get started with Coder API:
Get started with the Coder API:

##Quickstart

Generate a token on your Coder deployment by visiting:

```sh
https://coder.example.com/settings/tokens
```

List your workspaces

```sh
# CLI
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
-H"Coder-Session-Token: <your-token>"
```

##Use cases

See some common[use cases](../admin/automation.md#use-cases) for the REST API.

##Sections

<children>
This page is rendered onhttps://coder.com/docs/coder-oss/api. Refer to the other documents in the`api/` directory.
Expand Down
26 changes: 24 additions & 2 deletionsscripts/apidocgen/postprocess/main.go
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -18,10 +18,32 @@ import (
const (
apiSubdir = "api"
apiIndexFile = "index.md"
apiIndexContent = `Get started with Coder API:
apiIndexContent = `Get started with the Coder API:

## Quickstart

Generate a token on your Coder deployment by visiting:

` + "````sh" + `
https://coder.example.com/settings/tokens
` + "````" + `

List your workspaces

` + "````sh" + `
# CLI
curl https://coder.example.com/api/v2/workspaces?q=owner:me \
-H "Coder-Session-Token: <your-token>"
` + "````" + `

## Use cases

See some common [use cases](../admin/automation.md#use-cases) for the REST API.

## Sections

<children>
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`" + `api/` + "`" + ` directory.
This page is rendered on https://coder.com/docs/coder-oss/api. Refer to the other documents in the ` + "`api/`" + ` directory.
</children>
`
)
Expand Down
[8]ページ先頭
©2009-2025 Movatter.jp