在 AWS 上使用 Terraform 部署 LangSmith

使用公开的 Terraform 模块将 LangSmith 部署到 AWS。将部署作为代码管理，可以对环境进行版本控制、审查，并在不同账户间复制 LangSmith 环境，而无需在 AWS 控制台中手动操作。安装分两个阶段进行：

基础设施：Terraform 配置 VPC、EKS、RDS、ElastiCache、S3 和 IAM。
应用程序：Helm 在集群上安装 LangSmith chart。

基础安装完成后，可通过设置标志并重新部署来启用可选的附加组件。

前提条件

必需工具

工具	版本	用途
AWS CLI	v2	身份验证、查询 AWS 资源、管理 EKS kubeconfig
Terraform	1.5	运行基础设施模块
`kubectl`	1.33	检查 EKS 集群
Helm	3.12	安装和管理 LangSmith chart
`eksctl`	latest	可选，便于管理 kubeconfig 和调试

在 macOS 上安装：

brew install awscli kubectl helm eksctl
brew tap hashicorp/tap && brew install hashicorp/tap/terraform

验证每个工具是否在 PATH 中：

aws --version
terraform version
kubectl version --client
helm version

对于 Linux，请遵循 AWS CLI 安装指南，并使用您发行版的包管理器安装其余工具。

所需的 AWS IAM 权限

运行 Terraform 的 IAM 用户或角色需要创建和管理云基础架构的权限。以下托管策略涵盖了所有方面。将它们作为起点，并在部署稳定后调整为最小权限原则。

策略	用途
`AmazonEKSClusterPolicy`	创建和管理 EKS 集群
`AmazonVPCFullAccess`	创建 VPC、子网、路由表和 NAT
`AmazonRDSFullAccess`	创建和管理 RDS PostgreSQL 实例
`AmazonElastiCacheFullAccess`	创建 ElastiCache Redis 集群
`AmazonS3FullAccess`	创建 S3 存储桶和 VPC 端点
`IAMFullAccess`	创建 IRSA 角色和策略

认证后，从 modules/aws/ 运行 make preflight。预检脚本会确认当前凭证可以执行每个必需操作，并报告第一个缺失的权限，这比在 terraform apply 过程中发现问题更快。

身份验证

使用 CLI 配置 AWS 凭证：

aws configure

或导出环境变量：

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="us-west-2"

确认凭证有效，并且目标区域已在账户中启用：

aws sts get-caller-identity
aws ec2 describe-availability-zones --query 'AvailabilityZones[].ZoneName' --output table

许可证密钥和域名

在 terraform apply 之前，必须准备好两个非 AWS 项目：

LangSmith 许可证密钥。 联系销售团队获取。密钥由安装脚本存储在 AWS SSM Parameter Store 中，而不是在 tfvars 文件中。
域名或子域名，该域名解析到 AWS 账户，以及覆盖该域名的 ACM 证书（或者将 tls_certificate_source 变量设置为 letsencrypt / none）。

集群大小参考

两个独立的设置控制容量：

基础设施容量通过基础设施变量 eks_managed_node_groups、postgres_instance_type 和 redis_instance_type 直接设置实例类型和节点数量。模块默认值是一个 m5.4xlarge 节点组（最小 3，最大 10），RDS 使用 db.t3.large，ElastiCache 使用 cache.m6g.xlarge。
sizing_profile 选择 Helm 大小覆盖层（Pod 资源请求和限制）。init-values.sh 和 deploy.sh 会读取它；Terraform 不会。

在部署前，请根据您的目标层级调整基础设施大小。有关各层级的建议，请参考扩展指南。

对于生产工作负载，还计划配置外部的 LangChain 托管 ClickHouse 或自管理的外部 ClickHouse 集群。集群内 ClickHouse 仅支持用于开发/概念验证。

快速入门

有关 make 目标、所需变量和常见约束的精简速查表，请参阅 AWS 快速参考。

要获得从零到运行 LangSmith 实例的最快路径，请按顺序运行以下命令：

# 1. Clone the public modules
git clone https://github.com/langchain-ai/terraform.git
cd terraform/modules/aws

# 2. Generate terraform.tfvars interactively (Enter accepts current values)
make quickstart

# 3. Load secrets into SSM Parameter Store
#    Must be sourced, not executed
source infra/scripts/setup-env.sh

# 4. Provision infrastructure (~20 to 25 min)
make init
make plan
make apply

# 5. Configure kubectl
make kubeconfig
kubectl get nodes

# 6. Deploy LangSmith via Helm (~5 to 10 min)
make init-values
make deploy

# 7. Confirm
kubectl get pods -n langsmith
kubectl get ingress -n langsmith

