HomeAdministrationTemplatesExtending TemplatesReuse template code

Reuse template code

On this page

To reuse code across different Coder templates, such as common scripts or resource definitions, we suggest using Terraform Modules.

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:

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=<<EOF
  #!/bin/sh
  ${module.coder-base.code_server_install_command}
  EOF
}

Learn more about creating modules and module sources in the Terraform documentation.

Coder modules

Coder publishes plenty of modules that can be used to simplify some common tasks across templates. Some of the modules we publish are,

For a full list of available modules please check Coder module registry.

Module caching

Module caching is enabled by default for all templates. When you publish a new template version, Coder runs terraform init to resolve every module the template references, then archives the resulting .terraform/modules directory and stores it alongside that template version. On every subsequent workspace build, Coder provisioners reuse this cached archive instead of re-fetching modules from their original sources (a git repository, the Coder registry, or another Terraform registry). This avoids redundant network and disk I/O on each build and prevents build failures caused by a module source being slow or temporarily unavailable.

Coder limits cached module archives to 20MB per template version. If your modules exceed this limit, some are skipped and unavailable for Dynamic Parameters evaluation, though builds still fetch the skipped modules directly. Template versions published before Coder started archiving modules have no cache at all, which produces the same "Module not loaded" warnings for every module in the workspace creation form; publishing a new template version fixes this.

To force Coder to re-download modules on every workspace build instead of using the cached archive, select Disable Terraform module caching in a template's Settings > General page, or set disable_module_cache to true with the templates API.

Warning

Disabling module caching makes workspace builds slower and less predictable, since Terraform re-resolves and downloads every module on each build. This isn't recommended for production templates.

Offline installations

In offline and restricted deployments, there are three ways to fetch modules.

Artifactory Remote Terraform Repository (Recommended)
Artifactory Local Repository (manual publishing)
Private git repository

Artifactory Remote Terraform Repository (Recommended)

Configure Artifactory as a Remote Terraform Repository that proxies and caches the Coder registry. This approach provides automatic updates and requires no manual synchronization.

See Mirror the Coder Registry with JFrog Artifactory for complete setup instructions.

Artifactory Local Repository

Air-gapped users can clone the coder/registry repo and publish a local terraform module repository to resolve modules via Artifactory.

Create a local-terraform-repository with name coder-modules-local
Create a virtual repository with name tf
Follow the below instructions to publish coder modules to Artifactory

git clone https://github.com/coder/registry cd registry/registry/coder/modules jf tfc jf tf p --namespace="coder" --provider="coder" --tag="1.0.0"
Generate a token with access to the tf repo and set an ENV variable TF_TOKEN_example.jfrog.io="XXXXXXXXXXXXXXX" on the Coder provisioner.
Create a file .terraformrc with following content and mount at /home/coder/.terraformrc within the Coder provisioner.

provider_installation { direct { exclude = ["registry.terraform.io/*/*"] } network_mirror { url = "https://example.jfrog.io/artifactory/api/terraform/tf/providers/" } }
Update module source as:

module "module-name" { source = "https://example.jfrog.io/tf__coder/module-name/coder" version = "1.0.0" agent_id = coder_agent.example.id ... }

Replace example.jfrog.io with your Artifactory URL

Based on the instructions here.

Example template

We have an example template here that uses our JFrog Docker template as the underlying module.

Private git repository

If you are importing a module from a private git repository, the Coder server or provisioner 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 with read only access to the necessary repos.

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:

# /home/coder/.gitconfig
[credential]
  helper = store

# /home/coder/.git-credentials

# GitHub example:
https://your-github-username:[email protected]

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.

Pass git credentials in Kubernetes

First, create a .gitconfig and .git-credentials file on your local machine. 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.

export NAMESPACE=coder
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: git-secrets
  namespace: $NAMESPACE
type: Opaque
data:
  .gitconfig: $(cat .gitconfig | base64 | tr -d '\n')
  .git-credentials: $(cat .git-credentials | base64 | tr -d '\n')
EOF

Then, modify Coder's Helm values to mount the secret.

coder:
  volumes:
    - name: git-secrets
      secret:
        secretName: git-secrets
  volumeMounts:
    - name: git-secrets
      mountPath: "/home/coder/.gitconfig"
      subPath: .gitconfig
      readOnly: true
    - name: git-secrets
      mountPath: "/home/coder/.git-credentials"
      subPath: .git-credentials
      readOnly: true