在 GCP 上使用 Terraform 部署 LangSmith

使用公共 Terraform 模块将 LangSmith 部署到 GCP。将部署过程作为代码管理，让您能够跨项目对 LangSmith 环境进行版本控制、审查和复制，而无需在 Google Cloud 控制台中点击操作。安装过程分为两个阶段：

基础设施：Terraform 配置 VPC、GKE、Cloud SQL、Memorystore、GCS 和 Workload Identity。
应用程序：使用部署脚本或 Terraform app 层安装的 LangSmith 图表。

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

前提条件

所需工具

工具	版本	用途
Google Cloud SDK (`gcloud`)	450	进行身份验证、查询 GCP 资源、管理 GKE 凭证
Terraform	1.5	运行基础设施模块
`kubectl`	1.28	检查 GKE 集群
Helm	3.12	安装和管理 LangSmith 图表

在 macOS 上安装：

brew install --cask google-cloud-sdk
brew install kubectl helm
brew tap hashicorp/tap && brew install hashicorp/tap/terraform

gcloud version
terraform version
kubectl version --client
helm version

所需的 GCP API

Terraform 在首次执行时会自动启用这些 API，但必须首先启用 cloudresourcemanager.googleapis.com，以便 Terraform 能够启用其余 API。为了加速首次运行，请手动启用所有 API：

gcloud services enable \
  container.googleapis.com \
  compute.googleapis.com \
  sqladmin.googleapis.com \
  redis.googleapis.com \
  storage.googleapis.com \
  iam.googleapis.com \
  secretmanager.googleapis.com \
  certificatemanager.googleapis.com \
  servicenetworking.googleapis.com \
  cloudresourcemanager.googleapis.com \
  logging.googleapis.com \
  monitoring.googleapis.com \
  --project <your-project-id>

所需的 IAM 角色

运行 Terraform 的主体需要在目标项目上拥有以下角色。在初始部署稳定后，请裁减为最小权限。

角色	用途
`roles/container.admin`	创建和管理 GKE 集群
`roles/compute.networkAdmin`	创建 VPC、子网、防火墙规则
`roles/iam.serviceAccountAdmin`	为 Workload Identity 创建服务账户
`roles/cloudsql.admin`	创建和管理 Cloud SQL 实例
`roles/redis.admin`	创建和管理 Memorystore Redis
`roles/storage.admin`	创建 GCS 存储桶和生命周期策略
`roles/resourcemanager.projectIamAdmin`	在配置过程中授予 IAM 绑定
`roles/servicenetworking.networksAdmin`	创建私有服务连接（Cloud SQL 和 Redis 所需）

身份验证

gcloud auth login
gcloud config set project <your-project-id>
gcloud auth application-default login

您还需要一个 LangSmith 许可证密钥（联系销售）以及一个解析到 GCP 的域名或子域名。

快速入门

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

要以最快速度从零开始运行 LangSmith 实例，请按顺序运行以下命令：

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

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

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

# 4. Validate environment
make preflight

# 5. Provision infrastructure (~25 to 35 min)
make init
make plan
make apply

# 6. Configure kubectl
make kubeconfig
kubectl get nodes

# 7. Deploy LangSmith via Helm (~8 to 12 min)
make init-values
make deploy

# 8. Get the Gateway IP for DNS
kubectl get gateway -n langsmith \
  -o jsonpath='{.items[0].status.addresses[0].value}'

以下部分将详细介绍每个阶段。

配置基础设施

Terraform 配置以下 GCP 资源：

资源	用途
VPC + 子网 + Cloud NAT	集群和托管服务的私有网络
私有服务连接	为 Cloud SQL 和 Memorystore 私有 IP 建立的 VPC 对等连接
GKE 集群（标准版或 Autopilot）	Kubernetes 计算资源，已启用 Workload Identity
Cloud SQL PostgreSQL	LangSmith 操作数据，高可用备用，私有 IP
Memorystore Redis	队列和缓存，STANDARD_HA 层级，私有 IP
GCS 存储桶	跟踪数据有效负载的二进制大对象存储，生命周期规则
Workload Identity 服务账户	每个 Pod 无需静态密钥即可访问 GCP
cert-manager, KEDA, Envoy Gateway	与基础设施一起安装的引导工作负载

