---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags: [langchain, langsmith, terraform, aws, azure, gcp]
topic: LangSmith Terraform Provider 与 AWS/Azure/GCP 自托管模块
sources:
  - "https://docs.langchain.com/langsmith/manage-with-terraform"
  - "https://docs.langchain.com/langsmith/self-host-terraform"
  - "https://docs.langchain.com/langsmith/self-host-terraform-aws-architecture"
  - "https://docs.langchain.com/langsmith/self-host-terraform-aws-deploy"
  - "https://docs.langchain.com/langsmith/self-host-terraform-aws-quick-reference"
  - "https://docs.langchain.com/langsmith/self-host-terraform-aws-troubleshooting"
  - "https://docs.langchain.com/langsmith/self-host-terraform-aws-variables"
  - "https://docs.langchain.com/langsmith/self-host-terraform-azure-architecture"
  - "https://docs.langchain.com/langsmith/self-host-terraform-azure-deploy"
  - "https://docs.langchain.com/langsmith/self-host-terraform-azure-quick-reference"
  - "https://docs.langchain.com/langsmith/self-host-terraform-azure-troubleshooting"
  - "https://docs.langchain.com/langsmith/self-host-terraform-azure-variables"
  - "https://docs.langchain.com/langsmith/self-host-terraform-gcp-architecture"
  - "https://docs.langchain.com/langsmith/self-host-terraform-gcp-deploy"
  - "https://docs.langchain.com/langsmith/self-host-terraform-gcp-quick-reference"
  - "https://docs.langchain.com/langsmith/self-host-terraform-gcp-troubleshooting"
  - "https://docs.langchain.com/langsmith/self-host-terraform-gcp-variables"
last_verified: 2026-08-11
---

# Terraform 多云基础设施即代码

## 两类 Terraform 能力

| 能力 | 管什么 | 不管什么 |
| --- | --- | --- |
| LangSmith Terraform Provider | Workspace、Role/Member、Tag、ABAC Policy、Evaluator、Run Rule、Alert | Kubernetes/VPC/数据库 |
| LangChain self-host modules | VPC、EKS/AKS/GKE、PostgreSQL、Redis、Blob、Secret、DNS、Helm | 业务 Agent 与完整组织治理 |

Provider v0.0.6+ 才支持 Resource Tag 与 Access Policy。认证优先环境变量/Profile，不在 `.tf` 或 state 输出中硬编码 API key。Provider 与 API 修改同一资源时会 drift，必须确定单一权威来源。

## 通用两阶段部署

```text
infra layer: network + cluster + DB/cache/blob + IAM/secrets
     ↓ outputs / generated values
app layer: Kubernetes Secret + LangSmith Helm release
     ↓ optional flags
add-ons: Deployment / Fleet / Insights / Sandboxes / Engine
```

官方脚本驱动 Helm 是推荐路径；也可让 Terraform 管 Helm release。两条路径不能同时成为同一 release 的 owner，否则 state 与实际 Helm 历史会互相覆盖。已有自管集群只需 Helm 时，不必引入全套 Terraform module。

## 三云关键差异

| 主题 | AWS | Azure | GCP |
| --- | --- | --- | --- |
| Secret flow | `setup-env.sh` → SSM → External Secrets | `secrets.auto.tfvars` + Key Vault → K8s Secret | `setup-env.sh` → Secret Manager/TF env |
| Pod 身份 | IRSA | Workload Identity/Federated Credential | Workload Identity |
| 默认入口 | ALB，可选 Envoy | AGIC/Istio/Envoy | Envoy Gateway |
| TLS | ACM 或 cert-manager | Key Vault/cert-manager | cert-manager/Cloud DNS |
| 生产存储 | RDS、ElastiCache、S3 | Flexible PG、Managed Redis、Blob | Cloud SQL、Memorystore、GCS |

AWS 的 ALB 不能单独完成 split data plane，需要与 Envoy 链接；私有 EKS 可能需要 bastion。Azure 的 Key Vault purge protection 一旦启用不可关闭，Workload Identity 的 subject 必须精确匹配。GCP 需先启用 Cloud Resource Manager 等 API，GKE 与服务启用有较长冷启动窗口。

## Light 与 Production tier

Light 把 PostgreSQL/Redis/ClickHouse 等更多组件放在集群内，部署快但 HA、备份和升级责任重；Production 使用托管外部服务、工作负载身份与对象存储。选择是可靠性/运维责任的架构决定，不应仅按 Terraform 变量默认值决定。

## Secret 与 State 管理

- `terraform.tfvars` 只放非敏感区域、尺寸与 feature flag。
- license、密码、encryption key 通过脚本写 Secret Manager/Key Vault/SSM，并确保 `secrets.auto.tfvars` gitignored。
- Encryption key、API key salt 等首次部署后不得随意重生成；重新跑 wizard 前先对比现存 Secret。
- Terraform state 本身可能含连接信息，使用加密远端 backend、state locking、最小 IAM 和审计。

## Day-2 工作流

1. 固定 module commit/tag 与 provider 版本，`terraform init -upgrade` 需独立评审。
2. `plan` 输出进入 PR，检查 replacement、数据库 deletion protection、网络和 IAM 变化。
3. `apply` 只改基础设施；生成新 Helm values 后再执行应用发布与健康检查。
4. Add-on 通过 `enable_*` 打开后，重新生成 values 并核对节点容量/新增 Secret。
5. 日常排查先更新 kubeconfig，再用官方 health/preflight 脚本与云 CLI 验证身份、入口、数据库和 Secret sync。

## 高风险操作

- `terraform destroy` 前先禁用/删除 add-on 资源，保留数据快照，并确认 deletion protection；不要为“让 destroy 通过”直接关闭保护后立即执行。
- Azure `make clean` 若早于 destroy 可能让资源失去 state 管理；Key Vault/网络删除常因依赖与 purge protection 卡住。
- AWS PostgreSQL deletion protection 与 GCP deletion protection 都应通过显式变更、二次 plan 和审批处理。
- Envoy/Ingress 重建可能改变 IP/hostname；DNS TTL、证书与 allowlist 要纳入变更窗口。
- Helm `pending-upgrade`、migration/backfill hook 失败时先收集状态，禁止直接删除 migration Job 或强改数据库版本。

## 交付验收

1. `terraform plan` 无意外 replace/delete，敏感值未出现在日志。
2. Cluster、node pool、DB/cache/blob、identity 与 network path 分层验证。
3. Helm release、migration Job、Pod readiness、Ingress/TLS 与 smoke Trace 通过。
4. Add-on 逐个启用并验证相应 Pod、Secret、队列和 entitlement。
5. 运行备份恢复和升级预演，记录实际 RPO/RTO。
6. 用 variables reference 生成组织自己的受控配置表，不直接复制 quick reference 的默认值到生产。