As of Coder version 1.19, only workspace templates version 0.2 is supported. To update your workspace, you must update your templates to version 0.2.
Workspaces as code (WAC) allows you to define and create new workspaces using workspace templates.
Workspace templates are written in YAML and have a
For assistance with creating your Coder YAML file, you can use the template
Coder looks for your workspace template at the following path:
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.
Note that the fields are case-sensitive.
For detailed information on the fields available, see the subsequent sections of this article.
version: 0.2 workspace: # Type indicates the provider type to use when building the workspace. # It corresponds to the `kubernetes` section under `specs`. type: kubernetes specs: kubernetes: image: value: index.docker.io/ubuntu:18.04 container-based-vm: value: true cpu: value: 4 memory: value: 16 disk: value: 128 gpu-count: value: 1 labels: value: com.coder.custom.hello: "hello" com.coder.custom.world: "world" annotations: value: - key: annotation-key value: annotation-value configure: start: value: - name: "install curl" command: | apt update apt install -y curl - name: "Create organization directory" command: "mkdir -p /home/coder/go/src/github.com/my-org" # Be careful with keyscans like this! - name: "Add GitHub to known hosts" command: "sudo ssh-keyscan -H github.com >> /home/coder/.ssh/known_hosts" - name: "Clone Git Project" command: "git clone [email protected]:my-org/my-project.git" continue-on-error: true directory: /home/coder/go/src/github.com/my-org - name: "install Go binary" command: "go install" directory: /home/coder/go/src/github.com/my-org/my-project shell: "bash" continue-on-error: true env: GOPATH: /home/coder/go dev-urls: value: - name: MyWebsite port: 3000 scheme: http access: private - name: PublicPort port: 8080 scheme: https access: public - name: OrgWebsite port: 3001 scheme: http access: org - name: AuthedSite port: 8081 scheme: https access: authed
The version number of the config file being used. The currently supported
Required. The section containing all configuration information related to the workspace.
Required. Determines the type of workspace to be created. Currently, the
only accepted value is
Required. This section contains configuration information specific to the
This section contains all the properties related to a
Required. The image to use for the workspace. The image should include the
registry and (optionally) the tag, e.g.,
docker.io/ubuntu:18.04. If you omit
the tag, Coder uses the default value of
You must have imported the image into Coder, otherwise, the workspace will fail to build.
The Kubernetes labels to be added to the workspace pod.
labels: value: com.coder.custom.hello: hello com.coder.custom.world: world
labels is disabled by default and must be enabled by a site admin.
The Kubernetes annotations to be added to the workspace pod.
annotations: value: - key: annotation-key value: annotation-value
The number of GPUs to allocate to the workspace.
Determines whether the workspace should be created as a
container-based virtual machine (CVM). Default is
Required. The number of cores to allocate to the workspace.
Required. The amount of memory (in GB) to allocate to the workspace.
Required. The amount of disk space (in GB) to allocate to the workspace.
Adds Kubernetes tolerations to the workspace pod.
tolerations: value: - key: example1 operator: Exists value: value-1 effect: NoSchedule tolerationSeconds: 200 - key: example-3 operator: Equal value: value-2 effect: PreferNoSchedule tolerationSeconds: 400 - key: example-3 value: value-3 effect: NoExecute
tolerations is disabled by default and must be enabled by a site admin.
Adds Kubernetes NodeSelectors to the workspace pod. The value is a sequence of key/value pairs.
For example, the following snippet would add two
nodeSelectors for Kubernetes:
node-selector: value: - key: accelerator value: nvidia - key: disktype value: ssd
node-selector is disabled by default and must be enabled by a site admin.
This section lists the commands that run within the workspace after Coder builds the workspace. See Configure for more information.
The list of commands to run when Coder starts a workspace.
Required. Runs the provided command within the workspace (Coder supports the use of both single-line and multi-line commands).
- name: Install curl command: apt install -y curl
- name: Update and install curl command: | apt update apt install -y curl
The name of the command being run.
The shell Coder should use to run the command.
start: - name: First step shell: /bin/bash
The working directory from which Coder should run the command.
start: - name: First step directory: /home/coder
Any step that returns a non-zero exit code will fail. By default, a failure prevents the subsequent steps from executing. If you would like to change this behavior, this field (which accepts a Boolean value) will allow a step to fail and not halt subsequent steps.
The map of environment variables to set for the command.
start: - name: First step env: HOME: /home/coder GOPATH: /home/coder/go
This list allows you to provision dev URLs using the workspaces as code configuration file. The dev URLs will be provisioned in addition to any dev URLs you create.
dev-urls: value: - name: PublicPort port: 8080 scheme: https access: public - name: PrivatePort port: 8000 scheme: https access: private
The name of the dev URL to be created.
The workspace port that the dev URL exposes.
The URL scheme (protocol) to use (i.e.,
The permission level of the dev URL: