Oct 16, 2023 · Aug 16, 2023 · Aug 17, 2023 · Aug 17, 2023 · Aug 21, 2023 · Aug 22, 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 execute `terraform` during workspace and template builds. However, there are sometimes benefits to running external provisioner daemons:

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": "Templates & Terraform",
          "description": "Learn what makes up a template",
          "path": "./templates/concepts.md",
          "title": "Working with templates",
          "description": "Creating, editing, and updating templates",
          "path": "./templates/creating.md"
        },
        {
          "title": "Your first template",
          "description": "A tutorial for creating and editing your first template",
          "path": "./templates/tutorial.md"
        },
        {
          "title": "Guided tour",
          "description": "Create a template from scratch",
          "path": "./templates/tour.md"
        },
        {
          "title": "Setting up templates",
          "description": "Best practices for writing templates",
          "path": "./templates/best-practices.md",
          "children": [
            {
              "title": "Parameters",
              "description": "Use parameters to customize templates",
              "path": "./templates/parameters.md",
              "icon_path": "./images/icons/code.svg"
              "title": "Change management",
              "description": "Versioning templates with git and CI",
              "path": "./templates/change-management.md",
              "icon_path": "./images/icons/git.svg"
            },
            {
              "title": "Terraform Modules",
              "description": "Reuse code across Coder templates",
              "path": "./templates/modules.md"
              "title": "Provider authentication",
              "description": "Authenticate the provisioner",
              "path": "./templates/authentication.md",
              "icon_path": "./images/icons/key.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"
              "title": "Resource persistence",
              "description": "How resource persistence works in Coder",
              "path": "./templates/resource-persistence.md",
              "icon_path": "./images/icons/infinity.svg"
            },
            {
              "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": "Terraform modules",
              "description": "Reuse code across Coder templates",
              "path": "./templates/modules.md"
            }
          ]
        },
        {
          "title": "Best Practices",
          "description": "Best practices for writing/managing templates",
          "path": "./templates/best-practices.md",
          "title": "Customizing templates",
          "description": "Give information and options to workspace users",
          "path": "./templates/customizing.md",
          "children": [
            {
              "title": "Provider Authentication",
              "description": "Learn how to authenticate the provisioner",
              "path": "./templates/authentication.md",
              "icon_path": "./images/icons/key.svg"
              "title": "Agent metadata",
              "description": "Show operational metrics in the workspace",
              "path": "./templates/agent-metadata.md"
            },
            {
              "title": "Resource Persistence",
              "description": "Learn how resource persistence works in Coder",
              "path": "./templates/resource-persistence.md",
              "icon_path": "./images/icons/infinity.svg"
              "title": "Resource metadata",
              "description": "Show information in the workspace about template resources",
              "path": "./templates/resource-metadata.md"
            },
            {
              "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": "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"
        },
          "description": "Use devcontainers in workspaces",
          "path": "./templates/devcontainers.md",
          "state": "alpha"
        },
        {
          "title": "Troubleshooting templates",
          "description": "Fix common template problems",
          "path": "./templates/troubleshooting.md"
        }
      ]
    },
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

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

 You can also show agent metadata for information about the workspace's host.

 [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:
 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://linux.die.net/man/8/vmstat) 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://linux.die.net/man/1/dstat) is considerably more
 parseablethan `vmstat` but often not included in base images. It is
 easily installed bymost package 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 your
 database if you're not careful. The approximate writes per second can be
 calculated using the formula:
 Agent metadata can generate a significant write load and overwhelm
 your Coderdatabase if you're not careful. The approximate writes per
 second can becalculated using the formula:

 ```text
 (metadata_count * num_running_agents * 2) / metadata_avg_interval
 - each with 6 metadata snippets
 - with an average interval of 4 seconds

 You can expect `(10 * 6 * 2) / 4` or 30 writes per second.
 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.
 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.
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 the provisioner as parameters or execute Coder
 in an environment that is authenticated with the cloud provider.
 The Coder 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 providers may be supported; 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.
 Other providers might also support authenticated environments. Check
 the [documentation of the Terraform
 provider](https://registry.terraform.io/browse/providers) for details.
diff --git a/docs/templates/best-practices.md b/docs/templates/best-practices.md
 # Template best practices

 Templates are very flexible
 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 source controlling 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
    --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 execute `terraform` during workspace and template builds. However, there are sometimes benefits to running external provisioner daemons:

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -134,75 +134,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": "Templates & Terraform",
		"description": "Learn what makes up a template",
		"path": "./templates/concepts.md",
		"title": "Working with templates",
		"description": "Creating, editing, and updating templates",
		"path": "./templates/creating.md"
		},
		{
		"title": "Your first template",
		"description": "A tutorial for creating and editing your first template",
		"path": "./templates/tutorial.md"
		},
		{
		"title": "Guided tour",
		"description": "Create a template from scratch",
		"path": "./templates/tour.md"
		},
		{
		"title": "Setting up templates",
		"description": "Best practices for writing templates",
		"path": "./templates/best-practices.md",
		"children": [
		{
		"title": "Parameters",
		"description": "Use parameters to customize templates",
		"path": "./templates/parameters.md",
		"icon_path": "./images/icons/code.svg"
		"title": "Change management",
		"description": "Versioning templates with git and CI",
		"path": "./templates/change-management.md",
		"icon_path": "./images/icons/git.svg"
		},
		{
		"title": "Terraform Modules",
		"description": "Reuse code across Coder templates",
		"path": "./templates/modules.md"
		"title": "Provider authentication",
		"description": "Authenticate the provisioner",
		"path": "./templates/authentication.md",
		"icon_path": "./images/icons/key.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"
		"title": "Resource persistence",
		"description": "How resource persistence works in Coder",
		"path": "./templates/resource-persistence.md",
		"icon_path": "./images/icons/infinity.svg"
		},
		{
		"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": "Terraform modules",
		"description": "Reuse code across Coder templates",
		"path": "./templates/modules.md"
		}
		]
		},
		{
		"title": "Best Practices",
		"description": "Best practices for writing/managing templates",
		"path": "./templates/best-practices.md",
		"title": "Customizing templates",
		"description": "Give information and options to workspace users",
		"path": "./templates/customizing.md",
		"children": [
		{
		"title": "Provider Authentication",
		"description": "Learn how to authenticate the provisioner",
		"path": "./templates/authentication.md",
		"icon_path": "./images/icons/key.svg"
		"title": "Agent metadata",
		"description": "Show operational metrics in the workspace",
		"path": "./templates/agent-metadata.md"
		},
		{
		"title": "Resource Persistence",
		"description": "Learn how resource persistence works in Coder",
		"path": "./templates/resource-persistence.md",
		"icon_path": "./images/icons/infinity.svg"
		"title": "Resource metadata",
		"description": "Show information in the workspace about template resources",
		"path": "./templates/resource-metadata.md"
		},
		{
		"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": "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		@@ -211,6 +222,11 @@
		"description": "Use devcontainers in workspaces",
		"path": "./templates/devcontainers.md",
		"state": "alpha"
		},
		{
		"title": "Troubleshooting templates",
		"description": "Fix common template problems",
		"path": "./templates/troubleshooting.md"
		}
		]
		},
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,20 +1,26 @@
		# 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

		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.
		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 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		@@ -82,44 +88,46 @@ resource "coder_agent" "main" {
		}
		```

		## Utilities
		## Useful utilities

		You can also show agent metadata for information about the workspace's host.

		[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:
		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://linux.die.net/man/8/vmstat) 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://linux.die.net/man/1/dstat) is considerably more
		parseablethan `vmstat` but often not included in base images. It is
		easily installed bymost package 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 your
		database if you're not careful. The approximate writes per second can be
		calculated using the formula:
		Agent metadata can generate a significant write load and overwhelm
		your Coderdatabase if you're not careful. The approximate writes per
		second can becalculated using the formula:

		```text
		(metadata_count * num_running_agents * 2) / metadata_avg_interval
Expand All		@@ -131,7 +139,8 @@ For example, let's say you have
		- each with 6 metadata snippets
		- with an average interval of 4 seconds

		You can expect `(10 * 6 * 2) / 4` or 30 writes per second.
		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.
		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.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,28 +7,42 @@
		</p>
		</blockquote>

		Coder's provisioner process needs to authenticate with cloud provider APIs to provision
		workspaces. You can either pass credentials to the provisioner as parameters or execute Coder
		in an environment that is authenticated with the cloud provider.
		The Coder 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 providers may be supported; 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.
		Other providers might also support authenticated environments. Check
		the [documentation of the Terraform
		provider](https://registry.terraform.io/browse/providers) for details.
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1,7 @@
		# Template best practices

		Templates are very flexible
		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,6 +1,8 @@
		# Template Change Management

		We recommend source controlling 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
matifali marked this conversation as resolved. Show resolvedHide resolved
		template versions.

		```console
		# Install the Coder CLI
Expand All		@@ -25,7 +27,7 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
		--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).