opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-22 13:10:21 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
eb0783ff2412111132ccbc8577fa58a11ad05c49
coder/docs/api/agents.md
T
Mathias Fredriksson 8dac0356ed refactor: replace startup script logs EOF with starting/ready time (#8082) 
This commit reverts some of the changes in #8029 and implements an
alternative method of keeping track of when the startup script has ended
and there will be no more logs.

This is achieved by adding new agent fields for tracking when the agent
enters the "starting" and "ready"/"start_error" lifecycle states. The
timestamps simplify logic since we don't need understand if the current
state is before or after the state we're interested in. They can also be
used to show data like how long the startup script took to execute. This
also allowed us to remove the EOF field from the logs as the
implementation was problematic when we returned the EOF log entry in the
response since requesting _after_ that ID would give no logs and the API
would thus lose track of EOF.
2023-06-20 14:41:55 +03:00

23 KiB
Raw Blame History

Agents

Authenticate agent on AWS instance

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/aws-instance-identity \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/aws-instance-identity

Body parameter

{
  "document": "string",
  "signature": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.AWSInstanceIdentityToken true Instance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.AuthenticateResponse

To perform this operation, you must be authenticated. Learn more.

Authenticate agent on Azure instance

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/azure-instance-identity \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/azure-instance-identity

Body parameter

{
  "encoding": "string",
  "signature": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.AzureInstanceIdentityToken true Instance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.AuthenticateResponse

To perform this operation, you must be authenticated. Learn more.

Authenticate agent on Google Cloud instance

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceagents/google-instance-identity \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /workspaceagents/google-instance-identity

Body parameter

{
  "json_web_token": "string"
}

Parameters

Name In Type Required Description
body body agentsdk.GoogleInstanceIdentityToken true Instance identity token

Example responses

200 Response

{
  "session_token": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.AuthenticateResponse

To perform this operation, you must be authenticated. Learn more.

Submit workspace agent application health

Code samples

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

POST /workspaceagents/me/app-health

Body parameter

{
  "healths": {
    "property1": "disabled",
    "property2": "disabled"
  }
}

Parameters

Name In Type Required Description
body body agentsdk.PostAppHealthsRequest true Application health request

Responses

Status Meaning Description Schema
200 OK OK

To perform this operation, you must be authenticated. Learn more.

Coordinate workspace agent via Tailnet

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/coordinate \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/coordinate

It accepts a WebSocket connection to an agent that listens to incoming connections and publishes node updates.

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

Get workspace agent Git auth

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitauth?url=http%3A%2F%2Fexample.com \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/gitauth

Parameters

Name In Type Required Description
url query string(uri) true Git URL
listen query boolean false Wait for a new token to be issued

Example responses

200 Response

{
  "password": "string",
  "url": "string",
  "username": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.GitAuthResponse

To perform this operation, you must be authenticated. Learn more.

Get workspace agent Git SSH key

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitsshkey \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/gitsshkey

Example responses

200 Response

{
  "private_key": "string",
  "public_key": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.GitSSHKey

To perform this operation, you must be authenticated. Learn more.

Get authorized workspace agent manifest

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/manifest \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/me/manifest

Example responses

200 Response

{
  "apps": [
    {
      "command": "string",
      "display_name": "string",
      "external": true,
      "health": "disabled",
      "healthcheck": {
        "interval": 0,
        "threshold": 0,
        "url": "string"
      },
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_level": "owner",
      "slug": "string",
      "subdomain": true,
      "url": "string"
    }
  ],
  "derpmap": {
    "omitDefaultRegions": true,
    "regions": {
      "property1": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "certName": "string",
            "derpport": 0,
            "forceHTTP": true,
            "hostName": "string",
            "insecureForTests": true,
            "ipv4": "string",
            "ipv6": "string",
            "name": "string",
            "regionID": 0,
            "stunonly": true,
            "stunport": 0,
            "stuntestIP": "string"
          }
        ],
        "regionCode": "string",
        "regionID": 0,
        "regionName": "string"
      },
      "property2": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "certName": "string",
            "derpport": 0,
            "forceHTTP": true,
            "hostName": "string",
            "insecureForTests": true,
            "ipv4": "string",
            "ipv6": "string",
            "name": "string",
            "regionID": 0,
            "stunonly": true,
            "stunport": 0,
            "stuntestIP": "string"
          }
        ],
        "regionCode": "string",
        "regionID": 0,
        "regionName": "string"
      }
    }
  },
  "directory": "string",
  "environment_variables": {
    "property1": "string",
    "property2": "string"
  },
  "git_auth_configs": 0,
  "metadata": [
    {
      "display_name": "string",
      "interval": 0,
      "key": "string",
      "script": "string",
      "timeout": 0
    }
  ],
  "motd_file": "string",
  "shutdown_script": "string",
  "shutdown_script_timeout": 0,
  "startup_script": "string",
  "startup_script_timeout": 0,
  "vscode_port_proxy_uri": "string"
}

