From ae00187ad5f3afa4f49f1589f3f22ba5ef6fbd41 Mon Sep 17 00:00:00 2001 From: Lucas Melin Date: Sun, 2 Mar 2025 14:53:50 -0500 Subject: [PATCH 1/4] docs: fix formatting of note callouts --- docs/admin/provisioners.md | 6 ++++-- docs/admin/templates/extending-templates/parameters.md | 3 ++- examples/templates/aws-devcontainer/README.md | 3 ++- examples/templates/docker-devcontainer/README.md | 3 ++- examples/templates/gcp-devcontainer/README.md | 3 ++- examples/templates/kubernetes-devcontainer/README.md | 3 ++- 6 files changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 1a27cf1d8f25a..837784328d1b5 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -166,7 +166,8 @@ inside the Terraform. See the [workspace tags documentation](../admin/templates/extending-templates/workspace-tags.md) for more information. -> [!NOTE] Workspace tags defined with the `coder_workspace_tags` data source +> [!NOTE] +> Workspace tags defined with the `coder_workspace_tags` data source > template **do not** automatically apply to the template import job! You may > need to specify the desired tags when importing the template. @@ -190,7 +191,8 @@ However, it will not pick up any build jobs that do not have either of the from templates with the tag `scope=user` set, or build jobs from templates in different organizations. -> [!NOTE] If you only run tagged provisioners, you will need to specify a set of +> [!NOTE] +> If you only run tagged provisioners, you will need to specify a set of > tags that matches at least one provisioner for _all_ template import jobs and > workspace build jobs. > diff --git a/docs/admin/templates/extending-templates/parameters.md b/docs/admin/templates/extending-templates/parameters.md index 2c4801c08e82b..95031bf4646c4 100644 --- a/docs/admin/templates/extending-templates/parameters.md +++ b/docs/admin/templates/extending-templates/parameters.md @@ -79,7 +79,8 @@ data "coder_parameter" "security_groups" { } ``` -> [!NOTE] Overriding a `list(string)` on the CLI is tricky because: +> [!NOTE] +> Overriding a `list(string)` on the CLI is tricky because: > > - `--parameter "parameter_name=parameter_value"` is parsed as CSV. > - `parameter_value` is parsed as JSON. diff --git a/examples/templates/aws-devcontainer/README.md b/examples/templates/aws-devcontainer/README.md index 36d30f62ba286..f5dd9f7349308 100644 --- a/examples/templates/aws-devcontainer/README.md +++ b/examples/templates/aws-devcontainer/README.md @@ -96,7 +96,8 @@ When creating the template, set the parameter `cache_repo` to a valid Docker rep See 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. -> [!NOTE] We recommend using a registry cache with authentication enabled. +> [!NOTE] +> We recommend using a registry cache with authentication enabled. > To allow Envbuilder to authenticate with a registry cache hosted on ECR, specify an IAM instance > profile that has read and write access to the given registry. For more information, see the > [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html). diff --git a/examples/templates/docker-devcontainer/README.md b/examples/templates/docker-devcontainer/README.md index 7b58c5b8cde86..3026a21fc8657 100644 --- a/examples/templates/docker-devcontainer/README.md +++ b/examples/templates/docker-devcontainer/README.md @@ -71,6 +71,7 @@ Then, when creating the template, enter `localhost:5000/devcontainer-cache` for See 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. -> [!NOTE] We recommend using a registry cache with authentication enabled. +> [!NOTE] +> We recommend using a registry cache with authentication enabled. > To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_docker_config_path` > with the path to a Docker config `.json` on disk containing valid credentials for the registry. diff --git a/examples/templates/gcp-devcontainer/README.md b/examples/templates/gcp-devcontainer/README.md index 8ad5fe21fa3e4..e77508d4ed7ad 100644 --- a/examples/templates/gcp-devcontainer/README.md +++ b/examples/templates/gcp-devcontainer/README.md @@ -70,7 +70,8 @@ When creating the template, set the parameter `cache_repo` to a valid Docker rep See 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. -> [!NOTE] We recommend using a registry cache with authentication enabled. +> [!NOTE] +> We recommend using a registry cache with authentication enabled. > To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_docker_config_path` > with the path to a Docker config `.json` on disk containing valid credentials for the registry. diff --git a/examples/templates/kubernetes-devcontainer/README.md b/examples/templates/kubernetes-devcontainer/README.md index 35bb6f1013d40..d044405f09f59 100644 --- a/examples/templates/kubernetes-devcontainer/README.md +++ b/examples/templates/kubernetes-devcontainer/README.md @@ -52,6 +52,7 @@ When creating the template, set the parameter `cache_repo`. See 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. -> [!NOTE] We recommend using a registry cache with authentication enabled. +> [!NOTE] +> We recommend using a registry cache with authentication enabled. > To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_dockerconfig_secret` > with the name of a Kubernetes secret in the same namespace as Coder. The secret must contain the key `.dockerconfigjson`. From c2aa3596109a2b1d6294d1a22a6e64f6eeb64814 Mon Sep 17 00:00:00 2001 From: Lucas Melin Date: Mon, 3 Mar 2025 06:46:51 -0500 Subject: [PATCH 2/4] docs: replace GitHub-style note callouts with blockquotes --- docs/admin/provisioners.md | 30 ++++++----- .../extending-templates/parameters.md | 53 ++++++++++--------- 2 files changed, 46 insertions(+), 37 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 837784328d1b5..ebb1a17f55eef 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -166,10 +166,13 @@ inside the Terraform. See the [workspace tags documentation](../admin/templates/extending-templates/workspace-tags.md) for more information. -> [!NOTE] -> Workspace tags defined with the `coder_workspace_tags` data source -> template **do not** automatically apply to the template import job! You may -> need to specify the desired tags when importing the template. +
+ +Workspace tags defined with the `coder_workspace_tags` data source +template **do not** automatically apply to the template import job! You may +need to specify the desired tags when importing the template. + +
A provisioner can run a given build job if one of the below is true: @@ -191,14 +194,17 @@ However, it will not pick up any build jobs that do not have either of the from templates with the tag `scope=user` set, or build jobs from templates in different organizations. -> [!NOTE] -> If you only run tagged provisioners, you will need to specify a set of -> tags that matches at least one provisioner for _all_ template import jobs and -> workspace build jobs. -> -> You may wish to run at least one additional provisioner with no additional -> tags so that provisioner jobs with no additional tags defined will be picked -> up instead of potentially remaining in the Pending state indefinitely. +
+ +If you only run tagged provisioners, you will need to specify a set of +tags that matches at least one provisioner for _all_ template import jobs and +workspace build jobs. + +You may wish to run at least one additional provisioner with no additional +tags so that provisioner jobs with no additional tags defined will be picked +up instead of potentially remaining in the Pending state indefinitely. + +
This is illustrated in the below table: diff --git a/docs/admin/templates/extending-templates/parameters.md b/docs/admin/templates/extending-templates/parameters.md index 95031bf4646c4..15b59d978a37a 100644 --- a/docs/admin/templates/extending-templates/parameters.md +++ b/docs/admin/templates/extending-templates/parameters.md @@ -79,31 +79,34 @@ data "coder_parameter" "security_groups" { } ``` -> [!NOTE] -> Overriding a `list(string)` on the CLI is tricky because: -> -> - `--parameter "parameter_name=parameter_value"` is parsed as CSV. -> - `parameter_value` is parsed as JSON. -> -> So, to properly specify a `list(string)` with the `--parameter` CLI argument, -> you will need to take care of both CSV quoting and shell quoting. -> -> For the above example, to override the default values of the `security_groups` -> parameter, you will need to pass the following argument to `coder create`: -> -> ```shell -> --parameter "\"security_groups=[\"\"DevOps Security Group\"\",\"\"Backend Security Group\"\"]\"" -> ``` -> -> Alternatively, you can use `--rich-parameter-file` to work around the above -> issues. This allows you to specify parameters as YAML. An equivalent parameter -> file for the above `--parameter` is provided below: -> -> ```yaml -> security_groups: -> - DevOps Security Group -> - Backend Security Group -> ``` +
+ +Overriding a `list(string)` on the CLI is tricky because: + +- `--parameter "parameter_name=parameter_value"` is parsed as CSV. +- `parameter_value` is parsed as JSON. + +So, to properly specify a `list(string)` with the `--parameter` CLI argument, +you will need to take care of both CSV quoting and shell quoting. + +For the above example, to override the default values of the `security_groups` +parameter, you will need to pass the following argument to `coder create`: + +```shell +--parameter "\"security_groups=[\"\"DevOps Security Group\"\",\"\"Backend Security Group\"\"]\"" +``` + +Alternatively, you can use `--rich-parameter-file` to work around the above +issues. This allows you to specify parameters as YAML. An equivalent parameter +file for the above `--parameter` is provided below: + +```yaml +security_groups: + - DevOps Security Group + - Backend Security Group +``` + +
## Options From 225c08b99a0a7bc4933d37f8b2fa8d04a219e316 Mon Sep 17 00:00:00 2001 From: Lucas Melin Date: Wed, 5 Mar 2025 12:14:52 -0500 Subject: [PATCH 3/4] docs: switch back to GitHub-style note callouts This reverts commit c2aa3596109a2b1d6294d1a22a6e64f6eeb64814. --- docs/admin/provisioners.md | 30 +++++------ .../extending-templates/parameters.md | 53 +++++++++---------- 2 files changed, 37 insertions(+), 46 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index ebb1a17f55eef..837784328d1b5 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -166,13 +166,10 @@ inside the Terraform. See the [workspace tags documentation](../admin/templates/extending-templates/workspace-tags.md) for more information. -
- -Workspace tags defined with the `coder_workspace_tags` data source -template **do not** automatically apply to the template import job! You may -need to specify the desired tags when importing the template. - -
+> [!NOTE] +> Workspace tags defined with the `coder_workspace_tags` data source +> template **do not** automatically apply to the template import job! You may +> need to specify the desired tags when importing the template. A provisioner can run a given build job if one of the below is true: @@ -194,17 +191,14 @@ However, it will not pick up any build jobs that do not have either of the from templates with the tag `scope=user` set, or build jobs from templates in different organizations. -
- -If you only run tagged provisioners, you will need to specify a set of -tags that matches at least one provisioner for _all_ template import jobs and -workspace build jobs. - -You may wish to run at least one additional provisioner with no additional -tags so that provisioner jobs with no additional tags defined will be picked -up instead of potentially remaining in the Pending state indefinitely. - -
+> [!NOTE] +> If you only run tagged provisioners, you will need to specify a set of +> tags that matches at least one provisioner for _all_ template import jobs and +> workspace build jobs. +> +> You may wish to run at least one additional provisioner with no additional +> tags so that provisioner jobs with no additional tags defined will be picked +> up instead of potentially remaining in the Pending state indefinitely. This is illustrated in the below table: diff --git a/docs/admin/templates/extending-templates/parameters.md b/docs/admin/templates/extending-templates/parameters.md index 15b59d978a37a..95031bf4646c4 100644 --- a/docs/admin/templates/extending-templates/parameters.md +++ b/docs/admin/templates/extending-templates/parameters.md @@ -79,34 +79,31 @@ data "coder_parameter" "security_groups" { } ``` -
- -Overriding a `list(string)` on the CLI is tricky because: - -- `--parameter "parameter_name=parameter_value"` is parsed as CSV. -- `parameter_value` is parsed as JSON. - -So, to properly specify a `list(string)` with the `--parameter` CLI argument, -you will need to take care of both CSV quoting and shell quoting. - -For the above example, to override the default values of the `security_groups` -parameter, you will need to pass the following argument to `coder create`: - -```shell ---parameter "\"security_groups=[\"\"DevOps Security Group\"\",\"\"Backend Security Group\"\"]\"" -``` - -Alternatively, you can use `--rich-parameter-file` to work around the above -issues. This allows you to specify parameters as YAML. An equivalent parameter -file for the above `--parameter` is provided below: - -```yaml -security_groups: - - DevOps Security Group - - Backend Security Group -``` - -
+> [!NOTE] +> Overriding a `list(string)` on the CLI is tricky because: +> +> - `--parameter "parameter_name=parameter_value"` is parsed as CSV. +> - `parameter_value` is parsed as JSON. +> +> So, to properly specify a `list(string)` with the `--parameter` CLI argument, +> you will need to take care of both CSV quoting and shell quoting. +> +> For the above example, to override the default values of the `security_groups` +> parameter, you will need to pass the following argument to `coder create`: +> +> ```shell +> --parameter "\"security_groups=[\"\"DevOps Security Group\"\",\"\"Backend Security Group\"\"]\"" +> ``` +> +> Alternatively, you can use `--rich-parameter-file` to work around the above +> issues. This allows you to specify parameters as YAML. An equivalent parameter +> file for the above `--parameter` is provided below: +> +> ```yaml +> security_groups: +> - DevOps Security Group +> - Backend Security Group +> ``` ## Options From 0fe27eddac77f493751629904745043ec9b0fe75 Mon Sep 17 00:00:00 2001 From: Lucas Melin Date: Wed, 5 Mar 2025 14:24:42 -0500 Subject: [PATCH 4/4] chore: regenerate examples.gen.json --- examples/examples.gen.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/examples.gen.json b/examples/examples.gen.json index 83201b5243961..dda06d5850b6f 100644 --- a/examples/examples.gen.json +++ b/examples/examples.gen.json @@ -13,7 +13,7 @@ "persistent", "devcontainer" ], - "markdown": "\n# Remote Development on AWS EC2 VMs using a Devcontainer\n\nProvision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs) with this example template.\n![Architecture Diagram](./architecture.svg)\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nBy default, this template authenticates to AWS using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\nThe simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.\n\nTo use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n\t\"Version\": \"2012-10-17\",\n\t\"Statement\": [\n\t\t{\n\t\t\t\"Sid\": \"VisualEditor0\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:GetDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeIamInstanceProfileAssociations\",\n\t\t\t\t\"ec2:DescribeTags\",\n\t\t\t\t\"ec2:DescribeInstances\",\n\t\t\t\t\"ec2:DescribeInstanceTypes\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:DescribeInstanceCreditSpecifications\",\n\t\t\t\t\"ec2:DescribeImages\",\n\t\t\t\t\"ec2:ModifyDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeVolumes\"\n\t\t\t],\n\t\t\t\"Resource\": \"*\"\n\t\t},\n\t\t{\n\t\t\t\"Sid\": \"CoderResources\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:DescribeInstanceAttribute\",\n\t\t\t\t\"ec2:UnmonitorInstances\",\n\t\t\t\t\"ec2:TerminateInstances\",\n\t\t\t\t\"ec2:StartInstances\",\n\t\t\t\t\"ec2:StopInstances\",\n\t\t\t\t\"ec2:DeleteTags\",\n\t\t\t\t\"ec2:MonitorInstances\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:ModifyInstanceAttribute\",\n\t\t\t\t\"ec2:ModifyInstanceCreditSpecification\"\n\t\t\t],\n\t\t\t\"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n\t\t\t\"Condition\": {\n\t\t\t\t\"StringEquals\": {\n\t\t\t\t\t\"aws:ResourceTag/Coder_Provisioned\": \"true\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t]\n}\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- AWS Instance\n\nCoder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\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` to a valid Docker repository in the form `host.tld/path/to/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 a registry cache hosted on ECR, specify an IAM instance\n\u003e profile that has read and write access to the given registry. For more information, see the\n\u003e [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html).\n\u003e\n\u003e Alternatively, you can 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\n## code-server\n\n`code-server` is installed via the [`code-server`](https://registry.coder.com/modules/code-server) registry module. For a list of all modules and templates pplease check [Coder Registry](https://registry.coder.com).\n" + "markdown": "\n# Remote Development on AWS EC2 VMs using a Devcontainer\n\nProvision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs) with this example template.\n![Architecture Diagram](./architecture.svg)\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nBy default, this template authenticates to AWS using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\nThe simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.\n\nTo use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n\t\"Version\": \"2012-10-17\",\n\t\"Statement\": [\n\t\t{\n\t\t\t\"Sid\": \"VisualEditor0\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:GetDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeIamInstanceProfileAssociations\",\n\t\t\t\t\"ec2:DescribeTags\",\n\t\t\t\t\"ec2:DescribeInstances\",\n\t\t\t\t\"ec2:DescribeInstanceTypes\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:DescribeInstanceCreditSpecifications\",\n\t\t\t\t\"ec2:DescribeImages\",\n\t\t\t\t\"ec2:ModifyDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeVolumes\"\n\t\t\t],\n\t\t\t\"Resource\": \"*\"\n\t\t},\n\t\t{\n\t\t\t\"Sid\": \"CoderResources\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:DescribeInstanceAttribute\",\n\t\t\t\t\"ec2:UnmonitorInstances\",\n\t\t\t\t\"ec2:TerminateInstances\",\n\t\t\t\t\"ec2:StartInstances\",\n\t\t\t\t\"ec2:StopInstances\",\n\t\t\t\t\"ec2:DeleteTags\",\n\t\t\t\t\"ec2:MonitorInstances\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:ModifyInstanceAttribute\",\n\t\t\t\t\"ec2:ModifyInstanceCreditSpecification\"\n\t\t\t],\n\t\t\t\"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n\t\t\t\"Condition\": {\n\t\t\t\t\"StringEquals\": {\n\t\t\t\t\t\"aws:ResourceTag/Coder_Provisioned\": \"true\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t]\n}\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- AWS Instance\n\nCoder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\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` to a valid Docker repository in the form `host.tld/path/to/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]\n\u003e We recommend using a registry cache with authentication enabled.\n\u003e To allow Envbuilder to authenticate with a registry cache hosted on ECR, specify an IAM instance\n\u003e profile that has read and write access to the given registry. For more information, see the\n\u003e [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html).\n\u003e\n\u003e Alternatively, you can 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\n## code-server\n\n`code-server` is installed via the [`code-server`](https://registry.coder.com/modules/code-server) registry module. For a list of all modules and templates pplease check [Coder Registry](https://registry.coder.com).\n" }, { "id": "aws-linux", @@ -91,7 +91,7 @@ "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" + "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]\n\u003e 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": "gcp-devcontainer", @@ -105,7 +105,7 @@ "gcp", "devcontainer" ], - "markdown": "\n# Remote Development in a Devcontainer on Google Compute Engine\n\n![Architecture Diagram](./architecture.svg)\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n\n## Architecture\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- GCP VM (persistent) with a running Docker daemon\n- GCP Disk (persistent, mounted to root)\n- [Envbuilder container](https://github.com/coder/envbuilder) inside the GCP VM\n\nCoder persists the root volume. The full filesystem is preserved when the workspace restarts.\nWhen the GCP VM starts, a startup script runs that ensures a running Docker daemon, and starts\nan Envbuilder container using this Docker daemon. The Docker socket is also mounted inside the container to allow running Docker containers inside the workspace.\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` to a valid Docker repository in the form `host.tld/path/to/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\n## code-server\n\n`code-server` is installed via the [`code-server`](https://registry.coder.com/modules/code-server) registry module. Please check [Coder Registry](https://registry.coder.com) for a list of all modules and templates.\n" + "markdown": "\n# Remote Development in a Devcontainer on Google Compute Engine\n\n![Architecture Diagram](./architecture.svg)\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Google Cloud. For example, run `gcloud auth application-default login` to\nimport credentials on the system and user running coderd. For other ways to\nauthenticate [consult the Terraform\ndocs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials).\n\nCoder requires a Google Cloud Service Account to provision workspaces. To create\na service account:\n\n1. Navigate to the [CGP\n console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),\n and select your Cloud project (if you have more than one project associated\n with your account)\n\n1. Provide a service account name (this name is used to generate the service\n account ID)\n\n1. Click **Create and continue**, and choose the following IAM roles to grant to\n the service account:\n\n - Compute Admin\n - Service Account User\n\n Click **Continue**.\n\n1. Click on the created key, and navigate to the **Keys** tab.\n\n1. Click **Add key** \u003e **Create new key**.\n\n1. Generate a **JSON private key**, which will be what you provide to Coder\n during the setup process.\n\n## Architecture\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- GCP VM (persistent) with a running Docker daemon\n- GCP Disk (persistent, mounted to root)\n- [Envbuilder container](https://github.com/coder/envbuilder) inside the GCP VM\n\nCoder persists the root volume. The full filesystem is preserved when the workspace restarts.\nWhen the GCP VM starts, a startup script runs that ensures a running Docker daemon, and starts\nan Envbuilder container using this Docker daemon. The Docker socket is also mounted inside the container to allow running Docker containers inside the workspace.\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` to a valid Docker repository in the form `host.tld/path/to/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]\n\u003e 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\n## code-server\n\n`code-server` is installed via the [`code-server`](https://registry.coder.com/modules/code-server) registry module. Please check [Coder Registry](https://registry.coder.com) for a list of all modules and templates.\n" }, { "id": "gcp-linux", @@ -169,7 +169,7 @@ "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" + "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]\n\u003e 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": "nomad-docker",