diff --git a/docs/manifest.json b/docs/manifest.json index dbee42248297c..f759af46797fe 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -175,6 +175,11 @@ "description": "Use docker inside containerized templates", "path": "./templates/docker-in-workspaces.md", "icon_path": "./images/icons/docker.svg" + }, + { + "title": "Terraform Modules", + "description": "Reuse code across Coder templates", + "path": "./templates/modules.md" } ] }, diff --git a/docs/templates/modules.md b/docs/templates/modules.md new file mode 100644 index 0000000000000..d13ae0ef0cd8c --- /dev/null +++ b/docs/templates/modules.md @@ -0,0 +1,89 @@ +# Template inheritance + +In instances where you want 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: + +```hcl +data "coder_workspace" "me" {} + +module "coder-base" { + source = "github.com/my-organization/coder-base" + + # Modules take in variables and can provision infrastructure + vpc_name = "devex-3" + subnet_tags = { "name": data.coder_workspace.me.name } + code_server_version = 4.14.1 +} + +resource "coder_agent" "dev" { + # Modules can provide outputs, such as helper scripts + startup_script=< 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. 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. + +If you are running Coder on a VM, make sure you have `git` installed and the `coder` user has access to the following files + +```sh +# /home/coder/.gitconfig +[credential] + helper = store +``` + +```sh +# /home/coder/.gitconfig + +# GitHub example: +https://your-github-username:your-github-pat@github.com +``` + +If you are running Coder on Docker or Kubernetes, `git` is pre-installed in the Coder image. However, you still need to mount credentials. This can be done via 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. + +Next, create the secret in Kubernetes. Be sure to do this in the same namespace that Coder is installed in. + +```sh +export NAMESPACE=coder +kubectl apply -f - <