AWS Terraform 故障排查

本页文档记录了使用 AWS Terraform 模块部署的 LangSmith 的常见问题、修复方案及诊断命令。

在升级前，请查阅 LangSmith 自托管更新日志了解重大变更和所需的变量更新。在运行任何 kubectl 命令之前，请先执行 aws eks update-kubeconfig --region <region> --name <cluster-name>。

若需本页所用 kubectl、helm 和 aws 调用的完整参考，请直接跳至诊断命令。

自动化诊断

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

# Deployment status across all layers + next-step guidance
make status

# SSM parameter validation
./infra/scripts/manage-ssm.sh validate

已知问题

EKS 节点组创建失败：CREATE_FAILED

症状

Error: waiting for EKS Node Group creation: unexpected state 'CREATE_FAILED'

原因： 节点组创建开始时，EKS 控制平面尚未完全就绪。常见于中断的 apply 操作之后。修复

aws eks wait cluster-active --name <cluster-name> --region <region>

aws eks describe-nodegroup \
  --cluster-name <cluster-name> \
  --nodegroup-name <nodegroup-name> \
  --region <region> \
  --query "nodegroup.health"

terraform apply -var-file=terraform.tfvars

kubectl 失败：‘You must be logged in to the server’

症状： 所有 kubectl 命令都报错 error: You must be logged in to the server (Unauthorized)。 原因： kubeconfig 过期、AWS 凭证与创建集群时使用的凭证不同，或令牌已过期。修复

aws eks update-kubeconfig --region <region> --name <cluster-name>
kubectl cluster-info

aws sts get-caller-identity

如果集群是用不同的 IAM 角色创建的，需要通过 aws-auth ConfigMap 授予访问权限：

kubectl edit configmap aws-auth -n kube-system
# Add your IAM user or role under mapUsers / mapRoles

Helm 安装后未创建 ALB

症状： 几分钟后，执行 kubectl get ingress -n langsmith 仍看不到 ADDRESS。 原因： AWS 负载均衡控制器未运行或缺少 IRSA 权限、Terraform 预置的 ALB 未被正确引用，或者设置了 alb_scheme = "internal"（内部 ALB 没有公共地址；请参见 ALB 没有公共地址（内部方案））。修复

kubectl get pods -n kube-system | grep aws-load-balancer
kubectl logs -n kube-system -l app.kubernetes.io/name=aws-load-balancer-controller --tail=50
kubectl get sa -n kube-system aws-load-balancer-controller -o yaml | grep eks.amazonaws.com

terraform output alb_dns_name
aws elbv2 describe-load-balancers --query "LoadBalancers[?DNSName=='<alb-dns-name>'].State"

来自 EKS Pod 的 RDS 连接被拒绝

症状： 后端日志显示 RDS 端点的 connection refused 或 timeout。 原因： RDS 安全组不允许来自 EKS 节点安全组或集群安全组的入站 TCP 5432 流量。修复

aws eks describe-cluster --name <cluster-name> \
  --query "cluster.resourcesVpcConfig.clusterSecurityGroupId"

aws rds describe-db-instances \
  --db-instance-identifier <db-id> \
  --query "DBInstances[0].VpcSecurityGroups"

aws ec2 describe-security-group-rules \
  --filter "Name=group-id,Values=<rds-sg-id>"

postgres 模块会自动设置安全组。如果该规则缺失，请重新应用：

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

Pod 访问 S3 被拒绝（IRSA 未配置）

症状： 后端日志在读取或写入 S3 时显示 AccessDenied。 原因： LangSmith 服务账户缺少 IRSA 注解，或 S3 VPC 网关端点路由不正确。修复

kubectl get sa langsmith -n langsmith -o yaml | grep eks.amazonaws.com

aws ec2 describe-vpc-endpoints \
  --filters "Name=service-name,Values=com.amazonaws.<region>.s3" \
  --query "VpcEndpoints[].State"

