templates

模板

编写或更新 Coder 模板。模板是 Coder 用来构建工作区的 Terraform 代码；一个模板可以用于多个工作区。

权威来源

应用任何特定主题的内容前，请先阅读最新的上游文档：

• https://coder.com/docs/llms.txt：文档索引。
• 仅当索引信息不足时，才查看 https://coder.com/docs/llms-full.txt。
• https://registry.coder.com/templates：规范的起始模板及其导入 ID。

本技能仅保留编写模板的工作流、用户交互规则，以及少数模板特有的注意事项。

用户交互

用户想要的是可用的工作区，而不是 Terraform 速成课程。

• 默认选择适合其基础设施的合理起始模板。只需询问用户确认。
• 写入任何内容前，展示计划的目录结构（模板名称、文件、参数）。只需询问一次是或否。
• 不要在聊天中索要云凭据。使用部署的 provisioner 身份验证；仅在缺少凭据时提出。

工作流

1. 选择起始模板

将用户的意图对应到 https://registry.coder.com/templates 中的一个官方起始模板：

• docker、docker-devcontainer、docker-rstudio：容器主机。
• kubernetes、kubernetes-devcontainer、kubernetes-envbox：K8s 集群。
• aws-linux、aws-windows、aws-devcontainer：AWS EC2。
• gcp-linux、gcp-windows、gcp-vm-container、gcp-devcontainer：GCP Compute Engine。
• azure-linux、azure-windows：Azure VM。
• digitalocean-linux：DigitalOcean Droplets。
• incus：LXD/Incus 容器。
• nomad-docker：由 Nomad 驱动的 Docker。
• scratch：仅供高级编写者使用的空模板。

搭建所选起始模板：

TEMPLATE_DIR="$(mktemp -d)/$TEMPLATE_NAME"
coder templates init --id "$STARTER_ID" "$TEMPLATE_DIR"

如果用户想编辑现有模板，则改为拉取：

TEMPLATE_DIR="$(mktemp -d)/$TEMPLATE_NAME"
coder templates pull "$TEMPLATE_NAME" "$TEMPLATE_DIR"

2. 了解模板结构

每个 Coder 模板的 main.tf 都包含以下组成部分：

• terraform 块：必需的 provider（始终包括 coder/coder，以及基础设施 provider）。
• data "coder_workspace" "me" 和 data "coder_workspace_owner" "me"：工作区上下文，包括 start_count。
• data "coder_parameter" 块：创建工作区时的用户输入。
• 一个 coder_agent 资源：在工作区内运行的 Agent。
• coder_app 资源：用于 VS Code、JetBrains、Jupyter 等应用的控制面板按钮。
• 基础设施资源：根据起始模板而定，例如 docker_container、kubernetes_deployment、aws_instance 等。
• 可选的 module 块：来自 registry.coder.com 的 Coder 模块。

3. 修改

应用用户要求的更改。常见模式：

• 添加 coder_parameter。当值应在重建时可更改，设置 mutable = true。使用 validation 块强制执行正则表达式或范围要求。使用 option 块设置枚举值。
• 添加来自 https://registry.coder.com/modules 的模块。具体模块的语法请参考 modules 技能或模块 README。
• 使用以工作区所有者为键的专用卷资源持久化数据。不要依赖容器或 VM 文件系统在重建后保留数据。
• 对于工作区停止时应销毁的资源，设置 count = data.coder_workspace.me.start_count。

切勿在 terraform.tfvars 中存储密钥，或通过普通的 --variable 传递密钥。请使用 Coder 的密钥变量或外部 provisioner。

4. 在本地验证

cd "$TEMPLATE_DIR"
terraform init
terraform fmt
terraform validate

5. 推送

首次推送：

coder templates create "$TEMPLATE_NAME" -d "$TEMPLATE_DIR" --yes

更新现有模板：

coder templates push "$TEMPLATE_NAME" -d "$TEMPLATE_DIR" --yes
coder templates versions list "$TEMPLATE_NAME"

推送时使用 --activate 发布新版本，或之后使用 coder templates versions promote 发布。

6. 测试

使用新版本创建一个工作区：

coder create "$WORKSPACE_NAME" \
  --template "$TEMPLATE_NAME" \
  --yes

显式传入每个必需参数。对于没有合理默认值的列表参数，使用 []。对于枚举，使用第一个选项。只有在没有合适默认值时才询问用户。

请等待 Agent 状态变为 ready，而不只是等待构建完成。如果 Agent 一直处于 connecting 状态，工作区将无法使用。

7. 移交

如果这是用户的第一个模板，请在结束前说明：

