From 353fb8724a273387f8ef1c4754466ab5cf15f6f5 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Mon, 19 Sep 2022 12:33:31 -0400 Subject: [PATCH] add docs: "docker in docker" and "systemd in docker" (#4051) --- docs/images/icons/system.svg | 1 + docs/manifest.json | 6 + docs/templates/docker-in-docker.md | 294 +++++++++++++++++++++++++++++ 3 files changed, 301 insertions(+) create mode 100644 docs/images/icons/system.svg create mode 100644 docs/templates/docker-in-docker.md diff --git a/docs/images/icons/system.svg b/docs/images/icons/system.svg new file mode 100644 index 0000000000..618d0654da --- /dev/null +++ b/docs/images/icons/system.svg @@ -0,0 +1 @@ + diff --git a/docs/manifest.json b/docs/manifest.json index 6c3d4ab1ea..a0aa731d77 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -84,6 +84,12 @@ "description": "Learn how to expose resource data to users", "path": "./templates/resource-metadata.md", "icon_path": "./images/icons/table-rows.svg" + }, + { + "title": "Docker in Docker", + "description": "Use docker inside containerized templates", + "path": "./templates/docker-in-docker.md", + "icon_path": "./images/icons/docker.svg" } ] }, diff --git a/docs/templates/docker-in-docker.md b/docs/templates/docker-in-docker.md new file mode 100644 index 0000000000..75ec428cb8 --- /dev/null +++ b/docs/templates/docker-in-docker.md @@ -0,0 +1,294 @@ +There are a few ways to run Docker within container-based Coder workspaces. + +## Sysbox runtime (recommended) + +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: + +```hcl +resource "docker_container" "workspace" { + # ... + name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}" + image = "codercom/enterprise-base:ubuntu" + env = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"] + command = ["sh", "-c", coder_agent.main.init_script] + # Use the Sysbox container runtime (required) + runtime = "sysbox-runc" +} + +resource "coder_agent" "main" { + arch = data.coder_provisioner.me.arch + os = "linux" + startup_script = < Currently, the official [Kubernetes Terraform Provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest) does not support specifying a custom RuntimeClass. [mingfang/k8s](https://registry.terraform.io/providers/mingfang/k8s), a third-party provider, can be used instead. + +```hcl +resource "coder_agent" "main" { + os = "linux" + arch = "amd64" + dir = "/home/coder" + startup_script = < 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. + +## Privileged sidecar container + +While less secure, you can attach a [privileged container](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) to your templates. This may come in handy if your nodes cannot run Sysbox. + +### Use a privileged sidecar container in Docker-based templates: + +```hcl +resource "coder_agent" "main" { + os = "linux" + arch = "amd64" +} + +resource "docker_network" "private_network" { + name = "network-${data.coder_workspace.me.id}" +} + +resource "docker_container" "dind" { + image = "docker:dind" + privileged = true + name = "dind-${data.coder_workspace.me.id}" + entrypoint = ["dockerd", "-H", "tcp://0.0.0.0:2375"] + networks_advanced { + name = docker_network.private_network.name + } +} + +resource "docker_container" "workspace" { + count = data.coder_workspace.me.start_count + image = "codercom/enterprise-base:ubuntu" + name = "dev-${data.coder_workspace.me.id}" + command = ["sh", "-c", coder_agent.main.init_script] + env = [ + "CODER_AGENT_TOKEN=${coder_agent.main.token}", + "DOCKER_HOST=${docker_container.dind.name}:2375" + ] + networks_advanced { + name = docker_network.private_network.name + } +} +``` + +### Use a privileged sidecar container in Kubernetes-based templates: + +```hcl +resource "coder_agent" "main" { + os = "linux" + arch = "amd64" +} + +resource "kubernetes_pod" "main" { + count = data.coder_workspace.me.start_count + metadata { + name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}" + namespace = var.namespace + } + spec { + # Run a privileged dind (Docker in Docker) container + container { + name = "docker-sidecar" + image = "docker:dind" + security_context { + privileged = true + } + command = ["dockerd", "-H", "tcp://127.0.0.1:2375"] + } + container { + name = "dev" + image = "codercom/enterprise-base:ubuntu" + command = ["sh", "-c", coder_agent.main.init_script] + security_context { + run_as_user = "1000" + } + env { + name = "CODER_AGENT_TOKEN" + value = coder_agent.main.token + } + # Use the Docker daemon in the "docker-sidecar" container + env { + name = "DOCKER_HOST" + value = "localhost:2375" + } + } + } +} +``` + +## Systemd in Docker + +Additionally, [Sysbox](https://github.com/nestybox/sysbox) can be used to give workspaces full `systemd` capabilities. + +### Use systemd 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 and start systemd: + +```hcl +resource "docker_container" "workspace" { + image = "codercom/enterprise-base:ubuntu" + name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}" + + # Use Sysbox container runtime (required) + runtime = "sysbox-runc" + # Run as root in order to start systemd (required) + user = "0:0" + + # Start systemd and the Coder agent + command = ["sh", "-c", < Currently, the official [Kubernetes Terraform Provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest) does not support specifying a custom RuntimeClass. [mingfang/k8s](https://registry.terraform.io/providers/mingfang/k8s), a third-party provider, can be used instead. + +```hcl +terraform { + required_providers { + coder = { + source = "coder/coder" + } + k8s = { + source = "mingfang/k8s" + } + } +} + + +resource "coder_agent" "main" { + os = "linux" + arch = "amd64" + dir = "/home/coder" +} + +resource "k8s_core_v1_pod" "dev" { + count = data.coder_workspace.me.start_count + metadata { + name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}" + namespace = var.workspaces_namespace + annotations = { + "io.kubernetes.cri-o.userns-mode" = "auto:size=65536" + } + } + + + spec { + + # Use Sysbox container runtime (required) + runtime_class_name = "sysbox-runc" + + # Run as root in order to start systemd (required) + security_context { + run_asuser = 0 + fsgroup = 0 + } + + containers { + name = "dev" + env { + name = "CODER_AGENT_TOKEN" + value = coder_agent.main.token + } + image = "codercom/enterprise-base:ubuntu" + command = ["sh", "-c", <