partial completion of admin/templates/extending-templates

coder · matifali · May 22, 2024 · May 23, 2024 · May 23, 2024 · May 23, 2024
commit 1235238c8fbf73ffd05c97eb4f755bf63f3d56b1
diff --git a/docs/admin/templates/concepts.md b/docs/admin/templates/concepts.md
@@ -1,11 +1,30 @@
 # Extending templates
 
-There are a variety of Coder-native features to extend the configuration of your development environments.
+There are a variety of Coder-native features to extend the configuration of your development environments. Many of the following features are defined in your templates using the [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs). The provider docs will provide code examples for usage; alternatively, you can view our [example templates](https://github.com/coder/coder/tree/main/examples/templates) to get started.  
 
 <!-- TODO: May divide into sub-pages later. -->
 
 ## Workspace agents
 
+For users to connect to a workspace, the template must include a [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent). The associated agent will facilitate [workspace connections](../../user-guides/workspace-access/README.md) via SSH, port forwarding, and IDEs. The agent may also display [workspace metadata](#agent-metadata) like resource usage. 
+
+```hcl
+resource "coder_agent" "dev" {
+  os   = "linux"
+  arch = "amd64"
+  dir  = "/workspace"
+  display_apps {
+    vscode = true
+  }
+}
+```
+
+Templates must include some computational resource to start the agent. All processes on the workspace are then spawned from the agent. All information in the dashboard's workspace view is pulled from the agent. 
+
+![A healthy workspace agent](../../images/templates/healthy-workspace-agent.png)
+
+Multiple agents may be used in a single template or even a single resource. Each agent may have it's own apps, startup script, and metadata. This can be used to associate multiple containers or VMs with a workspace. 
+
 ## Resource persistence
 
 The resources you define in a template may be _ephemeral_ or _persistent_. Persistent resources stay provisioned when workspaces are stopped, where as ephemeral resources are destroyed and recreated on restart. All resources are destroyed when a workspace is deleted.
@@ -21,6 +40,8 @@ A common configuration is a template whose only persistent resource is the home
 
 ## Template variables
 
+
+
 ## Parameters
 
 ## Coder apps

diff --git a/docs/admin/templates/extending-templates/README.md b/docs/admin/templates/extending-templates/README.md
@@ -0,0 +1,70 @@
+# Extending templates
+
+There are a variety of Coder-native features to extend the configuration of your development environments. Many of the following features are defined in your templates using the [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs). The provider docs will provide code examples for usage; alternatively, you can view our [example templates](https://github.com/coder/coder/tree/main/examples/templates) to get started.  
+
+<!-- TODO: Review structure
+
+extending-templates/
+README.md
+- workspace agent overview
+- resource persistence
+- coder apps
+- coder parameters
+- template variables
+agent-metadata.md (from old docs)
+resource-metadata.md (from old docs)
+resource-ordering.md (from old docs) 
+-->
+
+## Workspace agents
+
+For users to connect to a workspace, the template must include a [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent). The associated agent will facilitate [workspace connections](../../../user-guides/workspace-access/README.md) via SSH, port forwarding, and IDEs. The agent may also display [workspace metadata](#agent-metadata) like resource usage. 
+
+```hcl
+resource "coder_agent" "dev" {
+  os   = "linux"
+  arch = "amd64"
+  dir  = "/workspace"
+  display_apps {
+    vscode = true
+  }
+}
+```
+
+Templates must include some computational resource to start the agent. All processes on the workspace are then spawned from the agent. All information in the dashboard's workspace view is pulled from the agent. 
+
+![A healthy workspace agent](../../../images/templates/healthy-workspace-agent.png)
+
+Multiple agents may be used in a single template or even a single resource. Each agent may have it's own apps, startup script, and metadata. This can be used to associate multiple containers or VMs with a workspace. 
+
+## Resource persistence
+
+The resources you define in a template may be _ephemeral_ or _persistent_. Persistent resources stay provisioned when workspaces are stopped, where as ephemeral resources are destroyed and recreated on restart. All resources are destroyed when a workspace is deleted.
+
+> You can read more about how resource behavior and workspace state in the  [workspace lifecycle documentation](../../workspaces/lifecycle.md).
+
+Template resources follow the [behavior of Terraform resources](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration) and can be further configured  using the [lifecycle argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle).
+
+### Example usage
+
+A common configuration is a template whose only persistent resource is the home directory. This allows the developer to retain their work while ensuring the rest of their environment is consistently up-to-date on each workspace restart.
+
+
+## Template variables
+
+You can show live operational metrics to workspace users with agent metadata. It is the dynamic complement of resource metadata.
+
+You specify agent metadata in the coder_agent.
+
+## Parameters
+
+## Coder apps
+
+### App ordering
+
+## Agent metadata
+
+
+<children>
+
+</children>
diff --git a/docs/admin/templates/extending-templates/agent-metadata.md b/docs/admin/templates/extending-templates/agent-metadata.md
@@ -0,0 +1,148 @@
+# Agent metadata
+
+![agent-metadata](../../../images/admin/templates/agent-metadata-ui.png)
+
+You can show live operational metrics to workspace users with agent metadata. It
+is the dynamic complement of [resource metadata](./resource-metadata.md).
+
+You specify agent metadata in the
+[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
+
+## 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.
+
+Some of the examples use the [`coder stat`](../../../reference/cli/stat.md) command. This is
+useful for determining CPU and memory usage of the VM or container that the
+workspace is running in, which is more accurate than resource usage about the
+workspace's host.
+
+Here's a standard set of metadata snippets for Linux agents:
+
+```hcl
+resource "coder_agent" "main" {
+  os             = "linux"
+  ...
+  metadata {
+    display_name = "CPU Usage"
+    key  = "cpu"
+    # Uses the coder stat command to get container CPU usage.
+    script = "coder stat cpu"
+    interval = 1
+    timeout = 1
+  }
+
+  metadata {
+    display_name = "Memory Usage"
+    key  = "mem"
+    # Uses the coder stat command to get container memory usage in GiB.
+    script = "coder stat mem --prefix Gi"
+    interval = 1
+    timeout = 1
+  }
+
+  metadata {
+    display_name = "CPU Usage (Host)"
+    key  = "cpu_host"
+    # calculates CPU usage by summing the "us", "sy" and "id" columns of
+    # top.
+    script = <<EOT
+    top -bn1 | awk 'FNR==3 {printf "%2.0f%%", $2+$3+$4}'
+    EOT
+    interval = 1
+    timeout = 1
+  }
+
+    metadata {
+    display_name = "Memory Usage (Host)"
+    key  = "mem_host"
+    script = <<EOT
+    free | awk '/^Mem/ { printf("%.0f%%", $4/$2 * 100.0) }'
+    EOT
+    interval = 1
+    timeout = 1
+  }
+
+  metadata {
+    display_name = "Disk Usage"
+    key  = "disk"
+    script = "df -h | awk '$6 ~ /^\\/$/ { print $5 }'"
+    interval = 1
+    timeout = 1
+  }
+
+  metadata {
+    display_name = "Load Average"
+    key  = "load"
+    script = <<EOT
+        awk '{print $1,$2,$3}' /proc/loadavg
+    EOT
+    interval = 1
+    timeout = 1
+  }
+}
+```
+
+## Useful utilities
+
+You can also show agent metadata for information about the workspace's host.
+
+[top](https://manpages.ubuntu.com/manpages/jammy/en/man1/top.1.html) is
+available in most Linux distributions and provides virtual memory, CPU and IO
+statistics. Running `top` produces output that looks like:
+
+```text
+%Cpu(s): 65.8 us,  4.4 sy,  0.0 ni, 29.3 id,  0.3 wa,  0.0 hi,  0.2 si,  0.0 st
+MiB Mem :  16009.0 total,    493.7 free,   4624.8 used,  10890.5 buff/cache
+MiB Swap:      0.0 total,      0.0 free,      0.0 used.  11021.3 avail Mem
+```
+
+[vmstat](https://manpages.ubuntu.com/manpages/jammy/en/man8/vmstat.8.html) is
+available in most Linux distributions and provides virtual memory, CPU and IO
+statistics. Running `vmstat` produces output that looks like:
+
+```text
+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://manpages.ubuntu.com/manpages/jammy/man1/dstat.1.html) 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:
+
+```text
+--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
+```
+
+## Managing the database load
+
+Agent metadata can generate a significant write load and overwhelm your Coder
+database if you're not careful. The approximate writes per second can be
+calculated using the formula:
+
+```text
+(metadata_count * num_running_agents * 2) / metadata_avg_interval
+```
+
+For example, let's say you have
+
+- 10 running agents
+- each with 6 metadata snippets
+- with an average interval of 4 seconds
+
+You can expect `(10 * 6 * 2) / 4`, or 30 writes per second.
+
+One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table and the
+other to the `NOTIFY` query that enables live stats streaming in the UI.
+
+## Next Steps
+
+- [Resource metadata](./resource-metadata.md)
+- [Parameters](./parameters.md)
diff --git a/docs/admin/templates/extending-templates/icons.md b/docs/admin/templates/extending-templates/icons.md
@@ -0,0 +1,80 @@
+# Icons
+
+Coder uses icons in several places, including ones that can be configured
+throughout the app, or specified in your Terraform. They're specified by a URL,
+which can be to an image hosted on a CDN of your own, or one of the icons that
+come bundled with your Coder deployment.
+
+- **Template Icons**:
+
+  - Make templates and workspaces visually recognizable with a relevant or
+    memorable icon
+
+- [**Terraform**](https://registry.terraform.io/providers/coder/coder/latest/docs):
+
+  - [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app#icon)
+  - [`coder_parameter`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#icon)
+    and
+    [`option`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#nested-schema-for-option)
+    blocks
+  - [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script#icon)
+  - [`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata#icon)
+
+  These can all be configured to use an icon by setting the `icon` field.
+
+  ```hcl
+  data "coder_parameter" "my_parameter" {
+    icon = "/icon/coder.svg"
+
+    option {
+      icon = "/emojis/1f3f3-fe0f-200d-26a7-fe0f.png"
+    }
+  }
+  ```
+
+- [**Authentication Providers**](https://coder.com/docs/v2/latest/admin/external-auth):
+
+  - Use icons for external authentication providers to make them recognizable.
+    You can set an icon for each provider by setting the
+    `CODER_EXTERNAL_AUTH_X_ICON` environment variable, where `X` is the number
+    of the provider.
+
+    ```env
+    CODER_EXTERNAL_AUTH_0_ICON=/icon/github.svg
+    CODER_EXTERNAL_AUTH_1_ICON=/icon/google.svg
+    ```
+
+- [**Support Links**](../admin/appearance.md#support-links):
+
+  - Use icons for support links to make them recognizable. You can set the
+    `icon` field for each link in `CODER_SUPPORT_LINKS` array.
+
+## Bundled icons
+
+Coder is distributed with a bundle of icons for popular cloud providers and
+programming languages. You can see all of the icons (or suggest new ones) in our
+repository on
+[GitHub](https://github.com/coder/coder/tree/main/site/static/icon).
+
+You can also view the entire list, with search and previews, by navigating to
+/icons on your Coder deployment. E.g. [https://coder.example.com/icons](#). This
+can be particularly useful in airgapped deployments.
+
+![The icon gallery](../images/icons-gallery.png)
+
+## External icons
+
+You can use any image served over HTTPS as an icon, by specifying the full URL
+of the image. We recommend that you use a CDN that you control, but it can be
+served from any source that you trust.
+
+You can also embed an image by using data: URLs.
+
+- Only the https: and data: protocols are supported in icon URLs (not http:)
+
+- Be careful when using images hosted by someone else; they might disappear or
+  change!
+
+- Be careful when using data: URLs. They can get rather large, and can
+  negatively impact loading times for pages and queries they appear in. Only use
+  them for very small icons that compress well.