kubectl run s3-test --rm -it --image=amazon/aws-cli -n langsmith -- \
  s3 ls s3://<bucket-name>

如果 IRSA 注解缺失，请验证 terraform.tfvars 中 create_langsmith_irsa_role = true，并且 Helm values 中的服务账户名称与 langsmith 匹配。

ElastiCache Redis 连接超时

症状： Pod 无法连接到 Redis。日志显示 dial tcp: i/o timeout。 原因： ElastiCache 安全组不允许来自 EKS 节点安全组的入站 TCP 6379 流量。修复

aws elasticache describe-cache-clusters \
  --cache-cluster-id <cluster-id> \
  --query "CacheClusters[0].SecurityGroups"

kubectl run redis-test --rm -it --image=redis:7 -n langsmith -- \
  redis-cli -h <elasticache-endpoint> -a <auth-token> ping

EKS 节点未自动扩缩容

症状： Pod 持续处于 Pending 状态。节点数量未增加。 原因： 集群自动扩缩器缺少 IAM 权限、目标 ASG 设置错误，或节点组的 min_size = max_size。修复

kubectl logs -n kube-system -l app=cluster-autoscaler --tail=50

aws autoscaling describe-auto-scaling-groups \
  --query "AutoScalingGroups[?contains(Tags[].Key, 'k8s.io/cluster-autoscaler/<cluster-name>')].[AutoScalingGroupName]" \
  --output table

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

症状： kubectl get certificate -n langsmith 显示 READY=False。HTTP01 验证失败。 原因： ALB 未将端口 80 转发到 cert-manager 解析器 Pod，或该域名的 DNS 记录未指向 ALB。修复

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

aws elbv2 describe-listeners --load-balancer-arn <alb-arn>

dig +short <your-langsmith-domain>
# Expected: CNAME to the ALB DNS name

postgres_deletion_protection 阻止 terraform destroy

症状

Error: deleting RDS DB Instance: InvalidParameterCombination:
Cannot delete, DeletionProtection is enabled.

修复： 在 terraform.tfvars 中禁用删除保护，应用更改，然后执行销毁：

postgres_deletion_protection = false

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

ESO 同步失败：langsmith-config secret 缺失

症状： Pod 卡在 CreateContainerConfigError。kubectl get secret langsmith-config -n langsmith 返回 NotFound。 原因： ESO 同步是“全有或全无”的。如果 ExternalSecret 引用的任何一个 SSM 参数缺失，ESO 就会拒绝创建 Kubernetes Secret。所有 Pod 都会失败，包括那些与缺失参数无关的 Pod。修复

kubectl get externalsecret langsmith-config -n langsmith
kubectl describe externalsecret langsmith-config -n langsmith

./infra/scripts/manage-ssm.sh validate

source ./infra/scripts/setup-env.sh
./helm/scripts/apply-eso.sh

describe 输出会显示哪个 remoteRef.key 失败。将其与 SSM 前缀 /langsmith/{name_prefix}-{environment}/ 进行匹配。

SSM 参数前缀不匹配

症状： manage-ssm.sh validate 通过，但 ESO 仍然无法同步。或者 setup-env.sh 将参数写入了一个与 ESO 期望不同的前缀下。 原因： SSM 前缀来源于 terraform.tfvars 中的 name_prefix 和 environment。如果这些值在初始设置后发生了更改，旧的参数会保存在旧的前缀下，而 ESO 会去新的前缀下查找。修复

kubectl get externalsecret langsmith-config -n langsmith -o yaml | grep 'key:'

./infra/scripts/manage-ssm.sh list

./infra/scripts/migrate-ssm.sh

切勿在现有部署上更改 name_prefix 或 environment。

Terraform 验证拒绝 Postgres 密码

症状

Error: Invalid value for variable "postgres_password"
RDS master password must not contain '/', '@', '"', single quotes, or spaces.

原因： 密码中包含了 RDS 不允许在主密码中使用的字符。 修复： 重新生成一个不含受限字符的密码。setup-env.sh 会自动生成符合要求的密码；如需手动更新：

