GCP Terraform 故障排查

本页记录了使用 GCP Terraform 模块配置的 LangSmith 部署的常见问题、修复方法和诊断命令。

升级前，请查看 LangSmith 自托管版本更新日志了解破坏性变更和需要更新的变量。在运行任何 kubectl 命令之前，请先执行 gcloud container clusters get-credentials <cluster-name> --region <region> --project <project-id>。

如需本页中使用的所有 kubectl、helm 和 gcloud 命令的完整参考，请跳转至诊断命令。

自动化诊断

在运行单独的命令之前，请先尝试使用捆绑的脚本：

# Full deployment health check + next-step guidance
make status

# Secret Manager validation
make secrets    # → manage-secrets.sh validate

已知问题

terraform apply 失败：GCP API 未启用

症状

Error 403: ... has not been used in project <project-id> before or it is disabled.

原因： 所需的 GCP API 未启用。Terraform 通过 google_project_service 启用它们，但 cloudresourcemanager.googleapis.com 必须预先启用，Terraform 才能启用其他 API。修复

gcloud services enable cloudresourcemanager.googleapis.com --project <project-id>
cd modules/gcp/infra
terraform apply -var-file=terraform.tfvars

apply 后无法访问 GKE 集群 API 服务器

症状

Error: Get "https://<cluster-endpoint>/api/v1/namespaces": dial tcp: connection refused

原因： GKE 控制平面需要 10 到 15 分钟才能完全投入运行。Terraform 会等待 RUNNING 状态，然后增加 90 秒的缓冲时间。对于启动较慢的项目，冷启动 API 激活可能超出这个时间窗口。 修复： 等待 RUNNING 状态，然后重新运行：

gcloud container clusters describe <cluster-name> \
  --region <region> --project <project-id> --format="value(status)"

terraform apply -var-file=terraform.tfvars

GKE 节点未加入（状态为 NotReady）

症状： kubectl get nodes 显示没有节点或节点卡在 NotReady 状态。 原因： 节点池服务账户缺少 roles/container.nodeServiceAccount 角色，或者 VPC 防火墙规则阻止了节点与控制平面之间的通信。修复

gcloud container node-pools describe <pool-name> \
  --cluster <cluster-name> --region <region> \
  --format="value(config.serviceAccount)"

gcloud projects add-iam-policy-binding <project-id> \
  --member="serviceAccount:<node-sa-email>" \
  --role="roles/container.nodeServiceAccount"

gcloud compute firewall-rules list --filter="network:<vpc-name>"

GKE Pod 无法连接 Cloud SQL（连接被拒绝）

症状： 后端日志显示对 Cloud SQL 私有 IP 的 connection refused 或 no route to host 错误。 原因： 私有服务连接（VPC 对等互连）未建立，或者分配的 IP 范围太小。通常发生在网络模块运行之前未启用 servicenetworking.googleapis.com 的情况下。修复

gcloud services vpc-peerings list --network <vpc-name> --project <project-id>
gcloud sql instances describe <instance-name> --format="value(ipAddresses)"
gcloud compute networks peerings list --network <vpc-name>

如果缺少对等互连，请确保 enable_private_service_connection = true 并重新应用：

terraform apply -var-file=terraform.tfvars -target=module.networking
terraform apply -var-file=terraform.tfvars

Memorystore Redis 连接超时

症状： Pod 无法连接到 Redis。日志显示 dial tcp: connection timed out 或 redis: connection refused。 原因： Memorystore 的 authorized_network 与 GKE 的 VPC 不匹配，或者 Redis 的私有 IP 所在的范围无法从 GKE 子网路由。修复

gcloud redis instances describe <instance-name> --region <region> \
  --format="value(host,authorizedNetwork)"

kubectl run redis-test --rm -it --image=redis:7 -n langsmith -- \
  redis-cli -h <redis-private-ip> ping
# Expected: PONG

cert-manager 颁发 Let’s Encrypt 证书失败

症状： kubectl get certificate -n langsmith 显示 READY=False。HTTP01 验证失败。 原因： DNS A 记录未指向 Envoy Gateway 的 IP，或者负载均衡器上的 80 端口被阻止。修复

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}'

kubectl describe certificate <cert-name> -n langsmith
kubectl get challenges -n langsmith
kubectl describe challenge -n langsmith

