add diagram

bpmct · bpmct · commit 7119be113322 · 2023-07-30T02:06:46.000Z
diff --git a/docs/templates/writing/index.md b/docs/templates/writing/index.md
@@ -1,16 +1,18 @@
-# Writing Coder templates
+# Template structure
 
 Coder templates are written in [Terraform](https://terraform.io). All Terraform modules, resources, and properties can be provisioned by Coder. The Coder server essentially runs a `terraform apply` every time a workspace is created/started/stopped.
 
 Haven't written Terraform before? Check out Hashicorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials).
 
-## Key concepts in templates
+## Architecture
 
-There are some key concepts you should consider when writing templates.
+This is a simplified diagram of our [Kubernetes example template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes). Keep reading for a breakdown of each concept.
 
-### Coder Terraform Provider
+![Template architecture](https://user-images.githubusercontent.com/22407953/257021139-8c95a731-c131-4c4d-85cc-eed6a52e015c.png)
 
-The [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest) makes it possible for standard Terraform resources (e.g. `docker_container`) to connect to Coder. Additionally, the provider lets you to customize the behavior of workspaces using your template.
+## Coder Terraform Provider
+
+The [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest) makes it possible for standard Terraform resources (e.g. `kubernetes_deployment`) to connect to Coder. Additionally, the provider lets you to customize the behavior of workspaces using your template.
 
 ```hcl
 terraform {
@@ -22,54 +24,55 @@ terraform {
 }
 ```
 
-### coder_workspace
+## coder_agent
 
-This data source provides details about the state of a workspace, such as its name, owner, and whether the workspace is being started or stopped.
+All templates need to create & run a Coder agent in order for developers to connect to their workspaces. The Coder agent is a service that runs inside the compute aspect of your workspace (typically a VM or container). You do not need to have any open ports, but the compute will need `curl` access to the Coder server.
 
-The following snippet will create a container when the workspace is being started, and delete the container when it is stopped using Terraform's [count](https://developer.hashicorp.com/terraform/language/meta-arguments/count) meta-argument.
+This snippet creates the agent, runs it inside the container via the `entrypoint`, and authenticates to Coder via the agent's token.
 
 ```hcl
-data "coder_workspace" "me" {}
+resource "coder_agent" "main" {
+  os = "linux"
+  arch = "amd64"
+}
 
-# Delete the container when workspace is stopped (count = 0)
-resource "docker_container" "workspace" {
-  count = data.coder_workspace.me.transition == "start" ? 1 : 0
+resource "kubernetes_deployment" "workspace" {
+  entrypoint = ["sh", "-c", coder_agent.main.init_script]
+  env        = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"]
   # ...
 }
-
-# Persist the volume, even if stopped
-resource "docker_volume" "projects" {}
 ```
 
-### coder_agent
+Agents can also run startup scripts, set environment variables, and provide [metadata](../agent-metadata.md) about the workspace (e.g. CPU usage). Read the [coder_agent docs](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) for more details.
 
-All templates need to create & run a Coder agent in order for developers to connect to their workspaces. The Coder agent is a service that runs inside the compute aspect of your workspace (typically a VM or container).
+## coder_workspace
 
-This snippet creates the agent, runs it inside the container via the `entrypoint`, and authenticates to Coder via the agent's token.
+This data source provides details about the state of a workspace, such as its name, owner, and whether the workspace is being started or stopped.
+
+The following snippet will create a container when the workspace is being started, and delete the container when it is stopped using Terraform's [count](https://developer.hashicorp.com/terraform/language/meta-arguments/count) meta-argument.
 
 ```hcl
-resource "coder_agent" "main" {
-  os = "linux"
-  arch = "amd64"
-}
+data "coder_workspace" "me" {}
 
-resource "docker_container" "workspace" {
-  entrypoint = ["sh", "-c", coder_agent.main.init_script]
-  env        = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"]
+# Delete the container when workspace is stopped (count = 0)
+resource "kubernetes_deployment" "workspace" {
+  count = data.coder_workspace.me.transition == "start" ? 1 : 0
   # ...
 }
-```
 
-Agents can also run startup scripts, set environment variables, and provide metadata about the workspace (e.g. CPU usage). Read the [coder_agent docs](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) for more details.
+# Persist the volume, even if stopped
+resource "docker_volume" "projects" {}
+```
 
-### coder_app
+## coder_app
 
-Web apps that are running inside the workspace (e.g. `http://localhost:8080`) can be forwarded to the Coder dashboard with the `coder_app` resource. This is commonly used for [web IDEs](../ides/web-ides.md) such as code-server, RStudio, and JupyterLab. External apps, such as links to internal wikis or cloud consoles can also be embedded here.
+Web apps that are running inside the workspace (e.g. `http://localhost:8080`) can be forwarded to the Coder dashboard with the `coder_app` resource. This is commonly used for [web IDEs](../../ides/web-ides.md) such as code-server, RStudio, and JupyterLab. External apps, such as links to internal wikis or cloud consoles can also be embedded here.
 
 Apps are rendered on the workspace page:
 
-![]()
+![Apps in Coder workspace](https://user-images.githubusercontent.com/22407953/257020191-97a19ff0-83ca-4275-a699-113f6c97a9ab.png)
 
+The apps themselves have to be installed & running on the workspace. This can be done via the agent's startup script. See [web IDEs](../ides/web-ides.md) for some examples.
 
 ```hcl
 # coder_agent will install and start code-server
@@ -83,18 +86,22 @@ resource "coder_agent" "main" {
 
 # expose code-server on workspace via a coder_app
 resource "coder_app" "code-server" {
-  icon = "/icon/code.svg"
-  name = "code-server"
-  slug = "code"
-  url = "http://localhost:8080"
+  agent_id     = coder_agent.main.id
+  icon         = "/icon/code.svg"
+  display_name = "code-server"
+  slug         = "code"
+  url          = "http://localhost:8080"
 }
 
 # link to an external site
 resource "coder_app" "getting-started" {
-  icon     = "/icon/help.svg"
-  name     = "getting-started"
-  slug     = "getting-started"
-  url      = "https://wiki.example.com/coder/quickstart"
-  external = true
+  agent_id     = coder_agent.main.id
+  icon         = "/emojis/1f4dd.png"
+  display_name = "getting-started"
+  slug         = "getting-started"
+  url          = "https://wiki.example.com/coder/quickstart"
+  external     = true
 }
 ```
+
+Lorem ipsum
