用 Terraform 在 AWS 上部署 LangSmith

用 LangChain Terraform 模块在 AWS EKS 上预配自托管 LangSmith 的端到端演练。

用公开的 Terraform 模块把 LangSmith 部署到 AWS。以代码方式管理部署，让你能跨账户为 LangSmith 环境做版本控制、审查和复现，而非在 AWS 控制台里点点点。

安装分两个阶段运行：

基础设施：Terraform 预配 VPC、EKS、RDS、ElastiCache、S3 和 IAM。
应用：Helm 针对集群安装 LangSmith chart。

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

%%{init: {'flowchart': {'nodeSpacing': 25, 'rankSpacing': 30}}}%%
graph TB
    subgraph stage1["Set up infrastructure"]
        direction LR
        Start["setup-env.sh<br/>secrets to SSM"]
        TF["terraform apply"]
        Infra["VPC · EKS · RDS<br/>ElastiCache · S3 · ALB<br/>IAM"]
        Bootstrap["k8s-bootstrap<br/>ESO · KEDA<br/>cert-manager"]
        Start --> TF --> Infra -->|EKS ready| Bootstrap
    end
    subgraph stage2["Deploy the application"]
        direction LR
        Deploy["deploy.sh<br/>ARNs + hostname<br/>ESO syncs secrets"]
        Helm["helm install<br/>langsmith chart"]
        First{"First<br/>deploy?"}
        Running["LangSmith running<br/>all pods healthy"]
        Deploy --> Helm --> First
        First -->|no| Running
        First -->|yes, re-run| Helm
    end
    stage1 --> stage2

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef neutral fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33

    class Start trigger
    class TF,Bootstrap,Deploy,Helm process
    class Infra neutral
    class First decision
    class Running output

    style stage1 fill:none,stroke:#40668D,stroke-width:1px
    style stage2 fill:none,stroke:#40668D,stroke-width:1px

前置条件

必需工具

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

在 macOS 上安装：

bash

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

验证每个工具都在 PATH 上：

bash

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 角色和策略

TIP

在 modules/aws/ 中身份验证后运行 make preflight。preflight 脚本确认活动凭据能执行每个所需操作，并报告第一个缺失的权限，这比在 terraform apply 中途发现缺口更快。

身份验证

用 CLI 配置 AWS 凭据：

bash

aws configure

或导出环境变量：

bash

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

确认凭据可用且目标区域在账户中已启用：

bash

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 节点组（min 3，max 10）、RDS 用 db.t3.large、ElastiCache 用 cache.m6g.xlarge。
sizing_profile 选择 Helm 规格 overlay（pod 资源请求和限制）。init-values.sh 和 deploy.sh 读取它；Terraform 不读。

在部署前为你的目标层级给基础设施定规格。有关逐层级建议，参阅扩缩容指导。

NOTE

对于生产工作负载，也要计划预配外部 LangChain Managed ClickHouse 或一个自管理的外部 ClickHouse 集群。集群内 ClickHouse 仅对开发/POC 受支持。

快速开始

TIP

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

要从零到运行中的 LangSmith 实例走最快的路径，按顺序运行这些命令：

bash

# 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

要把基础设施和应用串在一条命令里：

bash

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 端点	追踪载荷 blob 存储
ALB + 监听器	带 TLS 的公共 ingress
SSM Parameter Store 条目	应用机密，由 External Secrets Operator 同步进集群
IRSA 角色 + IAM 策略	按服务的 AWS 访问
KEDA、cert-manager、ESO	与基础设施一起安装的 bootstrap 工作负载

克隆并配置

bash

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

所有后续命令都从 modules/aws/ 运行。运行 make help 查看完整目标列表。

用交互式向导生成 terraform.tfvars：

bash

make quickstart

向导会依次提示命名前缀、区域、EKS 规格、TLS 来源、外部对集群内服务，以及可选附加组件标志。它写入 infra/terraform.tfvars。重跑向导会预选现有值；在每个提示处按 Enter 以保留当前配置。

更想手动编辑？复制示例并填好必填字段：

bash

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

最少必需的变量：

hcl

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 变量参考。

TIP

在 apply 之前配置一个远程状态后端。编辑 infra/backend.tf 以指向你控制的一个 S3 存储桶和 DynamoDB 锁表。Terraform 仓库默认为首次评估附带一个本地后端。

把机密加载到 SSM Parameter Store

bash

source infra/scripts/setup-env.sh