dig +short <your-langsmith-domain>

DNS A 记录必须解析到 Gateway IP，证书才能颁发。cert-manager 的 HTTP01 解决程序需要 80 端口能从互联网访问。

LangSmith Pod 无法访问 GCS 存储桶（访问被拒绝）

症状： 后端日志在写入 GCS 时显示 AccessDeniedException: 403 Insufficient Permission 或 403 Forbidden。 原因：

在原生 GCS 模式（默认模式）下，通过 Workload Identity 绑定的 GCP 服务账户缺少存储桶的 roles/storage.objectAdmin 角色，或者 Pod 的 Kubernetes ServiceAccount 缺少 iam.gke.io/gcp-service-account 注解。
在可选的 S3 兼容模式下，传递给 Helm 的 HMAC 凭据不正确，或者其服务账户缺少存储桶的 roles/storage.objectAdmin 角色。

修复

# Confirm the bucket and its IAM bindings
helm get values langsmith -n langsmith | grep bucketName
gcloud storage buckets get-iam-policy gs://<bucket-name>

# Native GCS mode: verify the Workload Identity annotation on the pod ServiceAccount
kubectl get serviceaccount langsmith-backend -n langsmith \
  -o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}'

GCP 服务账户必须拥有存储桶的 roles/storage.objectAdmin 角色。如果注解本身缺失，请应用下面 Workload Identity 部分中的修复方法。对于 S3 兼容模式，请在 Cloud Storage → Settings → Interoperability 下创建 HMAC 密钥；其服务账户也需要存储桶的 roles/storage.objectAdmin 角色。

Envoy Gateway Webhook 阻止 GKE 操作

症状

Error from server (InternalError): failed calling webhook "validate.gateway.envoyproxy.io"

原因： Envoy Gateway 的准入 Webhook 未就绪或其 caBundle 已过时。修复

kubectl get pods -n envoy-gateway-system

kubectl rollout restart deployment/envoy-gateway -n envoy-gateway-system
kubectl rollout status deployment/envoy-gateway -n envoy-gateway-system

重新应用后 Envoy Gateway 外部 IP 发生变化

症状： Terraform 重新应用后，DNS 不再解析到正确的 IP，或者现有的防火墙允许列表停止工作。 原因： Envoy Gateway 的外部 IP 绑定到由 Terraform 管理的 Gateway Kubernetes 资源。如果该资源被删除并重建（例如 terraform taint、强制替换的模块更改或 terraform destroy + 重新应用），GCP 会分配一个新的 IP。如果不预先分配静态区域 IP，就无法保留原始 IP。 预防措施

不要对 Gateway 资源执行 terraform taint 或手动删除操作。
仅在完全拆除和重建时使用 make destroy + make apply。
在任何可能重建 Gateway 的操作之前，请记下当前的 IP。

恢复： 将你的 DNS A 记录更新为新的 IP：

kubectl get gateway -n langsmith -o jsonpath='{.items[0].status.addresses[0].value}'

gcloud dns record-sets update <your-domain>. \
  --type=A --ttl=300 \
  --rrdatas=<new-ip> \
  --zone=<zone-name> \
  --project=<project-id>

terraform destroy 失败：启用了删除保护

症状

Error: googleapi: Error 409: The instance is protected from deletion.

原因： gke_deletion_protection = true（默认）或 postgres_deletion_protection = true 阻止了 Terraform 销毁资源。修复

# terraform.tfvars
gke_deletion_protection      = false
postgres_deletion_protection = false

terraform apply -var-file=terraform.tfvars
terraform destroy

Workload Identity 不工作（GCS 权限被拒绝）

症状

AccessDeniedException: 403 <pod-sa>@<project>.iam.gserviceaccount.com
  does not have storage.objects.create access to the Google Cloud Storage bucket.

原因： LangSmith Pod 使用的 Kubernetes ServiceAccount 缺少 Workload Identity 注解，或者 GCP 服务账户缺少 GCS IAM 绑定。诊断

kubectl get serviceaccount langsmith-backend -n langsmith \
  -o jsonpath='{.metadata.annotations}' | python3 -m json.tool

BUCKET=$(terraform -chdir=infra output -raw storage_bucket_name)
gsutil iam get gs://$BUCKET | grep -A3 "serviceAccount"

