AWS Terraform 变量参考

AWS EKS 上自托管 LangSmith 的 Terraform 变量完整参考。

完整参考 AWS Terraform 模块公开的每个输入变量。在首次填写 terraform.tfvars 或调整现有部署时使用它。

变量分为两类：

• 非敏感（区域、规模、功能标志）：在 infra/terraform.tfvars 中设置。
• 敏感（许可证密钥、密码、加密密钥）：通过 infra/scripts/setup-env.sh 获取，该脚本将它们写入 AWS SSM Parameter Store；然后 External Secrets Operator 将它们同步到集群中。

有关端到端安装，请参阅部署指南。有关模块如何组合在一起，请参阅架构参考。

核心

变量	默认值	必填	描述
name_prefix	—	是	所有资源名称的前缀。最多 15 个字符：小写字母、数字和连字符，以字母开头。格式：{prefix}-{environment}-{resource}。
environment	dev	否	环境标签：dev、staging、prod、test 或 uat。
region	us-west-2	否	所有资源的 AWS 区域。
owner	""	否	负责部署的团队或个人。作为标签应用。
cost_center	""	否	成本中心或计费标签。非空时作为标签应用。
tags	{}	否	应用于所有资源的其他标签。

网络

变量	默认值	必填	描述
create_vpc	true	否	创建新的 VPC。设置为 false 以使用现有 VPC。
vpc_id	null	当 !create_vpc 时	现有 VPC ID。
private_subnets	[]	当 !create_vpc 时	现有私有子网 ID。
public_subnets	[]	当 !create_vpc 时	现有公有子网 ID。
vpc_cidr_block	null	当 !create_vpc 时	现有 VPC CIDR 块。
vpc_private_subnets	[]	否	当 create_vpc = true 时覆盖私有子网的 CIDR。空值使用模块默认值。
vpc_public_subnets	[]	否	当 create_vpc = true 时覆盖公有子网的 CIDR。空值使用模块默认值。

EKS

变量	默认值	必填	描述
enable_public_eks_cluster	true	否	启用公共 EKS API 端点。设置为 false 以使用私有集群，并启用 create_bastion 以通过 SSM 从堡垒机运行 Terraform 和 Helm。
eks_public_access_cidrs	["0.0.0.0/0"]	否	允许访问公共 EKS API 端点的 CIDR。限制为公司 VPN 出口 CIDR 以锁定访问。
eks_cluster_version	1.33	否	EKS Kubernetes 版本。
eks_managed_node_group_defaults	{ami_type = "AL2023_x86_64_STANDARD"}	否	应用于所有托管节点组的默认配置。
eks_managed_node_groups	一个 default 组：m5.4xlarge，最小 3 / 最大 10	否	托管节点组定义。省略时 desired_size 默认为 min_size。
create_gp3_storage_class	true	否	创建 gp3 并将其设置为默认 StorageClass，启用卷扩展。
eks_cluster_enabled_log_types	["api", "audit", "authenticator", "controllerManager", "scheduler"]	否	发送到 CloudWatch 的 EKS 控制平面日志类型。设置为 [] 以禁用。
eks_addons	{}	否	EKS 托管附加组件配置（coredns、kube-proxy、vpc-cni 等）。
create_langsmith_irsa_role	true	否	为 LangSmith pod 创建 IRSA 角色（S3 访问）。

PostgreSQL (RDS)

变量	默认值	必填	描述
postgres_source	external	否	external（具有私有访问权限的 RDS）或 in-cluster（通过 Helm 部署）。
postgres_instance_type	db.t3.large	否	RDS 实例类。
postgres_storage_gb	10	否	初始 RDS 存储大小（GB）。
postgres_max_storage_gb	100	否	最大 RDS 存储大小（GB，自动扩缩容）。
postgres_username	langsmith	否	RDS 数据库用户名。
postgres_engine_version	16	否	PostgreSQL 引擎版本。PG 14 将于 2026 年 11 月达到 EOL；新部署建议使用 16。
postgres_password	""	当 external 时	RDS 密码。通过 TF_VAR_postgres_password 设置，或由 setup-env.sh 自动生成并存储在 SSM 中。
postgres_iam_database_authentication_enabled	true	否	在 RDS 上启用 IAM 数据库身份验证。
postgres_iam_database_user	null	否	用于 IAM 身份验证的数据库用户。必须在 PostgreSQL 中存在，并具有 GRANT rds_iam TO <user>。
postgres_deletion_protection	true	否	防止意外删除 RDS。开发/测试环境可设置为 false。
postgres_backup_retention_period	7	否	保留自动 RDS 备份的天数。0 禁用备份。

