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/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/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) diff --git a/docs/reference/agent-api/README.md b/docs/reference/agent-api/README.md new file mode 100644 index 0000000000000..21e7c5ec54f69 --- /dev/null +++ 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. + diff --git a/docs/reference/agent-api/debug.md b/docs/reference/agent-api/debug.md new file mode 100644 index 0000000000000..e9b2520f04701 --- /dev/null +++ b/docs/reference/agent-api/debug.md @@ -0,0 +1,76 @@ +# Debug + +## Get debug logs + +### Code samples + +```shell +curl $CODER_AGENT_DEBUG_ADDRESS/debug/logs +``` + +`GET /debug/logs` + +Get the first 10MiB of data from `$CODER_AGENT_LOG_DIR/coder-agent.log`. + +### 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 $CODER_AGENT_DEBUG_ADDRESS/debug/magicsock +``` + +`GET /debug/magicsock` + +See +[Tailscale's documentation](https://pkg.go.dev/tailscale.com/wgengine/magicsock#Conn.ServeHTTPDebug). + +## Toggle debug logging for magicsock + +### Code samples + +```shell +curl $CODER_AGENT_DEBUG_ADDRESS/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 | +| ------- | ---- | ------- | -------- | ------------------- | +| `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 $CODER_AGENT_DEBUG_ADDRESS/debug/manifest +``` + +`GET /debug/manifest` + +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.md#agentsdkmanifest) | diff --git a/docs/reference/agent-api/schemas.md b/docs/reference/agent-api/schemas.md new file mode 100644 index 0000000000000..7aba4ebd5d230 --- /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.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.md#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 | | |