diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 0767c2da92d55..62a35c1ede1ad 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -1,4 +1,4 @@ -# Provisioners +# External provisioners By default, the Coder server runs [built-in provisioner daemons](../cli/server.md#provisioner-daemons), which diff --git a/docs/images/autostart.png b/docs/images/autostart.png index f96eba3bee971..a0855e7ae8ec4 100644 Binary files a/docs/images/autostart.png and b/docs/images/autostart.png differ diff --git a/docs/images/autostop.png b/docs/images/autostop.png index e86249e45d1cb..2b93efd757a4f 100644 Binary files a/docs/images/autostop.png and b/docs/images/autostop.png differ diff --git a/docs/images/creating-workspace-ui.png b/docs/images/creating-workspace-ui.png new file mode 100644 index 0000000000000..27bb47cbe7d15 Binary files /dev/null and b/docs/images/creating-workspace-ui.png differ diff --git a/docs/images/schedule.png b/docs/images/schedule.png index 224cf575c63c4..16c861d534658 100644 Binary files a/docs/images/schedule.png and b/docs/images/schedule.png differ diff --git a/docs/images/template-variables.png b/docs/images/template-variables.png new file mode 100644 index 0000000000000..3a2429de7ecb7 Binary files /dev/null and b/docs/images/template-variables.png differ diff --git a/docs/images/templates/build-template.png b/docs/images/templates/build-template.png new file mode 100644 index 0000000000000..53052794d068b Binary files /dev/null and b/docs/images/templates/build-template.png differ diff --git a/docs/images/templates/choosing-edit-template.gif b/docs/images/templates/choosing-edit-template.gif new file mode 100644 index 0000000000000..faf49624e1a18 Binary files /dev/null and b/docs/images/templates/choosing-edit-template.gif differ diff --git a/docs/images/templates/coder-login-web.png b/docs/images/templates/coder-login-web.png new file mode 100644 index 0000000000000..161ff92a00401 Binary files /dev/null and b/docs/images/templates/coder-login-web.png differ diff --git a/docs/images/templates/coder-session-token.png b/docs/images/templates/coder-session-token.png new file mode 100644 index 0000000000000..f982550901813 Binary files /dev/null and b/docs/images/templates/coder-session-token.png differ diff --git a/docs/images/templates/create-template.png b/docs/images/templates/create-template.png new file mode 100644 index 0000000000000..3705cea3a6b50 Binary files /dev/null and b/docs/images/templates/create-template.png differ diff --git a/docs/images/templates/create-workspace.png b/docs/images/templates/create-workspace.png new file mode 100644 index 0000000000000..cb2a6678c6bf9 Binary files /dev/null and b/docs/images/templates/create-workspace.png differ diff --git a/docs/images/templates/develop-in-docker-template.png b/docs/images/templates/develop-in-docker-template.png new file mode 100644 index 0000000000000..bbd812d3109e5 Binary files /dev/null and b/docs/images/templates/develop-in-docker-template.png differ diff --git a/docs/images/templates/edit-files.png b/docs/images/templates/edit-files.png new file mode 100644 index 0000000000000..e9ae92a72ef8a Binary files /dev/null and b/docs/images/templates/edit-files.png differ diff --git a/docs/images/templates/edit-source-code.png b/docs/images/templates/edit-source-code.png new file mode 100644 index 0000000000000..6eafd4caaeac7 Binary files /dev/null and b/docs/images/templates/edit-source-code.png differ diff --git a/docs/images/templates/new-workspace.png b/docs/images/templates/new-workspace.png new file mode 100644 index 0000000000000..85fdd002d8bce Binary files /dev/null and b/docs/images/templates/new-workspace.png differ diff --git a/docs/images/templates/publish.png b/docs/images/templates/publish.png new file mode 100644 index 0000000000000..bd72230a425fd Binary files /dev/null and b/docs/images/templates/publish.png differ diff --git a/docs/images/templates/select-template.png b/docs/images/templates/select-template.png new file mode 100644 index 0000000000000..4210064de8479 Binary files /dev/null and b/docs/images/templates/select-template.png differ diff --git a/docs/images/templates/source-code.png b/docs/images/templates/source-code.png new file mode 100644 index 0000000000000..641b97171c0cb Binary files /dev/null and b/docs/images/templates/source-code.png differ diff --git a/docs/images/templates/starter-templates-button.png b/docs/images/templates/starter-templates-button.png new file mode 100644 index 0000000000000..d8607abc06007 Binary files /dev/null and b/docs/images/templates/starter-templates-button.png differ diff --git a/docs/images/templates/starter-templates.png b/docs/images/templates/starter-templates.png new file mode 100644 index 0000000000000..2008a41f5b4b0 Binary files /dev/null and b/docs/images/templates/starter-templates.png differ diff --git a/docs/images/templates/template-architecture.png b/docs/images/templates/template-architecture.png new file mode 100644 index 0000000000000..6d84ac27738d3 Binary files /dev/null and b/docs/images/templates/template-architecture.png differ diff --git a/docs/images/templates/template-tour.png b/docs/images/templates/template-tour.png new file mode 100644 index 0000000000000..d5a75f5155fdb Binary files /dev/null and b/docs/images/templates/template-tour.png differ diff --git a/docs/images/templates/template-variables.png b/docs/images/templates/template-variables.png new file mode 100644 index 0000000000000..e900fb9f3c6dc Binary files /dev/null and b/docs/images/templates/template-variables.png differ diff --git a/docs/images/templates/update.png b/docs/images/templates/update.png new file mode 100644 index 0000000000000..799a96cbc4ac3 Binary files /dev/null and b/docs/images/templates/update.png differ diff --git a/docs/images/templates/use-template.png b/docs/images/templates/use-template.png new file mode 100644 index 0000000000000..e8e11a15ba040 Binary files /dev/null and b/docs/images/templates/use-template.png differ diff --git a/docs/images/templates/workspace-apps.png b/docs/images/templates/workspace-apps.png new file mode 100644 index 0000000000000..cf4f8061899e6 Binary files /dev/null and b/docs/images/templates/workspace-apps.png differ diff --git a/docs/images/templates/workspace-ready.png b/docs/images/templates/workspace-ready.png new file mode 100644 index 0000000000000..8f4fc70d9c598 Binary files /dev/null and b/docs/images/templates/workspace-ready.png differ diff --git a/docs/images/workspace-update.png b/docs/images/workspace-update.png new file mode 100644 index 0000000000000..2ae1fcd483e61 Binary files /dev/null and b/docs/images/workspace-update.png differ diff --git a/docs/manifest.json b/docs/manifest.json index 9ecb9428ff964..7353f80931d75 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -139,55 +139,86 @@ }, { "title": "Templates", - "description": "Learn about templates, which define the infrastructure underlying workspaces", + "description": "Templates define the infrastructure for workspaces", "path": "./templates/index.md", "icon_path": "./images/icons/picture.svg", "children": [ { - "title": "Resource Persistence", - "description": "Learn how resource persistence works in Coder", - "path": "./templates/resource-persistence.md", - "icon_path": "./images/icons/infinity.svg" + "title": "Working with templates", + "description": "Creating, editing, and updating templates", + "path": "./templates/creating.md" }, { - "title": "Provider Authentication", - "description": "Learn how to authenticate the provisioner", - "path": "./templates/authentication.md", - "icon_path": "./images/icons/key.svg" - }, - { - "title": "Change Management", - "description": "Learn how to source-control templates with git and CI", - "path": "./templates/change-management.md", - "icon_path": "./images/icons/git.svg" + "title": "Your first template", + "description": "A tutorial for creating and editing your first template", + "path": "./templates/tutorial.md" }, { - "title": "Resource Metadata", - "description": "Learn how to expose resource data to users", - "path": "./templates/resource-metadata.md", - "icon_path": "./images/icons/table-rows.svg" + "title": "Guided tour", + "description": "Create a template from scratch", + "path": "./templates/tour.md" }, { - "title": "Agent Metadata", - "description": "Learn how to expose live agent information to users", - "path": "./templates/agent-metadata.md", - "icon_path": "./images/icons/table-rows.svg" + "title": "Setting up templates", + "description": "Best practices for writing templates", + "path": "./templates/best-practices.md", + "children": [ + { + "title": "Change management", + "description": "Versioning templates with git and CI", + "path": "./templates/change-management.md", + "icon_path": "./images/icons/git.svg" + }, + { + "title": "Provider authentication", + "description": "Authenticate the provisioner", + "path": "./templates/authentication.md", + "icon_path": "./images/icons/key.svg" + }, + { + "title": "Resource persistence", + "description": "How resource persistence works in Coder", + "path": "./templates/resource-persistence.md", + "icon_path": "./images/icons/infinity.svg" + }, + { + "title": "Terraform modules", + "description": "Reuse code across Coder templates", + "path": "./templates/modules.md" + } + ] }, { - "title": "Parameters", - "description": "Use parameters to customize templates", - "path": "./templates/parameters.md", - "icon_path": "./images/icons/code.svg" + "title": "Customizing templates", + "description": "Give information and options to workspace users", + "path": "./templates/customizing.md", + "children": [ + { + "title": "Agent metadata", + "description": "Show operational metrics in the workspace", + "path": "./templates/agent-metadata.md" + }, + { + "title": "Resource metadata", + "description": "Show information in the workspace about template resources", + "path": "./templates/resource-metadata.md" + }, + { + "title": "Parameters", + "description": "Prompt the user for additional information about a workspace", + "path": "./templates/parameters.md" + } + ] }, { "title": "Open in Coder", - "description": "Learn how to add an \"Open in Coder\" button to your repos", + "description": "Add an \"Open in Coder\" button to your repos", "path": "./templates/open-in-coder.md", "icon_path": "./images/icons/key.svg" }, { - "title": "Docker in Workspaces", - "description": "Use docker inside containerized templates", + "title": "Docker in workspaces", + "description": "Use Docker inside containerized templates", "path": "./templates/docker-in-workspaces.md", "icon_path": "./images/icons/docker.svg" }, @@ -198,9 +229,9 @@ "state": "alpha" }, { - "title": "Terraform Modules", - "description": "Reuse code across Coder templates", - "path": "./templates/modules.md" + "title": "Troubleshooting templates", + "description": "Fix common template problems", + "path": "./templates/troubleshooting.md" }, { "title": "Process Logging", @@ -337,7 +368,7 @@ "icon_path": "./images/icons/scale.svg" }, { - "title": "Provisioners", + "title": "External Provisioners", "description": "Run provisioners isolated from the Coder server", "path": "./admin/provisioners.md", "icon_path": "./images/icons/queue.svg", diff --git a/docs/platforms/jfrog.md b/docs/platforms/jfrog.md index 180c46192f014..d25cd491be33f 100644 --- a/docs/platforms/jfrog.md +++ b/docs/platforms/jfrog.md @@ -24,6 +24,10 @@ The admin-level access token is used to provision user tokens and is never expos developers or stored in workspaces. +
+You can skip the whole page and use [JFrog module](https://registry.coder.com/modules/jfrog) for easy JFrog Artifactory integration. +
+ ## Provisioner Authentication The most straight-forward way to authenticate your template with Artifactory is diff --git a/docs/templates/agent-metadata.md b/docs/templates/agent-metadata.md index f36893e918d74..52d01d769e65a 100644 --- a/docs/templates/agent-metadata.md +++ b/docs/templates/agent-metadata.md @@ -1,13 +1,12 @@ -# Agent Metadata +# Agent metadata ![agent-metadata](../images/agent-metadata.png) -With Agent Metadata, template admins can expose operational metrics from their -workspaces to their users. It is the dynamic complement of -[Resource Metadata](./resource-metadata.md). +You can show live operational metrics to workspace users with agent metadata. It +is the dynamic complement of [resource metadata](./resource-metadata.md). -See the -[Terraform reference](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#metadata). +You specify agent metadata in the +[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent). ## Examples @@ -16,9 +15,10 @@ All of these examples use for the script declaration. With heredoc strings, you can script without messy escape codes, just as if you were working in your terminal. -Some of the below examples use the [`coder stat`](../cli/stat.md) command. This -is useful for determining CPU/memory usage inside a container, which can be -tricky otherwise. +Some of the examples use the [`coder stat`](../cli/stat.md) command. This is +useful for determining CPU and memory usage of the VM or container that the +workspace is running in, which is more accurate than resource usage about the +workspace's host. Here's a standard set of metadata snippets for Linux agents: @@ -86,11 +86,13 @@ resource "coder_agent" "main" { } ``` -## Utilities +## Useful utilities -[top](https://linux.die.net/man/1/top) is available in most Linux distributions -and provides virtual memory, CPU and IO statistics. Running `top` produces -output that looks like: +You can also show agent metadata for information about the workspace's host. + +[top](https://manpages.ubuntu.com/manpages/jammy/en/man1/top.1.html) is +available in most Linux distributions and provides virtual memory, CPU and IO +statistics. Running `top` produces output that looks like: ```text %Cpu(s): 65.8 us, 4.4 sy, 0.0 ni, 29.3 id, 0.3 wa, 0.0 hi, 0.2 si, 0.0 st @@ -98,9 +100,9 @@ MiB Mem : 16009.0 total, 493.7 free, 4624.8 used, 10890.5 buff/cache MiB Swap: 0.0 total, 0.0 free, 0.0 used. 11021.3 avail Mem ``` -[vmstat](https://linux.die.net/man/8/vmstat) is available in most Linux -distributions and provides virtual memory, CPU and IO statistics. Running -`vmstat` produces output that looks like: +[vmstat](https://manpages.ubuntu.com/manpages/jammy/en/man8/vmstat.8.html) is +available in most Linux distributions and provides virtual memory, CPU and IO +statistics. Running `vmstat` produces output that looks like: ```text procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu----- @@ -108,10 +110,10 @@ r b swpd free buff cache si so bi bo in cs us sy id wa st 0 0 19580 4781680 12133692 217646944 0 2 4 32 1 0 1 1 98 0 0 ``` -[dstat](https://linux.die.net/man/1/dstat) is considerably more parseable than -`vmstat` but often not included in base images. It is easily installed by most -package managers under the name `dstat`. The output of running `dstat 1 1` looks -like: +[dstat](https://manpages.ubuntu.com/manpages/jammy/man1/dstat.1.html) is +considerably more parseable than `vmstat` but often not included in base images. +It is easily installed by most package managers under the name `dstat`. The +output of running `dstat 1 1` looks like: ```text --total-cpu-usage-- -dsk/total- -net/total- ---paging-- ---system-- @@ -119,27 +121,28 @@ usr sys idl wai stl| read writ| recv send| in out | int csw 1 1 98 0 0|3422k 25M| 0 0 | 153k 904k| 123k 174k ``` -## DB Write Load +## Managing the database load -Agent metadata can generate a significant write load and overwhelm your database -if you're not careful. The approximate writes per second can be calculated using -the following formula (applied once for each unique metadata interval): +Agent metadata can generate a significant write load and overwhelm your Coder +database if you're not careful. The approximate writes per second can be +calculated using the formula: ```text -num_running_agents * write_multiplier / metadata_interval +(metadata_count * num_running_agents * 2) / metadata_avg_interval ``` -For example, let's say you have: +For example, let's say you have - 10 running agents -- each with 4 metadata snippets -- where two have an interval of 4 seconds, and the other two 6 seconds +- each with 6 metadata snippets +- with an average interval of 4 seconds + +You can expect `(10 * 6 * 2) / 4`, or 30 writes per second. + +One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table and the +other to the `NOTIFY` query that enables live stats streaming in the UI. -You can expect at most `(10 * 2 / 4) + (10 * 2 / 6)` or ~8 writes per second. -The actual writes per second may be a bit lower due to batching of metadata. -Adding more metadata with the same interval will not increase writes per second, -but it may still increase database load slightly. +## Next Steps -We use a `write_multiplier` of `2` because each metadata write generates two -writes. One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table -and the other to the `NOTIFY` query that enables live stats streaming in the UI. +- [Resource metadata](./resource-metadata.md) +- [Parameters](./parameters.md) diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md index 3597c83b26dfe..770aeb3179927 100644 --- a/docs/templates/authentication.md +++ b/docs/templates/authentication.md @@ -7,31 +7,42 @@

-Coder's provisioner process needs to authenticate with cloud provider APIs to -provision workspaces. You can either pass credentials to the provisioner as -parameters or execute Coder in an environment that is authenticated with the -cloud provider. +The Coder server's +[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner) +process needs to authenticate with other provider APIs to provision workspaces. +There are two approaches to do this: -We encourage the latter where supported. This approach simplifies the template, -keeps cloud provider credentials out of Coder's database (making it a less -valuable target for attackers), and is compatible with agent-based -authentication schemes (that handle credential rotation and/or ensure the -credentials are not written to disk). +- Pass credentials to the provisioner as parameters. +- Preferred: Execute the Coder server in an environment that is authenticated + with the provider. -Cloud providers for which the Terraform provider supports authenticated -environments include +We encourage the latter approach where supported: + +- Simplifies the template. +- Keeps provider credentials out of Coder's database, making it a less valuable + target for attackers. +- Compatible with agent-based authentication schemes, which handle credential + rotation or ensure the credentials are not written to disk. + +Generally, you can set up an environment to provide credentials to Coder in +these ways: + +- A well-known location on disk. For example, `~/.aws/credentials` for AWS on + POSIX systems. +- Environment variables. + +It is usually sufficient to authenticate using the CLI or SDK for the provider +before running Coder, but check the Terraform provider's documentation for +details. + +These platforms have Terraform providers that support authenticated +environments: - [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs) - [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) - [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) - [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) -Additional providers may be supported; check the +Other providers might also support authenticated environments. Check the [documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for details. - -The way these generally work is via the credentials being available to Coder -either in some well-known location on disk (e.g. `~/.aws/credentials` for AWS on -posix systems), or via environment variables. It is usually sufficient to -authenticate using the CLI or SDK for the cloud provider before running Coder -for this to work, but check the Terraform provider documentation for details. diff --git a/docs/templates/best-practices.md b/docs/templates/best-practices.md new file mode 100644 index 0000000000000..71aed19447d39 --- /dev/null +++ b/docs/templates/best-practices.md @@ -0,0 +1,7 @@ +# Template best practices + +We recommend a few ways to manage workspace resources, authentication, and +versioning. + + + diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md index 6c4fecfa8da2f..fe995070ce780 100644 --- a/docs/templates/change-management.md +++ b/docs/templates/change-management.md @@ -1,7 +1,7 @@ # Template Change Management -We recommend source controlling your templates as you would other code. -[Install Coder](../install/) in CI/CD pipelines to push new template versions. +We recommend source-controlling your templates as you would other code. You can +[install Coder](../install/) in CI/CD pipelines to push new template versions. ```console # Install the Coder CLI @@ -21,14 +21,12 @@ export CODER_TEMPLATE_DIR=.coder/templates/kubernetes export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD) # Push the new template version to Coder -coder login --url $CODER_URL --token $CODER_SESSION_TOKEN coder templates push --yes $CODER_TEMPLATE_NAME \ --directory $CODER_TEMPLATE_DIR \ --name=$CODER_TEMPLATE_VERSION # Version name is optional ``` -> Looking for an example? See how we push our development image and template -> [via GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml). - -> To cap token lifetime on creation, -> [configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime) +To cap token lifetime on creation, +[configure Coder server to set a shorter max token lifetime](../cli/server.md#--max-token-lifetime). +For an example, see how we push our development image and template +[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml). diff --git a/docs/templates/creating.md b/docs/templates/creating.md new file mode 100644 index 0000000000000..7ebbafac2c084 --- /dev/null +++ b/docs/templates/creating.md @@ -0,0 +1,94 @@ +# Working with templates + +You create and edit Coder templates as [Terraform](./tour.md) configuration +files (`.tf`) and any supporting files, like a README or configuration files for +other services. + +## Who creates templates? + +The [Template Admin](../admin/users.md) role (and above) can create templates. +End users, like developers, create workspaces from them. + +Templates can also be [managed with git](./change-management.md), allowing any +developer to propose changes to a template. + +You can give different users and groups access to templates with +[role-based access control](../admin/rbac.md). + +## Starter templates + +We provide starter templates for common cloud providers, like AWS, and +orchestrators, like Kubernetes. From there, you can modify them to use your own +images, VPC, cloud credentials, and so on. Coder supports all Terraform +resources and properties, so fear not if your favorite cloud provider isn't +here! + +![Starter templates](../images/templates/starter-templates.png) + +If you prefer to use Coder on the [command line](../cli.md), use +`coder templates init`. + +> Coder starter templates are also available on our +> [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates). + +## Community Templates + +As well as Coder's starter templates, you can see a list of community templates +by our users +[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md). + +## Editing templates + +Our starter templates are meant to be modified for your use cases. You can edit +any template's files directly in the Coder dashboard. + +![Editing a template](../images/templates/choosing-edit-template.gif) + +If you'd prefer to use the CLI, use `coder templates pull`, edit the template +files, then `coder templates push`. + +> Even if you are a Terraform expert, we suggest reading our +> [guided tour](./tour.md). + +## Updating templates + +Coder tracks a template's versions, keeping all developer workspaces up-to-date. +When you publish a new version, developers are notified to get the latest +infrastructure, software, or security patches. Learn more about +[change management](./change-management.md). + +![Updating a template](../images/templates/update.png) + +## Delete templates + +You can delete a template using both the coder CLI and UI. Only +[template admins and owners](../admin/users.md) can delete a template, and the +template must not have any running workspaces associated to it. + +In the UI, navigate to the template you want to delete, and select the dropdown +in the right-hand corner of the page to delete the template. + +![delete-template](../images/delete-template.png) + +Using the CLI, login to Coder and run the following command to delete a +template: + +```shell +coder templates delete +``` + +### Delete workspaces + +When a workspace is deleted, the Coder server essentially runs a +[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all +resources associated with the workspace. + +> Terraform's +> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy) +> and +> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes) +> meta-arguments can be used to prevent accidental data loss. + +## Next steps + +- [Your first template](./tutorial.md) diff --git a/docs/templates/customizing.md b/docs/templates/customizing.md new file mode 100644 index 0000000000000..16a951243371c --- /dev/null +++ b/docs/templates/customizing.md @@ -0,0 +1,6 @@ +# Customizing templates + +You can give developers more information and control over their workspaces: + + + diff --git a/docs/templates/devcontainers.md b/docs/templates/devcontainers.md index 10a107ca451b0..d8b0417ac1149 100644 --- a/docs/templates/devcontainers.md +++ b/docs/templates/devcontainers.md @@ -2,31 +2,31 @@ [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. +infrastructure. It can run on Docker or Kubernetes. 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) +- Easier to start projects from Coder. Just create a new workspace then pick a + 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. +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 +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. +Developers can edit the `devcontainer.json` in their workspace to rebuild to +iterate on their development environments. ## Example templates @@ -35,13 +35,13 @@ Coder: ![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. +Your template can prompt the user for a repo URL with +[Parameters](./parameters.md). ## 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 +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. diff --git a/docs/templates/docker-in-workspaces.md b/docs/templates/docker-in-workspaces.md index 8a3f822cb2d2b..9388450ae7b4c 100644 --- a/docs/templates/docker-in-workspaces.md +++ b/docs/templates/docker-in-workspaces.md @@ -4,7 +4,7 @@ There are a few ways to run Docker within container-based Coder workspaces. | Method | Description | Limitations | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Sysbox container runtime](#sysbox-container-runtime) | Install the sysbox runtime on your Kubernetes nodes for secure docker-in-docker and systemd-in-docker. Works with GKE, EKS, AKS. | Requires [compatible nodes](https://github.com/nestybox/sysbox#host-requirements). | +| [Sysbox container runtime](#sysbox-container-runtime) | Install the sysbox runtime on your Kubernetes nodes for secure docker-in-docker and systemd-in-docker. Works with GKE, EKS, AKS. | Requires [compatible nodes](https://github.com/nestybox/sysbox#host-requirements). [Limitations](https://github.com/nestybox/sysbox/blob/master/docs/user-guide/limitations.md) | | [Envbox](#envbox) | A container image with all the packages necessary to run an inner sysbox container. Removes the need to setup sysbox-runc on your nodes. Works with GKE, EKS, AKS. | Requires running the outer container as privileged (the inner container that acts as the workspace is locked down). Requires compatible [nodes](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility). | | [Rootless Podman](#rootless-podman) | Run podman inside Coder workspaces. Does not require a custom runtime or privileged containers. Works with GKE, EKS, AKS, RKE, OpenShift | Requires smarter-device-manager for FUSE mounts. [See all](https://github.com/containers/podman/blob/main/rootless.md#shortcomings-of-rootless-podman) | | [Privileged docker sidecar](#privileged-sidecar-container) | Run docker as a privileged sidecar container. | Requires a privileged container. Workspaces can break out to root on the host machine. | @@ -18,10 +18,6 @@ from the workspace containers. Sysbox requires a to implement these security features. Sysbox can also be used to run systemd inside Coder workspaces. See [Systemd in Docker](#systemd-in-docker). -The Sysbox container runtime is not compatible with our -[workspace process logging](./process-logging.md) feature. Envbox is compatible -with process logging, however. - ### Use Sysbox in Docker-based templates After [installing Sysbox](https://github.com/nestybox/sysbox#installation) on @@ -197,8 +193,7 @@ env { compatible with OCI containers specification. which can run rootless inside Kubernetes pods. No custom RuntimeClass is required. -Prior to completing the steps below, please review the following Podman -documentation: +Before using Podman, please review the following documentation: - [Basic setup and use of Podman in a rootless environment](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md) @@ -256,7 +251,7 @@ documentation: > Otherwise, your nodes may drop the labels and break podman functionality. 3. For systems running SELinux (typically Fedora-, CentOS-, and Red Hat-based - systems), you may need to disable SELinux or set it to permissive mode. + systems), you might need to disable SELinux or set it to permissive mode. 4. Import our [kubernetes-with-podman](https://github.com/coder/coder/tree/main/examples/templates/kubernetes-with-podman) diff --git a/docs/templates/icons.md b/docs/templates/icons.md index 0f3a6f0b5ab8b..a9072c3f14a01 100644 --- a/docs/templates/icons.md +++ b/docs/templates/icons.md @@ -20,6 +20,7 @@ come bundled with your Coder deployment. [`option`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/parameter#nested-schema-for-option) blocks - [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script#icon) + - [`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata#icon) These can all be configured to use an icon by setting the `icon` field. diff --git a/docs/templates/index.md b/docs/templates/index.md index ef557b7db897c..75f0a37e47e8e 100644 --- a/docs/templates/index.md +++ b/docs/templates/index.md @@ -1,633 +1,8 @@ # Templates -Templates are written in [Terraform](https://www.terraform.io/) and describe the -infrastructure for workspaces (e.g., docker_container, aws_instance, -kubernetes_pod). +Templates define the underlying infrastructure that Coder +[workspaces](../workspaces.md) run on. All workspaces are created from +templates. -In most cases, a small group of users (team leads or Coder administrators) -[have permissions](../admin/users.md#roles) to create and manage templates. -Then, other users provision their [workspaces](../workspaces.md) from templates -using the UI or CLI. - -## Get the CLI - -The CLI and the server are the same binary. We did this to encourage virality so -individuals can start their own Coder deployments. - -From your local machine, download the CLI for your operating system from the -[releases](https://github.com/coder/coder/releases/latest) or run: - -```shell -curl -fsSL https://coder.com/install.sh | sh -``` - -To see the sub-commands for managing templates, run: - -```shell -coder templates --help -``` - -## Login to your Coder Deployment - -Before you can create templates, you must first login to your Coder deployment -with the CLI. - -```shell -coder login https://coder.example.com # aka the URL to your coder instance -``` - -This will open a browser and ask you to authenticate to your Coder deployment, -returning an API Key. - -> Make a note of the API Key. You can re-use the API Key in future CLI logins or -> sessions. - -```shell -coder --token login https://coder.example.com/ # aka the URL to your coder instance -``` - -## Add a template - -Before users can create workspaces, you'll need at least one template in Coder. - -```shell -# create a local directory to store templates -mkdir -p $HOME/coder/templates -cd $HOME/coder/templates - -# start from an example -coder templates init - -# optional: modify the template -vim /main.tf - -# add the template to Coder deployment -coder templates create -``` - -> See the documentation and source code for each example as well as community -> templates in the -> [examples/](https://github.com/coder/coder/tree/main/examples/templates) -> directory in the repo. - -## Configure Max Workspace Autostop - -To control cost, specify a maximum time to live flag for a template in hours or -minutes. - -```shell -coder templates create my-template --default-ttl 4h -``` - -## Customize templates - -Example templates are not designed to support every use (e.g -[examples/aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux) -does not support custom VPCs). You can add these features by editing the -Terraform code once you run `coder templates init` (new) or -`coder templates pull` (existing). - -Refer to the following resources to build your own templates: - -- Terraform: [Documentation](https://developer.hashicorp.com/terraform/docs) and - [Registry](https://registry.terraform.io) -- Common [concepts in templates](#concepts-in-templates) and - [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs) -- [Coder example templates](https://github.com/coder/coder/tree/main/examples/templates) - code - -## Concepts in templates - -While templates are written with standard Terraform, the -[Coder Terraform Provider](https://registry.terraform.io/providers/coder/coder/latest/docs) -is used to define the workspace lifecycle and establish a connection from -resources to Coder. - -Below is an overview of some key concepts in templates (and workspaces). For all -template options, reference -[Coder Terraform provider docs](https://registry.terraform.io/providers/coder/coder/latest/docs). - -### Resource - -Resources in Coder are simply -[Terraform resources](https://www.terraform.io/language/resources). If a Coder -agent is attached to a resource, users can connect directly to the resource over -SSH or web apps. - -### Coder agent - -Once a Coder workspace is created, the Coder agent establishes a connection -between a resource (docker_container) and Coder, so that a user can connect to -their workspace from the web UI or CLI. A template can have multiple agents to -allow users to connect to multiple resources in their workspace. - -> Resources must download and start the Coder agent binary to connect to Coder. -> This means the resource must be able to reach your Coder URL. - -```hcl -data "coder_workspace" "me" { -} - -resource "coder_agent" "pod1" { - os = "linux" - arch = "amd64" -} - -resource "kubernetes_pod" "pod1" { - spec { - ... - container { - command = ["sh", "-c", coder_agent.pod1.init_script] - env { - name = "CODER_AGENT_TOKEN" - value = coder_agent.dev.token - } - } - } -} -``` - -The `coder_agent` resource can be configured with additional arguments. For -example, you can use the `env` property to set environment variables that will -be inherited by all child processes of the agent, including SSH sessions. See -the -[Coder Terraform Provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent) -for the full list of supported arguments for the `coder_agent`. - -#### `startup_script` - -Use the Coder agent's `startup_script` to run additional commands like -installing IDEs, [cloning dotfiles](../dotfiles.md#templates), and cloning -project repos. - -**Note:** By default, the startup script is executed in the background. This -allows users to access the workspace before the script completes. If you want to -change this, see [`startup_script_behavior`](#startup_script_behavior) below. - -Here are a few guidelines for writing a good startup script (more on these -below): - -1. Use `set -e` to exit the script if any command fails and `|| true` for - commands that are allowed to fail -2. Use `&` to start a process in the background, allowing the startup script to - complete -3. Inform the user about what's going on via `echo` - -```hcl -resource "coder_agent" "coder" { - os = "linux" - arch = "amd64" - dir = "/home/coder" - startup_script = </tmp/code-server.log 2>&1 & - -# Notice: var.repo and var.dotfiles_uri are specified elsewhere in the Terraform -# code as input variables. -REPO=${var.repo} -DOTFILES_URI=${var.dotfiles_uri} - -# clone repo -ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts -echo "Cloning $REPO..." -git clone --progress git@github.com:"$REPO" - -# use coder CLI to clone and install dotfiles -echo "Cloning dotfiles..." -coder dotfiles -y "$DOTFILES_URI" - EOT -} -``` - -The startup script can contain important steps that must be executed -successfully so that the workspace is in a usable state, for this reason we -recommend using `set -e` (exit on error) at the top and `|| true` (allow command -to fail) to ensure the user is notified when something goes wrong. These are not -shown in the example above because, while useful, they need to be used with -care. For more assurance, you can utilize -[shellcheck](https://www.shellcheck.net) to find bugs in the script and employ -[`set -euo pipefail`](https://wizardzines.com/comics/bash-errors/) to exit on -error, unset variables, and fail on pipe errors. - -We also recommend that startup scripts do not run forever. Long-running -processes, like code-server, should be run in the background. This is usually -achieved by adding `&` to the end of the command. For example, `sleep 10 &` will -run the command in the background and allow the startup script to complete. - -> **Note:** If a backgrounded command (`&`) writes to stdout or stderr, the -> startup script will not complete until the command completes or closes the -> file descriptors. To avoid this, you can redirect the stdout and stderr to a -> file. For example, `sleep 10 >/dev/null 2>&1 &` will redirect the stdout and -> stderr to `/dev/null` (discard) and run the command in the background. - -PS. Notice how each step starts with `echo "..."` to provide feedback to the -user about what is happening? This is especially useful when the startup script -behavior is set to blocking because the user will be informed about why they're -waiting to access their workspace. - -#### `startup_script_behavior` - -Use the Coder agent's `startup_script_behavior` to change the behavior between -`blocking` and `non-blocking` (default). The blocking behavior is recommended -for most use cases because it allows the startup script to complete before the -user accesses the workspace. For example, let's say you want to check out a very -large repo in the startup script. If the startup script is non-blocking, the -user may log in via SSH or open the IDE before the repo is fully checked out. -This can lead to a poor user experience. - -```hcl -resource "coder_agent" "coder" { - os = "linux" - arch = "amd64" - startup_script_behavior = "blocking" - startup_script = "echo 'Starting...'" -``` - -Whichever behavior is enabled, the user can still choose to override it by -specifying the appropriate flags (or environment variables) in the CLI when -connecting to the workspace. The behavior can be overridden by one of the -following means: - -- Set an environment variable (for use with `ssh` or `coder ssh`): - - `export CODER_SSH_WAIT=yes` (blocking) - - `export CODER_SSH_WAIT=no` (non-blocking) -- Use a flag with `coder ssh`: - - `coder ssh --wait=yes my-workspace` (blocking) - - `coder ssh --wait=no my-workspace` (non-blocking) -- Use a flag to configure all future `ssh` connections: - - `coder config-ssh --wait=yes` (blocking) - - `coder config-ssh --wait=no` (non-blocking) - -### Start/stop - -[Learn about resource persistence in Coder](./resource-persistence.md) - -Coder workspaces can be started/stopped. This is often used to save on cloud -costs or enforce ephemeral workflows. When a workspace is started or stopped, -the Coder server runs an additional -[terraform apply](https://www.terraform.io/cli/commands/apply), informing the -Coder provider that the workspace has a new transition state. - -This template sample has one persistent resource (docker volume) and one -ephemeral resource (docker container). - -```hcl -data "coder_workspace" "me" { -} - -resource "docker_volume" "home_volume" { - # persistent resource (remains a workspace is stopped) - count = 1 - name = "coder-${data.coder_workspace.me.id}-home" - lifecycle { - ignore_changes = all - } -} - -resource "docker_container" "workspace" { - # ephemeral resource (deleted when workspace is stopped, created when started) - count = data.coder_workspace.me.start_count # 0 (stopped), 1 (started) - volumes { - container_path = "/home/coder/" - volume_name = docker_volume.home_volume.name - read_only = false - } - # ... other config -} -``` - -#### Using updated images when rebuilding a workspace - -To ensure that Coder uses an updated image when rebuilding a workspace, we -suggest that admins update the tag in the template (e.g., `my-image:v0.4.2` -> -`my-image:v0.4.3`) or digest (`my-image@sha256:[digest]` -> -`my-image@sha256:[new_digest]`). - -Alternatively, if you're willing to wait for longer start times from Coder, you -can set the `imagePullPolicy` to `Always` in your Terraform template; when set, -Coder will check `image:tag` on every build and update if necessary: - -```hcl -resource "kubernetes_pod" "podName" { - spec { - container { - image_pull_policy = "Always" - } - } -} -``` - -### Edit templates - -You can edit a template using the coder CLI or the UI. Only -[template admins and owners](../admin/users.md) can edit a template. - -Using the UI, navigate to the template page, click on the menu, and select "Edit -files". In the template editor, you create, edit and remove files. Before -publishing a new template version, you can test your modifications by clicking -the "Build template" button. Newly published template versions automatically -become the default version selection when creating a workspace. - -> **Tip**: Even without publishing a version as active, you can still use it to -> create a workspace before making it the default for everybody in your -> organization. This may help you debug new changes without impacting others. - -Using the CLI, login to Coder and run the following command to edit a single -template: - -```shell -coder templates edit --description "This is my template" -``` - -Review editable template properties by running `coder templates edit -h`. - -Alternatively, you can pull down the template as a tape archive (`.tar`) to your -current directory: - -```shell -coder templates pull file.tar -``` - -Then, extract it by running: - -```shell -tar -xf file.tar -``` - -Make the changes to your template then run this command from the root of the -template folder: - -```shell -coder templates push -``` - -Your updated template will now be available. Outdated workspaces will have a -prompt in the dashboard to update. - -### Delete templates - -You can delete a template using both the coder CLI and UI. Only -[template admins and owners](../admin/users.md) can delete a template, and the -template must not have any running workspaces associated to it. - -Using the CLI, login to Coder and run the following command to delete a -template: - -```shell -coder templates delete -``` - -In the UI, navigate to the template you want to delete, and select the dropdown -in the right-hand corner of the page to delete the template. - -![delete-template](../images/delete-template.png) - -#### Delete workspaces - -When a workspace is deleted, the Coder server essentially runs a -[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all -resources associated with the workspace. - -> Terraform's -> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy) -> and -> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes) -> meta-arguments can be used to prevent accidental data loss. - -### Coder apps - -By default, all templates allow developers to connect over SSH and a web -terminal. See [Configuring Web IDEs](../ides/web-ides.md) to learn how to give -users access to additional web applications. - -Template administrators can hide apps like the web-based Terminal or VS Code -Desktop with the -[`display_apps`](https://registry.terraform.io/providers/coder/coder/0.11.2/docs/resources/agent#display_apps) -configuration in the -[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent) -resource. For example, the following configuration block will hide all default -Coder apps except the web terminal. - -```hcl - display_apps { - vscode = false - vscode_insiders = false - ssh_helper = false - port_forwarding_helper = false - web_terminal = true - } -``` - -Example use cases for `display_apps` are JetBrains users or zero-trust -deployments who do not want nor should have access to a local VS Code IDE. - -![display-apps](../images/display-apps.png) - -### Data source - -When a workspace is being started or stopped, the `coder_workspace` data source -provides some useful parameters. See the -[Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace) -for more information. - -For example, the -[Docker quick-start template](https://github.com/coder/coder/tree/main/examples/templates/docker) -sets a few environment variables based on the username and email address of the -workspace's owner, so that you can make Git commits immediately without any -manual configuration: - -```hcl -resource "coder_agent" "main" { - # ... - 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}" - } -} -``` - -You can add these environment variable definitions to your own templates, or -customize them however you like. - -## Troubleshooting templates - -Occasionally, you may run into scenarios where a workspace is created, but the -agent is either not connected or the -[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) -has failed or timed out. - -### Agent connection issues - -If the agent is not connected, it means the agent or -[init script](https://github.com/coder/coder/tree/main/provisionersdk/scripts) -has failed on the resource. - -```console -$ coder ssh myworkspace -⢄⡱ Waiting for connection from [agent]... -``` - -While troubleshooting steps vary by resource, here are some general best -practices: - -- Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`) -- Ensure the resource can `curl` your Coder - [access URL](../admin/configure.md#access-url) -- Manually connect to the resource and check the agent logs (e.g., - `kubectl exec`, `docker exec` or AWS console) - - The Coder agent logs are typically stored in `/tmp/coder-agent.log` - - The Coder agent startup script logs are typically stored in - `/tmp/coder-startup-script.log` - - The Coder agent shutdown script logs are typically stored in - `/tmp/coder-shutdown-script.log` -- This can also happen if the websockets are not being forwarded correctly when - running Coder behind a reverse proxy. - [Read our reverse-proxy docs](../admin/configure.md#tls--reverse-proxy) - -### Startup script issues - -Depending on the contents of the -[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script), -and whether or not the -[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) -is set to blocking or non-blocking, you may notice issues related to the startup -script. In this section we will cover common scenarios and how to resolve them. - -#### Unable to access workspace, startup script is still running - -If you're trying to access your workspace and are unable to because the -[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) -is still running, it means the -[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) -option is set to blocking or you have enabled the `--wait=yes` option (for e.g. -`coder ssh` or `coder config-ssh`). In such an event, you can always access the -workspace by using the web terminal, or via SSH using the `--wait=no` option. If -the startup script is running longer than it should, or never completing, you -can try to [debug the startup script](#debugging-the-startup-script) to resolve -the issue. Alternatively, you can try to force the startup script to exit by -terminating processes started by it or terminating the startup script itself (on -Linux, `ps` and `kill` are useful tools). - -For tips on how to write a startup script that doesn't run forever, see the -[`startup_script`](#startup_script) section. For more ways to override the -startup script behavior, see the -[`startup_script_behavior`](#startup_script_behavior) section. - -Template authors can also set the -[startup script behavior](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script_behavior) -option to non-blocking, which will allow users to access the workspace while the -startup script is still running. Note that the workspace must be updated after -changing this option. - -#### Your workspace may be incomplete - -If you see a warning that your workspace may be incomplete, it means you should -be aware that programs, files, or settings may be missing from your workspace. -This can happen if the -[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) -is still running or has exited with a non-zero status (see -[startup script error](#startup-script-error)). No action is necessary, but you -may want to -[start a new shell session](#session-was-started-before-the-startup-script-finished-web-terminal) -after it has completed or check the -[startup script logs](#debugging-the-startup-script) to see if there are any -issues. - -#### Session was started before the startup script finished - -The web terminal may show this message if it was started before the -[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) -finished, but the startup script has since finished. This message can safely be -dismissed, however, be aware that your preferred shell or dotfiles may not yet -be activated for this shell session. You can either start a new session or -source your dotfiles manually. Note that starting a new session means that -commands running in the terminal will be terminated and you may lose unsaved -work. - -Examples for activating your preferred shell or sourcing your dotfiles: - -- `exec zsh -l` -- `source ~/.bashrc` - -#### Startup script exited with an error - -When the -[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) -exits with an error, it means the last command run by the script failed. When -`set -e` is used, this means that any failing command will immediately exit the -script and the remaining commands will not be executed. This also means that -[your workspace may be incomplete](#your-workspace-may-be-incomplete). If you -see this error, you can check the -[startup script logs](#debugging-the-startup-script) to figure out what the -issue is. - -Common causes for startup script errors: - -- A missing command or file -- A command that fails due to missing permissions -- Network issues (e.g., unable to reach a server) - -#### Debugging the startup script - -The simplest way to debug the -[startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script) -is to open the workspace in the Coder dashboard and click "Show startup log" (if -not already visible). This will show all the output from the script. Another -option is to view the log file inside the workspace (usually -`/tmp/coder-startup-script.log`). If the logs don't indicate what's going on or -going wrong, you can increase verbosity by adding `set -x` to the top of the -startup script (note that this will show all commands run and may output -sensitive information). Alternatively, you can add `echo` statements to show -what's going on. - -Here's a short example of an informative startup script: - -```shell -echo "Running startup script..." -echo "Run: long-running-command" -/path/to/long-running-command -status=$? -echo "Done: long-running-command, exit status: ${status}" -if [ $status -ne 0 ]; then - echo "Startup script failed, exiting..." - exit $status -fi -``` - -> **Note:** We don't use `set -x` here because we're manually echoing the -> commands. This protects against sensitive information being shown in the log. - -This script tells us what command is being run and what the exit status is. If -the exit status is non-zero, it means the command failed and we exit the script. -Since we are manually checking the exit status here, we don't need `set -e` at -the top of the script to exit on error. - -## Template permissions (enterprise) - -Template permissions can be used to give users and groups access to specific -templates. [Learn more about RBAC](../admin/rbac.md) to learn how to manage - -## Community Templates - -You can see a list of community templates by our users -[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md). - -## Next Steps - -- Learn about [Authentication & Secrets](./authentication.md) -- Learn about [Change Management](./change-management.md) -- Learn about [Resource Metadata](./resource-metadata.md) -- Learn about [Workspaces](../workspaces.md) + + diff --git a/docs/templates/modules.md b/docs/templates/modules.md index 070e1d06cd7a3..137679d82bf95 100644 --- a/docs/templates/modules.md +++ b/docs/templates/modules.md @@ -1,12 +1,12 @@ -# Template inheritance +# Reusing template code -In instances where you want to reuse code across different Coder templates, such -as common scripts or resource definitions, we suggest using +To reuse code across different Coder templates, such as common scripts or +resource definitions, we suggest using [Terraform Modules](https://developer.hashicorp.com/terraform/language/modules). -These modules can be stored externally from Coder, like in a Git repository or a -Terraform registry. Below is an example of how to reference a module in your -template: +You can store these modules externally from your Coder deployment, like in a git +repository or a Terraform registry. This example shows how to reference a module +from your template: ```hcl data "coder_workspace" "me" {} @@ -29,32 +29,32 @@ resource "coder_agent" "dev" { } ``` -> Learn more about -> [creating modules](https://developer.hashicorp.com/terraform/language/modules) -> and -> [module sources](https://developer.hashicorp.com/terraform/language/modules/sources) -> in the Terraform documentation. +Learn more about +[creating modules](https://developer.hashicorp.com/terraform/language/modules) +and +[module sources](https://developer.hashicorp.com/terraform/language/modules/sources) +in the Terraform documentation. ## Git authentication -If you are importing a module from a private git repository, the Coder server -[or provisioner](../admin/provisioners.md) needs git credentials. Since this -token will only be used for cloning your repositories with modules, it is best -to create a token with limited access to repositories and no extra permissions. +If you are importing a module from a private git repository, the Coder server or +[provisioner](../admin/provisioners.md) needs git credentials. Since this token +will only be used for cloning your repositories with modules, it is best to +create a token with access limited to the repository and no extra permissions. In GitHub, you can generate a [fine-grained token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28) -with read only access to repos. +with read only access to the necessary repos. -If you are running Coder on a VM, make sure you have `git` installed and the -`coder` user has access to the following files +If you are running Coder on a VM, make sure that you have `git` installed and +the `coder` user has access to the following files: -```toml +```shell # /home/coder/.gitconfig [credential] helper = store ``` -```toml +```shell # /home/coder/.git-credentials # GitHub example: @@ -68,8 +68,8 @@ a Docker volume mount or Kubernetes secrets. ### Passing git credentials in Kubernetes First, create a `.gitconfig` and `.git-credentials` file on your local machine. -You may want to do this in a temporary directory to avoid conflicting with your -own git credentials. +You might want to do this in a temporary directory to avoid conflicting with +your own git credentials. Next, create the secret in Kubernetes. Be sure to do this in the same namespace that Coder is installed in. @@ -158,3 +158,4 @@ Learn more about [here](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-registry). - Configuring the JFrog toolchain inside a workspace [here](../platforms/jfrog.md). +- Coder Module Registry [here](https://registry.coder.com/modules) diff --git a/docs/templates/open-in-coder.md b/docs/templates/open-in-coder.md index 69ecd7dc45716..a2478d233685b 100644 --- a/docs/templates/open-in-coder.md +++ b/docs/templates/open-in-coder.md @@ -1,7 +1,7 @@ # Open in Coder -An "Open in Coder" button can be embedded into your git repos or internal wikis -to allow developers to quickly launch a new workspace. +You can embed an "Open in Coder" button into your git repos or internal wikis to +let developers quickly launch a new workspace.