coder · greyscaled · Mar 31, 2021 · Mar 30, 2021 · mterhar · Mar 31, 2021
diff --git a/admin/templates.md b/admin/templates.md
@@ -0,0 +1,20 @@
+---
+title: Templates
+description:
+  Learn how to create an embeddable "Open In Coder" button for your Workspaces
+  As Code Template
+---
+
+The **Templates** tab features a form you can use for generating an embeddable
+button. This button makes it easy for developers to use your
+[workspace template](../environments/workspaces-as-code/index.md).
+
+To create your button:
+
+1. Go to **Manage** > **Admin** > **Templates**.
+1. Fill out the fields.
+
+Once you've filled out the form, Coder generates a custom Markdown snippet,
+which you can then add to your repository's `README.md`.
+
+![Open In Coder Button](../assets/wac-badge.png)
diff --git a/assets/wac-badge.png b/assets/wac-badge.png
diff --git a/assets/wac-location.png b/assets/wac-location.png
diff --git a/changelog/1.17.2.md b/changelog/1.17.2.md
@@ -0,0 +1,41 @@
+---
+title: "1.17.2"
+description: "Released on 03/30/21"
+---
+
+### Breaking Changes ❗
+
+There are no breaking changes in 1.17.2.
+
+### Features ✨
+
+- Workspaces As Code (**WAC**): Workspaces as code (WAC) brings the
+  _Infrastructure As Code_ paradigm to Coder environments. WAC allows you to
+  define and create new environments using **workspace templates**.
+  - web: New page available via **Admin** > **Templates** for creating an
+    embeddable quickstart button.
+  - web: New options available when clicking **New Environment** from the
+    **Environments** page
+  - web: **workspace template** information is now displayed on the
+    **Environments** page for environments built from a template.
+- web: Added _Cordon_ and _Uncordon_ actions to _Provider_ audit logs
+
+### Bug Fixes 🐛
+
+- infra: Fixes an issue whereby using `coder/configure` to create Dev URLs would
+  fail
+- infra: Fixes an issue authenticating using OpenID Connect Identity Providers
+  (IdPs) that omit name information, such as GitLab. In this case, Coder will
+  use the email address as the user's name.
+- infra: Improved validation for environment names. Previously, a long
+  environment name may have caused build errors.
+- web: The Dev URLs card on the **Environments** page now refreshes after an
+  environment finishes building
+- jetbrains: Fixed an issue whereby Jetbrains IDE processes would start and
+  always run. They now start on request when opening Jetbrains IDEs.
+- web: Improved reliability of the workspace provider ping indicator
+- web: Fixed incorrect timestamps in an image's _Available Tags_ table
+
+### Security Updates 🔐
+
+There are no security updates in 1.17.2.
diff --git a/environments/workspaces-as-code/index.md b/environments/workspaces-as-code/index.md
@@ -0,0 +1,29 @@
+---
+title: "Workspaces as code"
+description: "Learn how to describe environment configuration as code."
+state: beta
+---
+
+Workspaces as code (WAC) brings the _Infrastructure As Code_ paradigm to Coder
+environments. WAC allows you to define and create new environments using
+**workspace templates**.
+
+[Workspace Templates](./templates.md) are declarative YAML files that describe
+how to configure environments and their supporting infrastructure.
+
+## Requirements
+
+- You must configure a [GitHub or GitLab OAuth service](../../admin/git.md)
+- The image you use in your template **must** have been
+  [imported](../../images/importing.md) into Coder
+
+## Creating a workspace template
+
+You can find a fully populated workspace template and descriptions of each field
+in our [syntax guide](templates.md).
+
+## Adding an Embeddable Button
+
+To make it easy for your developers to use your template, you can generate an
+embeddable Markdown button for use in your repo. See the
+[admin guide](../../admin/templates.md) for details.
diff --git a/environments/workspaces-as-code/templates.md b/environments/workspaces-as-code/templates.md
@@ -0,0 +1,206 @@
+---
+title: "Workspace templates"
+description: "Learn how to write a template for creating environments."
+state: beta
+---
+
+Workspaces as code (WAC) allows you to define and create new environments using
+**workspace templates**.
+
+Workspace templates are written as YAML and have a `.yaml` or `.yml` extension.
+Coder looks for your workspace template at the following path:
+
+```text
+<repository-root>/.coder/coder.yaml
+```
+
+![Template Location](../../assets/wac-location.png)
+
+## Workspace template sample
+
+The following is a sample workspace template that makes use of all available
+fields. Depending on your use case, you may not need all of the options
+available.
+
+For detailed information on the fields available, see the
+[subsequent sections](#workspace-template-fields) of this article
+
+```yaml
+version: 0.1
+workspace:
+  type: kubernetes
+  spec:
+    image: index.docker.io/ubuntu:18.04
+    container-based-vm: true
+    cpu: 4
+    memory: 16
+    disk: 128
+    gpuCount: 1
+    labels:
+      com.coder.custom.hello: "hello"
+      com.coder.custom.world: "world"
+    tolerations:
+      - key: my-key
+        operator: Equal
+        value: my-value
+        effect: NoExecute
+        tolerationSeconds: 3600
+  configure:
+    - name: "install curl"
+      run: |
+        apt update
+        apt install -y curl
+    - name: "install Go binary"
+      run: "go install"
+      directory: /home/coder/go/src/github.com/my-project
+      shell: "bash"
+      env:
+        GOPATH: /home/coder/go
+```
+
+## Workspace template fields
+
+### version
+
+The version number of the config file being used. The current version is `0.1`.
+
+### workspace
+
+**Required**. The section containing all configuration information related to
+the environment.
+
+#### workspace.type
+
+**Required**. Determines the type of workspace to be created. Currently, the
+only accepted value is `kubernetes`.
+
+#### workspace.spec
+
+**Required**. This section contains configuration information specific to the
+`workspace.type`.
+
+#### workspace.spec.image
+
+**Required**. The image to use for the environment. The image should include the
+registry and (optionally) the tag, i.e. `docker.io/ubuntu:18.04`. If you omit
+the tag, Coder uses the default value of `latest`.
+
+You must have [imported the image](../../images/importing.md) into Coder,
+otherwise the environment will fail to build.
+
+#### workspace.spec.labels
+
+The
+[Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
+to be added to the environment pod.
+
+```yaml
+workspace:
+  labels:
+    com.coder.custom.hello: hello
+    com.coder.custom.world: world
+```
+
+#### workspace.spec.tolerations
+
+This section defines the
+[Kubernetes tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)
+to be added to the pod hosting the environment.
+
+```yaml
+workspace:
+  tolerations:
+    - key: my-key
+      operator: equals
+      value: my-value
+      effect: NoExecute
+      tolerationSeconds: 3600
+```
+
+#### workspace.spec.gpucount
+
+The number of GPUs to inject into the environment.
+
+#### workspace.spec.container-based-vm
+
+Determines whether the environment should be created as a
+[container-based virtual machine (CVM)](../cvms.md). Default is `false`.
+
+#### workspace.spec.cpu
+
+**Required**. The number of cores to allocate to the environment.
+
+#### workspace.spec.memory
+
+**Required**. The amount of memory (in GB) to allocate to the environment.
+
+#### workspace.spec.disk
+
+**Required**. The amount of disk space (in GB) to allocate to the environment.
+
+#### workspace.configure
+
+This section lists the commands that run within the environment after Coder
+builds the environment. See [Configure](../../images/configure.md) for more
+information.
+
+#### workspace.configure.start
+
+The list of commands to run when Coder _starts_ an environment.
+
+#### workspace.configure.start[*].command
+
+**Required**. Runs the provided command within the environment (Coder supports
+the use of both single-line and multi-line commands).
+
+- Single-line command:
+
+  ```yaml
+  - name: Install curl
+    run: apt install -y curl
+  ```
+
+- Multi-line command:
+
+  ```yaml
+  - name: Update and install curl
+    run: |
+      apt update
+      apt install -y curl
+  ```
+
+#### workspace.configure.start[*].name
+
+The name of the command being run.
+
+#### workspace.configure.start[*].shell
+
+The shell Coder should use to run the command.
+
+```yaml
+start:
+  - name: First step
+    shell: /bin/bash
+```
+
+#### workspace.configure.start[*].directory
+
+The working directory from which Coder should run the command.
+
+```yaml
+start:
+  - name: First step
+    directory: /home/coder
+```
+
+#### workspace.configure.start[*].env
+
+The map of environment variables to set for the command.
+
+```yaml
+start:
+  - name: First step
+    env:
+      HOME: /home/coder
+      GOPATH: /home/coder/go
+```
diff --git a/manifest.json b/manifest.json
@@ -22,7 +22,13 @@
         { "path": "./environments/personalization.md" },
         { "path": "./environments/preferences.md" },
         { "path": "./environments/pwa.md" },
-        { "path": "./environments/ssh.md" }
+        { "path": "./environments/ssh.md" },
+        {
+          "path": "./environments/workspaces-as-code/index.md",
+          "children": [
+            { "path": "./environments/workspaces-as-code/templates.md" }
+          ]
+        }
       ]
     },
     {
@@ -109,7 +115,8 @@
         { "path": "./admin/devurls.md" },
         { "path": "./admin/git.md" },
         { "path": "./admin/metrics.md" },
-        { "path": "./admin/telemetry.md" }
+        { "path": "./admin/telemetry.md" },
+        { "path": "./admin/templates.md" }
       ]
     },
     {
@@ -165,6 +172,7 @@
     {
       "path": "./changelog/index.md",
       "children": [
+        { "path": "./changelog/1.17.2.md" },
         { "path": "./changelog/1.17.1.md" },
         { "path": "./changelog/1.17.0.md" },
         { "path": "./changelog/1.16.3.md" },