要将基础设施和应用程序连接在一个命令中：

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

make quickdeploy 按顺序运行 terraform apply → kubeconfig → init-values → helm deploy。如果任何步骤失败，命令将退出并提供从该步骤恢复的说明。以下部分将详细介绍每个阶段。

配置基础设施

Terraform 配置以下 AWS 资源：

资源	用途
VPC + 子网 + NAT	集群和托管服务的私有网络
EKS 集群 + 节点组	Kubernetes 计算
RDS PostgreSQL	LangSmith 操作数据
ElastiCache Redis	队列和缓存
S3 存储桶 + VPC 端点	跟踪负载的二进制存储
ALB + 监听器	具有 TLS 的公共入口
SSM Parameter Store 条目	应用程序密钥，由 External Secrets Operator 同步到集群
IRSA 角色 + IAM 策略	每个服务的 AWS 访问权限
KEDA, cert-manager, ESO	与基础设施一起安装的引导工作负载

克隆和配置

git clone https://github.com/langchain-ai/terraform.git
cd terraform/modules/aws

所有后续命令均从 modules/aws/ 运行。运行 make help 获取完整的目标列表。使用交互式向导生成 terraform.tfvars：

make quickstart

向导会提示输入命名前缀、区域、EKS 大小、TLS 来源、外部与集群内服务，以及可选的附加组件标志。它将写入 infra/terraform.tfvars。重新运行向导会预先选择现有值；在每个提示处按 Enter 保持当前配置。更喜欢手动编辑？复制示例并填写必填字段：

cp infra/terraform.tfvars.example infra/terraform.tfvars
vi infra/terraform.tfvars

最低要求的变量：

name_prefix = "acme"
environment = "prod"
region      = "us-west-2"

eks_cluster_version = "1.33"
eks_managed_node_groups = {
  default = {
    name           = "node-group-default"
    instance_types = ["m5.4xlarge"]
    min_size       = 3
    max_size       = 10
  }
}

postgres_source = "external"
redis_source    = "external"

tls_certificate_source = "acm"
acm_certificate_arn    = "arn:aws:acm:us-west-2:<account-id>:certificate/<cert-id>"
langsmith_domain       = "langsmith.example.com"

有关每个输入变量，请参阅 AWS 变量参考。

在应用之前配置远程状态后端。编辑 infra/backend.tf 以指向您控制的 S3 存储桶和 DynamoDB 锁表。Terraform 存储库默认提供本地后端，供首次评估使用。

将密钥加载到 SSM Parameter Store

source infra/scripts/setup-env.sh

脚本读取 terraform.tfvars，派生 SSM 路径 /langsmith/{name_prefix}-{environment}/，然后对于每个密钥，要么重用导出的值，读取现有的 SSM 参数，自动生成一个（用于盐和令牌），要么提示您输入。许可证密钥和管理员密码是您需要交互式提供的两个值。该脚本必须通过 source 执行（而不是直接执行），因为 make 无法将环境变量导出回父 shell。脚本管理以下 SSM 参数：

SSM 键	如何设置	注意事项
`postgres-password`	提示输入	RDS 使用此密码
`redis-auth-token`	自动生成 (`openssl rand -hex 32`)	ElastiCache 需要十六进制格式
`langsmith-api-key-salt`	自动生成 (`openssl rand -base64 32`)	切勿轮换，否则会破坏所有 API 密钥
`langsmith-jwt-secret`	自动生成 (`openssl rand -base64 32`)	切勿轮换，否则会使所有会话失效
`langsmith-license-key`	提示输入	来自您的 LangChain 账户团队
`langsmith-admin-password`	提示输入	必须包含符号
`deployments-encryption-key`	自动生成 Fernet 密钥	LangSmith 部署附加组件
`agent-builder-encryption-key`	自动生成 Fernet 密钥	Agent Builder 附加组件（Fleet 复用）
`insights-encryption-key`	自动生成 Fernet 密钥	Insights 附加组件
`polly-encryption-key`	自动生成 Fernet 密钥	Polly 附加组件

验证密钥是否存在并且 TF_VAR_* 环境变量已导出：

make secrets

应用

在干净账户上配置 AWS 云基础架构大约需要 20 到 25 分钟。不要中断应用过程。

make init
make plan
make apply

make plan 显示建议的差异。应用前请检查输出。make apply 按依赖顺序进行配置：VPC 和安全组，然后是 EKS（约 12 分钟）和 RDS（约 8 分钟，并行进行），然后是节点组、ElastiCache、S3 和 ALB。

配置 kubectl

make kubeconfig
kubectl get nodes
kubectl get pods -n kube-system

