AWS Terraform 快速参考

用于 AWS EKS 上 LangSmith 自托管的 Make 目标、Terraform 命令、kubectl、AWS CLI 和 Helm 操作。

使用 AWS Terraform 模块预置的 AWS LangSmith 部署日常操作命令速查表。所有 make 目标都从 modules/aws/ 运行。运行 make help 查看内联摘要。

完整部署设置请参阅 AWS 部署指南。

首次设置

cd terraform/modules/aws

# 1. Generate terraform.tfvars (interactive wizard)
make quickstart

# 2. Load secrets into SSM Parameter Store and export TF_VAR_* into your shell.
#    Must use `source` — Make runs each target in a subshell.
source infra/scripts/setup-env.sh

# 2a. Confirm secrets and TF_VAR_* are set (optional but recommended)
make secrets

# 3. Provision infrastructure (~20–25 min)
make init
make plan       # review — confirm no unexpected destroy/replace actions
make apply

# 3a. Verify post-infra state (optional)
make preflight-post

# 4. Update kubeconfig for the EKS cluster
make kubeconfig

# 5. Generate Helm values from Terraform outputs
make init-values

# 6. Deploy LangSmith (~10 min)
make deploy

完成 make quickstart 和 source infra/scripts/setup-env.sh 后的快速路径：

make quickdeploy        # interactive (prompts before terraform apply)
make quickdeploy-auto   # non-interactive (auto-approves terraform)

日常运维

# Check deployment state across all layers; print next-step guidance
make status

# Re-deploy after editing Helm values or upgrading
make deploy

# Re-generate Helm values after Terraform changes
make init-values

# Re-sync ESO secrets without redeploying
make apply-eso

# Check SSM secrets and TF_VAR_* export status (read-only)
make secrets

# List all SSM parameters with last-modified timestamps
make secrets-list

# Manage SSM secrets interactively (view, set, rotate, diff vs cluster)
make ssm

# Update kubeconfig for the EKS cluster
make kubeconfig

预检

# Pre-Terraform: AWS credentials + IAM permissions
make preflight

# Post-apply: kubectl, SSM params, Helm values, TLS config
make preflight-post

# SSM only — confirm all parameters are populated (after make setup-env)
make preflight-ssm

附加组件

附加组件由 infra/terraform.tfvars 中的 enable_* 标志控制。设置这些标志，重新运行 init-values 以复制匹配的 values 文件，然后重新部署。

# infra/terraform.tfvars
enable_deployments     = true   # LangGraph Platform (required for Fleet, Agent Builder, and Polly)
enable_fleet           = true   # Fleet (formerly Agent Builder), standalone (chart v0.15+); requires external Postgres + Redis
enable_agent_builder   = false  # Older agent-builder path; mutually exclusive with enable_fleet
enable_insights        = true   # ClickHouse-backed analytics
enable_polly           = true   # Polly AI eval/monitoring
enable_usage_telemetry = false  # Extended usage telemetry

make init-values
make deploy

规格配置

在 terraform.tfvars 中设置 sizing_profile，然后重新运行 make init-values && make deploy。

sizing_profile = "production"        # multi-replica with HPA (recommended)
sizing_profile = "production-large"  # high-volume (~50 users, ~1000 traces/sec)
sizing_profile = "dev"               # single-replica, minimal resources
sizing_profile = "minimum"           # smallest footprint, for constrained clusters
sizing_profile = "default"           # chart defaults (no sizing file)

Make 目标

设置与密钥

命令	说明
make quickstart	交互式向导。生成 infra/terraform.tfvars（区域、节点规格、TLS 方式、附加组件）。
make setup-env	打印用于将密钥加载到 shell 的确切 source 命令。无法直接导出变量。
make secrets	显示每个参数的 SSM 密钥状态（✓ SET / ✗ MISSING），检查 TF_VAR_* 导出，并给出后续步骤。
make secrets-list	列出此部署的所有 SSM 参数及其最后修改时间戳。
make ssm	交互式 SSM 参数管理器。查看、设置、轮换、验证，并与集群 Secret 进行 diff。

预检

命令	说明
make preflight	在 Terraform 运行前验证 AWS 凭证、IAM 权限和必需的 CLI 工具。
make preflight-post	在 make apply 之后运行。检查 kubectl 上下文、集群可达性、SSM 参数已填充、Helm values 存在、TLS 配置。
make preflight-ssm	仅检查 SSM 参数。范围比 preflight-post 更窄。

基础设施

命令	说明
make init	terraform init。下载 provider 和模块。可安全重复运行。
make plan	terraform plan。预览更改。每次 apply 前请审阅。
make apply	terraform apply。预置 VPC、EKS、RDS、ElastiCache、S3、ALB、IRSA。需要 20 到 25 分钟。
make destroy	terraform destroy。拆除所有基础设施。请先运行 make uninstall。

Helm 部署