克隆并配置

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

所有后续命令都从 modules/gcp/ 目录运行。运行 make help 可查看完整的目标列表。使用交互式向导生成 terraform.tfvars：

make quickstart

向导会提示您输入项目 ID、命名前缀、区域、GKE 规模、TLS 来源、外部服务还是集群内服务，以及可选的附加组件标志。它会写入 infra/terraform.tfvars。重新运行时会预先选择现有值；在每个提示符下按 Enter 以保留当前配置。也可以选择手动编辑：

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

最低必需变量：

project_id            = "<你的-gcp-项目-id>"
name_prefix           = "ls"
environment           = "prod"
langsmith_license_key = "<你的许可证密钥>"
langsmith_domain      = "langsmith.example.com"

region = "us-west2"
zone   = "us-west2-a"

postgres_source   = "external"
postgres_password = "<强密码>"   # 或者: export TF_VAR_postgres_password=...

redis_source = "external"

clickhouse_source = "in-cluster"

tls_certificate_source = "letsencrypt"
letsencrypt_email      = "ops@example.com"

enable_langsmith_deployment = true

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

在执行 apply 前请配置远程状态后端。将 infra/backend.tf.example 复制到 infra/backend.tf 并将其指向您控制的 GCS 存储桶。本地状态很脆弱，在目录重组期间可能会丢失。

将密钥加载到 Secret Manager

source infra/scripts/setup-env.sh

该脚本读取 terraform.tfvars，推导密钥前缀，并对每个密钥进行如下处理：重用已导出的值、读取现有的 Secret Manager 密钥、自动生成一个（用于盐和 Fernet 密钥），或提示您输入。许可证密钥和管理员密码是您需要交互式提供的两个值。该脚本必须通过 source 执行，因为 make 无法将环境变量导出回父 shell。验证密钥是否存在：

make secrets

预检

make preflight

make preflight 会验证当前活动的 gcloud 凭证是否具有执行每个所需操作的权限、所需的 GCP API 是否已启用，以及目标区域是否包含模块请求的 SKU。在此处发现缺失项比在 terraform apply 过程中发现要快。

执行

在干净的项目上配置 GCP 云基础需要 25 到 35 分钟。请勿中断 apply 过程。

make init
make plan
make apply

make plan 显示建议的差异。在应用前请检查输出。make apply 按依赖顺序进行配置：VPC 和网络，然后是 GKE（约 10 到 15 分钟），私有服务连接，Cloud SQL（带高可用约 10 分钟），Memorystore，GCS，最后是引导工作负载。等效的直接 Terraform 流程：

cd modules/gcp/infra

terraform init
terraform plan -var-file=terraform.tfvars
terraform apply -var-file=terraform.tfvars

配置 kubectl

make kubeconfig
kubectl get nodes

所有节点都应报告 Ready 状态。

验证引导组件

kubectl get pods -n cert-manager
kubectl get pods -n keda
kubectl get secrets -n langsmith

cert-manager、KEDA 和 LangSmith 命名空间的密钥都应已就位。

部署 LangSmith

使用以下三种支持的部署方式之一：

方式	命令	适用场景
脚本驱动的 Helm 部署（推荐）	`make init-values && make deploy`	交互式输出，刷新 kubeconfig，预检。最适合首次部署和日常重新部署。
Terraform 管理的 Helm 发布	`make init-app && make apply-app`	Helm 发布在 Terraform 状态中与基础设施一起管理。最适合 GitOps 和 CI/CD 流水线。
手动 Helm 安装	`helm upgrade --install langsmith langchain/langsmith ...`	直接使用 `helm`，不通过包装脚本。最适合已有 Helm 工具的团队。

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

两条命令即可安装带有从 Terraform 输出连接而来的合理默认值的 LangSmith 图表：

cd modules/gcp

make init-values
make deploy

