docs: add devcontainer templates (#8256)

* start

* start a template

* basic structure

* Update docs/templates/devcontainers.md

Co-authored-by: Sebastiaan ten Pas <sebastiaan@diggimedia.nl>

* Update examples/templates/devcontainer-docker/main.tf

Co-authored-by: Muhammad Atif Ali <atif@coder.com>

* add kubernetes template

* mention parameters

* fixups

* fixes from feedback

---------

Co-authored-by: Sebastiaan ten Pas <sebastiaan@diggimedia.nl>
Co-authored-by: Muhammad Atif Ali <atif@coder.com>
This commit is contained in:
Ben Potter
2023-07-12 10:22:39 -04:00
committed by GitHub
parent 19f58350f2
commit 280112a366
7 changed files with 570 additions and 0 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 251 KiB

View File

@ -176,6 +176,12 @@
"path": "./templates/docker-in-workspaces.md",
"icon_path": "./images/icons/docker.svg"
},
{
"title": "Devcontainers",
"description": "Use devcontainers in workspaces",
"path": "./templates/devcontainers.md",
"state": "alpha"
},
{
"title": "Terraform Modules",
"description": "Reuse code across Coder templates",

38
docs/templates/devcontainers.md vendored Normal file
View File

@ -0,0 +1,38 @@
# 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.
There are several benefits to adding a devcontainer-compatible template to Coder:
- 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.
## How it works
- 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 can edit the `devcontainer.json` in their workspace to rebuild to iterate on their development environments.
## Example templates
- [Docker](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
- [Kubernetes](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
![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.
## 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.
## Caching
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.

View File

@ -0,0 +1,36 @@
---
name: Devcontainers in Docker
description: Develop using devcontainers in Docker
tags: [local, docker]
icon: /icon/docker.png
---
# devcontainer-docker
Develop using [devcontainers](https://containers.dev) in Docker.
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
## How it works
Coder supports devcontainers with [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/v2/latest/templates/devcontainers).
## code-server
`code-server` is installed via the `startup_script` argument in the `coder_agent`
resource block. The `coder_app` resource is defined to access `code-server` through
the dashboard UI over `localhost:13337`.
## Extending this template
See the [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker) Terraform provider documentation to add the following features to your Coder template:
- SSH/TCP docker host
- Registry authentication
- Build args
- Volume mounts
- Custom container spec
- More
We also welcome contributions!

View File

@ -0,0 +1,248 @@
terraform {
required_providers {
coder = {
source = "coder/coder"
version = "0.11.0"
}
docker = {
source = "kreuzwerker/docker"
version = "3.0.2"
}
}
}
data "coder_provisioner" "me" {
}
provider "docker" {
}
data "coder_workspace" "me" {
}
resource "coder_agent" "main" {
arch = data.coder_provisioner.me.arch
os = "linux"
startup_script_timeout = 180
startup_script = <<-EOT
set -e
# install and start code-server
curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --prefix=/tmp/code-server --version 4.11.0
/tmp/code-server/bin/code-server --auth none --port 13337 >/tmp/code-server.log 2>&1 &
EOT
dir = "/worskpaces"
# These environment variables allow you to make Git commits right away after creating a
# workspace. Note that they take precedence over configuration defined in ~/.gitconfig!
# You can remove this block if you'd prefer to configure Git manually or using
# dotfiles. (see docs/dotfiles.md)
env = {
GIT_AUTHOR_NAME = "${data.coder_workspace.me.owner}"
GIT_COMMITTER_NAME = "${data.coder_workspace.me.owner}"
GIT_AUTHOR_EMAIL = "${data.coder_workspace.me.owner_email}"
GIT_COMMITTER_EMAIL = "${data.coder_workspace.me.owner_email}"
}
# The following metadata blocks are optional. They are used to display
# information about your workspace in the dashboard. You can remove them
# if you don't want to display any information.
# For basic resources, you can use the `coder stat` command.
# If you need more control, you can write your own script.
metadata {
display_name = "CPU Usage"
key = "0_cpu_usage"
script = "coder stat cpu"
interval = 10
timeout = 1
}
metadata {
display_name = "RAM Usage"
key = "1_ram_usage"
script = "coder stat mem"
interval = 10
timeout = 1
}
metadata {
display_name = "Home Disk"
key = "3_home_disk"
script = "coder stat disk --path $HOME"
interval = 60
timeout = 1
}
metadata {
display_name = "CPU Usage (Host)"
key = "4_cpu_usage_host"
script = "coder stat cpu --host"
interval = 10
timeout = 1
}
metadata {
display_name = "Memory Usage (Host)"
key = "5_mem_usage_host"
script = "coder stat mem --host"
interval = 10
timeout = 1
}
metadata {
display_name = "Load Average (Host)"
key = "6_load_host"
# get load avg scaled by number of cores
script = <<EOT
echo "`cat /proc/loadavg | awk '{ print $1 }'` `nproc`" | awk '{ printf "%0.2f", $1/$2 }'
EOT
interval = 60
timeout = 1
}
metadata {
display_name = "Swap Usage (Host)"
key = "7_swap_host"
script = <<EOT
free -b | awk '/^Swap/ { printf("%.1f/%.1f", $3/1024.0/1024.0/1024.0, $2/1024.0/1024.0/1024.0) }'
EOT
interval = 10
timeout = 1
}
}
resource "coder_app" "code-server" {
agent_id = coder_agent.main.id
slug = "code-server"
display_name = "code-server"
url = "http://localhost:13337/?folder=/workspaces"
icon = "/icon/code.svg"
subdomain = false
share = "owner"
healthcheck {
url = "http://localhost:13337/healthz"
interval = 5
threshold = 6
}
}
resource "docker_volume" "workspaces" {
name = "coder-${data.coder_workspace.me.id}"
# Protect the volume from being deleted due to changes in attributes.
lifecycle {
ignore_changes = all
}
# Add labels in Docker to keep track of orphan resources.
labels {
label = "coder.owner"
value = data.coder_workspace.me.owner
}
labels {
label = "coder.owner_id"
value = data.coder_workspace.me.owner_id
}
labels {
label = "coder.workspace_id"
value = data.coder_workspace.me.id
}
# This field becomes outdated if the workspace is renamed but can
# be useful for debugging or cleaning out dangling volumes.
labels {
label = "coder.workspace_name_at_creation"
value = data.coder_workspace.me.name
}
}
data "coder_parameter" "repo" {
name = "repo"
display_name = "Repository (auto)"
order = 1
description = "Select a repository to automatically clone and start working with a devcontainer."
mutable = true
option {
name = "vercel/next.js"
description = "The React Framework"
value = "https://github.com/vercel/next.js"
}
option {
name = "home-assistant/core"
description = "🏡 Open source home automation that puts local control and privacy first."
value = "https://github.com/home-assistant/core"
}
option {
name = "discourse/discourse"
description = "A platform for community discussion. Free, open, simple."
value = "https://github.com/discourse/discourse"
}
option {
name = "denoland/deno"
description = "A modern runtime for JavaScript and TypeScript."
value = "https://github.com/denoland/deno"
}
option {
name = "microsoft/vscode"
icon = "/icon/code.svg"
description = "Code editing. Redefined."
value = "https://github.com/microsoft/vscode"
}
option {
name = "Custom"
icon = "/emojis/1f5c3.png"
description = "Specify a custom repo URL below"
value = "custom"
}
}
data "coder_parameter" "custom_repo_url" {
name = "custom_repo"
display_name = "Repository URL (custom)"
order = 2
default = ""
description = "Optionally enter a custom repository URL, see [awesome-devcontainers](https://github.com/manekinekko/awesome-devcontainers)."
mutable = true
}
resource "docker_container" "workspace" {
count = data.coder_workspace.me.start_count
image = "ghcr.io/coder/envbuilder:0.1.3"
# Uses lower() to avoid Docker restriction on container names.
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
# Hostname makes the shell more user friendly: coder@my-workspace:~$
hostname = data.coder_workspace.me.name
# Use the docker gateway if the access URL is 127.0.0.1
env = [
"CODER_AGENT_TOKEN=${coder_agent.main.token}",
"CODER_AGENT_URL=${replace(data.coder_workspace.me.access_url, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")}",
"GIT_URL=${data.coder_parameter.repo.value == "custom" ? data.coder_parameter.custom_repo_url.value : data.coder_parameter.repo.value}",
"INIT_SCRIPT=${replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")}",
"FALLBACK_IMAGE=codercom/enterprise-base:ubuntu" # This image runs if builds fail
]
host {
host = "host.docker.internal"
ip = "host-gateway"
}
volumes {
container_path = "/workspaces"
volume_name = docker_volume.workspaces.name
read_only = false
}
# Add labels in Docker to keep track of orphan resources.
labels {
label = "coder.owner"
value = data.coder_workspace.me.owner
}
labels {
label = "coder.owner_id"
value = data.coder_workspace.me.owner_id
}
labels {
label = "coder.workspace_id"
value = data.coder_workspace.me.id
}
labels {
label = "coder.workspace_name"
value = data.coder_workspace.me.name
}
}

View File

@ -0,0 +1,17 @@
---
name: Devcontainers in Kubernetes
description: Develop using devcontainers in Kubernetes
tags: [local, kubernetes]
icon: /icon/kubernetes.png
---
# devcontainer-kubernetes
Develop using [devcontainers](https://containers.dev) in Kubernetes.
To get started, run `coder templates init`. When prompted, select this template.
Follow the on-screen instructions to proceed.
## How it works
Coder supports devcontainers with [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/v2/latest/templates/devcontainers).

View File

@ -0,0 +1,225 @@
terraform {
required_providers {
coder = {
source = "coder/coder"
version = "0.11.0"
}
kubernetes = {
source = "hashicorp/kubernetes"
version = "~> 2.3.2"
}
}
}
data "coder_provisioner" "me" {
}
provider "coder" {
}
variable "use_kubeconfig" {
type = bool
description = <<-EOF
Use host kubeconfig? (true/false)
Set this to false if the Coder host is itself running as a Pod on the same
Kubernetes cluster as you are deploying workspaces to.
Set this to true if the Coder host is running outside the Kubernetes cluster
for workspaces. A valid "~/.kube/config" must be present on the Coder host.
EOF
default = false
}
variable "namespace" {
type = string
description = "The Kubernetes namespace to create workspaces in (must exist prior to creating workspaces)"
}
provider "kubernetes" {
# Authenticate via ~/.kube/config or a Coder-specific ServiceAccount, depending on admin preferences
config_path = var.use_kubeconfig == true ? "~/.kube/config" : null
}
data "coder_workspace" "me" {
}
resource "coder_agent" "main" {
arch = data.coder_provisioner.me.arch
os = "linux"
startup_script_timeout = 180
startup_script = <<-EOT
set -e
# install and start code-server
curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --prefix=/tmp/code-server --version 4.11.0
/tmp/code-server/bin/code-server --auth none --port 13337 >/tmp/code-server.log 2>&1 &
EOT
dir = "/worskpaces"
# These environment variables allow you to make Git commits right away after creating a
# workspace. Note that they take precedence over configuration defined in ~/.gitconfig!
# You can remove this block if you'd prefer to configure Git manually or using
# dotfiles. (see docs/dotfiles.md)
env = {
GIT_AUTHOR_NAME = "${data.coder_workspace.me.owner}"
GIT_COMMITTER_NAME = "${data.coder_workspace.me.owner}"
GIT_AUTHOR_EMAIL = "${data.coder_workspace.me.owner_email}"
GIT_COMMITTER_EMAIL = "${data.coder_workspace.me.owner_email}"
}
}
resource "coder_app" "code-server" {
agent_id = coder_agent.main.id
slug = "code-server"
display_name = "code-server"
url = "http://localhost:13337/?folder=/workspaces"
icon = "/icon/code.svg"
subdomain = false
share = "owner"
healthcheck {
url = "http://localhost:13337/healthz"
interval = 5
threshold = 6
}
}
resource "kubernetes_persistent_volume_claim" "workspaces" {
metadata {
name = "coder-${data.coder_workspace.me.id}"
namespace = var.namespace
labels = {
"coder.owner" = data.coder_workspace.me.owner
"coder.owner_id" = data.coder_workspace.me.owner_id
"coder.workspace_id" = data.coder_workspace.me.id
"coder.workspace_name_at_creation" = data.coder_workspace.me.name
}
}
spec {
access_modes = ["ReadWriteOnce"]
resources {
requests = {
storage = "10Gi" // adjust as needed
}
}
}
lifecycle {
ignore_changes = all
}
}
data "coder_parameter" "repo" {
name = "repo"
display_name = "Repository (auto)"
order = 1
description = "Select a repository to automatically clone and start working with a devcontainer."
mutable = true
option {
name = "vercel/next.js"
description = "The React Framework"
value = "https://github.com/vercel/next.js"
}
option {
name = "home-assistant/core"
description = "🏡 Open source home automation that puts local control and privacy first."
value = "https://github.com/home-assistant/core"
}
option {
name = "discourse/discourse"
description = "A platform for community discussion. Free, open, simple."
value = "https://github.com/discourse/discourse"
}
option {
name = "denoland/deno"
description = "A modern runtime for JavaScript and TypeScript."
value = "https://github.com/denoland/deno"
}
option {
name = "microsoft/vscode"
icon = "/icon/code.svg"
description = "Code editing. Redefined."
value = "https://github.com/microsoft/vscode"
}
option {
name = "Custom"
icon = "/emojis/1f5c3.png"
description = "Specify a custom repo URL below"
value = "custom"
}
}
data "coder_parameter" "custom_repo_url" {
name = "custom_repo"
display_name = "Repository URL (custom)"
order = 2
default = ""
description = "Optionally enter a custom repository URL, see [awesome-devcontainers](https://github.com/manekinekko/awesome-devcontainers)."
mutable = true
}
resource "kubernetes_deployment" "workspace" {
metadata {
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
namespace = var.namespace
labels = {
"coder.owner" = data.coder_workspace.me.owner
"coder.owner_id" = data.coder_workspace.me.owner_id
"coder.workspace_id" = data.coder_workspace.me.id
"coder.workspace_name" = data.coder_workspace.me.name
}
}
spec {
replicas = data.coder_workspace.me.start_count
selector {
match_labels = {
"coder.workspace_id" = data.coder_workspace.me.id
}
}
template {
metadata {
labels = {
"coder.workspace_id" = data.coder_workspace.me.id
}
}
spec {
container {
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
image = "ghcr.io/coder/envbuilder:0.1.3"
env {
name = "CODER_AGENT_TOKEN"
value = coder_agent.main.token
}
env {
name = "CODER_AGENT_URL"
value = replace(data.coder_workspace.me.access_url, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")
}
env {
name = "GIT_URL"
value = data.coder_parameter.repo.value == "custom" ? data.coder_parameter.custom_repo_url.value : data.coder_parameter.repo.value
}
env {
name = "INIT_SCRIPT"
value = replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")
}
env {
name = "FALLBACK_IMAGE"
value = "codercom/enterprise-base:ubuntu"
}
volume_mount {
name = "workspaces"
mount_path = "/workspaces"
}
}
volume {
name = "workspaces"
persistent_volume_claim {
claim_name = kubernetes_persistent_volume_claim.workspaces.metadata.0.name
}
}
}
}
}
}