opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add agent metadata (#6614)

Browse Source
This commit is contained in:
Ammar Bandukwala
2023-03-31 15:26:19 -05:00
committed by GitHub
parent c191692751
commit ca4fa81570
62 changed files with 3139 additions and 727 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/agents.md
+13 -4
View File
@@ -273,18 +273,18 @@ curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/gitsshkey \
To perform this operation, you must be authenticated. [Learn more](authentication.md).
## Get authorized workspace agent metadata
## Get authorized workspace agent manifest
### Code samples
```shell
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/metadata \
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/metadata`
`GET /workspaceagents/me/manifest`
### Example responses
@@ -368,6 +368,15 @@ curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/metadata \
"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,
@@ -381,7 +390,7 @@ curl -X GET http://coder-server:8080/api/v2/workspaceagents/me/metadata \
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.Metadata](schemas.md#agentsdkmetadata) |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [agentsdk.Manifest](schemas.md#agentsdkmanifest) |
To perform this operation, you must be authenticated. [Learn more](authentication.md).
docs/api/schemas.md
+67 -15
View File
@@ -94,7 +94,7 @@
| ---------------- | ------ | -------- | ------------ | ----------- |
| `json_web_token` | string | true | | |
## agentsdk.Metadata
## agentsdk.Manifest
```json
{
@@ -174,6 +174,15 @@
"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,
@@ -185,20 +194,21 @@
### Properties
| Name | Type | Required | Restrictions | Description |
| ------------------------- | ------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps` | array of [codersdk.WorkspaceApp](#codersdkworkspaceapp) | false | | |
| `derpmap` | [tailcfg.DERPMap](#tailcfgderpmap) | false | | |
| `directory` | string | false | | |
| `environment_variables` | object | false | | |
| » `[any property]` | string | false | | |
| `git_auth_configs` | integer | false | | Git auth configs stores the number of Git configurations the Coder deployment has. If this number is >0, we set up special configuration in the workspace. |
| `motd_file` | string | false | | |
| `shutdown_script` | string | false | | |
| `shutdown_script_timeout` | integer | false | | |
| `startup_script` | string | false | | |
| `startup_script_timeout` | integer | false | | |
| `vscode_port_proxy_uri` | string | false | | |
| Name | Type | Required | Restrictions | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apps` | array of [codersdk.WorkspaceApp](#codersdkworkspaceapp) | false | | |
| `derpmap` | [tailcfg.DERPMap](#tailcfgderpmap) | false | | |
| `directory` | string | false | | |
| `environment_variables` | object | false | | |
| » `[any property]` | string | false | | |
| `git_auth_configs` | integer | false | | Git auth configs stores the number of Git configurations the Coder deployment has. If this number is >0, we set up special configuration in the workspace. |
| `metadata` | array of [codersdk.WorkspaceAgentMetadataDescription](#codersdkworkspaceagentmetadatadescription) | false | | |
| `motd_file` | string | false | | |
| `shutdown_script` | string | false | | |
| `shutdown_script_timeout` | integer | false | | |
| `startup_script` | string | false | | |
| `startup_script_timeout` | integer | false | | |
| `vscode_port_proxy_uri` | string | false | | |
## agentsdk.PatchStartupLogs
@@ -251,6 +261,26 @@
| ------- | -------------------------------------------------------------------- | -------- | ------------ | ----------- |
| `state` | [codersdk.WorkspaceAgentLifecycle](#codersdkworkspaceagentlifecycle) | false | | |
## agentsdk.PostMetadataRequest
```json
{
"age": 0,
"collected_at": "2019-08-24T14:15:22Z",
"error": "string",
"value": "string"
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| -------------- | ------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `age` | integer | false | | Age is the number of seconds since the metadata was collected. It is provided in addition to CollectedAt to protect against clock skew. |
| `collected_at` | string | false | | |
| `error` | string | false | | |
| `value` | string | false | | |
## agentsdk.PostStartupRequest
```json
@@ -4680,6 +4710,28 @@ Parameter represents a set value for the scope.
| ------- | ------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ports` | array of [codersdk.WorkspaceAgentListeningPort](#codersdkworkspaceagentlisteningport) | false | | If there are no ports in the list, nothing should be displayed in the UI. There must not be a "no ports available" message or anything similar, as there will always be no ports displayed on platforms where our port detection logic is unsupported. |
## codersdk.WorkspaceAgentMetadataDescription
```json
{
"display_name": "string",
"interval": 0,
"key": "string",
"script": "string",
"timeout": 0
}
```
### Properties
| Name | Type | Required | Restrictions | Description |
| -------------- | ------- | -------- | ------------ | ----------- |
| `display_name` | string | false | | |
| `interval` | integer | false | | |
| `key` | string | false | | |
| `script` | string | false | | |
| `timeout` | integer | false | | |
## codersdk.WorkspaceAgentStartupLog
```json
docs/images/agent-metadata.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

docs/manifest.json
+7
View File
@@ -135,6 +135,13 @@
"path": "./templates/resource-metadata.md",
"icon_path": "./images/icons/table-rows.svg"
},
{
"title": "Agent Metadata",
"description": "Learn how to expose live agent information to users",
"path": "./templates/agent-metadata.md",
"icon_path": "./images/icons/table-rows.svg",
"state": "alpha"
},
{
"title": "Docker in Docker",
"description": "Use docker inside containerized templates",
docs/templates/agent-metadata.md
Vendored
+90
View File
@@ -0,0 +1,90 @@
# Agent Metadata (alpha)
<blockquote class="warning">
Agent metadata is in an alpha state and may break or disappear at any time.
</blockquote>
![agent-metadata](../images/agent-metadata.png)
With Agent Metadata, template admin can expose operational metrics from
their workspaces to their users. It is a sibling of [Resource Metadata](./resource-metadata.md).
See the [Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
## Examples
All of these examples use [heredoc strings](https://developer.hashicorp.com/terraform/language/expressions/strings#heredoc-strings) for the script declaration. With heredoc strings you
can script without messy escape codes, just as if you were working in your terminal.
Here are useful agent metadata snippets for Linux agents:
```hcl
resource "coder_agent" "main" {
os = "linux"
...
metadata {
display_name = "CPU Usage"
key = "cpu"
# calculates CPU usage by summing the "us", "sy" and "id" columns of
# vmstat.
script = <<EOT
vmstat | awk 'FNR==3 {printf "%2.0f%%", $13+$14+$16}'
EOT
interval = 1
timeout = 1
}
metadata {
display_name = "Disk Usage"
key = "cpu"
script = <<EOT
df -h | awk -v mount="/" '$6 == mount { print $5 }'
EOT
interval = 1
timeout = 1
}
metadata {
display_name = "Memory Usage"
key = "mem"
script = <<EOT
free | awk '/^Mem/ { printf("%.0f%%", $4/$2 * 100.0) }'
EOT
interval = 1
timeout = 1
}
metadata {
display_name = "Load Average"
key = "load"
script = <<EOT
awk '{print $1,$2,$3}' /proc/loadavg
>>
interval = 1
timeout = 1
}
}
```
## Utilities
[vmstat](https://linux.die.net/man/8/vmstat) is available in most Linux
distributions and contains virtual memory, CPU and IO statistics. Running `vmstat`
produces output that looks like:
```
procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu-----
r b swpd free buff cache si so bi bo in cs us sy id wa st
0 0 19580 4781680 12133692 217646944 0 2 4 32 1 0 1 1 98 0 0
```
[dstat](https://linux.die.net/man/1/dstat) is considerably more parseable
than `vmstat` but often not included in base images. It is easily installed by
most package managers under the name `dstat`. The output of running `dstat 1 1` looks
like:
```
--total-cpu-usage-- -dsk/total- -net/total- ---paging-- ---system--
usr sys idl wai stl| read writ| recv send| in out | int csw
1 1 98 0 0|3422k 25M| 0 0 | 153k 904k| 123k 174k
```
docs/templates/resource-metadata.md
Vendored
+22
View File
@@ -97,6 +97,28 @@ To make easier for you to customize your resource we added some built-in icons:
We also have other icons related to the IDEs. You can see all the icons [here](https://github.com/coder/coder/tree/main/site/static/icon).
## Agent Metadata
In cases where you want to present automatically updating, dynamic values. You
can use the `metadata` block in the `coder_agent` resource. For example:
```hcl
resource "coder_agent" "dev" {
os = "linux"
arch = "amd64"
dir = "/workspace"
metadata {
name = "Process Count"
script = "ps aux | wc -l"
interval = 1
timeout = 3
}
}
```
Read more [here](./agent-metadata.md).
## Up next
- Learn about [secrets](../secrets.md)
- Learn about [Agent Metadata](../agent-metadata.md)