GCP Terraform 变量参考

GCP GKE 上自托管 LangSmith 的 Terraform 变量完整参考。

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

变量分为两类：

• 非敏感（区域、规模、功能标志）：在 infra/terraform.tfvars 中设置。
• 敏感（许可证密钥、密码、加密密钥）：通过 infra/scripts/setup-env.sh 获取，该脚本将它们写入 Google Secret Manager，并为 Terraform 和 Helm 步骤导出。

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

核心

变量	默认值	必填	描述
project_id	—	是	创建资源的 GCP 项目 ID。
region	us-west2	否	区域资源的 GCP 区域。
zone	us-west2-a	否	可用区资源的 GCP 可用区。
environment	prod	否	应用于标签的环境名称：dev、staging 或 prod。
name_prefix	ls	否	所有资源名称的前缀。1 到 11 个字符，以小写字母开头；仅限小写字母、数字和连字符。
unique_suffix	true	否	在资源名称后追加随机后缀。多租户项目推荐使用。
owner	platform-team	否	应用于所有资源的所有者标签。
cost_center	""	否	用于计费归因的成本中心标签。
labels	{}	否	应用于所有资源的其他标签。

网络

变量	默认值	必填	描述
subnet_cidr	10.0.0.0/20	否	GKE 子网的 CIDR。不得与现有范围重叠。
pods_cidr	10.4.0.0/14	否	GKE pod 的 CIDR。不得与子网或服务范围重叠。
services_cidr	10.8.0.0/20	否	GKE 服务的 CIDR。不得与子网或 pod 范围重叠。
gke_master_authorized_cidrs	[]	否	允许访问 GKE 控制平面端点的外部 CIDR。空值会使控制平面可公开访问，以便 Terraform 管理的 Helm 和 kubectl 步骤可从任何应用主机运行。生产环境请填入操作员和 CI 出口 CIDR。

GKE

变量	默认值	必填	描述
gke_use_autopilot	false	否	使用 GKE Autopilot 模式。Autopilot 始终使用 Dataplane V2。
gke_node_count	2	否	每个区域的初始节点数（仅标准模式）。
gke_min_nodes	2	否	自动扩缩容时每个区域的最小节点数。
gke_max_nodes	10	否	自动扩缩容时每个区域的最大节点数。
gke_machine_type	e2-standard-4	否	GKE 节点机器类型（例如 e2-standard-4、n2-standard-8）。
gke_disk_size	100	否	节点磁盘大小（GB）。
gke_release_channel	REGULAR	否	GKE 发布通道：RAPID、REGULAR 或 STABLE。
gke_deletion_protection	true	否	在 GKE 集群上启用删除保护。
gke_network_policy_provider	DATA_PLANE_V2	否	网络策略提供程序：CALICO（旧版）或 DATA_PLANE_V2（基于 Cilium，推荐）。

PostgreSQL (Cloud SQL)

变量	默认值	必填	描述
postgres_source	external	否	external（具有私有 IP 的 Cloud SQL）或 in-cluster（通过 Helm 部署）。
postgres_version	POSTGRES_15	否	Cloud SQL PostgreSQL 版本。
postgres_tier	db-custom-2-8192	否	Cloud SQL 机器层级（例如 db-f1-micro、db-custom-2-8192）。
postgres_disk_size	50	否	Cloud SQL 磁盘大小（GB）。
postgres_high_availability	true	否	启用 Cloud SQL HA（区域备用）。
postgres_deletion_protection	true	否	在 Cloud SQL 上启用删除保护。
postgres_database_flags	见描述	否	在 Cloud SQL 实例上设置的数据库标志。默认为 max_connections = 500 以及检查点和连接日志标志。
postgres_ssl_mode	ENCRYPTED_ONLY	否	Cloud SQL SSL 强制。ENCRYPTED_ONLY 要求每个连接使用 TLS。ALLOW_UNENCRYPTED_AND_ENCRYPTED 接受明文。TRUSTED_CLIENT_CERTIFICATE_REQUIRED 还要求客户端证书。
postgres_password	""	当 external 时	Cloud SQL 密码。通过 TF_VAR_postgres_password 设置，或由 setup-env.sh 存储在 Secret Manager 中。

Redis (Memorystore)

变量	默认值	必填	描述
redis_source	external	否	external（具有私有 IP 的 Memorystore）或 in-cluster（通过 Helm 部署）。
redis_version	REDIS_7_0	否	Memorystore Redis 版本。
redis_memory_size	5	否	Memorystore Redis 内存大小（GB）。
redis_high_availability	true	否	启用 Memorystore HA（标准 HA 层级）。
redis_prevent_destroy	false	否	防止意外 Terraform 销毁 Redis 实例。

ClickHouse

变量	默认值	必填	描述
clickhouse_source	in-cluster	否	in-cluster（仅开发/POC）、langsmith-managed（生产环境推荐）或 external（自托管）。
clickhouse_host	""	当 managed 或 external 时	ClickHouse 主机。
clickhouse_port	9440	否	ClickHouse 原生协议端口（TLS 使用 9440，非 TLS 使用 9000）。
clickhouse_http_port	8443	否	ClickHouse HTTP 端口（TLS 使用 8443，非 TLS 使用 8123）。
clickhouse_user	default	否	ClickHouse 用户名。
clickhouse_password	""	当 managed 或 external 时	ClickHouse 密码。
clickhouse_database	default	否	ClickHouse 数据库名称。
clickhouse_tls	true	否	为 ClickHouse 连接启用 TLS。
clickhouse_ca_cert	""	否	用于 TLS 验证的 ClickHouse CA 证书（PEM）。空值使用系统 CA。

