GCP Terraform 快速参考

面向 GKE 上自托管 LangSmith 的 Make targets、Terraform、kubectl、gcloud 和 Helm 命令。

面向使用 GCP Terraform 模块预配的 GCP LangSmith 部署进行日常操作的命令速查表。所有 make target 都在 modules/gcp/ 下运行。运行 make help 查看内联摘要。

部署概览

阶段	部署内容	命令
基础设施	VPC + GKE + Cloud SQL + Memorystore + GCS + IAM + cert-manager + KEDA + Envoy Gateway	`make apply`
集群凭据	连接到新 GKE 集群的 Kubeconfig	`make kubeconfig`
LangSmith 基础	Frontend、backend、ingest、queue、ClickHouse	`make init-values && make deploy`
Fleet 附加组件（standalone）	standalone-fleet-* API server、tool server、trigger server、queue	`make apply && make init-values && make deploy`
LangSmith Deployment 附加组件	host-backend、listener、operator	`make apply && make init-values && make deploy`
Agent Builder 附加组件（已弃用）	tool-server、trigger-server + agent-builder LGP	`make init-values && make deploy`
Insights + Polly 附加组件	Clio analytics、Polly eval agent	`make init-values && make deploy`

每个阶段都基于前一个阶段。在启用下一阶段前，先确认 pod 健康。

首次设置

bash

cd terraform/modules/gcp

# Interactive wizard — generates terraform.tfvars
make quickstart

# Set up secrets in Secret Manager (auto-generates passwords + Fernet keys)
# Must be sourced so it can export TF_VAR_* into your shell
source infra/scripts/setup-env.sh

# Verify secrets are stored correctly
make secrets

# Deploy infrastructure
make init
make plan
make apply

# Generate Helm values from Terraform outputs
make init-values

# Deploy LangSmith
make deploy

make deploy-all 会用一条命令串联 apply、init-values 和 deploy。

如果希望 Helm release 由 Terraform 而非部署脚本管理，请使用 app 层：

bash

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 (make destroy-app to remove)

app 层使用自己的变量名：sizing（而不是 sizing_profile）和 enable_agent_deploys（而不是 enable_deployments）。

日常运维

bash

# Check deployment state and next-step guidance
make status              # full check
make status-quick        # skip Secret Manager and K8s queries

# Re-deploy after changing Helm values or upgrading chart version
make deploy

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

# Manage Secret Manager secrets interactively
make secrets

# Update kubeconfig for the GKE cluster
make kubeconfig

附加组件

在 terraform.tfvars 中设置标志，然后运行 make init-values && make deploy。init-values.sh 会自动把匹配的示例文件复制到 helm/values/。

hcl

# terraform.tfvars
enable_deployments   = true
enable_fleet         = true   # Fleet (formerly Agent Builder), standalone (chart v0.15+); no enable_deployments required
enable_agent_builder = false  # deprecated, superseded by enable_fleet; mutually exclusive with it
enable_insights      = true
enable_polly         = true   # requires enable_deployments = true + Polly license
enable_usage_telemetry = true # extended usage telemetry

如果要在初次安装后添加附加组件而不重新运行 init-values.sh，请手动复制：

bash

cp helm/values/examples/langsmith-values-agent-deploys.yaml helm/values/
cp helm/values/examples/langsmith-values-fleet.yaml         helm/values/
cp helm/values/examples/langsmith-values-insights.yaml      helm/values/
cp helm/values/examples/langsmith-values-polly.yaml         helm/values/

make deploy

规格配置

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

hcl

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

Profile	使用场景
`default`	Chart 默认值——快速测试，不应用 overlay
`minimum`	绝对下限；适配 `e2-standard-4`；用于成本停车或 CI 冒烟测试
`dev`	单副本、最小资源
`production`	多副本并启用 HPA；推荐用于真实工作负载
`production-large`	高内存和高 CPU；50+ 用户或 1000+ 追踪/秒

kubectl

bash

# 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

# Backend logs (live)
kubectl logs -n langsmith deploy/langsmith-backend --tail=100 -f

# Gateway and HTTPRoute
kubectl get gateway -n langsmith
kubectl get httproute -n langsmith
kubectl get svc -n envoy-gateway-system

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

# Workload Identity
kubectl get serviceaccount langsmith-ksa -n langsmith -o yaml | grep annotation -A5

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

# LangSmith Deployment
kubectl get lgp -n langsmith
kubectl get crd | grep langchain

gcloud

bash

# Re-auth if you hit oauth2 invalid_grant / invalid_rapt errors
gcloud auth login
gcloud auth application-default login

# Cluster credentials
gcloud container clusters get-credentials <cluster-name> --region <region> --project <project-id>

# List clusters
gcloud container clusters list --project <project-id>

# Cluster status
gcloud container clusters describe <cluster-name> --region <region> --format="value(status)"

# Cloud SQL
gcloud sql instances list --project <project-id>
gcloud sql instances describe <instance-name> --format="value(ipAddresses)"

# Memorystore Redis
gcloud redis instances list --region <region>
gcloud redis instances describe <instance-name> --region <region> --format="value(host)"

# GCS bucket
gsutil ls gs://<bucket-name>
gsutil iam get gs://<bucket-name>

# Workload Identity binding
gcloud iam service-accounts get-iam-policy <gsa-email> --project <project-id>

# Enabled APIs
gcloud services list --enabled --project <project-id>

# VPC peering
gcloud services vpc-peerings list --network <vpc-name> --project <project-id>

# Secret Manager
gcloud secrets list --project <project-id> --filter="name:langsmith"
gcloud secrets versions access latest --secret=<secret-id> --project <project-id>

Terraform

bash

cd modules/gcp/infra

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

# Target a specific module
terraform apply -var-file=terraform.tfvars -target=module.networking

# Outputs
terraform output
terraform output -raw cluster_name
terraform output -raw storage_bucket_name

# State
terraform state list
terraform state show module.gke_cluster
terraform refresh -var-file=terraform.tfvars

关键约束

在 terraform destroy 之前先卸载 Helm。Envoy Gateway 负载均衡器引用了 VPC；留着它会阻止网络删除。务必先运行 make uninstall。
config.deployment.url 必须包含 https://。没有协议时，operator 生成的 agent 会一直卡在 DEPLOYING。
LangSmith Deployment 附加组件需要 config.deployment.enabled: true。只设置 URL 而不设置 enabled: true 会静默跳过 listener 和 operator。
加密密钥在首次启用后绝不能更改。轮换 insights_encryption_key 或 polly_encryption_key 会永久破坏现有的加密数据。
首次启用 Polly 后重启前端。agentBootstrap 会在注册后创建 langsmith-polly-config ConfigMap；更早启动的 frontend pod 不会加载它。
Envoy Gateway 的 IP 会在拆除时变化。Gateway 被删除时，GCP 会释放外部 IP。在 terraform destroy 并重新 apply 后，请更新你的 DNS A 记录。
langsmith-ksa 注解不是永久的。operator 会在运行时创建 ServiceAccount，它不会在 namespace 删除后保留。deploy.sh 会以幂等方式重新添加注解。

拆除

bash

# 1. Remove LangSmith Deployment resources (if the add-on was enabled)
kubectl delete lgp --all -n langsmith 2>/dev/null || true

# 2. Uninstall LangSmith
make uninstall

# 3. Set deletion protection = false in terraform.tfvars, then:
make destroy

hcl

# terraform.tfvars
gke_deletion_protection      = false
postgres_deletion_protection = false

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织