Oct 17, 2023 · Jul 28, 2023 · Jul 28, 2023 · Jul 28, 2023 · Jul 30, 2023 · Jul 31, 2023
diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md
 #Provisioners
 #External provisioners

 By default, the Coder server runs
 [built-in provisioner daemons](../cli/server.md#provisioner-daemons), which
diff --git a/docs/images/autostart.png b/docs/images/autostart.png
diff --git a/docs/images/autostop.png b/docs/images/autostop.png
diff --git a/docs/images/creating-workspace-ui.png b/docs/images/creating-workspace-ui.png
diff --git a/docs/images/schedule.png b/docs/images/schedule.png
diff --git a/docs/images/template-variables.png b/docs/images/template-variables.png
diff --git a/docs/images/templates/build-template.png b/docs/images/templates/build-template.png
diff --git a/docs/images/templates/choosing-edit-template.gif b/docs/images/templates/choosing-edit-template.gif
diff --git a/docs/images/templates/coder-login-web.png b/docs/images/templates/coder-login-web.png
diff --git a/docs/images/templates/coder-session-token.png b/docs/images/templates/coder-session-token.png
diff --git a/docs/images/templates/create-template.png b/docs/images/templates/create-template.png
diff --git a/docs/images/templates/create-workspace.png b/docs/images/templates/create-workspace.png
diff --git a/docs/images/templates/develop-in-docker-template.png b/docs/images/templates/develop-in-docker-template.png
diff --git a/docs/images/templates/edit-files.png b/docs/images/templates/edit-files.png
diff --git a/docs/images/templates/edit-source-code.png b/docs/images/templates/edit-source-code.png
diff --git a/docs/images/templates/new-workspace.png b/docs/images/templates/new-workspace.png
diff --git a/docs/images/templates/publish.png b/docs/images/templates/publish.png
diff --git a/docs/images/templates/select-template.png b/docs/images/templates/select-template.png
diff --git a/docs/images/templates/source-code.png b/docs/images/templates/source-code.png
diff --git a/docs/images/templates/starter-templates-button.png b/docs/images/templates/starter-templates-button.png
diff --git a/docs/images/templates/starter-templates.png b/docs/images/templates/starter-templates.png
diff --git a/docs/images/templates/template-architecture.png b/docs/images/templates/template-architecture.png
diff --git a/docs/images/templates/template-tour.png b/docs/images/templates/template-tour.png
diff --git a/docs/images/templates/template-variables.png b/docs/images/templates/template-variables.png
diff --git a/docs/images/templates/update.png b/docs/images/templates/update.png
diff --git a/docs/images/templates/use-template.png b/docs/images/templates/use-template.png
diff --git a/docs/images/templates/workspace-apps.png b/docs/images/templates/workspace-apps.png
diff --git a/docs/images/templates/workspace-ready.png b/docs/images/templates/workspace-ready.png
diff --git a/docs/images/workspace-update.png b/docs/images/workspace-update.png
diff --git a/docs/manifest.json b/docs/manifest.json
    },
    {
      "title": "Templates",
      "description": "Learn about templates, whichdefine the infrastructureunderlying workspaces",
      "description": "Templatesdefine the infrastructurefor workspaces",
      "path": "./templates/index.md",
      "icon_path": "./images/icons/picture.svg",
      "children": [
        {
          "title": "Resource Persistence",
          "description": "Learn how resource persistence works in Coder",
          "path": "./templates/resource-persistence.md",
          "icon_path": "./images/icons/infinity.svg"
          "title": "Working with templates",
          "description": "Creating, editing, and updating templates",
          "path": "./templates/creating.md"
        },
        {
          "title": "Provider Authentication",
          "description": "Learn how to authenticate the provisioner",
          "path": "./templates/authentication.md",
          "icon_path": "./images/icons/key.svg"
        },
        {
          "title": "Change Management",
          "description": "Learn how to source-control templates with git and CI",
          "path": "./templates/change-management.md",
          "icon_path": "./images/icons/git.svg"
          "title": "Your first template",
          "description": "A tutorial for creating and editing your first template",
          "path": "./templates/tutorial.md"
        },
        {
          "title": "Resource Metadata",
          "description": "Learn how to expose resource data to users",
          "path": "./templates/resource-metadata.md",
          "icon_path": "./images/icons/table-rows.svg"
          "title": "Guided tour",
          "description": "Create a template from scratch",
          "path": "./templates/tour.md"
        },
        {
          "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"
          "title": "Setting up templates",
          "description": "Best practices for writing templates",
          "path": "./templates/best-practices.md",
          "children": [
            {
              "title": "Change management",
              "description": "Versioning templates with git and CI",
              "path": "./templates/change-management.md",
              "icon_path": "./images/icons/git.svg"
            },
            {
              "title": "Provider authentication",
              "description": "Authenticate the provisioner",
              "path": "./templates/authentication.md",
              "icon_path": "./images/icons/key.svg"
            },
            {
              "title": "Resource persistence",
              "description": "How resource persistence works in Coder",
              "path": "./templates/resource-persistence.md",
              "icon_path": "./images/icons/infinity.svg"
            },
            {
              "title": "Terraform modules",
              "description": "Reuse code across Coder templates",
              "path": "./templates/modules.md"
            }
          ]
        },
        {
          "title": "Parameters",
          "description": "Use parameters to customize templates",
          "path": "./templates/parameters.md",
          "icon_path": "./images/icons/code.svg"
          "title": "Customizing templates",
          "description": "Give information and options to workspace users",
          "path": "./templates/customizing.md",
          "children": [
            {
              "title": "Agent metadata",
              "description": "Show operational metrics in the workspace",
              "path": "./templates/agent-metadata.md"
            },
            {
              "title": "Resource metadata",
              "description": "Show information in the workspace about template resources",
              "path": "./templates/resource-metadata.md"
            },
            {
              "title": "Parameters",
              "description": "Prompt the user for additional information about a workspace",
              "path": "./templates/parameters.md"
            }
          ]
        },
        {
          "title": "Open in Coder",
          "description": "Learn how to add an \"Open in Coder\" button to your repos",
          "description": "Add an \"Open in Coder\" button to your repos",
          "path": "./templates/open-in-coder.md",
          "icon_path": "./images/icons/key.svg"
        },
        {
          "title": "Docker inWorkspaces",
          "description": "Usedocker inside containerized templates",
          "title": "Docker inworkspaces",
          "description": "UseDocker inside containerized templates",
          "path": "./templates/docker-in-workspaces.md",
          "icon_path": "./images/icons/docker.svg"
        },
          "state": "alpha"
        },
        {
          "title": "Terraform Modules",
          "description": "Reuse code across Coder templates",
          "path": "./templates/modules.md"
          "title": "Troubleshooting templates",
          "description": "Fix common template problems",
          "path": "./templates/troubleshooting.md"
        },
        {
          "title": "Process Logging",
          "icon_path": "./images/icons/scale.svg"
        },
        {
          "title": "Provisioners",
          "title": "ExternalProvisioners",
          "description": "Run provisioners isolated from the Coder server",
          "path": "./admin/provisioners.md",
          "icon_path": "./images/icons/queue.svg",
diff --git a/docs/platforms/jfrog.md b/docs/platforms/jfrog.md
 developers or stored in workspaces.
 </blockquote>

 <blockquote class="info">
 You can skip the whole page and use [JFrog module](https://registry.coder.com/modules/jfrog) for easy JFrog Artifactory integration.
 </blockquote>

 ## Provisioner Authentication

 The most straight-forward way to authenticate your template with Artifactory is
diff --git a/docs/templates/agent-metadata.md b/docs/templates/agent-metadata.md
 # AgentMetadata
 # Agentmetadata

 ![agent-metadata](../images/agent-metadata.png)

 With Agent Metadata, template admins can expose operational metrics from their
 workspaces to their users. It is the dynamic complement of
 [Resource Metadata](./resource-metadata.md).
 You can show live operational metrics to workspace users with agent metadata. It
 is the dynamic complement of [resource metadata](./resource-metadata.md).

 See the
 [Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
 You specify agent metadata in the
 [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).

 ## Examples

 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 below examples use the [`coder stat`](../cli/stat.md) command. This
 is useful for determining CPU/memory usage inside a container, which can be
 tricky otherwise.
 Some of the examples use the [`coder stat`](../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:

 }
 ```

 ##Utilities
 ##Useful utilities

 [top](https://linux.die.net/man/1/top) is available in most Linux distributions
 and provides virtual memory, CPU and IO statistics. Running `top` produces
 output that looks like:
 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://linux.die.net/man/8/vmstat) is available in most Linux
 distributions and provides virtual memory, CPU and IO statistics. Running
 `vmstat` produces output that looks like:
 [vmstat](https://manpages.ubuntu.com/manpages/jammy/en/man8/vmstat.8.html) is
 available in most Linuxdistributions 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://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:
 [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 mostpackage managers under the name `dstat`. The
 output of running `dstat 1 1` lookslike:

 ```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
 ```

 ##DB Write Load
 ##Managing the database load

 Agent metadata can generate a significant write load and overwhelm yourdatabase
 if you're not careful. The approximate writes per second can be calculated using
 the following formula (applied once for each unique metadata interval):
 Agent metadata can generate a significant write load and overwhelm yourCoder
 databaseif you're not careful. The approximate writes per second can be
 calculated using the formula:

 ```text
 num_running_agents *write_multiplier /metadata_interval
 (metadata_count *num_running_agents *2) /metadata_avg_interval
 ```

 For example, let's say you have:
 For example, let's say you have

 - 10 running agents
 - each with 4 metadata snippets
 - where two have an interval of 4 seconds, and the other two 6 seconds
 - 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.

 You can expect at most `(10 * 2 / 4) + (10 * 2 / 6)` or ~8 writes per second.
 The actual writes per second may be a bit lower due to batching of metadata.
 Adding more metadata with the same interval will not increase writes per second,
 but it may still increase database load slightly.
 ## Next Steps

 We use a `write_multiplier` of `2` because each metadata write generates two
 writes. 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.
 - [Resource metadata](./resource-metadata.md)
 - [Parameters](./parameters.md)
diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md
  </p>
 </blockquote>

 Coder's provisioner process needs to authenticate with cloud provider APIs to
 provision workspaces. You can either pass credentials to theprovisioner as
 parameters or execute Coder in an environment that is authenticated with the
 cloud provider.
 TheCoder server's
 [provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner)
 process needs to authenticate with other provider APIs to provision workspaces.
 There are two approaches to do this:

 We encourage the latter where supported. This approach simplifies the template,
 keeps cloud provider credentials out of Coder's database (making it a less
 valuable target for attackers), and is compatible with agent-based
 authentication schemes (that handle credential rotation and/or ensure the
 credentials are not written to disk).
 - Pass credentials to the provisioner as parameters.
 - Preferred: Execute the Coder server in an environment that is authenticated
  with the provider.

 Cloud providers for which the Terraform provider supports authenticated
 environments include
 We encourage the latter approach where supported:

 - Simplifies the template.
 - Keeps provider credentials out of Coder's database, making it a less valuable
  target for attackers.
 - Compatible with agent-based authentication schemes, which handle credential
  rotation or ensure the credentials are not written to disk.

 Generally, you can set up an environment to provide credentials to Coder in
 these ways:

 - A well-known location on disk. For example, `~/.aws/credentials` for AWS on
  POSIX systems.
 - Environment variables.

 It is usually sufficient to authenticate using the CLI or SDK for the provider
 before running Coder, but check the Terraform provider's documentation for
 details.

 These platforms have Terraform providers that support authenticated
 environments:

 - [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
 - [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
 - [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
 - [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)

 Additional providersmay be supported; check the
 Other providersmight also support authenticated environments. Check the
 [documentation of the Terraform provider](https://registry.terraform.io/browse/providers)
 for details.

 The way these generally work is via the credentials being available to Coder
 either in some well-known location on disk (e.g. `~/.aws/credentials` for AWS on
 posix systems), or via environment variables. It is usually sufficient to
 authenticate using the CLI or SDK for the cloud provider before running Coder
 for this to work, but check the Terraform provider documentation for details.
diff --git a/docs/templates/best-practices.md b/docs/templates/best-practices.md
 # Template best practices

 We recommend a few ways to manage workspace resources, authentication, and
 versioning.

 <children>
 </children>
diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md
 # Template Change Management

 We recommend sourcecontrolling your templates as you would other code.
 [Install Coder](../install/) in CI/CD pipelines to push new template versions.
 We recommend source-controlling your templates as you would other code. You can
 [install Coder](../install/) in CI/CD pipelines to push new template versions.

 ```console
 # Install the Coder CLI
 export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD)

 # Push the new template version to Coder
 coder login --url $CODER_URL --token $CODER_SESSION_TOKEN
 coder templates push --yes $CODER_TEMPLATE_NAME \
    --directory $CODER_TEMPLATE_DIR \
    --name=$CODER_TEMPLATE_VERSION # Version name is optional
 ```

 > Looking for an example? See how we push our development image and template
 > [via GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).

 > To cap token lifetime on creation,
 > [configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime)
 To cap token lifetime on creation,
 [configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime).
 For an example, see how we push our development image and template
 [with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,4 @@
		#Provisioners
		#External provisioners

		By default, the Coder server runs
		[built-in provisioner daemons](../cli/server.md#provisioner-daemons), which
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -139,55 +139,86 @@
		},
		{
		"title": "Templates",
		"description": "Learn about templates, whichdefine the infrastructureunderlying workspaces",
		"description": "Templatesdefine the infrastructurefor workspaces",
		"path": "./templates/index.md",
		"icon_path": "./images/icons/picture.svg",
		"children": [
		{
		"title": "Resource Persistence",
		"description": "Learn how resource persistence works in Coder",
		"path": "./templates/resource-persistence.md",
		"icon_path": "./images/icons/infinity.svg"
		"title": "Working with templates",
		"description": "Creating, editing, and updating templates",
		"path": "./templates/creating.md"
		},
		{
		"title": "Provider Authentication",
		"description": "Learn how to authenticate the provisioner",
		"path": "./templates/authentication.md",
		"icon_path": "./images/icons/key.svg"
		},
		{
		"title": "Change Management",
		"description": "Learn how to source-control templates with git and CI",
		"path": "./templates/change-management.md",
		"icon_path": "./images/icons/git.svg"
		"title": "Your first template",
		"description": "A tutorial for creating and editing your first template",
		"path": "./templates/tutorial.md"
		},
		{
		"title": "Resource Metadata",
		"description": "Learn how to expose resource data to users",
		"path": "./templates/resource-metadata.md",
		"icon_path": "./images/icons/table-rows.svg"
		"title": "Guided tour",
		"description": "Create a template from scratch",
		"path": "./templates/tour.md"
		},
		{
		"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"
		"title": "Setting up templates",
		"description": "Best practices for writing templates",
		"path": "./templates/best-practices.md",
		"children": [
		{
		"title": "Change management",
		"description": "Versioning templates with git and CI",
		"path": "./templates/change-management.md",
		"icon_path": "./images/icons/git.svg"
		},
		{
		"title": "Provider authentication",
		"description": "Authenticate the provisioner",
		"path": "./templates/authentication.md",
		"icon_path": "./images/icons/key.svg"
		},
		{
		"title": "Resource persistence",
		"description": "How resource persistence works in Coder",
		"path": "./templates/resource-persistence.md",
		"icon_path": "./images/icons/infinity.svg"
		},
		{
		"title": "Terraform modules",
		"description": "Reuse code across Coder templates",
		"path": "./templates/modules.md"
		}
		]
		},
		{
		"title": "Parameters",
		"description": "Use parameters to customize templates",
		"path": "./templates/parameters.md",
		"icon_path": "./images/icons/code.svg"
		"title": "Customizing templates",
		"description": "Give information and options to workspace users",
		"path": "./templates/customizing.md",
		"children": [
		{
		"title": "Agent metadata",
		"description": "Show operational metrics in the workspace",
		"path": "./templates/agent-metadata.md"
		},
		{
		"title": "Resource metadata",
		"description": "Show information in the workspace about template resources",
		"path": "./templates/resource-metadata.md"
		},
		{
		"title": "Parameters",
		"description": "Prompt the user for additional information about a workspace",
		"path": "./templates/parameters.md"
		}
		]
		},
		{
		"title": "Open in Coder",
		"description": "Learn how to add an \"Open in Coder\" button to your repos",
		"description": "Add an \"Open in Coder\" button to your repos",
		"path": "./templates/open-in-coder.md",
		"icon_path": "./images/icons/key.svg"
		},
		{
		"title": "Docker inWorkspaces",
		"description": "Usedocker inside containerized templates",
		"title": "Docker inworkspaces",
		"description": "UseDocker inside containerized templates",
		"path": "./templates/docker-in-workspaces.md",
		"icon_path": "./images/icons/docker.svg"
		},
Expand All		@@ -198,9 +229,9 @@
		"state": "alpha"
		},
		{
		"title": "Terraform Modules",
		"description": "Reuse code across Coder templates",
		"path": "./templates/modules.md"
		"title": "Troubleshooting templates",
		"description": "Fix common template problems",
		"path": "./templates/troubleshooting.md"
		},
		{
		"title": "Process Logging",
Expand DownExpand Up		@@ -337,7 +368,7 @@
		"icon_path": "./images/icons/scale.svg"
		},
		{
		"title": "Provisioners",
		"title": "ExternalProvisioners",
		"description": "Run provisioners isolated from the Coder server",
		"path": "./admin/provisioners.md",
		"icon_path": "./images/icons/queue.svg",
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,6 +24,10 @@ The admin-level access token is used to provision user tokens and is never expos
		developers or stored in workspaces.
		</blockquote>

		<blockquote class="info">
		You can skip the whole page and use [JFrog module](https://registry.coder.com/modules/jfrog) for easy JFrog Artifactory integration.
		</blockquote>

		## Provisioner Authentication

		The most straight-forward way to authenticate your template with Artifactory is
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,13 +1,12 @@
		# AgentMetadata
		# Agentmetadata

		![agent-metadata](../images/agent-metadata.png)

		With Agent Metadata, template admins can expose operational metrics from their
		workspaces to their users. It is the dynamic complement of
		[Resource Metadata](./resource-metadata.md).
matifali marked this conversation as resolved. Show resolvedHide resolved
		You can show live operational metrics to workspace users with agent metadata. It
		is the dynamic complement of [resource metadata](./resource-metadata.md).

		See the
		[Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
		You specify agent metadata in the
		[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).

		## Examples

Expand All		@@ -16,9 +15,10 @@ All of these examples use
		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 below examples use the [`coder stat`](../cli/stat.md) command. This
		is useful for determining CPU/memory usage inside a container, which can be
		tricky otherwise.
		Some of the examples use the [`coder stat`](../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:

Expand DownExpand Up		@@ -86,60 +86,63 @@ resource "coder_agent" "main" {
		}
		```

		##Utilities
		##Useful utilities

		[top](https://linux.die.net/man/1/top) is available in most Linux distributions
		and provides virtual memory, CPU and IO statistics. Running `top` produces
		output that looks like:
		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://linux.die.net/man/8/vmstat) is available in most Linux
		distributions and provides virtual memory, CPU and IO statistics. Running
		`vmstat` produces output that looks like:
		[vmstat](https://manpages.ubuntu.com/manpages/jammy/en/man8/vmstat.8.html) is
		available in most Linuxdistributions 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://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:
		[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 mostpackage managers under the name `dstat`. The
		output of running `dstat 1 1` lookslike:

		```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
		```

		##DB Write Load
		##Managing the database load

		Agent metadata can generate a significant write load and overwhelm yourdatabase
		if you're not careful. The approximate writes per second can be calculated using
		the following formula (applied once for each unique metadata interval):
		Agent metadata can generate a significant write load and overwhelm yourCoder
		databaseif you're not careful. The approximate writes per second can be
		calculated using the formula:

		```text
		num_running_agents *write_multiplier /metadata_interval
		(metadata_count num_running_agents 2) /metadata_avg_interval
		```

		For example, let's say you have:
		For example, let's say you have

		- 10 running agents
		- each with 4 metadata snippets
		- where two have an interval of 4 seconds, and the other two 6 seconds
		- 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.

		You can expect at most `(10 * 2 / 4) + (10 * 2 / 6)` or ~8 writes per second.
		The actual writes per second may be a bit lower due to batching of metadata.
		Adding more metadata with the same interval will not increase writes per second,
		but it may still increase database load slightly.
		## Next Steps

		We use a `write_multiplier` of `2` because each metadata write generates two
		writes. 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.
		- [Resource metadata](./resource-metadata.md)
		- [Parameters](./parameters.md)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,31 +7,42 @@
		</p>
		</blockquote>

		Coder's provisioner process needs to authenticate with cloud provider APIs to
		provision workspaces. You can either pass credentials to theprovisioner as
		parameters or execute Coder in an environment that is authenticated with the
		cloud provider.
		TheCoder server's
		[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner)
		process needs to authenticate with other provider APIs to provision workspaces.
		There are two approaches to do this:

		We encourage the latter where supported. This approach simplifies the template,
		keeps cloud provider credentials out of Coder's database (making it a less
		valuable target for attackers), and is compatible with agent-based
		authentication schemes (that handle credential rotation and/or ensure the
		credentials are not written to disk).
		- Pass credentials to the provisioner as parameters.
		- Preferred: Execute the Coder server in an environment that is authenticated
		with the provider.

		Cloud providers for which the Terraform provider supports authenticated
		environments include
		We encourage the latter approach where supported:

		- Simplifies the template.
		- Keeps provider credentials out of Coder's database, making it a less valuable
		target for attackers.
		- Compatible with agent-based authentication schemes, which handle credential
		rotation or ensure the credentials are not written to disk.

		Generally, you can set up an environment to provide credentials to Coder in
		these ways:

		- A well-known location on disk. For example, `~/.aws/credentials` for AWS on
		POSIX systems.
		- Environment variables.

		It is usually sufficient to authenticate using the CLI or SDK for the provider
		before running Coder, but check the Terraform provider's documentation for
		details.

		These platforms have Terraform providers that support authenticated
		environments:

		- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
		- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
		- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
		- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)

		Additional providersmay be supported; check the
		Other providersmight also support authenticated environments. Check the
		[documentation of the Terraform provider](https://registry.terraform.io/browse/providers)
		for details.

		The way these generally work is via the credentials being available to Coder
		either in some well-known location on disk (e.g. `~/.aws/credentials` for AWS on
		posix systems), or via environment variables. It is usually sufficient to
		authenticate using the CLI or SDK for the cloud provider before running Coder
		for this to work, but check the Terraform provider documentation for details.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,7 @@
		# Template best practices

		We recommend a few ways to manage workspace resources, authentication, and
		versioning.

		<children>
		</children>
Original file line number	Diff line number	Diff line change
		@@ -1,7 +1,7 @@
		# Template Change Management

		We recommend sourcecontrolling your templates as you would other code.
		[Install Coder](../install/) in CI/CD pipelines to push new template versions.
		We recommend source-controlling your templates as you would other code. You can
		[install Coder](../install/) in CI/CD pipelines to push new template versions.

		```console
		# Install the Coder CLI
Expand All		@@ -21,14 +21,12 @@ export CODER_TEMPLATE_DIR=.coder/templates/kubernetes
		export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD)

		# Push the new template version to Coder
		coder login --url $CODER_URL --token $CODER_SESSION_TOKEN
		coder templates push --yes $CODER_TEMPLATE_NAME \
		--directory $CODER_TEMPLATE_DIR \
		--name=$CODER_TEMPLATE_VERSION # Version name is optional
		```

		> Looking for an example? See how we push our development image and template
		> [via GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).

		> To cap token lifetime on creation,
		> [configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime)
		To cap token lifetime on creation,
		[configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime).
		For an example, see how we push our development image and template
		[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).