Redis (ElastiCache)

变量	默认值	必填	描述
redis_source	external	否	external（具有私有访问权限的 ElastiCache）或 in-cluster（通过 Helm 部署）。
redis_instance_type	cache.m6g.xlarge	否	ElastiCache 节点类型。
redis_auth_token	""	当 external 时	ElastiCache 认证 token。由 setup-env.sh 自动生成并存储在 SSM 中。通过 TF_VAR_redis_auth_token 设置。

S3

变量	默认值	必填	描述
s3_ttl_enabled	true	否	启用 S3 生命周期规则以使追踪 blob 过期。
s3_ttl_short_days	14	否	短生命周期对象（ttl_s/ 前缀）过期前的天数。
s3_ttl_long_days	400	否	长生命周期对象（ttl_l/ 前缀）过期前的天数。
s3_kms_key_arn	""	否	用于 S3 加密的 KMS CMK ARN。空值使用 SSE-S3 (AES256)。
s3_versioning_enabled	false	否	启用 S3 桶版本控制。由于保留先前版本，会增加存储成本。

TLS 和 DNS

变量	默认值	必填	描述
tls_certificate_source	acm	否	TLS 来源：acm、letsencrypt（通过 ALB 解决的 cert-manager HTTP-01 ACME）或 none。对于通过 Route 53（集群内网关）的 DNS-01 挑战，请改用 create_cert_manager_irsa；二者互斥。
acm_certificate_arn	""	当 acm 时	现有 ACM 证书 ARN。
letsencrypt_email	""	当 letsencrypt 时	Let's Encrypt ACME 注册邮箱。
langsmith_domain	""	否	自定义域名。设置后（且 acm_certificate_arn 为空），会配置 Route 53 托管区域、ACM 证书和别名记录。空值使用 ALB 主机名。
dns_include_wildcard_san	false	否	向 ACM 证书添加通配符 SAN（*.<langsmith_domain>）。子域上的 HTTPS 需要此项。
langsmith_namespace	langsmith	否	LangSmith 的 Kubernetes 命名空间。

Ingress

变量	默认值	必填	描述
alb_scheme	internet-facing	否	ALB 方案：internet-facing（公有子网）或 internal（私有子网，可通过 VPN、对等连接或 PrivateLink 访问）。
alb_allowed_cidr_blocks	["0.0.0.0/0"]	否	允许通过 HTTP/HTTPS 访问 ALB 的 CIDR。对于受限访问部署，限制为 VPN 或办公 CIDR。
alb_access_logs_enabled	false	否	启用 ALB 访问日志，写入专用 S3 桶。
enable_envoy_gateway	false	否	安装 Envoy Gateway（Kubernetes Gateway API）而不是 ALB Ingress。多命名空间数据平面部署需要此项。
enable_nginx_ingress	false	否	安装 NGINX ingress controller。ALB 通过 TargetGroupBinding 将流量转发到 NGINX controller pod。
enable_istio_gateway	false	否	在节点安全组上打开端口 15017，用于 istiod sidecar-injector webhook。在 EKS 上运行 Istio 时需要此项。
istio_nlb_scheme	internet-facing	否	Istio ingress gateway NLB 的方案：internet-facing 或 internal。由设置向导写入 tfvars，但尚未被任何模块使用；Istio 路径目前使用 ALB TargetGroupBinding 后面的 ClusterIP 服务。
create_cert_manager_irsa	false	否	为通过 Route 53 的 cert-manager DNS-01 挑战创建 IRSA 角色。使用 Istio Gateway 的 Let's Encrypt 需要此项。应用后运行 make tls。
cert_manager_hosted_zone_id	""	当 create_cert_manager_irsa 时	用于 cert-manager DNS-01 TXT 记录的 Route 53 托管区域 ID。

ClickHouse

变量	默认值	必填	描述
clickhouse_source	in-cluster	否	in-cluster（仅开发/POC）或 external（LangChain 托管 ClickHouse，生产环境推荐）。

Bastion（私有集群）