GCS 存储

变量	默认值	必填	描述
storage_ttl_short_days	14	否	ttl_s/ 前缀的 GCS TTL 天数。
storage_ttl_long_days	400	否	ttl_l/ 前缀的 GCS TTL 天数。
storage_force_destroy	false	否	即使桶内有对象也允许删除桶。请谨慎使用。

LangSmith 应用

变量	默认值	必填	描述
langsmith_namespace	langsmith	否	LangSmith 的 Kubernetes 命名空间。
langsmith_domain	langsmith.example.com	否	LangSmith 的完全限定域名。
langsmith_license_key	""	否	许可证密钥。使用 TF_VAR_langsmith_license_key。
langsmith_helm_chart_version	""	否	建议的 chart 版本，作为 Terraform 输出公开。部署脚本通过 CHART_VERSION 环境变量固定 chart 行（默认 ~0.15.1，最新的 0.15.x 补丁）。导出 CHART_VERSION 以覆盖。

Ingress 和 TLS

变量	默认值	必填	描述
install_ingress	true	否	通过 Terraform 安装 ingress controller。Gateway 仅支持 HTTPS，因此 tls_certificate_source 必须为 letsencrypt 或 existing。
ingress_type	envoy	否	Ingress 类型：envoy（已实现），或 istio / other（保留）。
tls_certificate_source	none	否	none、letsencrypt（通过 cert-manager 自动）或 existing（提供你自己的证书）。
install_cert_manager	false	否	为 Let's Encrypt 证书安装 cert-manager。
letsencrypt_email	""	当 letsencrypt 时	Let's Encrypt 通知邮箱。
tls_certificate_crt	""	当 existing 时	TLS 证书（PEM）。使用 file() 加载。
tls_certificate_key	""	当 existing 时	TLS 私钥（PEM）。使用 file() 加载。
tls_secret_name	langsmith-tls	否	Kubernetes 中 TLS secret 的名称。

KEDA

变量	默认值	必填	描述
enable_langsmith_deployment	true	否	安装 KEDA，以对 LangSmith worker 进行队列驱动的自动扩缩容。这是 KEDA 安装开关，不是 LangSmith Deployment 功能（请参阅 enable_deployments）。

可选的 GCP 模块

变量	默认值	必填	描述
enable_gcp_iam_module	true	否	连接 modules/iam，用于 Workload Identity 和桶 IAM 绑定。
enable_secret_manager_module	false	否	连接 modules/secrets，将生成的引导凭据存储在 Secret Manager 中。
enable_dns_module	false	否	连接 modules/dns，用于 Cloud DNS 和托管证书。
dns_create_zone	true	否	启用 DNS 模块时创建新的 Cloud DNS 托管区域。
dns_existing_zone_name	""	当 !dns_create_zone 时	要使用的现有 Cloud DNS 区域。
dns_create_certificate	true	否	启用 DNS 模块时创建 Google 管理的 SSL 证书。

规模和功能标志

app Terraform 层和 Helm 部署脚本会读取这些标志，以启用匹配的 chart 组件并配置按功能划分的数据库。sizing_profile 由部署脚本读取，用于选择 Helm 规模 overlay。

变量	默认值	必填	描述
sizing_profile	default	否	Helm 规模：production（~20 个用户，~100 条追踪/秒）、production-large（~50 个用户，~1000 条追踪/秒）、dev（单副本）、minimum（成本停泊下限，不用于生产）或 default（chart 默认值）。
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_fleet	false	否	启用 Fleet 独立部署（chart v0.15+）。不需要 enable_deployments。从 enable_agent_builder 迁移时复用 langsmith_agent_builder_encryption_key。
enable_standalone_polly	false	否	启用 Polly 独立部署（chart v0.15+）。不需要 enable_deployments。复用 langsmith_polly_encryption_key。
enable_standalone_insights	false	否	启用 Insights 独立部署（chart v0.15+）。不需要 enable_deployments。复用 langsmith_insights_encryption_key。
enable_usage_telemetry	false	否	启用扩展使用遥测报告（PHONE_HOME_USAGE_REPORTING_ENABLED）。

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

获取 infra/scripts/setup-env.sh 会将这些值写入 Google Secret Manager，并为 Terraform 和 Helm 步骤将它们导出到当前 shell。切勿在 terraform.tfvars 中内联设置这些值。

变量	描述
langsmith_license_key	LangSmith 企业许可证密钥。
langsmith_admin_password	初始组织管理员密码。
langsmith_api_key_salt	用于哈希 API 密钥的盐。首次部署后必须保持稳定。
langsmith_jwt_secret	用于 Basic Auth 会话的 JWT 密钥。必须保持稳定。
langsmith_deployments_encryption_key	用于 LangSmith Deployment 的 Fernet 密钥。绝不能更改。
langsmith_agent_builder_encryption_key	用于 Agent Builder 的 Fernet 密钥。绝不能更改。
langsmith_insights_encryption_key	用于 Insights 的 Fernet 密钥。绝不能更改。
langsmith_polly_encryption_key	用于 Polly 的 Fernet 密钥。绝不能更改。

---