• 模板在仪表板中的位置。
• 一个用户可以运行 coder ssh 连接的工作区名称。
• 用一句话说明如何更新：编辑 main.tf，然后运行 coder templates push。

常用参数

了解这些参数很有用，因为用户经常会询问：

• git_repo_url：工作区启动时要克隆的 URL。与 git-clone 模块配套使用。
• region：特定于提供商的区域选择器。与匹配的 *-region 模块配套使用。
• instance_type 或 node_size：特定于提供商的机器规格，带有 option 列表。
• dotfiles_uri：启动时克隆个人 dotfiles 仓库。与 dotfiles 模块配套使用。
• vscode_binary_version：用于固定 code-server 版本的可选参数。

variable 与 coder_parameter 的区别

对于基础设施级别的选项，请使用 Terraform variable（在运行 coder templates push 时通过 --variable 设置）。这些选项在整个模板部署中固定不变，并由管理员设置：

• 主机的 CPU 架构（arch）
• 存储池或卷组名称
• 远程主机标识符或集群端点

对于由工作区用户在创建或构建时选择的选项，请使用 data "coder_parameter"：

• 操作系统映像或发行版
• CPU 数量、内存和磁盘大小
• 合理情况下可能因工作区而异的任何值

绝不要将基础设施详情作为 coder_parameter 暴露。用户不应该需要了解主机的 CPU 架构或存储池名称。

# Good: arch is an admin concern, not a user choice
variable "arch" {
  description = "CPU architecture of the VM host (amd64 or arm64). Set at template push time."
  type        = string
  default     = "amd64"
}

# Good: image is a user choice made per workspace
data "coder_parameter" "image" {
  name    = "image"
  type    = "string"
  default = "ubuntu/noble/cloud"
  option {
    name  = "Ubuntu 24.04 LTS"
    value = "ubuntu/noble/cloud"
  }
}

在推送时传入 variable 值：

coder templates push my-template -d . --yes \
  --variable arch=arm64 \
  --variable storage_pool=fast-nvme

设置 coder_agent 目录

coder_agent 上的 dir 是可选的，默认值为 $HOME。它设置 SSH 和 Web 终端会话的起始目录，以及内置 VS Code 应用打开的文件夹。只有在用户需要进入项目检出目录时才设置，否则请省略。

resource "coder_agent" "main" {
  arch = var.arch
  os   = "linux"
  dir  = "/home/${local.username}/project"
}

• SFTP 和 scp 会将相对路径和以 ~/ 开头的路径解析为相对于 dir 的路径，因此文件传输时请使用绝对路径。
• Coder provider 2.17 到 2.19 版本将 dir 标记为已弃用，并在其值不是 $HOME 时发出警告。2.20.0 版本移除了弃用标记，因此可以忽略该警告。
• 在 macOS v0.8.4 或更高版本以及 Windows v0.8.5 或更高版本上，Coder Desktop 文件同步支持任何 dir。较早版本的 Desktop 在 dir 不是 $HOME 时无法启动文件同步。

向 coder/registry 贡献模板

提交 PR 前，请阅读 registry 的 AGENTS.md，了解代码风格、结构要求以及完整的 PR 审查清单。另请阅读 PR 模板，了解 PR 正文的格式要求。

以下是模板特有的补充说明（AGENTS.md 中未涵盖）：

• 模板位于 registry/<namespace>/templates/<name>/，包含 main.tf 和 README.md。无需提供 .tftest.hcl（只有模块需要测试）。

• PR 标题格式：feat(<namespace>/templates/<name>): <short description>（例如 feat(bpmct/templates/incus-vm): add Incus VM template）。

• 创建分支前，请先将 fork 的 main 与上游同步。 否则，PR 差异会将你所在命名空间中所有已有文件都显示为新增内容，而不只是你的更改：

  gh api -X POST /repos/<your-username>/registry/merge-upstream \
    -f branch=main
  

• 运行 bun fmt（它会运行 terraform fmt 和 Prettier），并确认推送前没有产生差异。

安全措施

• 不要推送未经 terraform validate 验证的模板版本。
• 未确认没有任何内容依赖某个活动模板版本前，不要将其归档或删除。
• 如果用户仍在迭代，不要在 coder templates push 中传入 --activate。他们可能想先审查新版本。
• 不要将云凭据、OAuth 密钥或工作区令牌放入 main.tf 或 terraform.tfvars。请使用密钥变量。
• 不要向尚未编写过 Terraform 的用户推荐 scratch。

捆绑资源

此技能不附带针对各个模板的操作指南。有关特定提供商的详细信息，请参阅 registry.coder.com 上各模板的 README 以及上游 Coder 文档。