Responses

Status Meaning Description Schema
200 OK OK agentsdk.Manifest

To perform this operation, you must be authenticated. Learn more.

Get workspace agent by ID

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Example responses

200 Response

{
  "apps": [
    {
      "command": "string",
      "display_name": "string",
      "external": true,
      "health": "disabled",
      "healthcheck": {
        "interval": 0,
        "threshold": 0,
        "url": "string"
      },
      "icon": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_level": "owner",
      "slug": "string",
      "subdomain": true,
      "url": "string"
    }
  ],
  "architecture": "string",
  "connection_timeout_seconds": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "directory": "string",
  "disconnected_at": "2019-08-24T14:15:22Z",
  "environment_variables": {
    "property1": "string",
    "property2": "string"
  },
  "expanded_directory": "string",
  "first_connected_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "instance_id": "string",
  "last_connected_at": "2019-08-24T14:15:22Z",
  "latency": {
    "property1": {
      "latency_ms": 0,
      "preferred": true
    },
    "property2": {
      "latency_ms": 0,
      "preferred": true
    }
  },
  "lifecycle_state": "created",
  "login_before_ready": true,
  "name": "string",
  "operating_system": "string",
  "ready_at": "2019-08-24T14:15:22Z",
  "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
  "shutdown_script": "string",
  "shutdown_script_timeout_seconds": 0,
  "started_at": "2019-08-24T14:15:22Z",
  "startup_logs_length": 0,
  "startup_logs_overflowed": true,
  "startup_script": "string",
  "startup_script_behavior": "blocking",
  "startup_script_timeout_seconds": 0,
  "status": "connecting",
  "subsystem": "envbox",
  "troubleshooting_url": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgent

To perform this operation, you must be authenticated. Learn more.

Get connection info for workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/connection \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/connection

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Example responses

200 Response

{
  "derp_map": {
    "omitDefaultRegions": true,
    "regions": {
      "property1": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "certName": "string",
            "derpport": 0,
            "forceHTTP": true,
            "hostName": "string",
            "insecureForTests": true,
            "ipv4": "string",
            "ipv6": "string",
            "name": "string",
            "regionID": 0,
            "stunonly": true,
            "stunport": 0,
            "stuntestIP": "string"
          }
        ],
        "regionCode": "string",
        "regionID": 0,
        "regionName": "string"
      },
      "property2": {
        "avoid": true,
        "embeddedRelay": true,
        "nodes": [
          {
            "certName": "string",
            "derpport": 0,
            "forceHTTP": true,
            "hostName": "string",
            "insecureForTests": true,
            "ipv4": "string",
            "ipv6": "string",
            "name": "string",
            "regionID": 0,
            "stunonly": true,
            "stunport": 0,
            "stuntestIP": "string"
          }
        ],
        "regionCode": "string",
        "regionID": 0,
        "regionName": "string"
      }
    }
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgentConnectionInfo

To perform this operation, you must be authenticated. Learn more.

Coordinate workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/coordinate \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/coordinate

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

Get listening ports for workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/listening-ports \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/listening-ports

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Example responses

200 Response

{
  "ports": [
    {
      "network": "string",
      "port": 0,
      "process_name": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceAgentListeningPortsResponse

To perform this operation, you must be authenticated. Learn more.

Open PTY to workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/pty \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/pty

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

Get startup logs by workspace agent

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/{workspaceagent}/startup-logs \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /workspaceagents/{workspaceagent}/startup-logs

Parameters

Name In Type Required Description
workspaceagent path string(uuid) true Workspace agent ID
before query integer false Before log id
after query integer false After log id
follow query boolean false Follow log stream

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": 0,
    "level": "trace",
    "output": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.WorkspaceAgentStartupLog

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) false
» id integer false
» level codersdk.LogLevel false
» output string false

Enumerated Values

Property Value
level trace
level debug
level info
level warn
level error

To perform this operation, you must be authenticated. Learn more.

Reference in New Issue View Git Blame Copy Permalink