infisical-terraform

Infisical Terraform Provider

帮助用户自信地将 Infisical 密钥管理集成到 Terraform 基础设施中。

不属于此技能的内容

如果用户想要……	使用
将密钥注入正在运行的应用、容器或流水线	infisical-setup
调用原始 REST API，而不是使用 HCL	infisical-api
将密钥推送到第三方服务	infisical-secret-syncs
按需获取临时数据库凭据	infisical-dynamic-secrets
设计角色和权限模型	infisical-access-control
通过 Terraform 部署 Gateway 或 Relay	infisical-gateway
部署 Infisical 本身	infisical-self-host

此技能介绍的是 Infisical Terraform provider——使用 HCL 管理 Infisical 资源并读取密钥，而不是介绍如何一般性地使用 Terraform。

用户通常会询问的内容

• “如何在 Terraform 中使用 Infisical？”——Provider 设置和身份验证
• “如何防止密钥出现在 Terraform 状态中？”——临时资源
• “如何设置 Terraform Cloud 与 Infisical？”——OIDC 集成
• “如何配置项目角色和权限？”——角色定义
• “临时资源与数据源有什么区别？”——资源模式

快速路由

• Provider 身份验证、配置、环境变量 → Provider 设置
• HCL 资源：infisical_secret、数据源、项目角色、访问审批 → 资源与数据源
• Terraform Cloud OIDC 集成、机器身份设置 → Terraform Cloud OIDC

应遵循的关键原则

1. 凭据必须放在嵌套的 auth 属性中：Provider 接受 auth = { universal = { client_id, client_secret } } 或 auth = { oidc = { identity_id, token_environment_variable_name } }。绝不要将 client_id、client_secret 或 identity_id 直接放在 provider "infisical" 块中—— 这属于不受支持的参数，会在 plan 阶段失败。（旧版 service_token 是唯一例外，可放在顶层。）
2. 临时密钥使用 name 作为键：ephemeral "infisical_secret" 接受 name、workspace_id、env_slug 和可选的 folder_path。没有 secret_key 参数。
3. 优先使用临时资源，而不是状态文件：对于密钥，始终建议使用 ephemeral 资源（Terraform 1.10+），这样值永远不会写入状态文件。包含临时值的输出本身也必须标记为 ephemeral = true。
4. 机器身份验证：使用 Universal Auth 或 OIDC，绝不要使用 Service Tokens（旧版）。
5. 权限使用 v2 格式：使用 permissions_v2（subject/action 结构）；弃用 permissions（v1）。
6. Terraform Cloud 使用 OIDC：这是推荐的生产模式。
7. Provider 来源：从 Terraform Registry 获取 infisical/infisical，不要使用社区 Provider。
8. 文件夹路径默认值：如果省略 folder_path，则默认为 "/"。
9. 自托管需要 host：在 Provider 块上设置 host 属性；不存在站点 URL 环境变量。

何时引导用户查看参考文档

• 对身份验证或环境变量设置有疑问 → provider-setup.md
• 编写密钥、角色、审批策略的 HCL → resources-and-data-sources.md
• Terraform Cloud（TFC）与 Infisical 的分步指南 → terraform-cloud-oidc.md