该脚本读取 terraform.tfvars，派生出 SSM 路径 /langsmith/{name_prefix}-{environment}/，然后对每个机密要么复用一个导出的值、要么读取现有的 SSM 参数、要么自动生成一个（用于盐和令牌）、要么提示你。许可密钥和 admin 密码是你交互式提供的两个值。该脚本必须被 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`	提示	来自我们的销售团队
`langsmith-admin-password`	提示	必须含有一个符号
`deployments-encryption-key`	自动生成的 Fernet 密钥	LangSmith Deployment 附加组件
`agent-builder-encryption-key`	自动生成的 Fernet 密钥	Agent Builder 附加组件（被 Fleet 复用）
`insights-encryption-key`	自动生成的 Fernet 密钥	Insights 附加组件
`polly-encryption-key`	自动生成的 Fernet 密钥	Polly 附加组件

验证机密存在且 TF_VAR_* 环境变量已导出：

bash

make secrets

Apply

NOTE

在一个干净账户上预配 AWS 云基础需要 20 到 25 分钟。不要打断 apply。

bash

make init
make plan
make apply

make plan 显示拟议的差异。在 apply 之前审阅输出。make apply 按依赖顺序预配：VPC 和安全组，然后 EKS（约 12 分钟）和 RDS（约 8 分钟，并行），然后节点组、ElastiCache、S3 和 ALB。

配置 kubectl

bash

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 部署（推荐）

最适合多数部署。交互式提示引导你完成规格和产品选择。

bash

cd modules/aws

make init-values
make deploy

init-values.sh 会提示 admin 邮箱，然后从 terraform.tfvars 读取 sizing_profile 和 enable_* 标志，并把 helm/values/examples/ 中匹配的 values 文件复制到 helm/values/。重跑时它会保留你的选择并刷新 Terraform 输出。

make deploy 运行 helm/scripts/deploy.sh，它会：

刷新 kubeconfig。
运行 preflight 检查（AWS 凭据、集群可达性、langchain Helm 仓库）。
应用 External Secrets Operator 的 ClusterSecretStore 和 ExternalSecret，使集群直接从 SSM 读取机密。
用分层的 values 文件安装 LangSmith Helm chart。

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

验证

bash

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

当所有 pod 都 Running 且 ingress 显示 ALB DNS 名时，部署就绪。用你在 langsmith_domain 中配置的域名（或 ALB DNS 名）访问 UI。

如果你完成了脚本驱动的部署，就到此为止。下一节是一条替代部署路径，而非额外的步骤。

Terraform 管理的 Helm 部署

最适合想把完整部署放进 Terraform 状态的团队，或“自带基础设施”的场景。app/ 模块直接管理 External Secrets Operator 接线、helm_release 和功能开关。

bash

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 文件控制应用配置：

hcl

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"

WARNING

在 make plan-app 之前必须先 make init-values。app 模块从 helm/values/ 读取 values 文件，而 init-values 会根据 infra/terraform.tfvars 中的规格和附加组件选择，从 helm/values/examples/ 填充它们。

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

启用附加组件

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

hcl

enable_deployments     = true   # LangGraph Platform (required for Fleet, Agent Builder, and Polly)
enable_fleet           = true   # Fleet (formerly Agent Builder), standalone service (chart v0.15+)
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 and monitoring
enable_usage_telemetry = false  # Extended usage telemetry

bash

make init-values
make deploy

有关每个附加组件的详情，见 LangSmith Deployment。

Fleet

NOTE

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

你可以用 enable_fleet 启用 Fleet。在 AWS 上，它需要 enable_deployments = true，因为 Fleet 聊天 UI 通过随 LangSmith Deployment 附带的 host-backend 解析 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 迁移会保持同样的密钥和数据。

NOTE

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 服务。

WARNING

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

可选：带 bastion 的私有 EKS 集群

对于必须运行完全私有 EKS API 端点的部署，这些模块附带一个 bastion 主机模式：

首先，从你的工作站以 create_bastion = true 和 enable_public_eks_cluster = true 运行，以便能创建 bastion。
在初始部署之后，设 enable_public_eks_cluster = false 并重新 apply。EKS API 端点变为仅私有。
所有后续 Terraform 工作都在 bastion 上进行。SSM 进入它，克隆仓库，复制你的 terraform.tfvars 和 SSM 机密，然后从那里运行部署。

hcl

enable_public_eks_cluster = false
create_bastion            = true

# Optional SSH access (SSM is the default and requires no key):
# bastion_key_name          = "my-keypair"
# bastion_enable_ssh        = true
# bastion_ssh_allowed_cidrs = ["203.0.113.0/24"]

通过 SSM Session Manager 连接：

bash

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

NOTE

bastion 位于一个公共子网中以供 SSM agent 连接，但如果你的 VPC 有 SSM、SSMMessages 和 EC2Messages VPC 端点，它就不需要公共 IP。bastion 预装了 kubectl、helm、terraform、git 和 jq，kubeconfig 已为 EKS 集群配好。在你工作站上为 AWS CLI 安装 Session Manager 插件。

可选：Envoy Gateway ingress

默认 ingress 是 AWS Load Balancer Controller（ALB）。在 terraform.tfvars 中设 enable_envoy_gateway = true 以改装 Envoy Gateway。当 langgraph-dataplane chart 在它自己的命名空间中运行时，多命名空间 dataplane 部署要求 Envoy Gateway。

hcl

# infra/terraform.tfvars
enable_envoy_gateway = true

bash

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。

在单独的命名空间中运行 dataplane chart 时，为每个 dataplane 命名空间各应用一次 RBAC 清单：

bash

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

这授予 langsmith-host-backend ServiceAccount 对 dataplane 命名空间中 pod、pod 日志、deployment 和 ReplicaSet 的读访问。没有它，agent 运行日志不会在 LangSmith UI 中流式显示。

后续步骤

参考 AWS 变量和快速参考。
审阅 AWS 架构了解平台层、IRSA 和模块依赖。
出问题时，查 AWS 故障排除指南。
用 LangSmith Deployment 在 UI 中启用 agent 部署。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织