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 以复制匹配的值文件，然后重新部署。
# infra/terraform.tfvars
enable_deployments = true # LangGraph 平台（Fleet、Agent Builder 和 Polly 所需）
enable_fleet = true # Fleet（原 Agent Builder），独立运行（chart v0.15+）；需要外部 Postgres + Redis
enable_agent_builder = false # 旧版 agent-builder 路径；与 enable_fleet 互斥
enable_insights = true # 基于 ClickHouse 的分析
enable_polly = true # Polly AI 评估/监控
enable_usage_telemetry = false # 扩展的使用遥测
make init-values
make deploy
规格配置
在terraform.tfvars 中设置 sizing_profile，然后重新运行 make init-values && make deploy。
sizing_profile = "production" # 多副本，带 HPA（推荐）
sizing_profile = "production-large" # 高流量（~50 用户，~1000 traces/sec）
sizing_profile = "dev" # 单副本，最小资源
sizing_profile = "minimum" # 最小占用，适用于资源受限的集群
sizing_profile = "default" # chart 默认值（无规格文件）
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 进行比较。 |
预检
| 命令 | 描述 |
|---|---|
make preflight | 在 Terraform 运行前验证 AWS 凭据、IAM 权限和所需的 CLI 工具。 |
make preflight-post | 在 make apply 之后运行。检查 kubectl 上下文、集群可达性、SSM 参数是否填充、Helm 值是否存在、TLS 配置。 |
make preflight-ssm | 仅检查 SSM 参数。范围比 preflight-post 更窄。 |
基础设施
| 命令 | 描述 |
|---|---|
make init | terraform init。下载提供程序和模块。可安全重复运行。 |
make plan | terraform plan。预览变更。在每次应用前务必审查。 |
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_* 标志复制附加功能的值文件。 |
make deploy | 通过 Helm 部署或升级 LangSmith。运行预检、ESO 同步、分层值构建和核心就绪检查。 |
make apply-eso | 仅重新应用 ESO ClusterSecretStore 和 ExternalSecret。在轮换密钥后但不需要完整 Helm 重新部署时使用。 |
make uninstall | 卸载 LangSmith Helm 发布版本。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 发布版本。 |
make destroy-app | 通过 Terraform 销毁 Helm 发布版本。基础设施保持不变。 |
快速路径
| 命令 | 描述 |
|---|---|
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 命令。Sourcing 它会将 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
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.