所有节点应报告 Ready，核心附加组件（CoreDNS、kube-proxy、VPC CNI、KEDA、ESO）应为 Running。cert-manager 仅在 tls_certificate_source = letsencrypt 或 create_cert_manager_irsa = true 时运行。

部署 LangSmith

支持两种部署路径。选择其一。

脚本驱动的 Helm 部署（推荐）

适用于大多数部署。交互式提示引导您完成大小和产品选择。

cd modules/aws

make init-values
make deploy

init-values.sh 会提示输入管理员电子邮件，然后读取 sizing_profile 和 terraform.tfvars 中的 enable_* 标志，并将匹配的值文件从 helm/values/examples/ 复制到 helm/values/。重新运行时，它会保留您的选择并刷新 Terraform 输出。 make deploy 运行 helm/scripts/deploy.sh，该脚本：

刷新 kubeconfig。
运行预检（AWS 凭证、集群可达性、langchain Helm 仓库）。
应用 External Secrets Operator ClusterSecretStore 和 ExternalSecret，以便集群直接从 SSM 读取密钥。
使用分层值文件安装 LangSmith Helm chart。

预计 chart 安装和 Pod 就绪需要 5 到 10 分钟。

验证

kubectl get pods -n langsmith
kubectl get ingress -n langsmith

当所有 Pod 都为 Running 且入口显示 ALB DNS 名称时，部署即准备就绪。使用您在 langsmith_domain 中配置的域名（或 ALB DNS 名称）访问 UI。如果您完成了脚本驱动的部署，则已完成。以下部分是替代部署路径，不是额外的步骤。

Terraform 管理的 Helm 部署

最适合希望将完整部署置于 Terraform 状态中的团队，或用于“自带基础设施”场景。app/ 模块直接管理 External Secrets Operator 布线、helm_release 和功能开关。

cd modules/aws

# Generate Helm values files from templates (required, the app module reads these)
make init-values

# Pull infra outputs into app/infra.auto.tfvars.json
make init-app

# Configure app-specific settings
cp app/terraform.tfvars.example app/terraform.tfvars
# Edit app/terraform.tfvars, set admin_email, sizing, and feature toggles

# Deploy
make plan-app
make apply-app

app/terraform.tfvars 文件控制应用程序配置：

admin_email          = "admin@example.com"
sizing               = "production"   # production | production-large | dev | none
enable_agent_deploys = true
enable_agent_builder = true
enable_insights      = true
enable_polly         = true
clickhouse_host      = "clickhouse.example.com"

在运行 make plan-app 之前，必须运行 make init-values。应用模块从 helm/values/ 读取值文件，init-values 根据 infra/terraform.tfvars 中的大小和附加组件选择从 helm/values/examples/ 填充它们。

对于“自带基础设施”，跳过 make init-app，并在 app/terraform.tfvars 中手动设置所有变量。

启用附加组件

每个附加组件都由 infra/terraform.tfvars 中的一个标志控制。设置标志后，重新运行 make init-values 以复制匹配的值文件，然后重新运行 make deploy。

enable_deployments     = true   # LangGraph 平台（Fleet、Agent Builder 和 Polly 所需）
enable_fleet           = true   # Fleet（原 Agent Builder），独立服务（chart v0.15+）
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

有关每个附加组件的详细信息，请参阅 LangSmith 部署。

Fleet

Fleet 是之前称为 Agent Builder 的功能的当前形式，作为独立服务部署（chart v0.15+）。

您可以通过 enable_fleet 启用 Fleet。在 AWS 上，它需要 enable_deployments = true，因为 Fleet 聊天 UI 通过随 LangSmith Deployment 一起提供的宿主后端解析 OAuth 提供商和令牌连接。它还需要外部 Postgres 和 Redis（postgres_source = "external" 和 redis_source = "external"）。 Terraform 在 RDS 上创建一个专用的 langsmith_fleet 数据库，并将 langsmith-fleet-postgres 和 langsmith-fleet-redis 密钥连接到现有的 RDS 和 ElastiCache 实例。Fleet 复用 langsmith_agent_builder_encryption_key，因此从 enable_agent_builder 迁移会保留相同的密钥和数据。

Fleet 需要 LangSmith Helm chart >=0.15.0 以及您许可证中的 Agent Builder 或 Fleet 授权。

Fleet 安装 standalone-fleet-api-server、standalone-fleet-tool-server、standalone-fleet-trigger-server 和 standalone-fleet-queue 服务。

不要同时启用 enable_fleet 和 enable_agent_builder。Fleet 值文件设置 config.agentBuilder.enabled: false，因此这两个附加组件是互斥的。

