make apply 之前，您可以对 LangSmith 部署进行规模调整、安全设置和自定义。
在规划部署或排查现有部署问题时，可将此页面作为参考。它涵盖：
- 平台层和应用核心服务。
- AWS 托管服务、IRSA 角色和集群基础设施。
- 网络拓扑、入口选项和 TLS/DNS 策略。
- LangSmith 部署附加组件。
- 模块依赖关系图和可选的安全模块。
平台层
LangSmith 在 AWS 上的部署分为两个阶段，并有一个可选的附加组件。基础设施阶段预置云基础。应用程序阶段安装 LangSmith Helm chart。LangSmith 部署附加组件是可选的，它添加了 host-backend、listener 和 operator 服务，用于从 UI 管理 LangGraph 应用程序。
组件与存储映射
应用核心服务
这些 Pod 在每次部署中都会运行。所有服务都会写入日志和指标；较繁忙的组件（backend, queue, ingest-queue）支持水平扩缩。一次性任务
Helm chart 在安装和升级时运行三个任务：LangSmith 部署附加组件
当enable_deployments = true 时，将安装三个额外服务，并注册一个 LangGraphPlatform CRD。用户在 LangSmith UI 中创建的每个部署都会在 langsmith 命名空间中生成一个 Kubernetes Deployment，由 operator 管理。
AWS 托管服务
当postgres_source = "external" 且 redis_source = "external"（推荐的生产设置）时，Terraform 会预配置以下 AWS 托管服务：
RDS PostgreSQL
- 默认大小：
db.t3.large，私有子网，端口 5432。 - 存储组织、用户、项目、API 密钥、设置。
- 密钥流：SSM
/langsmith/{base_name}/postgres-password→ ESO →langsmith-config。
ElastiCache Redis
- 默认大小：
cache.m6g.xlarge，私有子网，TLS 端口 6379。 - Trace 摄取队列、发布/订阅、短期缓存。
- 密钥流：SSM
/langsmith/{base_name}/redis-auth-token→ ESO →langsmith-config。
S3 存储桶
- Trace 有效负载：大型输入和输出、附件。
- 通过
langsmith_irsa_role的 IRSA（无静态密钥）。VPC 网关端点，无公网互联网访问。 - 前缀：
ttl_s/（短 TTL）和ttl_l/（长 TTL）。 - 无论何种层级，S3 存储桶始终是必需的。禁用 blob 存储会在大型有效负载时导致集群故障。
SSM 参数存储
- 所有 LangSmith 密钥的集中式密钥存储。
- 流程：
source infra/scripts/setup-env.sh将密钥写入 SSM。ESOClusterSecretStore读取它们并投射一个langsmith-configKubernetes Secret，Helm chart 通过config.existingSecretName挂载该 Secret。 - 前缀：
/langsmith/{name_prefix}-{environment}/。
集群基础设施
两个 Terraform 模块安装 LangSmith 所依赖的集群级服务。eks 模块通过 eks-blueprints-addons 安装 AWS 集成控制器；k8s-bootstrap 模块安装工作负载依赖项和可选的入口网关（参见入口选项）：
IRSA 角色
IRSA 取代了静态凭证。EKS 集群的 OIDC 颁发者是信任锚点；langsmith 和 kube-system 中的服务账户通过角色 ARN 进行注解，Pod 通过 EKS 令牌 webhook 接收临时凭证。
网络拓扑
默认 ALB 入口
Envoy 网关（可选）
使用 Terraform 默认值（enable_envoy_gateway = true）时，预先配置的 ALB 保持在前端，并通过 TargetGroupBinding 在端口 8080 绑定到 Envoy 服务，如入口选项表所示。下面的独立网络负载均衡器路径是一个变体（helm/values/examples/langsmith-values-ingress-envoy-gateway.yaml），其中 NLB 直接终止 TLS：
langsmith 和 langsmith-agents 都通过一个设置了 allowedRoutes: All 的 HTTPRoute 附加到共享的 langsmith-gateway。
带有网络防火墙的出口路径
当create_firewall = true 时，所有来自私有子网的出站互联网流量在到达 NAT 网关前都会被检查：
入口选项
模块提供四种互斥的入口选项。该选择决定了是否支持拆分数据平面（智能体 Pod 在单独的命名空间中）。为什么 ALB 不能支持拆分数据平面
标准的 Kubernetes Ingress 是命名空间范围的。ALB 控制器仅路由到与 Ingress 资源在同一命名空间中的服务。langsmith-agents 中的智能体 Pod 对于 langsmith 中的 Ingress 是不可见的。Envoy 网关和 Istio 都通过 Kubernetes Gateway API 支持跨命名空间路由。
ALB 加 Envoy 网关（链式）
当现有 ALB 已提供 SSO（Okta 或 Cognito OIDC）、WAF 和 TLS 时，Envoy 网关会插在它后面而不是替换它：helm/values/examples/langsmith-values-ingress-envoy-gateway.yaml。
TLS 和 DNS
tls_certificate_source 变量控制证书策略：
为什么 ACM 与 cert-manager 不同
ACM 证书不可导出。AWS 将它们直接附加到 ALB，这使得 ACM 在 TLS 在 ALB 处终止时成为正确选择。当 TLS 在集群内终止（Istio Gateway, Envoy Gateway）时，无法使用 ACM，因为这些网关需要将证书材料作为 Kubernetes Secret。letsencrypt 源是 ALB 路径的参考实现：它安装了带有绑定到 ALB 入口类的 Let’s Encrypt HTTP-01 ClusterIssuer 的 cert-manager。对于 Istio 或 Envoy 上的集群内 TLS，请改用设置 create_cert_manager_irsa = true，这将使用通过 Route 53 验证的 DNS-01 ClusterIssuer。HTTP-01（通过 ALB）和 DNS-01（通过 Route 53）是互斥的。在生产环境中，可将 ClusterIssuer 替换为任何兼容 cert-manager 的颁发者。
Terraform 模块预配置 cert-manager IRSA 角色和 Route 53 权限。只有
ClusterIssuer 清单会在不同颁发者之间变化。
自动配置的 DNS
当设置了langsmith_domain 且 acm_certificate_arn 为空时，Terraform 将激活 dns 模块，该模块会创建：
- 一个用于该域名的 Route 53 托管区域。
- 一个带有 DNS 验证记录的 ACM 证书。
- 一个 Route 53 别名记录，将域名指向 ALB。
langsmith_domain 并将 tls_certificate_source 设为 "none"。Terraform 会创建托管区域和证书，而不会在验证时阻塞。在您的域名注册商处委派 NS 记录，然后在后续应用中切换到 tls_certificate_source = "acm"。Terraform 将阻塞直到证书验证通过并将其接入 HTTPS 侦听器。
自带证书
直接设置acm_certificate_arn 可以跳过 dns 模块。对于集群内网关，请手动创建一个 Kubernetes TLS Secret，并在 Gateway 或 VirtualService 中引用它。
模块依赖关系图
可选安全模块
默认资源大小
有关生产环境规模调整建议，请参见扩展指南和 AWS 部署指南。
已验证的行为和已知约束
这些约束在 2026 年 4 月的网关排列测试运行期间得到了验证。验证命令
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.