./infra/scripts/manage-ssm.sh set postgres-password "$(openssl rand -base64 24 | tr -d '/+= ')"
source ./infra/scripts/setup-env.sh
terraform apply -var-file=terraform.tfvars

私有 EKS 集群不可达（需要堡垒机）

症状： 当 enable_public_eks_cluster = false 时，kubectl 和 terraform apply 超时。 原因： EKS API 端点是私有的。命令必须在 VPC 内部执行，可以通过堡垒主机或 VPN 连接。修复

# If the bastion was provisioned (create_bastion = true)
aws ssm start-session --target <bastion-instance-id>

# From the bastion
aws eks update-kubeconfig --region <region> --name <cluster-name>
kubectl get nodes

如果未预置堡垒主机，请设置 create_bastion = true 并重新应用，或者临时设置 enable_public_eks_cluster = true。

ALB 没有公共地址（内部方案）

症状： kubectl get ingress -n langsmith 显示了 ADDRESS，但它只在 VPC 内部可解析。 原因： 在 terraform.tfvars 中设置了 alb_scheme = "internal"。内部 ALB 只能从 VPC 内部（通过 VPN、对等连接或 PrivateLink）访问。 修复： 这是私有部署的有意设计。要使 ALB 可从公网访问：

alb_scheme = "internet-facing"

terraform apply -var-file=terraform.tfvars
# Then redeploy Helm to pick up the new ALB

Ingress 重建后 ALB 主机名更改

症状： LangSmith URL 停止工作。代理部署卡在 DEPLOYING。DNS 记录或书签指向一个不再解析的旧 ALB 主机名。 原因： 删除 Kubernetes ingress（通过 helm uninstall、kubectl delete ingress 或删除命名空间）会解除 ALB。当 ingress 被重新创建时，会分配一个具有不同主机名的新 ALB。Helm values 中的 config.deployment.url 仍然指向旧主机名，导致运维健康检查失败，部署一直卡住。如果 ALB 控制器创建了一个新的 ALB，而不是重用 Terraform 预置的那个，也会发生这种情况。这需要 group.name 注解与 load-balancer-arn 一起设置来防止。 预防措施

确保同时设置了 group.name 和 load-balancer-arn 注解。当存在预置的 ALB 时，init-values.sh 会自动完成此操作。
除非你计划更新所有依赖主机名的配置，否则不要删除 ingress。
避免不带 --server-side=false 执行 helm rollback。Ingress SSA 冲突可能触发删除/重建循环。

修复

# 1. Check what hostname the ingress currently has
kubectl get ingress langsmith-ingress -n langsmith \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

# 2. Check what Terraform expects
terraform output alb_dns_name

# 3. If they differ, re-run init-values.sh and redeploy
make init-values
make deploy

节点组扩缩容更改未被 Terraform 应用

症状： 在 terraform.tfvars 中更改 min_size 或 max_size 后，terraform plan 显示 “No changes”。 原因： ASG 已被通过其他方式（AWS CLI、控制台或集群自动扩缩器）更改，且 Terraform 状态已反映新值。社区 EKS 模块会忽略 desired_size 的更改，以便自动扩缩器进行管理；min_size 和 max_size 应正常传播。修复

terraform refresh
terraform plan

# For an immediate change, use the AWS CLI directly
aws eks update-nodegroup-config \
  --cluster-name <cluster> \
  --nodegroup-name <nodegroup> \
  --scaling-config minSize=3,maxSize=8,desiredSize=5 \
  --region <region>

诊断命令

集群访问

aws eks update-kubeconfig --region <region> --name <cluster-name>
kubectl config current-context
kubectl get nodes -o wide
aws sts get-caller-identity

Pods

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

ALB 和 Ingress

kubectl get ingress -n langsmith
kubectl describe ingress -n langsmith
aws elbv2 describe-load-balancers --query "LoadBalancers[?contains(LoadBalancerName, 'langsmith')]"