可选：带堡垒机的私有 EKS 集群

对于必须运行完全私有 EKS API 端点的部署，模块提供了堡垒机主机模式：

首先，从您的工作站运行，设置 create_bastion = true 和 enable_public_eks_cluster = true，以便创建堡垒机。
初始部署后，设置 enable_public_eks_cluster = false 并重新应用。EKS API 端点变为仅私有。
所有后续的 Terraform 工作都在堡垒机上进行。通过 SSM 进入堡垒机，克隆存储库，复制您的 terraform.tfvars 和 SSM 密钥，然后从那里运行部署。

enable_public_eks_cluster = false
create_bastion            = true

# 可选的 SSH 访问（SSM 是默认方式，不需要密钥）：
# bastion_key_name          = "my-keypair"
# bastion_enable_ssh        = true
# bastion_ssh_allowed_cidrs = ["203.0.113.0/24"]

通过 SSM Session Manager 连接：

terraform output bastion_ssm_command
aws ssm start-session --target <instance-id> --region us-west-2

堡垒机位于公共子网中以实现 SSM 代理连接，但如果您的 VPC 具有 SSM、SSMMessages 和 EC2Messages VPC 端点，则不需要公共 IP。堡垒机预装了 kubectl、helm、terraform、git 和 jq，并且 kubeconfig 已配置为连接到 EKS 集群。在您的工作站上安装 Session Manager 插件。

可选：Envoy Gateway 入口

默认入口是 AWS Load Balancer Controller (ALB)。在 terraform.tfvars 中设置 enable_envoy_gateway = true 以改为安装 Envoy Gateway。Envoy Gateway 是多命名空间数据平面部署所必需的，其中 langgraph-dataplane chart 在其自己的命名空间中运行。

# infra/terraform.tfvars
enable_envoy_gateway = true

source infra/scripts/setup-env.sh
make apply

make init-values
cp helm/values/examples/langsmith-values-ingress-envoy-gateway.yaml helm/values/
make deploy

当 tls_certificate_source = "acm" 时，部署脚本会自动为 Envoy Gateway NLB 服务添加 ACM 证书 ARN 的注释。TLS 在 NLB 处终止；Envoy 内部看到的是纯 HTTP。在单独的命名空间中运行数据平面 chart 时，请为每个数据平面命名空间应用一次 RBAC 清单：

kubectl apply -f helm/values/examples/dataplane-rbac.yaml

这授予 langsmith-host-backend ServiceAccount 对数据平面命名空间中的 Pod、Pod 日志、Deployments 和 ReplicaSets 的读取权限。没有它，代理运行日志将不会在 LangSmith UI 中流式传输。

后续步骤

参考 AWS 变量和快速参考。
查看 AWS 架构，了解平台层、IRSA 和模块依赖关系。
当出现问题时，请查看 AWS 故障排除指南。
通过 LangSmith 部署在 UI 中启用代理部署。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started by cloud provider

Deploy with Terraform

Setup guides

Configuration

Connect external services

Platform auth & access control

Self-hosted observability

Hybrid

Scripts

Reference

在 AWS 上使用 Terraform 部署 LangSmith

前提条件

必需工具

所需的 AWS IAM 权限

身份验证

许可证密钥和域名

集群大小参考

快速入门

配置基础设施

克隆和配置

将密钥加载到 SSM Parameter Store

应用

配置 kubectl

部署 LangSmith

脚本驱动的 Helm 部署（推荐）

验证

Terraform 管理的 Helm 部署

启用附加组件

Fleet

可选：带堡垒机的私有 EKS 集群

可选：Envoy Gateway 入口

后续步骤

​前提条件

​必需工具

​所需的 AWS IAM 权限

​身份验证

​许可证密钥和域名

​集群大小参考

​快速入门

​配置基础设施

​克隆和配置

​将密钥加载到 SSM Parameter Store

​应用

​配置 kubectl

​部署 LangSmith

​脚本驱动的 Helm 部署（推荐）

​验证

​Terraform 管理的 Helm 部署

​启用附加组件

​Fleet

​可选：带堡垒机的私有 EKS 集群

​可选：Envoy Gateway 入口

​后续步骤

前提条件

必需工具

所需的 AWS IAM 权限

身份验证

许可证密钥和域名

集群大小参考

快速入门

配置基础设施

克隆和配置

将密钥加载到 SSM Parameter Store

应用

配置 kubectl

部署 LangSmith

脚本驱动的 Helm 部署（推荐）

验证

Terraform 管理的 Helm 部署

启用附加组件

Fleet

可选：带堡垒机的私有 EKS 集群

可选：Envoy Gateway 入口

后续步骤