From a7084aa07aedb787bd35ccc6654ea51a4699f716 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Tue, 15 Oct 2024 14:18:40 +0100 Subject: [PATCH] chore(examples): add devcontainer-docker and devcontainer-kubernetes templates to examples.go --- .../coder_templates_init_--help.golden | 2 +- docs/reference/cli/templates_init.md | 6 ++--- examples/examples.gen.json | 26 +++++++++++++++++++ examples/examples.go | 2 ++ 4 files changed, 32 insertions(+), 4 deletions(-) diff --git a/cli/testdata/coder_templates_init_--help.golden b/cli/testdata/coder_templates_init_--help.golden index 5a1d4ffd947bf..01bf926a9e6ea 100644 --- a/cli/testdata/coder_templates_init_--help.golden +++ b/cli/testdata/coder_templates_init_--help.golden @@ -6,7 +6,7 @@ USAGE: Get started with a templated template. OPTIONS: - --id aws-devcontainer|aws-linux|aws-windows|azure-linux|do-linux|docker|gcp-devcontainer|gcp-linux|gcp-vm-container|gcp-windows|kubernetes|nomad-docker|scratch + --id aws-devcontainer|aws-linux|aws-windows|azure-linux|devcontainer-docker|devcontainer-kubernetes|do-linux|docker|gcp-devcontainer|gcp-linux|gcp-vm-container|gcp-windows|kubernetes|nomad-docker|scratch Specify a given example template by ID. ——— diff --git a/docs/reference/cli/templates_init.md b/docs/reference/cli/templates_init.md index d29088a4bde5e..ddbd84ab3d2c8 100644 --- a/docs/reference/cli/templates_init.md +++ b/docs/reference/cli/templates_init.md @@ -14,8 +14,8 @@ coder templates init [flags] [directory] ### --id -| | | -| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Type | aws-devcontainer\|aws-linux\|aws-windows\|azure-linux\|do-linux\|docker\|gcp-devcontainer\|gcp-linux\|gcp-vm-container\|gcp-windows\|kubernetes\|nomad-docker\|scratch | +| | | +| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Type | aws-devcontainer\|aws-linux\|aws-windows\|azure-linux\|devcontainer-docker\|devcontainer-kubernetes\|do-linux\|docker\|gcp-devcontainer\|gcp-linux\|gcp-vm-container\|gcp-windows\|kubernetes\|nomad-docker\|scratch | Specify a given example template by ID. diff --git a/examples/examples.gen.json b/examples/examples.gen.json index fbf8283ca0def..92260bb4c42b6 100644 --- a/examples/examples.gen.json +++ b/examples/examples.gen.json @@ -80,6 +80,32 @@ ], "markdown": "\n# Remote Development on Docker Containers\n\nProvision Docker containers as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Infrastructure\n\nThe VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:\n\n```sh\n# Add coder user to Docker group\nsudo adduser coder docker\n\n# Restart Coder server\nsudo systemctl restart coder\n\n# Test Docker\nsudo -u coder docker ps\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- Docker image (built by Docker socket and kept locally)\n- Docker container pod (ephemeral)\n- Docker volume (persistent on `/home/coder`)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n### Editing the image\n\nEdit the `Dockerfile` and run `coder templates push` to update workspaces.\n" }, + { + "id": "devcontainer-docker", + "url": "", + "name": "Devcontainers (Docker)", + "description": "Provision envbuilder containers as Coder workspaces", + "icon": "/icon/docker.png", + "tags": [ + "container", + "docker", + "devcontainer" + ], + "markdown": "\n# Remote Development on Docker Containers (with Devcontainers)\n\nProvision Devcontainers as [Coder workspaces](https://coder.com/docs/workspaces) in Docker with this example template.\n\n## Prerequisites\n\n### Infrastructure\n\nCoder must have access to a running Docker socket, and the `coder` user must be a member of the `docker` group:\n\n```shell\n# Add coder user to Docker group\nsudo usermod -aG docker coder\n\n# Restart Coder server\nsudo systemctl restart coder\n\n# Test Docker\nsudo -u coder docker ps\n```\n\n## Architecture\n\nCoder supports Devcontainers via [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/templates/dev-containers).\n\nThis template provisions the following resources:\n\n- Envbuilder cached image (conditional, persistent) using [`terraform-provider-envbuilder`](https://github.com/coder/terraform-provider-envbuilder)\n- Docker image (persistent) using [`envbuilder`](https://github.com/coder/envbuilder)\n- Docker container (ephemeral)\n- Docker volume (persistent on `/workspaces`)\n\nThe Git repository is cloned inside the `/workspaces` volume if not present.\nAny local changes to the Devcontainer files inside the volume will be applied when you restart the workspace.\nKeep in mind that any tools or files outside of `/workspaces` or not added as part of the Devcontainer specification are not persisted.\nEdit the `devcontainer.json` instead!\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## Docker-in-Docker\n\nSee the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/docker.md) for information on running Docker containers inside a devcontainer built by Envbuilder.\n\n## Caching\n\nTo speed up your builds, you can use a container registry as a cache.\nWhen creating the template, set the parameter `cache_repo` to a valid Docker repository.\n\nFor example, you can run a local registry:\n\n```shell\ndocker run --detach \\\n --volume registry-cache:/var/lib/registry \\\n --publish 5000:5000 \\\n --name registry-cache \\\n --net=host \\\n registry:2\n```\n\nThen, when creating the template, enter `localhost:5000/devcontainer-cache` for the parameter `cache_repo`.\n\nSee the [Envbuilder Terraform Provider Examples](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf/) for a more complete example of how the provider works.\n\n\u003e [!NOTE] We recommend using a registry cache with authentication enabled.\n\u003e To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_docker_config_path`\n\u003e with the path to a Docker config `.json` on disk containing valid credentials for the registry.\n" + }, + { + "id": "devcontainer-kubernetes", + "url": "", + "name": "Devcontainers (Kubernetes)", + "description": "Provision envbuilder pods as Coder workspaces", + "icon": "/icon/k8s.png", + "tags": [ + "container", + "kubernetes", + "devcontainer" + ], + "markdown": "\n# Remote Development on Kubernetes Pods (with Devcontainers)\n\nProvision Devcontainers as [Coder workspaces](https://coder.com/docs/workspaces) on Kubernetes with this example template.\n\n## Prerequisites\n\n### Infrastructure\n\n**Cluster**: This template requires an existing Kubernetes cluster.\n\n**Container Image**: This template uses the [envbuilder image](https://github.com/coder/envbuilder) to build a Devcontainer from a `devcontainer.json`.\n\n**(Optional) Cache Registry**: Envbuilder can utilize a Docker registry as a cache to speed up workspace builds. The [envbuilder Terraform provider](https://github.com/coder/terraform-provider-envbuilder) will check the contents of the cache to determine if a prebuilt image exists. In the case of some missing layers in the registry (partial cache miss), Envbuilder can still utilize some of the build cache from the registry.\n\n### Authentication\n\nThis template authenticates using a `~/.kube/config`, if present on the server, or via built-in authentication if the Coder provisioner is running on Kubernetes with an authorized ServiceAccount. To use another [authentication method](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication), edit the template.\n\n## Architecture\n\nCoder 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/templates/dev-containers).\n\nThis template provisions the following resources:\n\n- Kubernetes deployment (ephemeral)\n- Kubernetes persistent volume claim (persistent on `/workspaces`)\n- Envbuilder cached image (optional, persistent).\n\nThis template will fetch a Git repo containing a `devcontainer.json` specified by the `repo` parameter, and builds it\nwith [`envbuilder`](https://github.com/coder/envbuilder).\nThe Git repository is cloned inside the `/workspaces` volume if not present.\nAny local changes to the Devcontainer files inside the volume will be applied when you restart the workspace.\nAs you might suspect, any tools or files outside of `/workspaces` or not added as part of the Devcontainer specification are not persisted.\nEdit the `devcontainer.json` instead!\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## Caching\n\nTo speed up your builds, you can use a container registry as a cache.\nWhen creating the template, set the parameter `cache_repo`.\n\nSee the [Envbuilder Terraform Provider Examples](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf/) for a more complete example of how the provider works.\n\n\u003e [!NOTE] We recommend using a registry cache with authentication enabled.\n\u003e To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_dockerconfig_secret`\n\u003e with the name of a Kubernetes secret in the same namespace as Coder. The secret must contain the key `.dockerconfigjson`.\n" + }, { "id": "gcp-devcontainer", "url": "", diff --git a/examples/examples.go b/examples/examples.go index af2dc80bc6016..ef3a47549528d 100644 --- a/examples/examples.go +++ b/examples/examples.go @@ -29,6 +29,8 @@ var ( //go:embed templates/azure-linux //go:embed templates/do-linux //go:embed templates/docker + //go:embed templates/devcontainer-docker + //go:embed templates/devcontainer-kubernetes //go:embed templates/gcp-devcontainer //go:embed templates/gcp-linux //go:embed templates/gcp-vm-container