GSA=$(terraform -chdir=infra output -raw workload_identity_service_account_email)
gcloud projects get-iam-policy <project-id> \
  --flatten="bindings[].members" --filter="bindings.members:$GSA"

修复

terraform -chdir=infra apply -target=module.iam
make init-values
make deploy

`langsmith-ksa` 缺少 Workload Identity 注解

症状： 操作员生成的代理 Pod 无法启动或卡在 Pending 状态。日志显示权限错误或代理引导作业挂起。 原因： langsmith-ksa 由 LangSmith 操作员（而非 Helm）创建，它不会在命名空间删除或全新集群重建后保留。deploy.sh 会在部署后重新为其添加注解；如果之前的部署被中断，注解可能缺失。诊断

kubectl get serviceaccount langsmith-ksa -n langsmith \
  -o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}'

修复

# Re-run deploy; idempotently creates and annotates langsmith-ksa
make deploy

# Or annotate manually
WI=$(terraform -chdir=infra output -raw workload_identity_annotation)
kubectl create serviceaccount langsmith-ksa -n langsmith --dry-run=client -o yaml \
  | kubectl apply -f -
kubectl annotate serviceaccount langsmith-ksa -n langsmith \
  iam.gke.io/gcp-service-account="$WI" --overwrite

Helm 发布卡在 `pending-upgrade` 状态

症状

Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress

原因： 上一次 helm upgrade 被中断（在 --wait 期间按下了 Ctrl+C）。Helm 锁定了该发布。 修复： deploy.sh 能检测到并自动恢复此状态。如果手动运行：

helm rollback langsmith -n langsmith --wait --timeout 5m
make deploy

Secret Manager 访问被拒绝

症状

ERROR: PERMISSION_DENIED: Permission 'secretmanager.versions.access'
  denied on resource 'projects/.../secrets/...'

原因： 要么 secretmanager.googleapis.com 未启用，要么操作员账户缺少 roles/secretmanager.admin 角色。修复

gcloud services enable secretmanager.googleapis.com --project <project-id>

gcloud projects add-iam-policy-binding <project-id> \
  --member="user:$(gcloud config get account)" \
  --role="roles/secretmanager.admin"

`langsmith-postgres-credentials` 或 `langsmith-redis-credentials` Secret 缺失

症状： 部署后 Pod 立即因数据库连接错误而崩溃，或者 kubectl get secrets -n langsmith 未列出 langsmith-postgres-credentials / langsmith-redis-credentials。 原因： 这些 Secret 由 k8s-bootstrap 模块创建。如果 terraform apply 未运行、中途失败或命名空间被带外删除，则会缺失。修复

terraform -chdir=infra apply -target=module.k8s_bootstrap

kubectl get secret langsmith-postgres-credentials -n langsmith
kubectl get secret langsmith-redis-credentials -n langsmith

诊断命令

集群访问

gcloud container clusters get-credentials <cluster-name> --region <region> --project <project-id>
kubectl config current-context
kubectl get nodes -o wide

Pod

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=50
kubectl logs <pod-name> -n langsmith --previous --tail=50
kubectl logs -n langsmith deploy/langsmith-backend --tail=100 -f

TLS 和证书

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

Gateway 和负载均衡器

kubectl get gateway -n langsmith
kubectl get httproute -n langsmith
kubectl get svc -n envoy-gateway-system -o wide
kubectl get pods -n envoy-gateway-system

Helm

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

LangSmith 部署

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

Workload Identity 和 IAM

kubectl get serviceaccount langsmith-backend -n langsmith \
  -o jsonpath='{.metadata.annotations}' | python3 -m json.tool

kubectl get serviceaccount langsmith-ksa -n langsmith \
  -o jsonpath='{.metadata.annotations.iam\.gke\.io/gcp-service-account}'

BUCKET=$(terraform -chdir=infra output -raw storage_bucket_name 2>/dev/null)
gsutil iam get gs://$BUCKET

gcloud iam service-accounts list --project <project-id> --filter="displayName:langsmith"

Secrets 和引导程序

kubectl get secrets -n langsmith
kubectl get secret langsmith-postgres-credentials -n langsmith
kubectl get secret langsmith-redis-credentials -n langsmith

kubectl get secret langsmith-postgres-credentials -n langsmith \
  -o jsonpath='{.data.connection_url}' | base64 --decode

