From e2f8f51f49400d9a23711b9a7746b0d4250c70cf Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 27 Sep 2024 10:27:28 +0100 Subject: [PATCH 1/3] chore(docs): update devcontainer docs --- docs/architecture/architecture.md | 3 -- docs/templates/dev-containers.md | 82 +++++++++++++++++++++++++------ 2 files changed, 68 insertions(+), 17 deletions(-) diff --git a/docs/architecture/architecture.md b/docs/architecture/architecture.md index 76c0a46dbef3b..c0e076ce2546d 100644 --- a/docs/architecture/architecture.md +++ b/docs/architecture/architecture.md @@ -346,9 +346,6 @@ across multiple regions and diverse cloud platforms. ### Dev Containers -Note: _Dev containers_ are at early stage and considered experimental at the -moment. - This architecture enhances a Coder workspace with a [development container](https://containers.dev/) setup built using the [envbuilder](https://github.com/coder/envbuilder) project. Workspace users have diff --git a/docs/templates/dev-containers.md b/docs/templates/dev-containers.md index 787955ada7098..2aaa8fe050b67 100644 --- a/docs/templates/dev-containers.md +++ b/docs/templates/dev-containers.md @@ -1,9 +1,9 @@ -# Dev Containers (alpha) +# Dev Containers [Development containers](https://containers.dev) are an open source specification for defining development environments. -[envbuilder](https://github.com/coder/envbuilder) is an open source project by +[Envbuilder](https://github.com/coder/envbuilder) is an open source project by Coder that runs dev containers via Coder templates and your underlying infrastructure. It can run on Docker or Kubernetes. @@ -22,16 +22,30 @@ Coder: 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 +[Envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a container from the `devcontainer.json` specified in the repo. +When using the [Envbuilder Terraform provider](#provider), a previously built +and cached image can be re-used directly, allowing instantaneous dev container +starts. + 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) +- [Devcontainers (Docker)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker) + provisions a development container using Docker. +- [Devcontainers (Kubernetes)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes) + provisioners a development container on the Kubernetes. +- [Google Compute Engine (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer) + runs a development container inside a single GCP instance. It also mounts the + Docker socket from the VM inside the container to enable Docker inside the + workspace. +- [AWS EC2 (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer) + runs a development container inside a single EC2 instance. It also mounts the + Docker socket from the VM inside the container to enble Docker inside the + workspace. ![Devcontainer parameter screen](../images/templates/devcontainers.png) @@ -41,18 +55,58 @@ Your template can prompt the user for a repo URL with ## Authentication 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. +git provider such as GitLab, to use Envbuilder. See the +[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md) +for more information. ## Caching -To improve build times, dev containers can be cached. Refer to the -[envbuilder documentation](https://github.com/coder/envbuilder/) for more -information. +To improve build times, dev containers can be cached. There are two main forms +of caching: + +1. **Layer Caching** caches individual layers and pushes them to a remote + registry. When building the image, Envbuilder will check the remote registry + for pre-existing layers. These will be fetched and extracted to disk instead + of building the layers from scratch. +2. **Image Caching** caches the _entire image_, skipping the build process + completely (except for post-build lifecycle scripts). + +Refer to the +[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md) +for more information. + +## Envbuilder Terraform Provider + +To support resuming from a cached image, use the +[Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder) +in your template. The provider will: + +1. Clone the remote Git repository, +2. Perform a 'dry-run' build of the dev container in the same manner as + Envbuilder would, +3. Check for the presence of a previously built image in the provided cache + repository, +4. Output the image remote reference in SHA256 form, if found. + +The above example templates will use the provider if a remote cache repository +is provided. + +If you are building your own Devcontainer template, you can consult the +[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image). +You may also wish to consult a +[documented example usage of the `envbuilder_cached_image` resource](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf). ## 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 provides two release channels: + +- **Stable:** available at + [`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder). + Tags `>=1.0.0` are considered stable. +- **Preview:** available at + [`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview). + This is built from the tip of `main`, and should be considered + **experimental** and prone to **breaking changes**. + +Refer to the [Envbuilder GitHub repo](https://github.com/coder/envbuilder/) for +more information and to submit feature requests or bug reports. From be0541f48d91a69b1bc4f096d64a7721ab8eaee8 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 27 Sep 2024 11:19:21 +0100 Subject: [PATCH 2/3] fixup! chore(docs): update devcontainer docs --- docs/templates/dev-containers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/templates/dev-containers.md b/docs/templates/dev-containers.md index 2aaa8fe050b67..1f56f9023cc46 100644 --- a/docs/templates/dev-containers.md +++ b/docs/templates/dev-containers.md @@ -44,7 +44,7 @@ iterate on their development environments. workspace. - [AWS EC2 (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer) runs a development container inside a single EC2 instance. It also mounts the - Docker socket from the VM inside the container to enble Docker inside the + Docker socket from the VM inside the container to enable Docker inside the workspace. ![Devcontainer parameter screen](../images/templates/devcontainers.png) From d8fa0bb7c30c3a4c8d0170d1899d0a5562a40af0 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Fri, 27 Sep 2024 13:59:45 +0100 Subject: [PATCH 3/3] fixup! chore(docs): update devcontainer docs --- docs/manifest.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 119da3108a06a..24e84f78c892f 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -271,8 +271,7 @@ { "title": "Dev Containers", "description": "Use Dev Containers in workspaces", - "path": "./templates/dev-containers.md", - "state": "alpha" + "path": "./templates/dev-containers.md" }, { "title": "Troubleshooting templates",