TLS 和证书

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

ESO 和 Secrets

kubectl get externalsecret -n langsmith
kubectl describe externalsecret langsmith-config -n langsmith
kubectl get clustersecretstore langsmith-ssm
kubectl get secret langsmith-config -n langsmith -o jsonpath='{.data}' | jq 'keys'
./infra/scripts/manage-ssm.sh validate
./infra/scripts/manage-ssm.sh diff

Helm

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

IRSA 和 IAM

kubectl get sa langsmith -n langsmith -o yaml | grep eks.amazonaws.com
terraform output langsmith_irsa_role_arn
aws iam get-role --role-name <irsa-role-name>

LangSmith 部署

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

快速健康检查

echo "=== Context ===" && kubectl config current-context
echo "=== Nodes ===" && kubectl get nodes
echo "=== Pods ===" && kubectl get pods -n langsmith
echo "=== Ingress ===" && kubectl get ingress -n langsmith
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

自动化诊断

已知问题

EKS 节点组创建失败：CREATE_FAILED

kubectl 失败：‘You must be logged in to the server’

Helm 安装后未创建 ALB

来自 EKS Pod 的 RDS 连接被拒绝

Pod 访问 S3 被拒绝（IRSA 未配置）

ElastiCache Redis 连接超时

EKS 节点未自动扩缩容

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

postgres_deletion_protection 阻止 terraform destroy

ESO 同步失败：langsmith-config secret 缺失

SSM 参数前缀不匹配

Terraform 验证拒绝 Postgres 密码

私有 EKS 集群不可达（需要堡垒机）

ALB 没有公共地址（内部方案）

Ingress 重建后 ALB 主机名更改

节点组扩缩容更改未被 Terraform 应用

诊断命令

集群访问

Pods

ALB 和 Ingress

TLS 和证书

ESO 和 Secrets

Helm

IRSA 和 IAM

LangSmith 部署

快速健康检查

​自动化诊断

​已知问题

​EKS 节点组创建失败：CREATE_FAILED

​kubectl 失败：‘You must be logged in to the server’

​Helm 安装后未创建 ALB

​来自 EKS Pod 的 RDS 连接被拒绝

​Pod 访问 S3 被拒绝（IRSA 未配置）

​ElastiCache Redis 连接超时

​EKS 节点未自动扩缩容

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

​postgres_deletion_protection 阻止 terraform destroy

​ESO 同步失败：langsmith-config secret 缺失

​SSM 参数前缀不匹配

​Terraform 验证拒绝 Postgres 密码

​私有 EKS 集群不可达（需要堡垒机）

​ALB 没有公共地址（内部方案）

​Ingress 重建后 ALB 主机名更改

​节点组扩缩容更改未被 Terraform 应用

​诊断命令

​集群访问

​Pods

​ALB 和 Ingress

​TLS 和证书

​ESO 和 Secrets

​Helm

​IRSA 和 IAM

​LangSmith 部署

​快速健康检查

自动化诊断

已知问题

EKS 节点组创建失败：CREATE_FAILED

kubectl 失败：‘You must be logged in to the server’

Helm 安装后未创建 ALB

来自 EKS Pod 的 RDS 连接被拒绝

Pod 访问 S3 被拒绝（IRSA 未配置）

ElastiCache Redis 连接超时

EKS 节点未自动扩缩容

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

postgres_deletion_protection 阻止 terraform destroy

ESO 同步失败：langsmith-config secret 缺失

SSM 参数前缀不匹配

Terraform 验证拒绝 Postgres 密码

私有 EKS 集群不可达（需要堡垒机）

ALB 没有公共地址（内部方案）

Ingress 重建后 ALB 主机名更改

节点组扩缩容更改未被 Terraform 应用

诊断命令

集群访问

Pods

ALB 和 Ingress

TLS 和证书

ESO 和 Secrets

Helm

IRSA 和 IAM

LangSmith 部署

快速健康检查