opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2023-08-23 12:27:57 +03:00
committed by GitHub
parent ed2b1236c0
commit d37f6d80f7
96 changed files with 2838 additions and 1457 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/templates/README.md
Vendored
+14 -14
View File
@@ -16,13 +16,13 @@ individuals can start their own Coder deployments.
From your local machine, download the CLI for your operating system from the
[releases](https://github.com/coder/coder/releases/latest) or run:
```console
```shell
curl -fsSL https://coder.com/install.sh | sh
```
To see the sub-commands for managing templates, run:
```console
```shell
coder templates --help
```
@@ -31,7 +31,7 @@ coder templates --help
Before you can create templates, you must first login to your Coder deployment
with the CLI.
```console
```shell
coder login https://coder.example.com # aka the URL to your coder instance
```
@@ -41,7 +41,7 @@ returning an API Key.
> Make a note of the API Key. You can re-use the API Key in future CLI logins or
> sessions.
```console
```shell
coder --token <your-api-key> login https://coder.example.com/ # aka the URL to your coder instance
```
@@ -49,7 +49,7 @@ coder --token <your-api-key> login https://coder.example.com/ # aka the URL to y
Before users can create workspaces, you'll need at least one template in Coder.
```sh
```shell
# create a local directory to store templates
mkdir -p $HOME/coder/templates
cd $HOME/coder/templates
@@ -74,7 +74,7 @@ coder templates create <template-name>
To control cost, specify a maximum time to live flag for a template in hours or
minutes.
```sh
```shell
coder templates create my-template --default-ttl 4h
```
@@ -232,7 +232,7 @@ Alternatively, if you're willing to wait for longer start times from Coder, you
can set the `imagePullPolicy` to `Always` in your Terraform template; when set,
Coder will check `image:tag` on every build and update if necessary:
```tf
```hcl
resource "kubernetes_pod" "podName" {
spec {
container {
@@ -254,7 +254,7 @@ Using the UI, navigate to the template page, click on the menu, and select "Edit
Using the CLI, login to Coder and run the following command to edit a single
template:
```console
```shell
coder templates edit <template-name> --description "This is my template"
```
@@ -263,20 +263,20 @@ Review editable template properties by running `coder templates edit -h`.
Alternatively, you can pull down the template as a tape archive (`.tar`) to your
current directory:
```console
```shell
coder templates pull <template-name> file.tar
```
Then, extract it by running:
```sh
```shell
tar -xf file.tar
```
Make the changes to your template then run this command from the root of the
template folder:
```console
```shell
coder templates push <template-name>
```
@@ -292,7 +292,7 @@ have any running workspaces associated to it.
Using the CLI, login to Coder and run the following command to delete a
template:
```console
```shell
coder templates delete <template-name>
```
@@ -329,7 +329,7 @@ sets a few environment variables based on the username and email address of the
workspace's owner, so that you can make Git commits immediately without any
manual configuration:
```tf
```hcl
resource "coder_agent" "main" {
# ...
env = {
@@ -370,7 +370,7 @@ practices:
- The Coder agent logs are typically stored in `/tmp/coder-agent.log`
- The Coder agent startup script logs are typically stored in `/tmp/coder-startup-script.log`
- The Coder agent shutdown script logs are typically stored in `/tmp/coder-shutdown-script.log`
- This can also happen if the websockets are not being forwarded correctly when running Coder behind a reverse proxy. [Read our reverse-proxy docs](https://coder.com/docs/v2/latest/admin/configure#tls--reverse-proxy)
- This can also happen if the websockets are not being forwarded correctly when running Coder behind a reverse proxy. [Read our reverse-proxy docs](../admin/configure.md#tls--reverse-proxy)
### Agent does not become ready
docs/templates/agent-metadata.md
Vendored
+25 -21
View File
@@ -2,19 +2,23 @@
![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).
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).
See the [Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
See the
[Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata).
## 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 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.
Here's a standard set of metadata snippets for Linux agents:
@@ -84,9 +88,9 @@ resource "coder_agent" "main" {
## Utilities
[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:
[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:
```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
@@ -95,8 +99,8 @@ 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:
distributions and provides virtual memory, CPU and IO statistics. Running
`vmstat` produces output that looks like:
```text
procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu-----
@@ -104,9 +108,9 @@ 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
[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:
```text
@@ -117,9 +121,9 @@ usr sys idl wai stl| read writ| recv send| in out | int csw
## DB Write 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 database
if you're not careful. The approximate writes per second can be calculated using
the formula:
```text
(metadata_count * num_running_agents * 2) / metadata_avg_interval
@@ -133,5 +137,5 @@ For example, let's say you have
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.
docs/templates/authentication.md
Vendored
+18 -15
View File
@@ -7,16 +7,19 @@
</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.
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.
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).
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).
Cloud providers for which the Terraform provider supports authenticated environments include
Cloud providers for which the Terraform provider supports authenticated
environments include
- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
@@ -24,11 +27,11 @@ Cloud providers for which the Terraform provider supports authenticated environm
- [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.
[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.
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.
docs/templates/change-management.md
Vendored
+6 -4
View File
@@ -1,6 +1,7 @@
# 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.
[Install Coder](../install/) in CI/CD pipelines to push new template versions.
```console
# Install the Coder CLI
@@ -26,7 +27,8 @@ 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).
> 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)
docs/templates/devcontainers.md
Vendored
+31 -11
View File
@@ -1,20 +1,32 @@
# Devcontainers (alpha)
[Devcontainers](https://containers.dev) are an open source specification for defining development environments. [envbuilder](https://github.com/coder/envbuilder) is an open source project by Coder that runs devcontainers via Coder templates and your underlying infrastructure.
[Devcontainers](https://containers.dev) are an open source specification for
defining development environments.
[envbuilder](https://github.com/coder/envbuilder) is an open source project by
Coder that runs devcontainers via Coder templates and your underlying
infrastructure.
There are several benefits to adding a devcontainer-compatible template to Coder:
There are several benefits to adding a devcontainer-compatible template to
Coder:
- Drop-in migration from Codespaces (or any existing repositories that use devcontainers)
- Drop-in migration from Codespaces (or any existing repositories that use
devcontainers)
- Easier to start projects from Coder (new workspace, pick starter devcontainer)
- Developer teams can "bring their own image." No need for platform teams to manage complex images, registries, and CI pipelines.
- Developer teams can "bring their own image." No need for platform teams to
manage complex images, registries, and CI pipelines.
## How it works
- Coder admins add a devcontainer-compatible template to Coder (envbuilder can run on Docker or Kubernetes)
- Coder admins add a devcontainer-compatible template to Coder (envbuilder can
run on Docker or Kubernetes)
- Developers enter their repository URL as a [parameter](./parameters.md) when they create their workspace. [envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a container from the `devcontainer.json` specified in the repo.
- Developers enter their repository URL as a [parameter](./parameters.md) when
they create their workspace. [envbuilder](https://github.com/coder/envbuilder)
clones the repo and builds a container from the `devcontainer.json` specified
in the repo.
- Developers can edit the `devcontainer.json` in their workspace to rebuild to iterate on their development environments.
- Developers can edit the `devcontainer.json` in their workspace to rebuild to
iterate on their development environments.
## Example templates
@@ -23,16 +35,24 @@ There are several benefits to adding a devcontainer-compatible template to Coder
![Devcontainer parameter screen](../images/templates/devcontainers.png)
[Parameters](./parameters.md) can be used to prompt the user for a repo URL when they are creating a workspace.
[Parameters](./parameters.md) can be used to prompt the user for a repo URL when
they are creating a workspace.
## Authentication
You may need to authenticate to your container registry (e.g. Artifactory) or git provider (e.g. GitLab) to use envbuilder. Refer to the [envbuilder documentation](https://github.com/coder/envbuilder/) for more information.
You may need to authenticate to your container registry (e.g. Artifactory) or
git provider (e.g. GitLab) to use envbuilder. Refer to the
[envbuilder documentation](https://github.com/coder/envbuilder/) for more
information.
## Caching
To improve build times, devcontainers can be cached. Refer to the [envbuilder documentation](https://github.com/coder/envbuilder/) for more information.
To improve build times, devcontainers can be cached. Refer to the
[envbuilder documentation](https://github.com/coder/envbuilder/) for more
information.
## Other features & known issues
Envbuilder is still under active development. Refer to the [envbuilder GitHub repo](https://github.com/coder/envbuilder/) for more information and to submit feature requests.
Envbuilder is still under active development. Refer to the
[envbuilder GitHub repo](https://github.com/coder/envbuilder/) for more
information and to submit feature requests.
docs/templates/docker-in-workspaces.md
Vendored
+83 -39
View File
@@ -11,13 +11,21 @@ There are a few ways to run Docker within container-based Coder workspaces.
## Sysbox container runtime
The [Sysbox](https://github.com/nestybox/sysbox) container runtime allows unprivileged users to run system-level applications, such as Docker, securely from the workspace containers. Sysbox requires a [compatible Linux distribution](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md) to implement these security features. Sysbox can also be used to run systemd inside Coder workspaces. See [Systemd in Docker](#systemd-in-docker).
The [Sysbox](https://github.com/nestybox/sysbox) container runtime allows
unprivileged users to run system-level applications, such as Docker, securely
from the workspace containers. Sysbox requires a
[compatible Linux distribution](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md)
to implement these security features. Sysbox can also be used to run systemd
inside Coder workspaces. See [Systemd in Docker](#systemd-in-docker).
The Sysbox container runtime is not compatible with our [workspace process logging](./process-logging.md) feature. Envbox is compatible with process logging, however.
The Sysbox container runtime is not compatible with our
[workspace process logging](./process-logging.md) feature. Envbox is compatible
with process logging, however.
### Use Sysbox in Docker-based templates
After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on the Coder host, modify your template to use the sysbox-runc runtime:
After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on
the Coder host, modify your template to use the sysbox-runc runtime:
```hcl
resource "docker_container" "workspace" {
@@ -46,7 +54,10 @@ resource "coder_agent" "main" {
### Use Sysbox in Kubernetes-based templates
After [installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md), modify your template to use the sysbox-runc RuntimeClass. This requires the Kubernetes Terraform provider version 2.16.0 or greater.
After
[installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md),
modify your template to use the sysbox-runc RuntimeClass. This requires the
Kubernetes Terraform provider version 2.16.0 or greater.
```hcl
terraform {
@@ -111,15 +122,20 @@ resource "kubernetes_pod" "dev" {
}
```
> Sysbox CE (Community Edition) supports a maximum of 16 pods (workspaces) per node on Kubernetes. See the [Sysbox documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md#limitations) for more details.
> Sysbox CE (Community Edition) supports a maximum of 16 pods (workspaces) per
> node on Kubernetes. See the
> [Sysbox documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md#limitations)
> for more details.
## Envbox
[Envbox](https://github.com/coder/envbox) is an image developed and maintained by Coder that bundles the sysbox runtime. It works
by starting an outer container that manages the various sysbox daemons and spawns an unprivileged
inner container that acts as the user's workspace. The inner container is able to run system-level
software similar to a regular virtual machine (e.g. `systemd`, `dockerd`, etc). Envbox offers the
following benefits over running sysbox directly on the nodes:
[Envbox](https://github.com/coder/envbox) is an image developed and maintained
by Coder that bundles the sysbox runtime. It works by starting an outer
container that manages the various sysbox daemons and spawns an unprivileged
inner container that acts as the user's workspace. The inner container is able
to run system-level software similar to a regular virtual machine (e.g.
`systemd`, `dockerd`, etc). Envbox offers the following benefits over running
sysbox directly on the nodes:
- No custom runtime installation or management on your Kubernetes nodes.
- No limit to the number of pods that run envbox.
@@ -127,27 +143,37 @@ following benefits over running sysbox directly on the nodes:
Some drawbacks include:
- The outer container must be run as privileged
- Note: the inner container is _not_ privileged. For more information on the security of sysbox
containers see sysbox's [official documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/security.md).
- Initial workspace startup is slower than running `sysbox-runc` directly on the nodes. This is due
to `envbox` having to pull the image to its own Docker cache on its initial startup. Once the image
is cached in `envbox`, startup performance is similar.
- Note: the inner container is _not_ privileged. For more information on the
security of sysbox containers see sysbox's
[official documentation](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/security.md).
- Initial workspace startup is slower than running `sysbox-runc` directly on the
nodes. This is due to `envbox` having to pull the image to its own Docker
cache on its initial startup. Once the image is cached in `envbox`, startup
performance is similar.
Envbox requires the same kernel requirements as running sysbox directly on the nodes. Refer
to sysbox's [compatibility matrix](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility) to ensure your nodes are compliant.
Envbox requires the same kernel requirements as running sysbox directly on the
nodes. Refer to sysbox's
[compatibility matrix](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility)
to ensure your nodes are compliant.
To get started with `envbox` check out the [starter template](https://github.com/coder/coder/tree/main/examples/templates/envbox) or visit the [repo](https://github.com/coder/envbox).
To get started with `envbox` check out the
[starter template](https://github.com/coder/coder/tree/main/examples/templates/envbox)
or visit the [repo](https://github.com/coder/envbox).
### Authenticating with a Private Registry
Authenticating with a private container registry can be done by referencing the credentials
via the `CODER_IMAGE_PULL_SECRET` environment variable. It is encouraged to populate this
[environment variable](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) by using a Kubernetes [secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials).
Authenticating with a private container registry can be done by referencing the
credentials via the `CODER_IMAGE_PULL_SECRET` environment variable. It is
encouraged to populate this
[environment variable](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data)
by using a Kubernetes
[secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials).
Refer to your container registry documentation to understand how to best create this secret.
Refer to your container registry documentation to understand how to best create
this secret.
The following shows a minimal example using a the JSON API key from a GCP service account to pull
a private image:
The following shows a minimal example using a the JSON API key from a GCP
service account to pull a private image:
```bash
# Create the secret
@@ -172,17 +198,22 @@ env {
## Rootless podman
[Podman](https://docs.podman.io/en/latest/) is Docker alternative that is compatible with OCI containers specification. which can run rootless inside Kubernetes pods. No custom RuntimeClass is required.
[Podman](https://docs.podman.io/en/latest/) is Docker alternative that is
compatible with OCI containers specification. which can run rootless inside
Kubernetes pods. No custom RuntimeClass is required.
Prior to completing the steps below, please review the following Podman documentation:
Prior to completing the steps below, please review the following Podman
documentation:
- [Basic setup and use of Podman in a rootless environment](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
- [Shortcomings of Rootless Podman](https://github.com/containers/podman/blob/main/rootless.md#shortcomings-of-rootless-podman)
1. Enable [smart-device-manager](https://gitlab.com/arm-research/smarter/smarter-device-manager#enabling-access) to securely expose a FUSE devices to pods.
1. Enable
[smart-device-manager](https://gitlab.com/arm-research/smarter/smarter-device-manager#enabling-access)
to securely expose a FUSE devices to pods.
```sh
```shell
cat <<EOF | kubectl create -f -
apiVersion: apps/v1
kind: DaemonSet
@@ -220,30 +251,40 @@ Prior to completing the steps below, please review the following Podman document
2. Be sure to label your nodes to enable smarter-device-manager:
```sh
```shell
kubectl get nodes
kubectl label nodes --all smarter-device-manager=enabled
```
> ⚠️ **Warning**: If you are using a managed Kubernetes distribution (e.g. AKS, EKS, GKE), be sure to set node labels via your cloud provider. Otherwise, your nodes may drop the labels and break podman functionality.
> ⚠️ **Warning**: If you are using a managed Kubernetes distribution (e.g.
> AKS, EKS, GKE), be sure to set node labels via your cloud provider.
> Otherwise, your nodes may drop the labels and break podman functionality.
3. For systems running SELinux (typically Fedora-, CentOS-, and Red Hat-based systems), you may need to disable SELinux or set it to permissive mode.
3. For systems running SELinux (typically Fedora-, CentOS-, and Red Hat-based
systems), you may need to disable SELinux or set it to permissive mode.
4. Import our [kubernetes-with-podman](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-with-podman) example template, or make your own.
4. Import our
[kubernetes-with-podman](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-with-podman)
example template, or make your own.
```sh
```shell
echo "kubernetes-with-podman" | coder templates init
cd ./kubernetes-with-podman
coder templates create
```
> For more information around the requirements of rootless podman pods, see: [How to run Podman inside of Kubernetes](https://www.redhat.com/sysadmin/podman-inside-kubernetes)
> For more information around the requirements of rootless podman pods, see:
> [How to run Podman inside of Kubernetes](https://www.redhat.com/sysadmin/podman-inside-kubernetes)
## Privileged sidecar container
A [privileged container](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) can be added to your templates to add docker support. This may come in handy if your nodes cannot run Sysbox.
A
[privileged container](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
can be added to your templates to add docker support. This may come in handy if
your nodes cannot run Sysbox.
> ⚠️ **Warning**: This is insecure. Workspaces will be able to gain root access to the host machine.
> ⚠️ **Warning**: This is insecure. Workspaces will be able to gain root access
> to the host machine.
### Use a privileged sidecar container in Docker-based templates
@@ -347,10 +388,13 @@ resource "kubernetes_pod" "main" {
## Systemd in Docker
Additionally, [Sysbox](https://github.com/nestybox/sysbox) can be used to give workspaces full `systemd` capabilities.
Additionally, [Sysbox](https://github.com/nestybox/sysbox) can be used to give
workspaces full `systemd` capabilities.
After [installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md),
modify your template to use the sysbox-runc RuntimeClass. This requires the Kubernetes Terraform provider version 2.16.0 or greater.
After
[installing Sysbox on Kubernetes](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/install-k8s.md),
modify your template to use the sysbox-runc RuntimeClass. This requires the
Kubernetes Terraform provider version 2.16.0 or greater.
```hcl
terraform {
docs/templates/index.md
Vendored
+190 -73
View File
@@ -4,9 +4,10 @@ Templates are written in [Terraform](https://www.terraform.io/) and describe the
infrastructure for workspaces (e.g., docker_container, aws_instance,
kubernetes_pod).
In most cases, a small group of users (team leads or Coder administrators) [have permissions](../admin/users.md#roles) to create and manage templates. Then, other
users provision their [workspaces](../workspaces.md) from templates using the UI
or CLI.
In most cases, a small group of users (team leads or Coder administrators)
[have permissions](../admin/users.md#roles) to create and manage templates.
Then, other users provision their [workspaces](../workspaces.md) from templates
using the UI or CLI.
## Get the CLI
@@ -16,13 +17,13 @@ individuals can start their own Coder deployments.
From your local machine, download the CLI for your operating system from the
[releases](https://github.com/coder/coder/releases/latest) or run:
```console
```shell
curl -fsSL https://coder.com/install.sh | sh
```
To see the sub-commands for managing templates, run:
```console
```shell
coder templates --help
```
@@ -31,7 +32,7 @@ coder templates --help
Before you can create templates, you must first login to your Coder deployment
with the CLI.
```console
```shell
coder login https://coder.example.com # aka the URL to your coder instance
```
@@ -41,7 +42,7 @@ returning an API Key.
> Make a note of the API Key. You can re-use the API Key in future CLI logins or
> sessions.
```console
```shell
coder --token <your-api-key> login https://coder.example.com/ # aka the URL to your coder instance
```
@@ -49,7 +50,7 @@ coder --token <your-api-key> login https://coder.example.com/ # aka the URL to y
Before users can create workspaces, you'll need at least one template in Coder.
```sh
```shell
# create a local directory to store templates
mkdir -p $HOME/coder/templates
cd $HOME/coder/templates
@@ -74,7 +75,7 @@ coder templates create <template-name>
To control cost, specify a maximum time to live flag for a template in hours or
minutes.
```sh
```shell
coder templates create my-template --default-ttl 4h
```
@@ -83,28 +84,35 @@ coder templates create my-template --default-ttl 4h
Example templates are not designed to support every use (e.g
[examples/aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux)
does not support custom VPCs). You can add these features by editing the
Terraform code once you run `coder templates init` (new) or `coder templates pull` (existing).
Terraform code once you run `coder templates init` (new) or
`coder templates pull` (existing).
Refer to the following resources to build your own templates:
- Terraform: [Documentation](https://developer.hashicorp.com/terraform/docs) and
[Registry](https://registry.terraform.io)
- Common [concepts in templates](#concepts-in-templates) and [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs)
- [Coder example templates](https://github.com/coder/coder/tree/main/examples/templates) code
- Common [concepts in templates](#concepts-in-templates) and
[Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs)
- [Coder example templates](https://github.com/coder/coder/tree/main/examples/templates)
code
## Concepts in templates
While templates are written with standard Terraform, the [Coder Terraform Provider](https://registry.terraform.io/providers/coder/coder/latest/docs) is used to define the workspace lifecycle and establish a connection from resources
to Coder.
While templates are written with standard Terraform, the
[Coder Terraform Provider](https://registry.terraform.io/providers/coder/coder/latest/docs)
is used to define the workspace lifecycle and establish a connection from
resources to Coder.
Below is an overview of some key concepts in templates (and workspaces). For all
template options, reference [Coder Terraform provider docs](https://registry.terraform.io/providers/coder/coder/latest/docs).
template options, reference
[Coder Terraform provider docs](https://registry.terraform.io/providers/coder/coder/latest/docs).
### Resource
Resources in Coder are simply [Terraform resources](https://www.terraform.io/language/resources).
If a Coder agent is attached to a resource, users can connect directly to the
resource over SSH or web apps.
Resources in Coder are simply
[Terraform resources](https://www.terraform.io/language/resources). If a Coder
agent is attached to a resource, users can connect directly to the resource over
SSH or web apps.
### Coder agent
@@ -139,9 +147,10 @@ resource "kubernetes_pod" "pod1" {
}
```
The `coder_agent` resource can be configured with additional arguments. For example,
you can use the `env` property to set environment variables that will be inherited
by all child processes of the agent, including SSH sessions. See the
The `coder_agent` resource can be configured with additional arguments. For
example, you can use the `env` property to set environment variables that will
be inherited by all child processes of the agent, including SSH sessions. See
the
[Coder Terraform Provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent)
for the full list of supported arguments for the `coder_agent`.
@@ -151,14 +160,17 @@ Use the Coder agent's `startup_script` to run additional commands like
installing IDEs, [cloning dotfiles](../dotfiles.md#templates), and cloning
project repos.
**Note:** By default, the startup script is executed in the background.
This allows users to access the workspace before the script completes.
If you want to change this, see [`startup_script_behavior`](#startup_script_behavior) below.
**Note:** By default, the startup script is executed in the background. This
allows users to access the workspace before the script completes. If you want to
change this, see [`startup_script_behavior`](#startup_script_behavior) below.
Here are a few guidelines for writing a good startup script (more on these below):
Here are a few guidelines for writing a good startup script (more on these
below):
1. Use `set -e` to exit the script if any command fails and `|| true` for commands that are allowed to fail
2. Use `&` to start a process in the background, allowing the startup script to complete
1. Use `set -e` to exit the script if any command fails and `|| true` for
commands that are allowed to fail
2. Use `&` to start a process in the background, allowing the startup script to
complete
3. Inform the user about what's going on via `echo`
```hcl
@@ -198,17 +210,41 @@ coder dotfiles -y "$DOTFILES_URI"
}
```
The startup script can contain important steps that must be executed successfully so that the workspace is in a usable state, for this reason we recommend using `set -e` (exit on error) at the top and `|| true` (allow command to fail) to ensure the user is notified when something goes wrong. These are not shown in the example above because, while useful, they need to be used with care. For more assurance, you can utilize [shellcheck](https://www.shellcheck.net) to find bugs in the script and employ [`set -euo pipefail`](https://wizardzines.com/comics/bash-errors/) to exit on error, unset variables, and fail on pipe errors.
The startup script can contain important steps that must be executed
successfully so that the workspace is in a usable state, for this reason we
recommend using `set -e` (exit on error) at the top and `|| true` (allow command
to fail) to ensure the user is notified when something goes wrong. These are not
shown in the example above because, while useful, they need to be used with
care. For more assurance, you can utilize
[shellcheck](https://www.shellcheck.net) to find bugs in the script and employ
[`set -euo pipefail`](https://wizardzines.com/comics/bash-errors/) to exit on
error, unset variables, and fail on pipe errors.
We also recommend that startup scripts do not run forever. Long-running processes, like code-server, should be run in the background. This is usually achieved by adding `&` to the end of the command. For example, `sleep 10 &` will run the command in the background and allow the startup script to complete.
We also recommend that startup scripts do not run forever. Long-running
processes, like code-server, should be run in the background. This is usually
achieved by adding `&` to the end of the command. For example, `sleep 10 &` will
run the command in the background and allow the startup script to complete.
> **Note:** If a backgrounded command (`&`) writes to stdout or stderr, the startup script will not complete until the command completes or closes the file descriptors. To avoid this, you can redirect the stdout and stderr to a file. For example, `sleep 10 >/dev/null 2>&1 &` will redirect the stdout and stderr to `/dev/null` (discard) and run the command in the background.
> **Note:** If a backgrounded command (`&`) writes to stdout or stderr, the
> startup script will not complete until the command completes or closes the
> file descriptors. To avoid this, you can redirect the stdout and stderr to a
> file. For example, `sleep 10 >/dev/null 2>&1 &` will redirect the stdout and
> stderr to `/dev/null` (discard) and run the command in the background.
PS. Notice how each step starts with `echo "..."` to provide feedback to the user about what is happening? This is especially useful when the startup script behavior is set to blocking because the user will be informed about why they're waiting to access their workspace.
PS. Notice how each step starts with `echo "..."` to provide feedback to the
user about what is happening? This is especially useful when the startup script
behavior is set to blocking because the user will be informed about why they're
waiting to access their workspace.
#### `startup_script_behavior`
Use the Coder agent's `startup_script_behavior` to change the behavior between `blocking` and `non-blocking` (default). The blocking behavior is recommended for most use cases because it allows the startup script to complete before the user accesses the workspace. For example, let's say you want to check out a very large repo in the startup script. If the startup script is non-blocking, the user may log in via SSH or open the IDE before the repo is fully checked out. This can lead to a poor user experience.
Use the Coder agent's `startup_script_behavior` to change the behavior between
`blocking` and `non-blocking` (default). The blocking behavior is recommended
for most use cases because it allows the startup script to complete before the
user accesses the workspace. For example, let's say you want to check out a very
large repo in the startup script. If the startup script is non-blocking, the
user may log in via SSH or open the IDE before the repo is fully checked out.
This can lead to a poor user experience.
```hcl
resource "coder_agent" "coder" {
@@ -218,7 +254,10 @@ resource "coder_agent" "coder" {
startup_script = "echo 'Starting...'"
```
Whichever behavior is enabled, the user can still choose to override it by specifying the appropriate flags (or environment variables) in the CLI when connecting to the workspace. The behavior can be overridden by one of the following means:
Whichever behavior is enabled, the user can still choose to override it by
specifying the appropriate flags (or environment variables) in the CLI when
connecting to the workspace. The behavior can be overridden by one of the
following means:
- Set an environment variable (for use with `ssh` or `coder ssh`):
- `export CODER_SSH_WAIT=yes` (blocking)
@@ -236,8 +275,9 @@ Whichever behavior is enabled, the user can still choose to override it by speci
Coder workspaces can be started/stopped. This is often used to save on cloud
costs or enforce ephemeral workflows. When a workspace is started or stopped,
the Coder server runs an additional [terraform apply](https://www.terraform.io/cli/commands/apply),
informing the Coder provider that the workspace has a new transition state.
the Coder server runs an additional
[terraform apply](https://www.terraform.io/cli/commands/apply), informing the
Coder provider that the workspace has a new transition state.
This template sample has one persistent resource (docker volume) and one
ephemeral resource (docker container).
@@ -278,7 +318,7 @@ Alternatively, if you're willing to wait for longer start times from Coder, you
can set the `imagePullPolicy` to `Always` in your Terraform template; when set,
Coder will check `image:tag` on every build and update if necessary:
```tf
```hcl
resource "kubernetes_pod" "podName" {
spec {
container {
@@ -290,17 +330,23 @@ resource "kubernetes_pod" "podName" {
### Edit templates
You can edit a template using the coder CLI or the UI. Only [template admins and
owners](../admin/users.md) can edit a template.
You can edit a template using the coder CLI or the UI. Only
[template admins and owners](../admin/users.md) can edit a template.
Using the UI, navigate to the template page, click on the menu, and select "Edit files". In the template editor, you create, edit and remove files. Before publishing a new template version, you can test your modifications by clicking the "Build template" button. Newly published template versions automatically become the default version selection when creating a workspace.
Using the UI, navigate to the template page, click on the menu, and select "Edit
files". In the template editor, you create, edit and remove files. Before
publishing a new template version, you can test your modifications by clicking
the "Build template" button. Newly published template versions automatically
become the default version selection when creating a workspace.
> **Tip**: Even without publishing a version as active, you can still use it to create a workspace before making it the default for everybody in your organization. This may help you debug new changes without impacting others.
> **Tip**: Even without publishing a version as active, you can still use it to
> create a workspace before making it the default for everybody in your
> organization. This may help you debug new changes without impacting others.
Using the CLI, login to Coder and run the following command to edit a single
template:
```console
```shell
coder templates edit <template-name> --description "This is my template"
```
@@ -309,20 +355,20 @@ Review editable template properties by running `coder templates edit -h`.
Alternatively, you can pull down the template as a tape archive (`.tar`) to your
current directory:
```console
```shell
coder templates pull <template-name> file.tar
```
Then, extract it by running:
```sh
```shell
tar -xf file.tar
```
Make the changes to your template then run this command from the root of the
template folder:
```console
```shell
coder templates push <template-name>
```
@@ -331,14 +377,14 @@ prompt in the dashboard to update.
### Delete templates
You can delete a template using both the coder CLI and UI. Only [template admins
and owners](../admin/users.md) can delete a template, and the template must not
have any running workspaces associated to it.
You can delete a template using both the coder CLI and UI. Only
[template admins and owners](../admin/users.md) can delete a template, and the
template must not have any running workspaces associated to it.
Using the CLI, login to Coder and run the following command to delete a
template:
```console
```shell
coder templates delete <template-name>
```
@@ -349,9 +395,9 @@ in the right-hand corner of the page to delete the template.
#### Delete workspaces
When a workspace is deleted, the Coder server essentially runs a [terraform
destroy](https://www.terraform.io/cli/commands/destroy) to remove all resources
associated with the workspace.
When a workspace is deleted, the Coder server essentially runs a
[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
resources associated with the workspace.
> Terraform's
> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
@@ -368,14 +414,17 @@ users access to additional web applications.
### Data source
When a workspace is being started or stopped, the `coder_workspace` data source
provides some useful parameters. See the [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace) for more information.
provides some useful parameters. See the
[Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace)
for more information.
For example, the [Docker quick-start template](https://github.com/coder/coder/tree/main/examples/templates/docker)
For example, the
[Docker quick-start template](https://github.com/coder/coder/tree/main/examples/templates/docker)
sets a few environment variables based on the username and email address of the
workspace's owner, so that you can make Git commits immediately without any
manual configuration:
```tf
```hcl
resource "coder_agent" "main" {
# ...
env = {
@@ -393,12 +442,14 @@ customize them however you like.
## Troubleshooting templates
Occasionally, you may run into scenarios where a workspace is created, but the
agent is either not connected or the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
agent is either not connected or the
[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
has failed or timed out.
### Agent connection issues
If the agent is not connected, it means the agent or [init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts)
If the agent is not connected, it means the agent or
[init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts)
has failed on the resource.
```console
@@ -410,33 +461,78 @@ While troubleshooting steps vary by resource, here are some general best
practices:
- Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`)
- Ensure the resource can `curl` your Coder [access
URL](../admin/configure.md#access-url)
- Manually connect to the resource and check the agent logs (e.g., `kubectl exec`, `docker exec` or AWS console)
- Ensure the resource can `curl` your Coder
[access URL](../admin/configure.md#access-url)
- Manually connect to the resource and check the agent logs (e.g.,
`kubectl exec`, `docker exec` or AWS console)
- The Coder agent logs are typically stored in `/tmp/coder-agent.log`
- The Coder agent startup script logs are typically stored in `/tmp/coder-startup-script.log`
- The Coder agent shutdown script logs are typically stored in `/tmp/coder-shutdown-script.log`
- This can also happen if the websockets are not being forwarded correctly when running Coder behind a reverse proxy. [Read our reverse-proxy docs](https://coder.com/docs/v2/latest/admin/configure#tls--reverse-proxy)
- The Coder agent startup script logs are typically stored in
`/tmp/coder-startup-script.log`
- The Coder agent shutdown script logs are typically stored in
`/tmp/coder-shutdown-script.log`
- This can also happen if the websockets are not being forwarded correctly when
running Coder behind a reverse proxy.
[Read our reverse-proxy docs](../admin/configure.md#tls--reverse-proxy)
### Startup script issues
Depending on the contents of the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script), and whether or not the [startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) is set to blocking or non-blocking, you may notice issues related to the startup script. In this section we will cover common scenarios and how to resolve them.
Depending on the contents of the
[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script),
and whether or not the
[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior)
is set to blocking or non-blocking, you may notice issues related to the startup
script. In this section we will cover common scenarios and how to resolve them.
#### Unable to access workspace, startup script is still running
If you're trying to access your workspace and are unable to because the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running, it means the [startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) option is set to blocking or you have enabled the `--wait=yes` option (for e.g. `coder ssh` or `coder config-ssh`). In such an event, you can always access the workspace by using the web terminal, or via SSH using the `--wait=no` option. If the startup script is running longer than it should, or never completing, you can try to [debug the startup script](#debugging-the-startup-script) to resolve the issue. Alternatively, you can try to force the startup script to exit by terminating processes started by it or terminating the startup script itself (on Linux, `ps` and `kill` are useful tools).
If you're trying to access your workspace and are unable to because the
[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
is still running, it means the
[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior)
option is set to blocking or you have enabled the `--wait=yes` option (for e.g.
`coder ssh` or `coder config-ssh`). In such an event, you can always access the
workspace by using the web terminal, or via SSH using the `--wait=no` option. If
the startup script is running longer than it should, or never completing, you
can try to [debug the startup script](#debugging-the-startup-script) to resolve
the issue. Alternatively, you can try to force the startup script to exit by
terminating processes started by it or terminating the startup script itself (on
Linux, `ps` and `kill` are useful tools).
For tips on how to write a startup script that doesn't run forever, see the [`startup_script`](#startup_script) section. For more ways to override the startup script behavior, see the [`startup_script_behavior`](#startup_script_behavior) section.
For tips on how to write a startup script that doesn't run forever, see the
[`startup_script`](#startup_script) section. For more ways to override the
startup script behavior, see the
[`startup_script_behavior`](#startup_script_behavior) section.
Template authors can also set the [startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) option to non-blocking, which will allow users to access the workspace while the startup script is still running. Note that the workspace must be updated after changing this option.
Template authors can also set the
[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior)
option to non-blocking, which will allow users to access the workspace while the
startup script is still running. Note that the workspace must be updated after
changing this option.
#### Your workspace may be incomplete
If you see a warning that your workspace may be incomplete, it means you should be aware that programs, files, or settings may be missing from your workspace. This can happen if the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is still running or has exited with a non-zero status (see [startup script error](#startup-script-error)). No action is necessary, but you may want to [start a new shell session](#session-was-started-before-the-startup-script-finished-web-terminal) after it has completed or check the [startup script logs](#debugging-the-startup-script) to see if there are any issues.
If you see a warning that your workspace may be incomplete, it means you should
be aware that programs, files, or settings may be missing from your workspace.
This can happen if the
[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
is still running or has exited with a non-zero status (see
[startup script error](#startup-script-error)). No action is necessary, but you
may want to
[start a new shell session](#session-was-started-before-the-startup-script-finished-web-terminal)
after it has completed or check the
[startup script logs](#debugging-the-startup-script) to see if there are any
issues.
#### Session was started before the startup script finished
The web terminal may show this message if it was started before the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) finished, but the startup script has since finished. This message can safely be dismissed, however, be aware that your preferred shell or dotfiles may not yet be activated for this shell session. You can either start a new session or source your dotfiles manually. Note that starting a new session means that commands running in the terminal will be terminated and you may lose unsaved work.
The web terminal may show this message if it was started before the
[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
finished, but the startup script has since finished. This message can safely be
dismissed, however, be aware that your preferred shell or dotfiles may not yet
be activated for this shell session. You can either start a new session or
source your dotfiles manually. Note that starting a new session means that
commands running in the terminal will be terminated and you may lose unsaved
work.
Examples for activating your preferred shell or sourcing your dotfiles:
@@ -445,7 +541,15 @@ Examples for activating your preferred shell or sourcing your dotfiles:
#### Startup script exited with an error
When the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) exits with an error, it means the last command run by the script failed. When `set -e` is used, this means that any failing command will immediately exit the script and the remaining commands will not be executed. This also means that [your workspace may be incomplete](#your-workspace-may-be-incomplete). If you see this error, you can check the [startup script logs](#debugging-the-startup-script) to figure out what the issue is.
When the
[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
exits with an error, it means the last command run by the script failed. When
`set -e` is used, this means that any failing command will immediately exit the
script and the remaining commands will not be executed. This also means that
[your workspace may be incomplete](#your-workspace-may-be-incomplete). If you
see this error, you can check the
[startup script logs](#debugging-the-startup-script) to figure out what the
issue is.
Common causes for startup script errors:
@@ -455,11 +559,20 @@ Common causes for startup script errors:
#### Debugging the startup script
The simplest way to debug the [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) is to open the workspace in the Coder dashboard and click "Show startup log" (if not already visible). This will show all the output from the script. Another option is to view the log file inside the workspace (usually `/tmp/coder-startup-script.log`). If the logs don't indicate what's going on or going wrong, you can increase verbosity by adding `set -x` to the top of the startup script (note that this will show all commands run and may output sensitive information). Alternatively, you can add `echo` statements to show what's going on.
The simplest way to debug the
[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)
is to open the workspace in the Coder dashboard and click "Show startup log" (if
not already visible). This will show all the output from the script. Another
option is to view the log file inside the workspace (usually
`/tmp/coder-startup-script.log`). If the logs don't indicate what's going on or
going wrong, you can increase verbosity by adding `set -x` to the top of the
startup script (note that this will show all commands run and may output
sensitive information). Alternatively, you can add `echo` statements to show
what's going on.
Here's a short example of an informative startup script:
```sh
```shell
echo "Running startup script..."
echo "Run: long-running-command"
/path/to/long-running-command
@@ -471,9 +584,13 @@ if [ $status -ne 0 ]; then
fi
```
> **Note:** We don't use `set -x` here because we're manually echoing the commands. This protects against sensitive information being shown in the log.
> **Note:** We don't use `set -x` here because we're manually echoing the
> commands. This protects against sensitive information being shown in the log.
This script tells us what command is being run and what the exit status is. If the exit status is non-zero, it means the command failed and we exit the script. Since we are manually checking the exit status here, we don't need `set -e` at the top of the script to exit on error.
This script tells us what command is being run and what the exit status is. If
the exit status is non-zero, it means the command failed and we exit the script.
Since we are manually checking the exit status here, we don't need `set -e` at
the top of the script to exit on error.
## Template permissions (enterprise)
docs/templates/modules.md
Vendored
+42 -18
View File
@@ -1,8 +1,12 @@
# Template inheritance
In instances where you want to reuse code across different Coder templates, such as common scripts or resource definitions, we suggest using [Terraform Modules](https://developer.hashicorp.com/terraform/language/modules).
In instances where you want to reuse code across different Coder templates, such
as common scripts or resource definitions, we suggest using
[Terraform Modules](https://developer.hashicorp.com/terraform/language/modules).
These modules can be stored externally from Coder, like in a Git repository or a Terraform registry. Below is an example of how to reference a module in your template:
These modules can be stored externally from Coder, like in a Git repository or a
Terraform registry. Below is an example of how to reference a module in your
template:
```hcl
data "coder_workspace" "me" {}
@@ -25,36 +29,52 @@ resource "coder_agent" "dev" {
}
```
> Learn more about [creating modules](https://developer.hashicorp.com/terraform/language/modules) and [module sources](https://developer.hashicorp.com/terraform/language/modules/sources) in the Terraform documentation.
> Learn more about
> [creating modules](https://developer.hashicorp.com/terraform/language/modules)
> and
> [module sources](https://developer.hashicorp.com/terraform/language/modules/sources)
> in the Terraform documentation.
## Git authentication
If you are importing a module from a private git repository, the Coder server [or provisioner](../admin/provisioners.md) needs git credentials. Since this token will only be used for cloning your repositories with modules, it is best to create a token with limited access to repositories and no extra permissions. In GitHub, you can generate a [fine-grained token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28) with read only access to repos.
If you are importing a module from a private git repository, the Coder server
[or provisioner](../admin/provisioners.md) needs git credentials. Since this
token will only be used for cloning your repositories with modules, it is best
to create a token with limited access to repositories and no extra permissions.
In GitHub, you can generate a
[fine-grained token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28)
with read only access to repos.
If you are running Coder on a VM, make sure you have `git` installed and the `coder` user has access to the following files
If you are running Coder on a VM, make sure you have `git` installed and the
`coder` user has access to the following files
```sh
```toml
# /home/coder/.gitconfig
[credential]
helper = store
```
```sh
```toml
# /home/coder/.git-credentials
# GitHub example:
https://your-github-username:your-github-pat@github.com
```
If you are running Coder on Docker or Kubernetes, `git` is pre-installed in the Coder image. However, you still need to mount credentials. This can be done via a Docker volume mount or Kubernetes secrets.
If you are running Coder on Docker or Kubernetes, `git` is pre-installed in the
Coder image. However, you still need to mount credentials. This can be done via
a Docker volume mount or Kubernetes secrets.
### Passing git credentials in Kubernetes
First, create a `.gitconfig` and `.git-credentials` file on your local machine. You may want to do this in a temporary directory to avoid conflicting with your own git credentials.
First, create a `.gitconfig` and `.git-credentials` file on your local machine.
You may want to do this in a temporary directory to avoid conflicting with your
own git credentials.
Next, create the secret in Kubernetes. Be sure to do this in the same namespace that Coder is installed in.
Next, create the secret in Kubernetes. Be sure to do this in the same namespace
that Coder is installed in.
```sh
```shell
export NAMESPACE=coder
kubectl apply -f - <<EOF
apiVersion: v1
@@ -90,8 +110,8 @@ coder:
## Artifactory
JFrog Artifactory can serve as a Terraform module registry, allowing you to simplify
a Coder-stored template to a `module` block and input variables.
JFrog Artifactory can serve as a Terraform module registry, allowing you to
simplify a Coder-stored template to a `module` block and input variables.
With this approach, you can:
@@ -114,7 +134,7 @@ Remember to replace `cdr.jfrog.io` with your Artifactory instance URL.
You can upload the underlying module to Artifactory with:
```console
```shell
# one-time setup commands
# run this on the coder server (or external provisioners, if you have them)
terraform login cdr.jfrog.io; jf tfc --global
@@ -125,12 +145,16 @@ jf tf p --namespace=main --provider=docker --tag=v0.0.1
### Example template
We have an example template [here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/remote) that uses our [JFrog Docker](../platforms/jfrog.md) template
as the underlying module.
We have an example template
[here](https://github.com/coder/coder/tree/main/examples/templates/jfrog/remote)
that uses our [JFrog Docker](../platforms/jfrog.md) template as the underlying
module.
### Next up
Learn more about
- JFrog's Terraform Registry support [here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry).
- Configuring the JFrog toolchain inside a workspace [here](../platforms/jfrog.md).
- JFrog's Terraform Registry support
[here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry).
- Configuring the JFrog toolchain inside a workspace
[here](../platforms/jfrog.md).
docs/templates/open-in-coder.md
Vendored
+18 -8
View File
@@ -1,6 +1,7 @@
# Open in Coder
An "Open in Coder" button can be embedded into your git repos or internal wikis to allow developers to quickly launch a new workspace.
An "Open in Coder" button can be embedded into your git repos or internal wikis
to allow developers to quickly launch a new workspace.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/docs/images/templates/open-in-coder.mp4?raw=true" type="video/mp4">
@@ -9,13 +10,17 @@ Your browser does not support the video tag.
## How it works
To support any infrastructure and software stack, Coder provides a generic approach for "Open in Coder" flows.
To support any infrastructure and software stack, Coder provides a generic
approach for "Open in Coder" flows.
1. Set up [Git Authentication](../admin/git-providers.md#require-git-authentication-in-templates) in your Coder deployment
1. Set up
[Git Authentication](../admin/git-providers.md#require-git-authentication-in-templates)
in your Coder deployment
1. Modify your template to auto-clone repos:
> The id in the template's `coder_git_auth` data source must match the `CODER_GITAUTH_0_ID` in the Coder deployment configuration.
> The id in the template's `coder_git_auth` data source must match the
> `CODER_GITAUTH_0_ID` in the Coder deployment configuration.
- If you want the template to clone a specific git repo
@@ -46,7 +51,8 @@ To support any infrastructure and software stack, Coder provides a generic appro
> - `/home/coder/coder`
> - `coder` (relative to the home directory)
- If you want the template to support any repository via [parameters](./parameters.md)
- If you want the template to support any repository via
[parameters](./parameters.md)
```hcl
# Require git authentication to use this template
@@ -86,7 +92,9 @@ To support any infrastructure and software stack, Coder provides a generic appro
[![Open in Coder](https://YOUR_ACCESS_URL/open-in-coder.svg)](https://YOUR_ACCESS_URL/templates/YOUR_TEMPLATE/workspace)
```
> Be sure to replace `YOUR_ACCESS_URL` with your Coder access url (e.g. https://coder.example.com) and `YOUR_TEMPLATE` with the name of your template.
> Be sure to replace `YOUR_ACCESS_URL` with your Coder access url (e.g.
> https://coder.example.com) and `YOUR_TEMPLATE` with the name of your
> template.
1. Optional: pre-fill parameter values in the "Create Workspace" page
@@ -100,8 +108,10 @@ To support any infrastructure and software stack, Coder provides a generic appro
## Example: Kubernetes
For a full example of the Open in Coder flow in Kubernetes, check out [this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
For a full example of the Open in Coder flow in Kubernetes, check out
[this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
## Devcontainer support
Devcontainer support is on the roadmap. [Follow along here](https://github.com/coder/coder/issues/5559)
Devcontainer support is on the roadmap.
[Follow along here](https://github.com/coder/coder/issues/5559)
docs/templates/parameters.md
Vendored
+78 -37
View File
@@ -1,6 +1,7 @@
# Parameters
Templates can contain _parameters_, which allow prompting the user for additional information when creating workspaces in both the UI and CLI.
Templates can contain _parameters_, which allow prompting the user for
additional information when creating workspaces in both the UI and CLI.
![Parameters in Create Workspace screen](../images/parameters.png)
@@ -45,12 +46,15 @@ provider "docker" {
## Types
The following parameter types are supported: `string`, `list(string)`, `bool`, and `number`.
The following parameter types are supported: `string`, `list(string)`, `bool`,
and `number`.
### List of strings
List of strings is a specific parameter type, that can't be easily mapped to the default value, which is string type.
Parameters with the `list(string)` type must be converted to JSON arrays using [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
List of strings is a specific parameter type, that can't be easily mapped to the
default value, which is string type. Parameters with the `list(string)` type
must be converted to JSON arrays using
[jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode)
function.
```hcl
@@ -101,7 +105,9 @@ data "coder_parameter" "docker_host" {
## Required and optional parameters
A parameter is considered to be _required_ if it doesn't have the `default` property. The user **must** provide a value to this parameter before creating a workspace.
A parameter is considered to be _required_ if it doesn't have the `default`
property. The user **must** provide a value to this parameter before creating a
workspace.
```hcl
data "coder_parameter" "account_name" {
@@ -111,8 +117,8 @@ data "coder_parameter" "account_name" {
}
```
If a parameter contains the `default` property, Coder will use this value
if the user does not specify any:
If a parameter contains the `default` property, Coder will use this value if the
user does not specify any:
```hcl
data "coder_parameter" "base_image" {
@@ -122,7 +128,8 @@ data "coder_parameter" "base_image" {
}
```
Admins can also set the `default` property to an empty value so that the parameter field can remain empty:
Admins can also set the `default` property to an empty value so that the
parameter field can remain empty:
```hcl
data "coder_parameter" "dotfiles_url" {
@@ -133,7 +140,10 @@ data "coder_parameter" "dotfiles_url" {
}
```
Terraform [conditional expressions](https://developer.hashicorp.com/terraform/language/expressions/conditionals) can be used to determine whether the user specified a value for an optional parameter:
Terraform
[conditional expressions](https://developer.hashicorp.com/terraform/language/expressions/conditionals)
can be used to determine whether the user specified a value for an optional
parameter:
```hcl
resource "coder_agent" "main" {
@@ -150,7 +160,10 @@ resource "coder_agent" "main" {
## Mutability
Immutable parameters can be only set before workspace creation, or during update on the first usage to set the initial value for required parameters. The idea is to prevent users from modifying fragile or persistent workspace resources like volumes, regions, etc.:
Immutable parameters can be only set before workspace creation, or during update
on the first usage to set the initial value for required parameters. The idea is
to prevent users from modifying fragile or persistent workspace resources like
volumes, regions, etc.:
```hcl
data "coder_parameter" "region" {
@@ -161,16 +174,19 @@ data "coder_parameter" "region" {
}
```
It is allowed to modify the mutability state anytime. In case of emergency, template authors can temporarily allow for changing immutable parameters to fix an operational issue, but it is not
advised to overuse this opportunity.
It is allowed to modify the mutability state anytime. In case of emergency,
template authors can temporarily allow for changing immutable parameters to fix
an operational issue, but it is not advised to overuse this opportunity.
## Ephemeral parameters
Ephemeral parameters are introduced to users in the form of "build options." This functionality can be used to model
specific behaviors within a Coder workspace, such as reverting to a previous image, restoring from a volume snapshot, or
building a project without utilizing cache.
Ephemeral parameters are introduced to users in the form of "build options."
This functionality can be used to model specific behaviors within a Coder
workspace, such as reverting to a previous image, restoring from a volume
snapshot, or building a project without utilizing cache.
As these parameters are ephemeral in nature, subsequent builds will proceed in the standard manner.
As these parameters are ephemeral in nature, subsequent builds will proceed in
the standard manner.
```hcl
data "coder_parameter" "force_rebuild" {
@@ -185,12 +201,15 @@ data "coder_parameter" "force_rebuild" {
## Validation
Rich parameters support multiple validation modes - min, max, monotonic numbers, and regular expressions.
Rich parameters support multiple validation modes - min, max, monotonic numbers,
and regular expressions.
### Number
A _number_ parameter can be limited to boundaries - min, max. Additionally, the monotonicity (`increasing` or `decreasing`) between the current parameter value and the new one can be verified too.
Monotonicity can be enabled for resources that can't be shrunk without implications, for instance - disk volume size.
A _number_ parameter can be limited to boundaries - min, max. Additionally, the
monotonicity (`increasing` or `decreasing`) between the current parameter value
and the new one can be verified too. Monotonicity can be enabled for resources
that can't be shrunk without implications, for instance - disk volume size.
```hcl
data "coder_parameter" "instances" {
@@ -207,7 +226,9 @@ data "coder_parameter" "instances" {
### String
A _string_ parameter can have a regular expression defined to make sure that the parameter value matches the pattern. The `regex` property requires a corresponding `error` property.
A _string_ parameter can have a regular expression defined to make sure that the
parameter value matches the pattern. The `regex` property requires a
corresponding `error` property.
```hcl
data "coder_parameter" "project_id" {
@@ -224,21 +245,29 @@ data "coder_parameter" "project_id" {
### Legacy parameters are unsupported now
In Coder, workspaces using legacy parameters can't be deployed anymore. To address this, it is necessary to either remove or adjust incompatible templates.
In some cases, deleting a workspace with a hard dependency on a legacy parameter may be challenging. To cleanup unsupported workspaces, administrators are advised to take the following actions for affected templates:
In Coder, workspaces using legacy parameters can't be deployed anymore. To
address this, it is necessary to either remove or adjust incompatible templates.
In some cases, deleting a workspace with a hard dependency on a legacy parameter
may be challenging. To cleanup unsupported workspaces, administrators are
advised to take the following actions for affected templates:
1. Enable the `feature_use_managed_variables` provider flag.
2. Ensure that every legacy variable block has defined missing default values, or convert it to `coder_parameter`.
2. Ensure that every legacy variable block has defined missing default values,
or convert it to `coder_parameter`.
3. Push the new template version using UI or CLI.
4. Update unsupported workspaces to the newest template version.
5. Delete the affected workspaces that have been updated to the newest template version.
5. Delete the affected workspaces that have been updated to the newest template
version.
### Migration
> ⚠️ Migration is available until v0.24.0 (Jun 2023) release.
Terraform `variable` shouldn't be used for workspace scoped parameters anymore, and it's required to convert `variable` to `coder_parameter` resources. To make the migration smoother, there is a special property introduced -
`legacy_variable` and `legacy_variable_name` , which can link `coder_parameter` with a legacy variable.
Terraform `variable` shouldn't be used for workspace scoped parameters anymore,
and it's required to convert `variable` to `coder_parameter` resources. To make
the migration smoother, there is a special property introduced -
`legacy_variable` and `legacy_variable_name` , which can link `coder_parameter`
with a legacy variable.
```hcl
variable "legacy_cpu" {
@@ -263,33 +292,44 @@ data "coder_parameter" "cpu" {
1. Prepare and update a new template version:
- Add `coder_parameter` resource matching the legacy variable to migrate.
- Use `legacy_variable_name` and `legacy_variable` to link the `coder_parameter` to the legacy variable.
- Mark the new parameter as `mutable`, so that Coder will not block updating existing workspaces.
- Use `legacy_variable_name` and `legacy_variable` to link the
`coder_parameter` to the legacy variable.
- Mark the new parameter as `mutable`, so that Coder will not block updating
existing workspaces.
2. Update all workspaces to the updated template version. Coder will populate the added `coder_parameter`s with values from legacy variables.
2. Update all workspaces to the updated template version. Coder will populate
the added `coder_parameter`s with values from legacy variables.
3. Prepare another template version:
- Remove the migrated variables.
- Remove properties `legacy_variable` and `legacy_variable_name` from `coder_parameter`s.
- Remove properties `legacy_variable` and `legacy_variable_name` from
`coder_parameter`s.
4. Update all workspaces to the updated template version (2nd).
5. Prepare a third template version:
- Enable the `feature_use_managed_variables` provider flag to use managed Terraform variables for template customization. Once the flag is enabled, legacy variables won't be used.
- Enable the `feature_use_managed_variables` provider flag to use managed
Terraform variables for template customization. Once the flag is enabled,
legacy variables won't be used.
6. Update all workspaces to the updated template version (3rd).
7. Delete legacy parameters.
As a template improvement, the template author can consider making some of the new `coder_parameter` resources `mutable`.
As a template improvement, the template author can consider making some of the
new `coder_parameter` resources `mutable`.
## Terraform template-wide variables
> ⚠️ Flag `feature_use_managed_variables` is available until v0.25.0 (Jul 2023) release. After this release, template-wide Terraform variables will be enabled by default.
> ⚠️ Flag `feature_use_managed_variables` is available until v0.25.0 (Jul 2023)
> release. After this release, template-wide Terraform variables will be enabled
> by default.
As parameters are intended to be used only for workspace customization purposes, Terraform variables can be freely managed by the template author to build templates. Workspace users are not able to modify
template variables.
As parameters are intended to be used only for workspace customization purposes,
Terraform variables can be freely managed by the template author to build
templates. Workspace users are not able to modify template variables.
The template author can enable Terraform template-wide variables mode by specifying the following flag:
The template author can enable Terraform template-wide variables mode by
specifying the following flag:
```hcl
provider "coder" {
@@ -297,4 +337,5 @@ provider "coder" {
}
```
Once it's defined, coder will allow for modifying variables by using CLI and UI forms, but it will not be possible to use legacy parameters.
Once it's defined, coder will allow for modifying variables by using CLI and UI
forms, but it will not be possible to use legacy parameters.
docs/templates/resource-metadata.md
Vendored
+11 -6
View File
@@ -1,6 +1,8 @@
# Resource Metadata
Expose key workspace information to your users via [`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata) resources in your template code.
Expose key workspace information to your users via
[`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata)
resources in your template code.
![ui](../images/metadata-ui.png)
@@ -19,8 +21,8 @@ and any other Terraform resource attribute.
## Example
Expose the disk size, deployment name, and persistent
directory in a Kubernetes template with:
Expose the disk size, deployment name, and persistent directory in a Kubernetes
template with:
```hcl
resource "kubernetes_persistent_volume_claim" "root" {
@@ -57,7 +59,8 @@ resource "coder_metadata" "deployment" {
## Hiding resources in the UI
Some resources don't need to be exposed in the UI; this helps keep the workspace view clean for developers. To hide a resource, use the `hide` attribute:
Some resources don't need to be exposed in the UI; this helps keep the workspace
view clean for developers. To hide a resource, use the `hide` attribute:
```hcl
resource "coder_metadata" "hide_serviceaccount" {
@@ -73,7 +76,8 @@ resource "coder_metadata" "hide_serviceaccount" {
## Using custom resource icon
To use custom icons on your resources, use the `icon` attribute (must be a valid path or URL):
To use custom icons on your resources, use the `icon` attribute (must be a valid
path or URL):
```hcl
resource "coder_metadata" "resource_with_icon" {
@@ -95,7 +99,8 @@ To make easier for you to customize your resource we added some built-in icons:
- Widgets `/icon/widgets.svg`
- Database `/icon/database.svg`
We also have other icons related to the IDEs. You can see all the icons [here](https://github.com/coder/coder/tree/main/site/static/icon).
We also have other icons related to the IDEs. You can see all the icons
[here](https://github.com/coder/coder/tree/main/site/static/icon).
## Agent Metadata
docs/templates/resource-persistence.md
Vendored
+20 -16
View File
@@ -1,22 +1,23 @@
# Resource Persistence
Coder templates have full control over workspace ephemerality. In a
completely ephemeral workspace, there are zero resources in the Off state. In
a completely persistent workspace, there is no difference between the Off and
On states.
Coder templates have full control over workspace ephemerality. In a completely
ephemeral workspace, there are zero resources in the Off state. In a completely
persistent workspace, there is no difference between the Off and On states.
Most workspaces fall somewhere in the middle, persisting user data
such as filesystem volumes, but deleting expensive, reproducible resources
such as compute instances.
Most workspaces fall somewhere in the middle, persisting user data such as
filesystem volumes, but deleting expensive, reproducible resources such as
compute instances.
By default, all Coder resources are persistent, but
production templates **must** employ the practices laid out in this document
to prevent accidental deletion.
By default, all Coder resources are persistent, but production templates
**must** employ the practices laid out in this document to prevent accidental
deletion.
## Disabling Persistence
The [`coder_workspace` data source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace) exposes the `start_count = [0 | 1]` attribute that other
resources reference to become ephemeral.
The
[`coder_workspace` data source](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace)
exposes the `start_count = [0 | 1]` attribute that other resources reference to
become ephemeral.
For example:
@@ -45,8 +46,8 @@ resource "docker_volume" "home_volume" {
```
Because we depend on `coder_workspace.me.owner`, if the owner changes their
username, Terraform would recreate the volume (wiping its data!) the next
time the workspace restarts.
username, Terraform would recreate the volume (wiping its data!) the next time
the workspace restarts.
Therefore, persistent resource names must only depend on immutable IDs such as:
@@ -67,9 +68,12 @@ resource "docker_volume" "home_volume" {
## 🛡 Bulletproofing
Even if our persistent resource depends exclusively on static IDs, a change to
the `name` format or other attributes would cause Terraform to rebuild the resource.
the `name` format or other attributes would cause Terraform to rebuild the
resource.
Prevent Terraform from recreating the resource under any circumstance by setting the [`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
Prevent Terraform from recreating the resource under any circumstance by setting
the
[`ignore_changes = all` directive in the `lifecycle` block](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes).
```hcl
data "coder_workspace" "me" {