init-values.sh 会提示输入管理员邮箱，然后读取 terraform.tfvars 中的 sizing_profile 和 enable_* 标志，并将匹配的值文件从 helm/values/examples/ 复制到 helm/values/。它还会生成 values-overrides.yaml，其中包含您的主机名、Workload Identity 注解和 GCS 存储桶名称。 make deploy 运行 helm/scripts/deploy.sh，该脚本刷新 kubeconfig、运行预检、应用分层的值文件，并执行 helm upgrade --install。图表安装和 Pod 就绪预计需要 8 到 12 分钟。如果您已完成脚本驱动的部署，请跳转到验证并配置 DNS。以下两种方式是脚本驱动部署的替代方案。

Terraform 管理的 Helm 发布

将整个部署置于 Terraform 管理之下。app 层封装了与部署脚本相同的图表和分层值文件，并作为 helm_release 资源进行管理。

cd modules/gcp

make init-values  # generate the layered values files
make init-app     # pull infra outputs into app/infra.auto.tfvars.json
make apply-app    # terraform apply the Helm release

在 app/terraform.tfvars 中设置应用层输入（admin_email 是必需的；hostname、chart_version、sizing 和 enable_* 标志是可选的）。app 层使用自己的变量名：sizing（而不是 sizing_profile）和 enable_agent_deploys（而不是 enable_deployments）。make init-app 会将基础设施派生的输入（集群、存储桶、Workload Identity 注解）填充到 app/infra.auto.tfvars.json 中。该发布使用 wait = false 进行应用，因为操作员生成的代理在冷启动的集群上可能需要 10 多分钟；terraform apply 成功意味着发布已被接受，但不代表每个 Pod 都已就绪。如果您已完成 Terraform 管理的 Helm 发布，请跳转到验证并配置 DNS。以下是另一种方式。

手动 Helm 安装

最适合直接运行 helm 而不使用脚本的团队。首先生成所需的密钥：