命令	说明
make init-values	根据 Terraform 输出生成 helm/values/langsmith-values-overrides.yaml。根据 enable_* 标志复制附加组件 values 文件。
make deploy	通过 Helm 部署或升级 LangSmith。运行预检、ESO 同步、分层 values 构建和核心就绪检查。
make apply-eso	仅重新应用 ESO 的 ClusterSecretStore 和 ExternalSecret。在轮换密钥后使用，无需完整 Helm 重新部署。
make uninstall	卸载 LangSmith Helm release。Terraform 基础设施保持不变。

Terraform 管理的 Helm

命令	说明
make init-app	将实时基础设施的 Terraform 输出拉取到 app/infra.auto.tfvars.json。
make plan-app	对 app/ 模块执行 terraform plan。会先自动运行 init-app。
make apply-app	通过 Terraform（app/ 模块）部署 LangSmith Helm release。
make destroy-app	通过 Terraform 销毁 Helm release。基础设施保持不变。

快速路径

命令	说明
make quickdeploy	一条命令完成完整部署。按顺序串联 terraform apply → kubeconfig → init-values → helm deploy，并带有门禁。
make quickdeploy-auto	与 quickdeploy 相同，但非交互。向 terraform 传递 -auto-approve。
make deploy-all	依次执行 make apply → make kubeconfig → make init-values → make deploy。
make deploy-all-tf	依次执行 make apply → make init-values → Terraform app/ plan 和 apply。

实用工具

命令	说明
make status	检查所有层的部署状态，并打印下一步要运行的命令。
make status-quick	与 status 相同，但跳过 SSM 和 Kubernetes 查询（更快）。
make kubeconfig	打印要运行的 source infra/scripts/set-kubeconfig.sh 命令。source 后会将 KUBECONFIG 导出到专用的 ~/.kube/langsmith-<cluster> 文件，而不是编辑 ~/.kube/config。
make tls	自带 ACM 证书 + Route 53 A 别名。当设置了 langsmith_domain 且需要 DNS 接线时使用。
make clean	删除所有本地生成和敏感文件。在 make destroy 之后运行。

测试

命令	说明
make test-e2e	针对当前集群的端到端网关测试（ALB 或 Envoy Gateway）。
make test-permutations	在当前集群上顺序运行排列测试。使用 ARGS="1 2 5" 运行子集。
make test-parallel	在隔离集群上并行运行排列测试。你的集群不受影响。

kubectl

# Pod health
kubectl get pods -n langsmith
kubectl get pods -n langsmith -w
kubectl describe pod <pod-name> -n langsmith
kubectl logs <pod-name> -n langsmith --tail=100 -f
kubectl logs <pod-name> -n langsmith --previous --tail=50

# ALB and ingress
kubectl get ingress -n langsmith
kubectl describe ingress -n langsmith

# External Secrets Operator sync status
kubectl get externalsecret langsmith-config -n langsmith

# TLS
kubectl get certificate -n langsmith
kubectl get challenges -n langsmith
kubectl describe certificate <cert-name> -n langsmith

# Helm
helm status langsmith -n langsmith
helm history langsmith -n langsmith
helm get values langsmith -n langsmith

# IRSA — check per-component service account annotations
kubectl get sa -n langsmith -o yaml | grep eks.amazonaws.com

# LangSmith Deployment (LangGraph Platform)
kubectl get lgp -n langsmith
kubectl get crd | grep langchain
kubectl get pods -n keda

AWS CLI

# EKS
aws eks list-clusters --region <region>
aws eks describe-cluster --name <cluster-name> --region <region>
aws eks update-kubeconfig --region <region> --name <cluster-name>

# RDS
aws rds describe-db-instances \
  --query "DBInstances[?contains(DBInstanceIdentifier,'langsmith')]"

# ElastiCache
aws elasticache describe-cache-clusters \
  --query "CacheClusters[?contains(CacheClusterId,'langsmith')]"

# S3
aws s3 ls s3://<bucket-name>
aws s3api get-bucket-location --bucket <bucket-name>

# ALB
aws elbv2 describe-load-balancers \
  --query "LoadBalancers[?contains(LoadBalancerName,'langsmith')]"

# VPC endpoint
aws ec2 describe-vpc-endpoints \
  --filters "Name=service-name,Values=com.amazonaws.<region>.s3" \
  --query "VpcEndpoints[].State"

# SSM secrets
aws ssm get-parameters-by-path --path "/langsmith/<base-name>/" --with-decryption

# IAM role
aws iam get-role --role-name <irsa-role-name>

Terraform

cd modules/aws/infra

terraform init
terraform plan
terraform apply
terraform apply -target=module.eks
terraform output
terraform output -raw cluster_name
terraform output -raw alb_dns_name
terraform output -raw langsmith_irsa_role_arn
terraform output -raw bucket_name
terraform state list

拆除

cd terraform/modules/aws

# Option A: script-driven deploy
make uninstall

# Option B: Terraform-managed deploy
make destroy-app

# Then destroy infrastructure:
# 1. Set postgres_deletion_protection = false in infra/terraform.tfvars
# 2. Apply the change, then destroy
cd infra
terraform apply
terraform destroy

---