变量	默认值	必填	描述
create_bastion	false	否	在公有子网中创建 EC2 堡垒机，用于通过 SSM Session Manager 或 SSH 访问私有集群。
bastion_instance_type	t3.micro	否	堡垒机的 EC2 实例类型。
bastion_key_name	null	否	用于 SSH 的 EC2 密钥对。空值仅使用 SSM Session Manager。
bastion_enable_ssh	false	否	在堡垒机安全组上打开端口 22。
bastion_ssh_allowed_cidrs	[]	否	允许 SSH 到堡垒机的 CIDR。仅在 bastion_enable_ssh = true 时使用。
bastion_root_volume_size_gb	20	否	堡垒机根 EBS 卷大小（GB）。

安全和审计

变量	默认值	必填	描述
create_cloudtrail	false	否	创建 CloudTrail 追踪，将 AWS API 调用记录到 S3。如果已存在账户级或组织级追踪，请跳过。
cloudtrail_multi_region	true	否	记录所有区域的 API 调用。
cloudtrail_log_retention_days	365	否	在 S3 中保留 CloudTrail 日志的天数。0 表示无限期保留。
create_waf	false	否	将 WAFv2 Web ACL 附加到 ALB（AWS 托管规则，用于 OWASP Top 10、IP 信誉、错误输入）。成本：基础费用约 $8 到 $10/月。
create_firewall	false	否	部署 AWS Network Firewall 以进行基于 FQDN 的出口过滤。需要 create_vpc = true。成本：每个端点约 $0.395/hr 加上 $0.065/GB。
firewall_allowed_fqdns	["beacon.langchain.com"]	否	当 create_firewall = true 时允许出站流量的域。会根据 TLS SNI 和 HTTP Host 标头进行匹配。所有其他目标都会被丢弃。
firewall_subnet_cidr	10.0.64.0/21	否	防火墙子网的 CIDR。必须在 VPC CIDR 内，且不得与私有或公有子网重叠。

规模和功能标志

sizing_profile 和大多数 enable_* 标志由 init-values.sh 和 deploy.sh 读取；Terraform 不会直接对它们执行操作。它们会影响脚本生成的 Helm overlay 文件。三个独立标志（enable_fleet、enable_standalone_polly、enable_standalone_insights）是例外：Terraform 会读取它们以创建数据库初始化 Job 和 Kubernetes secret，并对其所需的外部 Postgres 和 Redis 输入强制执行计划时前置条件。

变量	默认值	必填	描述
sizing_profile	default	否	Helm 规模：production、production-large、dev、minimum 或 default。
enable_deployments	false	否	启用 LangSmith Deployment（listener、operator、host-backend）。需要 Deployments 许可证权益。
enable_agent_builder	false	否	启用 Agent Builder。需要 enable_deployments = true 和 Agent Builder 权益。
enable_insights	false	否	启用 Insights（ClickHouse 支持的分析）。需要 Insights 权益。
enable_polly	false	否	启用 Polly（AI 评估和监控）。需要 enable_deployments = true 和 Polly 权益。
enable_usage_telemetry	false	否	启用扩展使用遥测报告。
enable_fleet	false	否	启用 Fleet 独立部署（chart v0.15+）。需要 enable_deployments = true 以及外部 Postgres 和 Redis。
enable_standalone_polly	false	否	启用 Polly 独立部署（chart v0.15+）。不需要 enable_deployments。需要外部 Postgres 和 Redis。
enable_standalone_insights	false	否	启用 Insights 独立部署（chart v0.15+）。不需要 enable_deployments。需要外部 Postgres 和 Redis。

敏感值（使用 setup-env.sh 设置）

获取 infra/scripts/setup-env.sh 会将这些值写入 AWS SSM Parameter Store。External Secrets Operator 将它们作为 Kubernetes secret 同步到集群中。这些不是声明的 Terraform 变量，不应放在 terraform.tfvars 中；只能通过 SSM 设置。

变量	描述
langsmith_license_key	LangSmith 企业许可证密钥。
langsmith_admin_password	初始组织管理员密码。至少 12 个字符，包含小写、大写和符号。
langsmith_api_key_salt	用于哈希 API 密钥的盐。首次部署后必须保持稳定。
langsmith_jwt_secret	用于 Basic Auth 会话的 JWT 密钥。必须保持稳定。
langsmith_deployments_encryption_key	用于 LangSmith Deployments 的 Fernet 密钥。绝不能更改。
langsmith_agent_builder_encryption_key	用于 Agent Builder 的 Fernet 密钥。绝不能更改。
langsmith_insights_encryption_key	用于 Insights 的 Fernet 密钥。绝不能更改。
langsmith_polly_encryption_key	用于 Polly 的 Fernet 密钥。绝不能更改。

---