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.
Workspace templates 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 intellisense feature.
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 run-as-user: value: 1000 run-as-group: value: 1000 seccomp-profile-type: value: Localhost seccomp-profile-localhost-profile: value: profiles/custom-profile.json 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: 443 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.
The environment variables to set in the workspaces.
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.
Whether the workspace should be run as privileged (running as privileged disables most container security isolation).
The custom resources that can be requested.
The limits to apply to the custom resources requested.
The name of a Kubernetes RuntimeClass to associate with the workspaces.
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.
runAsUser attribute on the workspace's PodSecurityContext, which
controls the UID used within containers. The value must be a numeric UID.
If not specified, this defaults to the UID specified in the image metadata, as specified in the Kubernetes documentation.
runAsGroup attribute on the workspace's PodSecurityContext, which
controls the GID used within the workspace container. The value must be a
If not specified, this defaults to a GID specified by the container runtime, as specified in the Kubernetes documentation.
Applies a seccomp profile
to the workspace pod. The value is a string, corresponding to the
subfield of the PodSecurityContext
For example, the following snippet would explicitly disable seccomp protection:
seccomp-profile-type: value: Unconfined
seccomp-profile-type is disabled by default and must be enabled by a site
Applies a custom seccomp profile
to the workspace pod. The value is a string, corresponding to the
localhostProfile subfield of the PodSecurityContext
Per the Kubernetes
this attribute is only valid if used in combination with the
profile type. Its value must correspond to the path of a valid JSON profile that
is already configured on the Kubernetes worker nodes.
The following snippet demonstrates setting a custom profile:
seccomp-profile-type: value: Localhost seccomp-profile-localhost-profile: value: profiles/my-custom-profile.json
seccomp-profile-localhost-profile 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: value: - name: First step shell: /bin/bash
The working directory from which Coder should run the command.
start: value: - 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: value: - 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: 443 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:
- private: Can only be accessed by the owner of the workspace
- org: Can be accessed by all members of the organization to which the workspace belongs
- authed: Can be accessed by all users on the Coder deployment
- public: Can be accessed by anyone on the internet