From 582f3bfc449acc7cd4c1b883598465f81e198ba8 Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Tue, 27 Aug 2024 11:21:13 +0000 Subject: [PATCH 1/7] chore(docs): add agent api debug docs --- docs/manifest.json | 16 ++++ docs/reference/agent-api/README.md | 0 docs/reference/agent-api/debug.md | 71 ++++++++++++++++ docs/reference/agent-api/schemas.md | 124 ++++++++++++++++++++++++++++ 4 files changed, 211 insertions(+) create mode 100644 docs/reference/agent-api/README.md create mode 100644 docs/reference/agent-api/debug.md create mode 100644 docs/reference/agent-api/schemas.md diff --git a/docs/manifest.json b/docs/manifest.json index 91b1ae90efe9e..95cd3b0cb14cf 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1105,6 +1105,22 @@ "path": "reference/cli/whoami.md" } ] + }, + { + "title": "Agent API", + "description": "Learn how to use Coder Agent API", + "path": "./reference/agent-api/README.md", + "icon_path": "./images/icons/api.svg", + "children": [ + { + "title": "Debug", + "path": "./reference/agent-api/debug.md" + }, + { + "title": "Schemas", + "path": "./reference/agent-api/schemas.md" + } + ] } ] }, diff --git a/docs/reference/agent-api/README.md b/docs/reference/agent-api/README.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/docs/reference/agent-api/debug.md b/docs/reference/agent-api/debug.md new file mode 100644 index 0000000000000..d8bb67be9b0fc --- /dev/null +++ b/docs/reference/agent-api/debug.md @@ -0,0 +1,71 @@ +# Debug + +## Get debug logs + +### Code samples + +```shell +curl http://127.0.0.1:2113/debug/logs +``` + +`GET /debug/logs` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | | + +## Get debug info for magicsock + +### Code samples + +```shell +curl http://127.0.0.1:2113/debug/magicsock +``` + +`GET /debug/magicsock` + +### Responses + +See +[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.ServeHTTPDebug) +for response format. + +## Toggle debug logging for magicsock + +### Code samples + +```shell +curl http://127.0.0.1:2113/debug/magicsock/debug-logging/true +``` + +`GET /debug/magicsock/debug-logging/{state}` + +### Parameters + +| Name | In | Type | Required | Description | +| ------- | ---- | ------- | -------- | ------------------- | +| `state` | path | boolean | true | Debug logging state | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | | + +## Get debug manifest + +### Code samples + +```shell +curl http://127.0.0.1:2113/debug/manifest +``` + +`GET /debug/manifest` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | | diff --git a/docs/reference/agent-api/schemas.md b/docs/reference/agent-api/schemas.md new file mode 100644 index 0000000000000..d98dc5d9d8547 --- /dev/null +++ b/docs/reference/agent-api/schemas.md @@ -0,0 +1,124 @@ +# Schemas + +## agentsdk.Manifest + +```json +{ + "agent_id": "151321db-0713-473c-ab42-2cc6ddeab1a4", + "agent_name": "string", + "owner_name": "string", + "workspace_id": "8ef13a0d-a5c9-4fb4-abf2-f8f65c3830fb", + "workspace_name": "string", + "git_auth_configs": 1, + "vscode_port_proxy_uri": "string", + "apps": [ + { + "id": "c488c933-688a-444e-a55d-f1e88ecc78f5", + "url": "string", + "external": false, + "slug": "string", + "display_name": "string", + "icon": "string", + "subdomain": false, + "sharing_level": "owner", + "healthcheck": { + "url": "string", + "interval": 5, + "threshold": 6 + }, + "health": "initializing" + } + ], + "derpmap": { + "HomeParams": {}, + "Regions": { + "1000": { + "EmbeddedRelay": false, + "RegionID": 1000, + "RegionCode": "string", + "RegionName": "string", + "Nodes": [ + { + "Name": "string", + "RegionID": 1000, + "HostName": "string", + "STUNPort": 19302, + "STUNOnly": true + } + ] + } + } + }, + "derp_force_websockets": false, + "environment_variables": { + "OIDC_TOKEN": "string" + }, + "directory": "string", + "motd_file": "string", + "disable_direct_connections": false, + "metadata": [ + { + "display_name": "string", + "key": "string", + "script": "string", + "interval": 10, + "timeout": 1 + } + ], + "scripts": [ + { + "log_source_id": "3e79c8da-08ae-48f4-b73e-11e194cdea06", + "log_path": "string", + "script": "string", + "cron": "string", + "run_on_start": true, + "run_on_stop": false, + "start_blocks_login": true, + "timeout": 0 + } + ] +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------ | ----------- | +| `agent_id` | string | true | | | +| `agent_name` | string | true | | | +| `owner_name` | string | true | | | +| `workspace_id` | string | true | | | +| `workspace_name` | string | true | | | +| `git_auth_configs` | int | true | | | +| `vscode_port_proxy_uri` | string | true | | | +| `apps` | array of [codersdk.WorkspaceApp](../api/schemas#codersdkworkspaceapp) | true | | | +| `derpmap` | [tailcfg.DERPMap](../api/schemas#tailcfgderpmap) | true | | | +| `derp_force_websockets` | boolean | true | | | +| `environment_variables` | object | true | | | +| `directory` | string | true | | | +| `motd_file` | string | true | | | +| `disable_direct_connections` | boolean | true | | | +| `metadata` | array of [codersdk.WorkspaceAgentMetadataDescription](#codersdkworkspaceagentmetadatadescription) | true | | | +| `scripts` | array of [codersdk.WorkspaceAgentScript](../api/schemas#codersdkworkspaceagentscript) | true | | | + +## codersdk.WorkspaceAgentMetadataDescription + +```json +{ + "display_name": "string", + "key": "string", + "script": "string", + "interval": 10, + "timeout": 1 +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| -------------- | ------- | -------- | ------------ | ----------- | +| `display_name` | string | true | | | +| `key` | string | true | | | +| `script` | string | true | | | +| `interval` | integer | true | | | +| `timeout` | integer | true | | | From 4f9c0f93ac63fb1fd3b2a3da43ddfc26801ebb1c Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Tue, 27 Aug 2024 12:19:36 +0000 Subject: [PATCH 2/7] chore(docs): add sections to agent api readme --- docs/reference/agent-api/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/reference/agent-api/README.md b/docs/reference/agent-api/README.md index e69de29bb2d1d..21e7c5ec54f69 100644 --- a/docs/reference/agent-api/README.md +++ b/docs/reference/agent-api/README.md @@ -0,0 +1,5 @@ +## Sections + + + This page is rendered on https://coder.com/docs/reference/agent-api. Refer to the other documents in the `agent-api/` directory. + From d8814a5d42a5023001b26e370ce7cb4718b447bf Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Tue, 27 Aug 2024 13:22:51 +0000 Subject: [PATCH 3/7] chore(docs): link debug manifest to agentsdk.Manifest schema --- docs/reference/agent-api/debug.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/agent-api/debug.md b/docs/reference/agent-api/debug.md index d8bb67be9b0fc..2df5d846eec73 100644 --- a/docs/reference/agent-api/debug.md +++ b/docs/reference/agent-api/debug.md @@ -66,6 +66,6 @@ curl http://127.0.0.1:2113/debug/manifest ### Responses -| Status | Meaning | Description | Schema | -| ------ | ------------------------------------------------------- | ----------- | ------ | -| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | | +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.Manifest](./schemas#agentsdkmanifest) | From 02643881a6ec84dd473b0b061bc25412b7e989cd Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Tue, 27 Aug 2024 14:29:12 +0000 Subject: [PATCH 4/7] chore(docs): add high level overview of agent api debug docs --- agent/agent.go | 2 +- docs/reference/agent-api/debug.md | 13 +++++++++---- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/agent/agent.go b/agent/agent.go index 30db6f073cc69..f0e357479bc47 100644 --- a/agent/agent.go +++ b/agent/agent.go @@ -1787,7 +1787,7 @@ func (a *agent) HandleHTTPDebugLogs(w http.ResponseWriter, r *http.Request) { } defer f.Close() - // Limit to 10MB. + // Limit to 10MiB. w.WriteHeader(http.StatusOK) _, err = io.Copy(w, io.LimitReader(f, 10*1024*1024)) if err != nil && !errors.Is(err, io.EOF) { diff --git a/docs/reference/agent-api/debug.md b/docs/reference/agent-api/debug.md index 2df5d846eec73..9f56cd6e93219 100644 --- a/docs/reference/agent-api/debug.md +++ b/docs/reference/agent-api/debug.md @@ -10,6 +10,8 @@ curl http://127.0.0.1:2113/debug/logs `GET /debug/logs` +Get the first 10MiB of data from `$CODER_AGENT_LOG_DIR/coder-agent.log`. + ### Responses | Status | Meaning | Description | Schema | @@ -26,11 +28,8 @@ curl http://127.0.0.1:2113/debug/magicsock `GET /debug/magicsock` -### Responses - See -[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.ServeHTTPDebug) -for response format. +[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.ServeHTTPDebug). ## Toggle debug logging for magicsock @@ -42,6 +41,10 @@ curl http://127.0.0.1:2113/debug/magicsock/debug-logging/true `GET /debug/magicsock/debug-logging/{state}` +Set whether debug logging is enabled. See +[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.SetDebugLoggingEnabled) +for more information. + ### Parameters | Name | In | Type | Required | Description | @@ -64,6 +67,8 @@ curl http://127.0.0.1:2113/debug/manifest `GET /debug/manifest` +Get the manifest the agent fetched from `coderd` upon startup. + ### Responses | Status | Meaning | Description | Schema | From a0d0a950cc509c0d48a3781e417e7b2c6bc7571f Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Tue, 27 Aug 2024 14:43:22 +0000 Subject: [PATCH 5/7] chore(docs): link to agent api docs from reference --- docs/reference/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/README.md b/docs/reference/README.md index 2e8228638d626..53f812bd48ad5 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -4,3 +4,4 @@ Autogenerated documentation around Coder. - [REST API](./api) - [Command Line](./cli) +- [Agent API](./agent-api) From 6ff88ef818155f0ac3c7a75bfc39c27cc40a01fd Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Wed, 28 Aug 2024 07:46:11 +0000 Subject: [PATCH 6/7] chore(docs): fix invalid paths --- docs/reference/agent-api/debug.md | 6 +++--- docs/reference/agent-api/schemas.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/agent-api/debug.md b/docs/reference/agent-api/debug.md index 9f56cd6e93219..63c54217dac80 100644 --- a/docs/reference/agent-api/debug.md +++ b/docs/reference/agent-api/debug.md @@ -71,6 +71,6 @@ Get the manifest the agent fetched from `coderd` upon startup. ### Responses -| Status | Meaning | Description | Schema | -| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------- | -| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.Manifest](./schemas#agentsdkmanifest) | +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.Manifest](./schemas.md#agentsdkmanifest) | diff --git a/docs/reference/agent-api/schemas.md b/docs/reference/agent-api/schemas.md index d98dc5d9d8547..7aba4ebd5d230 100644 --- a/docs/reference/agent-api/schemas.md +++ b/docs/reference/agent-api/schemas.md @@ -91,15 +91,15 @@ | `workspace_name` | string | true | | | | `git_auth_configs` | int | true | | | | `vscode_port_proxy_uri` | string | true | | | -| `apps` | array of [codersdk.WorkspaceApp](../api/schemas#codersdkworkspaceapp) | true | | | -| `derpmap` | [tailcfg.DERPMap](../api/schemas#tailcfgderpmap) | true | | | +| `apps` | array of [codersdk.WorkspaceApp](../api/schemas.md#codersdkworkspaceapp) | true | | | +| `derpmap` | [tailcfg.DERPMap](../api/schemas.md#tailcfgderpmap) | true | | | | `derp_force_websockets` | boolean | true | | | | `environment_variables` | object | true | | | | `directory` | string | true | | | | `motd_file` | string | true | | | | `disable_direct_connections` | boolean | true | | | | `metadata` | array of [codersdk.WorkspaceAgentMetadataDescription](#codersdkworkspaceagentmetadatadescription) | true | | | -| `scripts` | array of [codersdk.WorkspaceAgentScript](../api/schemas#codersdkworkspaceagentscript) | true | | | +| `scripts` | array of [codersdk.WorkspaceAgentScript](../api/schemas.md#codersdkworkspaceagentscript) | true | | | ## codersdk.WorkspaceAgentMetadataDescription From bc59d172d507fb4a36228b162cbc912a9ee52930 Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Wed, 28 Aug 2024 08:16:55 +0000 Subject: [PATCH 7/7] chore(docs): use env variable for coder agent debug address --- docs/reference/agent-api/debug.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/agent-api/debug.md b/docs/reference/agent-api/debug.md index 63c54217dac80..e9b2520f04701 100644 --- a/docs/reference/agent-api/debug.md +++ b/docs/reference/agent-api/debug.md @@ -5,7 +5,7 @@ ### Code samples ```shell -curl http://127.0.0.1:2113/debug/logs +curl $CODER_AGENT_DEBUG_ADDRESS/debug/logs ``` `GET /debug/logs` @@ -23,7 +23,7 @@ Get the first 10MiB of data from `$CODER_AGENT_LOG_DIR/coder-agent.log`. ### Code samples ```shell -curl http://127.0.0.1:2113/debug/magicsock +curl $CODER_AGENT_DEBUG_ADDRESS/debug/magicsock ``` `GET /debug/magicsock` @@ -36,7 +36,7 @@ See ### Code samples ```shell -curl http://127.0.0.1:2113/debug/magicsock/debug-logging/true +curl $CODER_AGENT_DEBUG_ADDRESS/debug/magicsock/debug-logging/true ``` `GET /debug/magicsock/debug-logging/{state}` @@ -62,7 +62,7 @@ for more information. ### Code samples ```shell -curl http://127.0.0.1:2113/debug/manifest +curl $CODER_AGENT_DEBUG_ADDRESS/debug/manifest ``` `GET /debug/manifest`