学习笔记 · Obsidian
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，必须确定单一权威来源。
通用两阶段部署
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.tfvarsgitignored。 - Encryption key、API key salt 等首次部署后不得随意重生成；重新跑 wizard 前先对比现存 Secret。
- Terraform state 本身可能含连接信息，使用加密远端 backend、state locking、最小 IAM 和审计。
Day-2 工作流
- 固定 module commit/tag 与 provider 版本，
terraform init -upgrade需独立评审。 plan输出进入 PR，检查 replacement、数据库 deletion protection、网络和 IAM 变化。apply只改基础设施；生成新 Helm values 后再执行应用发布与健康检查。- Add-on 通过
enable_*打开后，重新生成 values 并核对节点容量/新增 Secret。 - 日常排查先更新 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 或强改数据库版本。
交付验收
terraform plan无意外 replace/delete，敏感值未出现在日志。- Cluster、node pool、DB/cache/blob、identity 与 network path 分层验证。
- Helm release、migration Job、Pod readiness、Ingress/TLS 与 smoke Trace 通过。
- Add-on 逐个启用并验证相应 Pod、Secret、队列和 entitlement。
- 运行备份恢复和升级预演，记录实际 RPO/RTO。
- 用 variables reference 生成组织自己的受控配置表，不直接复制 quick reference 的默认值到生产。