export API_KEY_SALT=$(openssl rand -base64 32)
export JWT_SECRET=$(openssl rand -base64 32)
export AGENT_BUILDER_ENCRYPTION_KEY=$(python3 -c \
  "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
export INSIGHTS_ENCRYPTION_KEY=$(python3 -c \
  "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
export ADMIN_EMAIL="admin@example.com"
export ADMIN_PASSWORD="<strong-password>"

附带的 helm/values/values.yaml 设置了 config.blobStorage.engine: GCS（原生 GCS 模式），因此 blob 存储通过 Workload Identity 进行身份验证，无需 HMAC 密钥。每个组件的 Workload Identity 注解位于 values-overrides.yaml 中；使用 make init-values 生成它，或者手动为每个组件添加 serviceAccount.annotations."iam.gke.io/gcp-service-account"。

helm repo add langchain https://langchain-ai.github.io/helm
helm repo update

helm upgrade --install langsmith langchain/langsmith \
  --namespace langsmith \
  --create-namespace \
  --version ~0.15.1 \
  -f ../helm/values/values.yaml \
  -f ../helm/values/values-overrides.yaml \
  --set config.langsmithLicenseKey="<your-license-key>" \
  --set config.apiKeySalt="$API_KEY_SALT" \
  --set config.basicAuth.jwtSecret="$JWT_SECRET" \
  --set config.hostname="<your-langsmith-domain>" \
  --set config.basicAuth.initialOrgAdminEmail="$ADMIN_EMAIL" \
  --set config.basicAuth.initialOrgAdminPassword="$ADMIN_PASSWORD" \
  --set config.agentBuilder.encryptionKey="$AGENT_BUILDER_ENCRYPTION_KEY" \
  --set config.insights.encryptionKey="$INSIGHTS_ENCRYPTION_KEY" \
  --set config.blobStorage.bucketName="$(terraform output -raw storage_bucket_name)" \
  --set gateway.enabled=true \
  --set ingress.enabled=false \
  --wait --timeout 15m

如果要使用兼容 S3 的 blob 存储代替 Workload Identity，请添加 --set config.blobStorage.engine=S3，并通过 --set config.blobStorage.accessKey=<key> 和 --set config.blobStorage.accessKeySecret=<secret> 传递 HMAC 密钥。在 Cloud Storage → 设置 → 互操作性下创建 HMAC 密钥。

验证并配置 DNS

kubectl get pods -n langsmith

EXTERNAL_IP=$(kubectl get svc -n envoy-gateway-system \
  -l gateway.envoyproxy.io/owning-gateway-name=langsmith-gateway \
  -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}')

echo "Create A record: $EXTERNAL_IP -> <your-langsmith-domain>"

kubectl get certificate -n langsmith

在 DNS A 记录解析到 Gateway IP 之前，cert-manager 无法颁发 Let’s Encrypt 证书。在您的 DNS 提供商处创建该记录，等待传播完成，然后重新检查证书状态。

规模配置

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

sizing_profile = "production"   # default | minimum | dev | production | production-large

配置	适用场景
`default`	图表默认值，不应用覆盖
`minimum`	绝对最低配置，适用于 `e2-standard-4`。用于成本停放或 CI 冒烟测试
`dev`	单副本，最小资源
`production`	带 HPA 的多副本。推荐用于实际工作负载
`production-large`	高内存，高 CPU。适用于 50+ 用户或 1000+ traces/sec

预期的 Pod

langsmith-ace-backend-xxx          1/1  Running    0
langsmith-backend-xxx              1/1  Running    0
langsmith-backend-auth-bootstrap   0/1  Completed  0
langsmith-backend-migrations       0/1  Completed  0
langsmith-clickhouse-0             1/1  Running    0
langsmith-frontend-xxx             1/1  Running    0
langsmith-ingest-queue-xxx         1/1  Running    0
langsmith-platform-backend-xxx     1/1  Running    0
langsmith-playground-xxx           1/1  Running    0
langsmith-queue-xxx                1/1  Running    0

启用附加组件

每个附加组件都由 infra/terraform.tfvars 中的一个标志控制。设置标志，重新应用 Terraform，然后重新运行 make init-values && make deploy。

LangSmith Deployment

添加 host-backend、listener 和 operator。在启用 Agent Builder 或 Insights 之前需要此组件。当 enable_langsmith_deployment = true 时，KEDA 会自动安装。

# infra/terraform.tfvars
enable_deployments = true

cd modules/gcp

make apply        # push the enable_deployments flag
make init-values  # pick up the change
make deploy       # roll out host-backend + listener + operator

验证：

kubectl get pods -n langsmith | grep -E "host-backend|listener|operator"
kubectl get lgp -n langsmith
kubectl get crd | grep langchain
kubectl get pods -n keda

config.deployment.url 必须包含 https://。没有协议前缀，操作员生成的代理会无限期地停留在 DEPLOYING 状态。

Fleet

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

您可以使用 enable_fleet 启用 Fleet。与已弃用的 enable_agent_builder 路径不同，它不需要 LangSmith Deployment。Terraform 在 Cloud SQL 上配置一个专用的 fleet 数据库，并将 langsmith-fleet-postgres 和 langsmith-fleet-redis 密钥连接到现有的 Cloud SQL 和 Memorystore 实例。Fleet 重用 langsmith_agent_builder_encryption_key，因此从 enable_agent_builder 迁移会保留相同的密钥和数据。

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

# infra/terraform.tfvars
enable_fleet = true

cd modules/gcp

make apply        # provision the fleet Cloud SQL database + secrets
make init-values  # copy langsmith-values-fleet.yaml
make deploy       # roll out the standalone-fleet-* services

验证：

kubectl get pods -n langsmith | grep standalone-fleet

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

Agent Builder (已弃用)

在 GCP 上，enable_agent_builder 已被 Fleet (enable_fleet, 图表 v0.15+) 取代。新部署请使用 Fleet。本节为现有安装记录旧路径。

前提条件：LangSmith Deployment 健康。添加 agent-builder-tool-server、agent-builder-trigger-server 和一个注册 Polly 代理 URL 的 agentBootstrap Job。

# infra/terraform.tfvars
enable_agent_builder = true

make init-values
make deploy

验证：

kubectl get pods -n langsmith | grep -E "tool-server|trigger-server|bootstrap"

在 agentBootstrap 完成后重启前端，使其加载 langsmith-polly-config ConfigMap：

kubectl rollout restart deployment langsmith-frontend -n langsmith

跳过前端重启会导致 Polly 显示“无法连接到 LangGraph 服务器”。

Insights 和 Polly

前提条件：Agent Builder 健康。Insights 启用基于 ClickHouse 的跟踪分析。Polly 是 AI 评估和监控代理。两者一起启用。

# infra/terraform.tfvars
enable_insights = true
enable_polly    = true

make init-values
make deploy

验证：

kubectl get pods -n langsmith | grep -E "clio|polly"
kubectl get pods -n langsmith -w

insights_encryption_key 和 polly_encryption_key 在首次启用后绝不能更改。轮换任何一个都会永久破坏现有的加密数据。

按附加组件划分的预期 Pod

LangSmith Deployment 添加： langsmith-host-backend, langsmith-listener, langsmith-operator。 Fleet 添加： standalone-fleet-api-server, standalone-fleet-tool-server, standalone-fleet-trigger-server, standalone-fleet-queue。 Agent Builder 添加： langsmith-agent-builder-tool-server, langsmith-agent-builder-trigger-server, langsmith-agent-builder-bootstrap (已完成), agent-builder-<hash> (操作员生成)。 Insights 和 Polly 添加： clio-<hash> (Insights 分析), smith-polly-<hash> (Polly 代理), lg-<hash>-0 (LangGraph StatefulSet)。

关键注意事项

config.deployment.url 必须包含 https://。没有它，操作员生成的代理会停留在 DEPLOYING 状态。
config.deployment.enabled: true 对 LangSmith Deployment 是必需的。只设置 URL 而不设置 enabled: true 会导致图表静默跳过 listener 和 operator。
加密密钥在首次启用后绝不能更改。轮换 insights_encryption_key 或 polly_encryption_key 会永久破坏现有的加密数据。
首次启用 Polly 后重启前端。agentBootstrap 在注册后创建 langsmith-polly-config ConfigMap。在引导完成之前启动的前端 Pod 不会自动加载它。
Envoy Gateway IP 在销毁时会更改。Gateway 删除时 GCP 会释放外部 IP。重新应用后，会分配新的 IP，因此请更新您的 DNS A 记录。
langsmith-ksa 注解不是永久的。操作员在运行时创建 langsmith-ksa；它不会在命名空间删除后保留。deploy.sh 会幂等地重新注解它。如果集群重建后操作员 Pod 失去 GCS 访问权限，请重新运行 make deploy。

后续步骤

参考 GCP 变量和快速参考。
查阅 GCP 架构以了解模块结构、流量和 Workload Identity。
当出现问题时，请查阅 GCP 故障排除指南。
在 UI 中启用代理部署，请参阅 LangSmith Deployment。

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

在 GCP 上使用 Terraform 部署 LangSmith

前提条件

所需工具

所需的 GCP API

所需的 IAM 角色

身份验证

快速入门

配置基础设施

克隆并配置

将密钥加载到 Secret Manager

预检

执行

配置 kubectl

验证引导组件

部署 LangSmith

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

Terraform 管理的 Helm 发布

手动 Helm 安装

验证并配置 DNS

规模配置

预期的 Pod

启用附加组件

LangSmith Deployment

Fleet

Agent Builder (已弃用)

Insights 和 Polly

按附加组件划分的预期 Pod

关键注意事项

后续步骤

​前提条件

​所需工具

​所需的 GCP API

​所需的 IAM 角色

​身份验证

​快速入门

​配置基础设施

​克隆并配置

​将密钥加载到 Secret Manager

​预检

​执行

​配置 kubectl

​验证引导组件

​部署 LangSmith

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

​Terraform 管理的 Helm 发布

​手动 Helm 安装

​验证并配置 DNS

​规模配置

​预期的 Pod

​启用附加组件

​LangSmith Deployment

​Fleet

​Agent Builder (已弃用)

​Insights 和 Polly

​按附加组件划分的预期 Pod

​关键注意事项

​后续步骤

前提条件

所需工具

所需的 GCP API

所需的 IAM 角色

身份验证

快速入门

配置基础设施

克隆并配置

将密钥加载到 Secret Manager

预检

执行

配置 kubectl

验证引导组件

部署 LangSmith

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

Terraform 管理的 Helm 发布

手动 Helm 安装

验证并配置 DNS

规模配置

预期的 Pod

启用附加组件

LangSmith Deployment

Fleet

Agent Builder (已弃用)

Insights 和 Polly

按附加组件划分的预期 Pod

关键注意事项

后续步骤