diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 8f733fdccaa7d..bda26a8f0552e 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -1,4 +1,4 @@ -# Provisioners +# External provisioners By default, the Coder server runs [built-in provisioner daemons](../cli/server.md#provisioner-daemons), which execute `terraform` during workspace and template builds. However, there are sometimes benefits to running external provisioner daemons: diff --git a/docs/images/autostart.png b/docs/images/autostart.png index f96eba3bee971..a0855e7ae8ec4 100644 Binary files a/docs/images/autostart.png and b/docs/images/autostart.png differ diff --git a/docs/images/autostop.png b/docs/images/autostop.png index e86249e45d1cb..2b93efd757a4f 100644 Binary files a/docs/images/autostop.png and b/docs/images/autostop.png differ diff --git a/docs/images/creating-workspace-ui.png b/docs/images/creating-workspace-ui.png new file mode 100644 index 0000000000000..27bb47cbe7d15 Binary files /dev/null and b/docs/images/creating-workspace-ui.png differ diff --git a/docs/images/schedule.png b/docs/images/schedule.png index 224cf575c63c4..16c861d534658 100644 Binary files a/docs/images/schedule.png and b/docs/images/schedule.png differ diff --git a/docs/images/template-variables.png b/docs/images/template-variables.png new file mode 100644 index 0000000000000..3a2429de7ecb7 Binary files /dev/null and b/docs/images/template-variables.png differ diff --git a/docs/images/templates/build-template.png b/docs/images/templates/build-template.png new file mode 100644 index 0000000000000..53052794d068b Binary files /dev/null and b/docs/images/templates/build-template.png differ diff --git a/docs/images/templates/choosing-edit-template.gif b/docs/images/templates/choosing-edit-template.gif new file mode 100644 index 0000000000000..faf49624e1a18 Binary files /dev/null and b/docs/images/templates/choosing-edit-template.gif differ diff --git a/docs/images/templates/coder-login-web.png b/docs/images/templates/coder-login-web.png new file mode 100644 index 0000000000000..161ff92a00401 Binary files /dev/null and b/docs/images/templates/coder-login-web.png differ diff --git a/docs/images/templates/coder-session-token.png b/docs/images/templates/coder-session-token.png new file mode 100644 index 0000000000000..f982550901813 Binary files /dev/null and b/docs/images/templates/coder-session-token.png differ diff --git a/docs/images/templates/create-template.png b/docs/images/templates/create-template.png new file mode 100644 index 0000000000000..3705cea3a6b50 Binary files /dev/null and b/docs/images/templates/create-template.png differ diff --git a/docs/images/templates/create-workspace.png b/docs/images/templates/create-workspace.png new file mode 100644 index 0000000000000..cb2a6678c6bf9 Binary files /dev/null and b/docs/images/templates/create-workspace.png differ diff --git a/docs/images/templates/develop-in-docker-template.png b/docs/images/templates/develop-in-docker-template.png new file mode 100644 index 0000000000000..bbd812d3109e5 Binary files /dev/null and b/docs/images/templates/develop-in-docker-template.png differ diff --git a/docs/images/templates/edit-files.png b/docs/images/templates/edit-files.png new file mode 100644 index 0000000000000..e9ae92a72ef8a Binary files /dev/null and b/docs/images/templates/edit-files.png differ diff --git a/docs/images/templates/edit-source-code.png b/docs/images/templates/edit-source-code.png new file mode 100644 index 0000000000000..6eafd4caaeac7 Binary files /dev/null and b/docs/images/templates/edit-source-code.png differ diff --git a/docs/images/templates/new-workspace.png b/docs/images/templates/new-workspace.png new file mode 100644 index 0000000000000..85fdd002d8bce Binary files /dev/null and b/docs/images/templates/new-workspace.png differ diff --git a/docs/images/templates/publish.png b/docs/images/templates/publish.png new file mode 100644 index 0000000000000..bd72230a425fd Binary files /dev/null and b/docs/images/templates/publish.png differ diff --git a/docs/images/templates/select-template.png b/docs/images/templates/select-template.png new file mode 100644 index 0000000000000..4210064de8479 Binary files /dev/null and b/docs/images/templates/select-template.png differ diff --git a/docs/images/templates/source-code.png b/docs/images/templates/source-code.png new file mode 100644 index 0000000000000..641b97171c0cb Binary files /dev/null and b/docs/images/templates/source-code.png differ diff --git a/docs/images/templates/starter-templates-button.png b/docs/images/templates/starter-templates-button.png new file mode 100644 index 0000000000000..d8607abc06007 Binary files /dev/null and b/docs/images/templates/starter-templates-button.png differ diff --git a/docs/images/templates/starter-templates.png b/docs/images/templates/starter-templates.png new file mode 100644 index 0000000000000..2008a41f5b4b0 Binary files /dev/null and b/docs/images/templates/starter-templates.png differ diff --git a/docs/images/templates/template-architecture.png b/docs/images/templates/template-architecture.png new file mode 100644 index 0000000000000..6d84ac27738d3 Binary files /dev/null and b/docs/images/templates/template-architecture.png differ diff --git a/docs/images/templates/template-tour.png b/docs/images/templates/template-tour.png new file mode 100644 index 0000000000000..d5a75f5155fdb Binary files /dev/null and b/docs/images/templates/template-tour.png differ diff --git a/docs/images/templates/template-variables.png b/docs/images/templates/template-variables.png new file mode 100644 index 0000000000000..e900fb9f3c6dc Binary files /dev/null and b/docs/images/templates/template-variables.png differ diff --git a/docs/images/templates/update.png b/docs/images/templates/update.png new file mode 100644 index 0000000000000..799a96cbc4ac3 Binary files /dev/null and b/docs/images/templates/update.png differ diff --git a/docs/images/templates/use-template.png b/docs/images/templates/use-template.png new file mode 100644 index 0000000000000..e8e11a15ba040 Binary files /dev/null and b/docs/images/templates/use-template.png differ diff --git a/docs/images/templates/workspace-apps.png b/docs/images/templates/workspace-apps.png new file mode 100644 index 0000000000000..cf4f8061899e6 Binary files /dev/null and b/docs/images/templates/workspace-apps.png differ diff --git a/docs/images/templates/workspace-ready.png b/docs/images/templates/workspace-ready.png new file mode 100644 index 0000000000000..8f4fc70d9c598 Binary files /dev/null and b/docs/images/templates/workspace-ready.png differ diff --git a/docs/images/workspace-update.png b/docs/images/workspace-update.png new file mode 100644 index 0000000000000..2ae1fcd483e61 Binary files /dev/null and b/docs/images/workspace-update.png differ diff --git a/docs/manifest.json b/docs/manifest.json index b0981de6a3088..a1a6b637cd652 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -134,75 +134,86 @@ }, { "title": "Templates", - "description": "Learn about templates, which define the infrastructure underlying workspaces", + "description": "Templates define the infrastructure for workspaces", "path": "./templates/index.md", "icon_path": "./images/icons/picture.svg", "children": [ { - "title": "Templates & Terraform", - "description": "Learn what makes up a template", - "path": "./templates/concepts.md", + "title": "Working with templates", + "description": "Creating, editing, and updating templates", + "path": "./templates/creating.md" + }, + { + "title": "Your first template", + "description": "A tutorial for creating and editing your first template", + "path": "./templates/tutorial.md" + }, + { + "title": "Guided tour", + "description": "Create a template from scratch", + "path": "./templates/tour.md" + }, + { + "title": "Setting up templates", + "description": "Best practices for writing templates", + "path": "./templates/best-practices.md", "children": [ { - "title": "Parameters", - "description": "Use parameters to customize templates", - "path": "./templates/parameters.md", - "icon_path": "./images/icons/code.svg" + "title": "Change management", + "description": "Versioning templates with git and CI", + "path": "./templates/change-management.md", + "icon_path": "./images/icons/git.svg" }, { - "title": "Terraform Modules", - "description": "Reuse code across Coder templates", - "path": "./templates/modules.md" + "title": "Provider authentication", + "description": "Authenticate the provisioner", + "path": "./templates/authentication.md", + "icon_path": "./images/icons/key.svg" }, { - "title": "Agent Metadata", - "description": "Learn how to expose live agent information to users", - "path": "./templates/agent-metadata.md", - "icon_path": "./images/icons/table-rows.svg" + "title": "Resource persistence", + "description": "How resource persistence works in Coder", + "path": "./templates/resource-persistence.md", + "icon_path": "./images/icons/infinity.svg" }, { - "title": "Resource Metadata", - "description": "Learn how to expose resource data to users", - "path": "./templates/resource-metadata.md", - "icon_path": "./images/icons/table-rows.svg" + "title": "Terraform modules", + "description": "Reuse code across Coder templates", + "path": "./templates/modules.md" } ] }, { - "title": "Best Practices", - "description": "Best practices for writing/managing templates", - "path": "./templates/best-practices.md", + "title": "Customizing templates", + "description": "Give information and options to workspace users", + "path": "./templates/customizing.md", "children": [ { - "title": "Provider Authentication", - "description": "Learn how to authenticate the provisioner", - "path": "./templates/authentication.md", - "icon_path": "./images/icons/key.svg" + "title": "Agent metadata", + "description": "Show operational metrics in the workspace", + "path": "./templates/agent-metadata.md" }, { - "title": "Resource Persistence", - "description": "Learn how resource persistence works in Coder", - "path": "./templates/resource-persistence.md", - "icon_path": "./images/icons/infinity.svg" + "title": "Resource metadata", + "description": "Show information in the workspace about template resources", + "path": "./templates/resource-metadata.md" }, { - "title": "Change Management", - "description": "Learn how to source-control templates with git and CI", - "path": "./templates/change-management.md", - "icon_path": "./images/icons/git.svg" + "title": "Parameters", + "description": "Prompt the user for additional information about a workspace", + "path": "./templates/parameters.md" } ] }, - { "title": "Open in Coder", - "description": "Learn how to add an \"Open in Coder\" button to your repos", + "description": "Add an \"Open in Coder\" button to your repos", "path": "./templates/open-in-coder.md", "icon_path": "./images/icons/key.svg" }, { - "title": "Docker in Workspaces", - "description": "Use docker inside containerized templates", + "title": "Docker in workspaces", + "description": "Use Docker inside containerized templates", "path": "./templates/docker-in-workspaces.md", "icon_path": "./images/icons/docker.svg" }, @@ -211,6 +222,11 @@ "description": "Use devcontainers in workspaces", "path": "./templates/devcontainers.md", "state": "alpha" + }, + { + "title": "Troubleshooting templates", + "description": "Fix common template problems", + "path": "./templates/troubleshooting.md" } ] }, diff --git a/docs/templates/agent-metadata.md b/docs/templates/agent-metadata.md index 34a8c19a76760..0481c789fe8d2 100644 --- a/docs/templates/agent-metadata.md +++ b/docs/templates/agent-metadata.md @@ -1,20 +1,26 @@ -# Agent Metadata +# Agent metadata ![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). +You can show live operational metrics to workspace users with agent +metadata. 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). +You specify agent metadata in the +[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent). ## 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 examples use the [`coder stat`](../cli/stat.md) command. +This is useful for determining CPU and memory usage of the VM or +container that the workspace is running in, which is more accurate +than resource usage about the workspace's host. Here's a standard set of metadata snippets for Linux agents: @@ -82,11 +88,13 @@ resource "coder_agent" "main" { } ``` -## Utilities +## Useful utilities + +You can also show agent metadata for information about the workspace's host. [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: +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 @@ -94,9 +102,9 @@ MiB Mem : 16009.0 total, 493.7 free, 4624.8 used, 10890.5 buff/cache 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: +[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: ```text procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu----- @@ -104,10 +112,10 @@ 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 -like: +[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 --total-cpu-usage-- -dsk/total- -net/total- ---paging-- ---system-- @@ -115,11 +123,11 @@ usr sys idl wai stl| read writ| recv send| in out | int csw 1 1 98 0 0|3422k 25M| 0 0 | 153k 904k| 123k 174k ``` -## DB Write Load +## Managing the database 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 Coder 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 @@ -131,7 +139,8 @@ For example, let's say you have - each with 6 metadata snippets - with an average interval of 4 seconds -You can expect `(10 * 6 * 2) / 4` or 30 writes per second. +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. diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md index 4f25be1711b74..54e742a0f8033 100644 --- a/docs/templates/authentication.md +++ b/docs/templates/authentication.md @@ -7,28 +7,42 @@