gcloud secrets list --project <project-id> --filter="name:langsmith"

gcloud secrets versions access latest \
  --secret=langsmith-<prefix>-<env>-postgres-password \
  --project <project-id>

make secrets

快速健康检查

echo "=== Context ===" && kubectl config current-context
echo "=== Nodes ===" && kubectl get nodes
echo "=== Pods ===" && kubectl get pods -n langsmith
echo "=== Certificate ===" && kubectl get certificate -n langsmith
echo "=== Gateway ===" && kubectl get gateway -n langsmith
echo "=== Secrets ===" && kubectl get secrets -n langsmith | grep -E "langsmith-postgres-credentials|langsmith-redis-credentials"
echo "=== Helm ===" && helm status langsmith -n langsmith 2>/dev/null | grep -E "STATUS|LAST DEPLOYED"

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

自动化诊断

已知问题

terraform apply 失败：GCP API 未启用

apply 后无法访问 GKE 集群 API 服务器

GKE 节点未加入（状态为 NotReady）

GKE Pod 无法连接 Cloud SQL（连接被拒绝）

Memorystore Redis 连接超时

cert-manager 颁发 Let’s Encrypt 证书失败

LangSmith Pod 无法访问 GCS 存储桶（访问被拒绝）

Envoy Gateway Webhook 阻止 GKE 操作

重新应用后 Envoy Gateway 外部 IP 发生变化

terraform destroy 失败：启用了删除保护

Workload Identity 不工作（GCS 权限被拒绝）

`langsmith-ksa` 缺少 Workload Identity 注解

Helm 发布卡在 `pending-upgrade` 状态

Secret Manager 访问被拒绝

`langsmith-postgres-credentials` 或 `langsmith-redis-credentials` Secret 缺失

诊断命令

集群访问

Pod

TLS 和证书

Gateway 和负载均衡器

Helm

LangSmith 部署

Workload Identity 和 IAM

Secrets 和引导程序

快速健康检查

​自动化诊断

​已知问题

​terraform apply 失败：GCP API 未启用

​apply 后无法访问 GKE 集群 API 服务器

​GKE 节点未加入（状态为 NotReady）

​GKE Pod 无法连接 Cloud SQL（连接被拒绝）

​Memorystore Redis 连接超时

​cert-manager 颁发 Let’s Encrypt 证书失败

​LangSmith Pod 无法访问 GCS 存储桶（访问被拒绝）

​Envoy Gateway Webhook 阻止 GKE 操作

​重新应用后 Envoy Gateway 外部 IP 发生变化

​terraform destroy 失败：启用了删除保护

​Workload Identity 不工作（GCS 权限被拒绝）

​langsmith-ksa 缺少 Workload Identity 注解

​Helm 发布卡在 pending-upgrade 状态

​Secret Manager 访问被拒绝

​langsmith-postgres-credentials 或 langsmith-redis-credentials Secret 缺失

​诊断命令

​集群访问

​Pod

​TLS 和证书

​Gateway 和负载均衡器

​Helm

​LangSmith 部署

​Workload Identity 和 IAM

​Secrets 和引导程序

​快速健康检查

自动化诊断

已知问题

terraform apply 失败：GCP API 未启用

apply 后无法访问 GKE 集群 API 服务器

GKE 节点未加入（状态为 NotReady）

GKE Pod 无法连接 Cloud SQL（连接被拒绝）

Memorystore Redis 连接超时

cert-manager 颁发 Let’s Encrypt 证书失败

LangSmith Pod 无法访问 GCS 存储桶（访问被拒绝）

Envoy Gateway Webhook 阻止 GKE 操作

重新应用后 Envoy Gateway 外部 IP 发生变化

terraform destroy 失败：启用了删除保护

Workload Identity 不工作（GCS 权限被拒绝）

`langsmith-ksa` 缺少 Workload Identity 注解

Helm 发布卡在 `pending-upgrade` 状态

Secret Manager 访问被拒绝

`langsmith-postgres-credentials` 或 `langsmith-redis-credentials` Secret 缺失

诊断命令

集群访问

Pod

TLS 和证书

Gateway 和负载均衡器

Helm

LangSmith 部署

Workload Identity 和 IAM

Secrets 和引导程序

快速健康检查