-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. +The Coder server's +[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner) +process needs to authenticate with other provider APIs to provision +workspaces. There are two approaches to do this: -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). +- Pass credentials to the provisioner as parameters. +- Preferred: Execute the Coder server in an environment that is + authenticated with the provider. -Cloud providers for which the Terraform provider supports authenticated environments include +We encourage the latter approach where supported: + +- Simplifies the template. +- Keeps provider credentials out of Coder's database, making it + a less valuable target for attackers. +- Compatible with agent-based authentication schemes, which handle + credential rotation or ensure the credentials are not written to disk. + +Generally, you can set up an environment to provide credentials to +Coder in these ways: + +- A well-known location on disk. For example, `~/.aws/credentials` for + AWS on POSIX systems. +- Environment variables. + +It is usually sufficient to authenticate using the CLI or SDK for the +provider before running Coder, but check the Terraform provider's +documentation for details. + +These platforms have Terraform providers that support authenticated +environments: - [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs) - [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) - [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) - [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. - -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. +Other providers might also support authenticated environments. Check +the [documentation of the Terraform +provider](https://registry.terraform.io/browse/providers) for details. diff --git a/docs/templates/best-practices.md b/docs/templates/best-practices.md index 35fc9a72df2c2..1a0a09586285e 100644 --- a/docs/templates/best-practices.md +++ b/docs/templates/best-practices.md @@ -1,3 +1,7 @@ # Template best practices -Templates are very flexible +We recommend a few ways to manage workspace resources, authentication, +and versioning. + + + diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md index a1add78ec64f8..8e9445dc0ebd7 100644 --- a/docs/templates/change-management.md +++ b/docs/templates/change-management.md @@ -1,6 +1,8 @@ # 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. You can [install Coder](../install/) in CI/CD pipelines to push new +template versions. ```console # Install the Coder CLI @@ -25,7 +27,7 @@ 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). - -> 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). +For an example, see how we push our development image and template +[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml). diff --git a/docs/templates/concepts.md b/docs/templates/concepts.md deleted file mode 100644 index fbe4bda584b91..0000000000000 --- a/docs/templates/concepts.md +++ /dev/null @@ -1,154 +0,0 @@ -# Template concepts - -Coder templates are written in [Terraform](https://terraform.io). All Terraform modules, resources, and properties can be provisioned by Coder. The Coder server essentially runs a `terraform apply` every time a workspace is created/started/stopped. - -Haven't written Terraform before? Check out Hashicorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials). - -## Architecture - -This is a simplified diagram of our [Kubernetes example template](https://github.com/coder/coder/blob/main/examples/templates/kubernetes/main.tf). Keep reading for a breakdown of each concept. - -![Template architecture](https://user-images.githubusercontent.com/22407953/257021139-8c95a731-c131-4c4d-85cc-eed6a52e015c.png) - -## Coder Terraform Provider - -The [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest) makes it possible for standard Terraform resources (e.g. `kubernetes_deployment`) to connect to Coder. Additionally, the provider lets you to customize the behavior of workspaces using your template. - -```hcl -terraform { - required_providers { - coder = { - source = "coder/coder" - } - } -} -``` - -### coder_agent - -All templates need to create & run a Coder agent in order for developers to connect to their workspaces. The Coder agent is a service that runs inside the compute aspect of your workspace (typically a VM or container). You do not need to have any open ports, but the compute will need `curl` access to the Coder server. - -This snippet creates the agent, runs it inside the container via the `entrypoint`, and authenticates to Coder via the agent's token. - -```hcl -resource "coder_agent" "main" { - os = "linux" - arch = "amd64" -} - -resource "kubernetes_deployment" "workspace" { - entrypoint = ["sh", "-c", coder_agent.main.init_script] - env = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"] - # ... -} -``` - -Agents can also run startup scripts, set environment variables, and provide [metadata](../agent-metadata.md) about the workspace (e.g. CPU usage). Read the [coder_agent docs](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) for more details. - -### coder_workspace - -This data source provides details about the state of a workspace, such as its name, owner, and whether the workspace is being started or stopped. - -The following snippet will create a container when the workspace is being started, and delete the container when it is stopped using Terraform's [count](https://developer.hashicorp.com/terraform/language/meta-arguments/count) meta-argument. - -```hcl -data "coder_workspace" "me" {} - -# Delete the container when workspace is stopped (count = 0) -resource "kubernetes_deployment" "workspace" { - count = data.coder_workspace.me.transition == "start" ? 1 : 0 - # ... -} - -# Persist the volume, even if stopped -resource "docker_volume" "projects" {} -``` - -### coder_app - -Web apps that are running inside the workspace (e.g. `http://localhost:8080`) can be forwarded to the Coder dashboard with the `coder_app` resource. This is commonly used for [web IDEs](../../ides/web-ides.md) such as code-server, RStudio, and JupyterLab. External apps, such as links to internal wikis or cloud consoles can also be embedded here. - -Apps are rendered on the workspace page: - -![Apps in Coder workspace](https://user-images.githubusercontent.com/22407953/257020191-97a19ff0-83ca-4275-a699-113f6c97a9ab.png) - -The apps themselves have to be installed & running on the workspace. This can be done via the agent's startup script. See [web IDEs](../ides/web-ides.md) for some examples. - -```hcl -# coder_agent will install and start code-server -resource "coder_agent" "main" { - # ... - startup_script =< Per-workspace settings can be defined via [Parameters](./parameters.md). - -## Best practices - -Before making major changes or creating your own template, we recommend reading these best practices: - -- [Resource Persistence](./resource-persistence.md): Control which resources are persistent/ephemeral and avoid accidental disk deletion. -- [Provider Authentication](./provider-authentication.md): Securely authenticate with cloud APIs with Terraform -- [Change Management](./change-management.md): Manage Coder templates in git with CI/CD pipelines. - -## Use cases - -- [Devcontainers](./devcontainers.md): Add devcontainer support to your Coder templates. -- [Docker in Workspaces](./docker-in-workspaces.md): Add docker-in-Docker support or even run system-level services. -- [Open in Coder](./open-in-coder.md): Auto-create a workspace from your GitHub repository or internal wiki with deep links. diff --git a/docs/templates/creating.md b/docs/templates/creating.md new file mode 100644 index 0000000000000..753cb1f61fd38 --- /dev/null +++ b/docs/templates/creating.md @@ -0,0 +1,94 @@ +# Working with templates + +You create and edit Coder templates as [Terraform](./concepts.md) +configuration files (`.tf`) and any supporting files, like a README or +configuration files for other services. + +## Who creates templates? + +The [Template Admin](../admin/users.md) role (and above) can create +templates. End users, like developers, create workspaces from them. + +Templates can also be [managed with git](./change-management.md), +allowing any developer to propose changes to a template. + +You can give different users and groups access to templates with +[role-based access control](../admin/rbac.md). + +## Starter templates + +We provide starter templates for common cloud providers, like AWS, and +orchestrators, like Kubernetes. From there, you can modify them to use +your own images, VPC, cloud credentials, and so on. Coder supports all +Terraform resources and properties, so fear not if your favorite cloud +provider isn't here! + +![Starter templates](../images/templates/starter-templates.png) + +If you prefer to use Coder on the [command line](../cli.md), use +`coder templates init`. + +> Coder starter templates are also available on our [GitHub +> repo](https://github.com/coder/coder/tree/main/examples/templates). + +## Community Templates + +As well as Coder's starter templates, you can see a list of community +templates by our users +[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md). + +## Editing templates + +Our starter templates are meant to be modified for your use cases. You +can edit any template's files directly in the Coder dashboard. + +![Editing a template](../images/templates/choosing-edit-template.gif) + +If you'd prefer to use the CLI, use `coder templates pull`, edit the +template files, then `coder templates push`. + +> Even if you are a Terraform expert, we suggest reading our [guided +> tour](./tour.md). + +## Updating templates + +Coder tracks a template's versions, keeping all developer workspaces +up-to-date. When you publish a new version, developers are notified to +get the latest infrastructure, software, or security patches. Learn +more about [change management](./change-management.md). + +![Updating a template](../images/templates/update.png) + +## 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. + +In the UI, navigate to the template you want to delete, and select the dropdown +in the right-hand corner of the page to delete the template. + +![delete-template](../images/delete-template.png) + +Using the CLI, login to Coder and run the following command to delete a +template: + +```shell +coder templates delete +``` + +### 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. + +> Terraform's +> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy) +> and +> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes) +> meta-arguments can be used to prevent accidental data loss. + +## Next steps + +- [Your first template](./tutorial.md) diff --git a/docs/templates/customizing.md b/docs/templates/customizing.md new file mode 100644 index 0000000000000..a69fbce519f13 --- /dev/null +++ b/docs/templates/customizing.md @@ -0,0 +1,7 @@ +# Customizing templates + +You can give developers more information and control over their +workspaces: + + + diff --git a/docs/templates/devcontainers.md b/docs/templates/devcontainers.md index 3a92e79a90843..96b799728ad3c 100644 --- a/docs/templates/devcontainers.md +++ b/docs/templates/devcontainers.md @@ -1,20 +1,33 @@ # 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. -There are several benefits to adding a devcontainer-compatible template to Coder: +[envbuilder](https://github.com/coder/envbuilder) is an open source +project by Coder that runs devcontainers via Coder templates and your +underlying infrastructure. It can run on Docker or Kubernetes. -- 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. +There are several benefits to adding a devcontainer-compatible +template to Coder: -## How it works +- Drop-in migration from Codespaces (or any existing repositories that + use devcontainers) +- Easier to start projects from Coder. Just create a new workspace + then pick a starter devcontainer. +- Developer teams can "bring their own image." No need for platform + teams to manage complex images, registries, and CI pipelines. -- Coder admins add a devcontainer-compatible template to Coder (envbuilder can run on Docker or Kubernetes) +## How it works -- 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. +A Coder admin adds a devcontainer-compatible template to Coder +(envbuilder). Then 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 +36,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. +Your template can prompt the user for a repo URL with +[Parameters](./parameters.md). ## 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, such as +Artifactory, or git provider such as GitLab, to use envbuilder. See +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. diff --git a/docs/templates/docker-in-workspaces.md b/docs/templates/docker-in-workspaces.md index c0e0cf9bc351a..350f175b5223d 100644 --- a/docs/templates/docker-in-workspaces.md +++ b/docs/templates/docker-in-workspaces.md @@ -11,11 +11,20 @@ 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). ### 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" { @@ -44,7 +53,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 { @@ -109,43 +121,61 @@ 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: - -- No custom runtime installation or management on your Kubernetes 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. 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 + - 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 @@ -170,15 +200,19 @@ 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: +Before using Podman, please review the following 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 cat < ⚠️ **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 might 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. @@ -345,10 +381,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 { diff --git a/docs/templates/index.md b/docs/templates/index.md index 06b44c9ccf8b7..75f0a37e47e8e 100644 --- a/docs/templates/index.md +++ b/docs/templates/index.md @@ -1,52 +1,8 @@ # Templates -Templates define the underlying infrastructure that workspaces run on. All Coder workspaces are created from a -template. +Templates define the underlying infrastructure that Coder +[workspaces](../workspaces.md) run on. All workspaces are created from +templates. -## Who creates templates? - -The [Template Admin](../admin/users.md) role (and above) can create templates. End users (developers) create workspaces from them. However, templates can also be [managed via git](./change-management.md), allowing any developer to propose changes to a template. - -> [Template RBAC](../admin/rbac.md) allows you to give different users & groups access to templates. - -## Starter templates - -We provide starter templates for common cloud providers (e.g. AWS) and orchestrators (e.g. Kubernetes). From there, you can modify them with [Terraform](https://terraform.io) to use your own images, VPC, cloud credentials, etc. All Terraform resources and properties are supported, so fear not if your favorite cloud isn't here! - -![Starter templates](https://user-images.githubusercontent.com/22407953/256705348-e6fb2963-27f5-414f-9f5c-345cd3b7ee28.png) - -If you'd prefer to use the CLI, use `coder templates init`. - -> The Terraform code for our starter templates are avalible on our [GitHub](https://github.com/coder/coder/tree/main/examples/templates). - -## Editing templates - -Our starter templates are meant to me modified work for your use cases! You can edit the Terraform code for a template directly in the UI. - -![Editing a template](https://user-images.githubusercontent.com/22407953/256706060-71fb48f4-9a1b-42ad-9380-0ecc02db3218.gif) - - -If you'd prefer to use the CLI, use `coder templates pull` and `coder templates push`. - -> Even if you are a Terraform expert, we suggest reading our full guide on [writing Coder templates](./managing.md). - -## Template updates - -Templates are versioned, keeping all developer workspaces up-to-date. When a new version is published, developers are notified to get the latest infrastructure, software, or security patches. - -![Template update screen](https://user-images.githubusercontent.com/22407953/256712740-96121f81-a3c8-4be0-90dc-c1c4cabed634.png) - -## Template parameters - -You'll likely want to hardcode certain properties for workspaces (e.g. "security group, VPC"). Others can be exposed via parameters to give developers flexibility (e.g. instance size, GitHub repo URL). - -Paramaters let users customize their individual workspaces: - -![Parameters in templates](https://user-images.githubusercontent.com/22407953/256707889-18baf2be-2dae-4eb2-ae89-71e5b00248f8.png) - -> Paramaters are defined via the template's Terraform code. [Learn more](./parameters.md) - -## Next steps - -- [Template structure](./structure.md) -- [Template structure](./structure.md) + + diff --git a/docs/templates/modules.md b/docs/templates/modules.md index 06827bc2c0fbd..15104773fa25e 100644 --- a/docs/templates/modules.md +++ b/docs/templates/modules.md @@ -1,8 +1,12 @@ -# Template inheritance +# Reusing template code -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). +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: +You can store these modules externally from your Coder deployment, +like in a git repository or a Terraform registry. This example shows +how to reference a module from your template: ```hcl data "coder_workspace" "me" {} @@ -25,13 +29,21 @@ 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 access +limited to the repository 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 the necessary 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 that you have `git` +installed and the `coder` user has access to the following files: ```sh # /home/coder/.gitconfig @@ -46,13 +58,19 @@ If you are running Coder on a VM, make sure you have `git` installed and the `co 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 might 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 export NAMESPACE=coder diff --git a/docs/templates/open-in-coder.md b/docs/templates/open-in-coder.md index d179fabd36187..9a9d46e6fd79c 100644 --- a/docs/templates/open-in-coder.md +++ b/docs/templates/open-in-coder.md @@ -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. +You can embed an "Open in Coder" button into your git repos or +internal wikis to let developers quickly launch a new workspace.