Azure Terraform 变量参考

Azure AKS 上自托管 LangSmith 的 Terraform 变量完整参考。

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

变量分为两类：

• 非敏感（区域、规模、功能标志）：在 infra/terraform.tfvars 中设置。
• 敏感（许可证密钥、密码、加密密钥）：使用 make setup-env 设置，它会将它们写入 infra/secrets.auto.tfvars（被 gitignore，由 Terraform 自动加载）并存储在 Azure Key Vault 中。

有关端到端安装，请参阅部署指南。有关模块如何协同工作，请参阅架构参考。

核心

变量	默认值	必填	描述
subscription_id	—	是	部署的 Azure 订阅 ID。
location	eastus	否	部署的 Azure 区域。
identifier	""	否	附加到每个资源名称的后缀，用于区分环境（例如 -prod、-staging）。必须以连字符开头或为空。
environment	dev	否	应用于所有资源的环境标签。
owner	""	否	资源所有者的电子邮件或团队名称。作为标签应用。
cost_center	""	否	成本中心或账单代码。作为标签应用。

网络

变量	默认值	必填	描述
create_vnet	true	否	创建新的 VNet。设置为 false 以使用你自己的 VNet 和子网。
vnet_id	""	当 !create_vnet 时	现有 VNet 资源 ID。
aks_subnet_id	""	当 !create_vnet 时	AKS 集群的现有子网 ID。
postgres_subnet_id	""	当 !create_vnet 时	PostgreSQL 服务器的现有子网 ID。
redis_subnet_id	""	当 !create_vnet 时	Redis 实例的现有子网 ID。
postgres_subnet_address_prefix	["10.0.32.0/20"]	否	PostgreSQL 子网的 CIDR 前缀。可以是不相交的范围。
redis_subnet_address_prefix	["10.0.48.0/20"]	否	Redis 子网的 CIDR 前缀。可以是不相交的范围。
aks_authorized_ip_ranges	[]	否	允许访问 AKS API 服务器的外部 CIDR。为空时，API 服务器可公开访问，因此 Terraform 驱动的 Helm 和 kubectl 步骤可以从任何 apply 主机运行。生产环境请填入运维人员和 CI 出口 CIDR。

AKS

变量	默认值	必填	描述
default_node_pool_vm_size	Standard_D8s_v3	否	默认节点池的 VM 大小。Standard_D8s_v3（8 vCPU / 32 GiB）是使用外部 Postgres 和 Redis 的核心平台的推荐基线。仅对使用集群内数据库的轻量或演示部署使用 Standard_D4s_v3（4 vCPU / 16 GiB）。
default_node_pool_min_count	1	否	默认池的最小节点数。自动扩缩器永远不会缩减到此下限以下。生产环境设置为 3（核心平台需要约 14.4 vCPU，三个 Standard_D8s_v3 节点即可覆盖）。最小或开发部署设置为 1。
default_node_pool_max_count	10	否	默认池的最大节点数。核心平台使用 4 到 6 个节点；启用附加组件时增加余量（LangSmith Deployment ~6，Agent Builder ~8，Insights 10 到 12）。提高此值会立即生效，无需重启节点。
default_node_pool_max_pods	60	否	默认池中每个节点的最大 pod 数。Azure CNI 默认值 30 对 LangSmith 来说太低；60 可以在单个节点上容纳完整部署。不可变：更改它会重新创建节点池。
additional_node_pools	large: Standard_D16s_v3, 0–2	否	附加节点池。默认 large 池（Standard_D16s_v3，16 vCPU / 64 GiB）是 ClickHouse（请求 3.5 vCPU / 15 GiB）和 LangSmith Deployment agent pod 所必需的。min_count = 0 会在空闲时将其缩容到零。对于具有多个同时部署的 Agent Builder，将 max_count 提高到 3 或更多。
aks_service_cidr	10.0.64.0/20	否	Kubernetes 服务 CIDR。不得与 VNet 重叠。
aks_dns_service_ip	10.0.64.10	否	CoreDNS 服务 IP。必须在 aks_service_cidr 内。
aks_deletion_protection	true	否	防止意外删除 AKS 集群。开发/测试设置为 false。
availability_zones	["1"]	否	要部署到的可用区。使用 ["1", "2", "3"] 实现区域冗余高可用性。

数据源

变量	默认值	必填	描述
postgres_source	external	否	external 预配 Azure Database for PostgreSQL Flexible Server（私有 VNet）。in-cluster 使用 chart 管理的 Postgres pod（仅开发/演示）。
redis_source	external	否	external 预配 Azure Managed Redis（私有 VNet）。in-cluster 使用 chart 管理的 Redis pod（仅开发/演示）。
clickhouse_source	in-cluster	否	in-cluster（仅开发/POC）或 external 使用 LangChain Managed ClickHouse，生产环境推荐。

PostgreSQL

变量	默认值	必填	描述
postgres_admin_username	langsmith	否	PostgreSQL 管理员用户名。
postgres_admin_password	""	当外部时	PostgreSQL 管理员密码。通过 make setup-env 设置。
postgres_database_name	langsmith	否	LangSmith 连接的数据库名称。必须与服务器上存在的数据库匹配。
postgres_deletion_protection	true	否	防止意外删除 PostgreSQL 服务器。开发/测试设置为 false。
postgres_geo_redundant_backup	false	否	为 PostgreSQL 启用异地冗余备份。
postgres_standby_availability_zone	""	否	PostgreSQL 区域冗余高可用性的备用可用区。为空则禁用高可用备用。

Redis

变量	默认值	必填	描述
amr_sku	Balanced_B0	否	Azure Managed Redis SKU。Balanced_B0 是最小的。如果区域报告 AllocationFailed，请向上调整（Balanced_B1、Balanced_B3 等）。替代经典的 redis_capacity。

Blob 存储

变量	默认值	必填	描述
blob_ttl_enabled	true	否	在 blob 容器上启用生命周期 TTL 规则。
blob_ttl_short_days	14	否	短期追踪 blob 的 TTL（天）。
blob_ttl_long_days	400	否	长期追踪 blob 的 TTL（天）。
storage_allowed_ips	[]	否	允许通过存储账户默认拒绝防火墙的公共 IP 或 CIDR。AKS pod 流量会通过 Microsoft.Storage 服务终结点自动加入允许列表。仅添加需要 blob 数据平面的外部客户端（运维工作站、CI runner）。

Key Vault

变量	默认值	必填	描述
keyvault_name	""	否	Key Vault 名称。必须全局唯一，3 到 24 个字符。为空时，main.tf 会计算 langsmith-kv<identifier>。覆盖以避免命名冲突。
keyvault_purge_protection	true	否	启用清除保护。开发/测试设置为 false，以允许销毁后立即重用名称。
keyvault_default_action	Allow	否	Key Vault 数据平面防火墙的默认操作。Allow 可保持首次 apply（通过数据平面创建密钥）正常工作。生产环境设置为 Deny 并填充 keyvault_allowed_ips。
keyvault_allowed_ips	[]	否	当 keyvault_default_action = "Deny" 时，允许通过 Key Vault 防火墙的公共 IP 或 CIDR。AKS 子网会通过 Microsoft.KeyVault 服务终结点自动加入允许列表。

Ingress

变量	默认值	必填	描述
ingress_controller	nginx	否	Ingress 控制器：nginx、istio（自管理 Helm）、istio-addon（Azure 托管 Istio，Azure 上推荐）、agic（Application Gateway Ingress Controller）、envoy-gateway（Gateway API）或 none。有关 TLS 兼容性矩阵，请参阅 INGRESS_CONTROLLERS.md。
istio_version	1.29.1	否	Istio Helm chart 版本。仅在 ingress_controller = "istio" 时使用。
istio_addon_revision	asm-1-27	否	Azure Service Mesh 修订版（asm-1-<minor>）。使用 az aks mesh get-upgrades 列出可用修订版。仅在 ingress_controller = "istio-addon" 时使用。
agic_subnet_address_prefix	["10.0.96.0/24"]	否	Application Gateway 专用子网的 CIDR。必须为 /24 或更大。仅在 ingress_controller = "agic" 时使用。
agw_sku_tier	Standard_v2	否	Application Gateway SKU 层级：Standard_v2 或 WAF_v2（启用 WAF）。仅在 ingress_controller = "agic" 时使用。
envoy_gateway_version	v1.2.0	否	Envoy Gateway Helm chart 版本。仅在 ingress_controller = "envoy-gateway" 时使用。
ingress_ip	""	否	Ingress 负载均衡器的公共 IP，DNS 模块用于 A 记录。使用 kubectl get svc -n ingress-nginx 获取。

DNS 和 TLS

变量	默认值	必填	描述
dns_label	""	否	Ingress 负载均衡器的 Azure 公共 IP DNS 标签。结果为 <label>.<region>.cloudapp.azure.com。适用于 nginx、istio、istio-addon 和 envoy-gateway。为空则跳过。
langsmith_domain	""	否	LangSmith 的自定义主机名（例如 langsmith.example.com）。用于 Helm values 和 ingress TLS。优先于 dns_label。
tls_certificate_source	letsencrypt	否	letsencrypt（通过 cert-manager 的 HTTP-01）、dns01（通过 cert-manager 的 DNS-01）、existing（自带证书）或 none（仅 HTTP，演示/开发）。
letsencrypt_email	""	当 letsencrypt 或 dns01 时	用于 Let's Encrypt 证书通知的电子邮件。
create_dns_zone	false	否	为 LangSmith 域创建 Azure DNS 区域和 A 记录。DNS-01 签发所必需。

LangSmith 应用

变量	默认值	必填	描述
langsmith_namespace	langsmith	否	LangSmith 的 Kubernetes 命名空间。用于限定 blob 存储的 Workload Identity 作用域。
langsmith_release_name	langsmith	否	Helm release 名称。用于 Workload Identity 联合凭据主体。
langsmith_domain	""	否	请参阅 DNS 和 TLS。
langsmith_helm_chart_version	""	否	固定 chart 版本以实现可复现部署。部署脚本的优先级是 CHART_VERSION 环境变量，然后是此变量，最后是固定行默认值 ~0.15.1（最新的 0.15.x 补丁）。
langsmith_admin_email	""	否	初始组织管理员电子邮件（Helm values 中的 initialOrgAdminEmail）。通过 make setup-env 设置。

规模和附加组件标志

init-values.sh 和 deploy.sh 读取这些标志；Terraform 会忽略它们。它们控制脚本生成哪些 Helm overlay。

变量	默认值	必填	描述
sizing_profile	production	否	Helm 规模 overlay：minimum、dev、production 或 production-large。
enable_deployments	false	否	启用 LangSmith Deployment（host-backend、listener、operator）。
enable_agent_builder	false	否	启用 Agent Builder UI。需要 enable_deployments = true。
enable_insights	false	否	启用 Insights（由 ClickHouse 支持的分析）。需要 enable_deployments = true。
enable_polly	false	否	启用 Polly（AI 评估和监控）。需要 enable_deployments = true。

安全和审计

变量	默认值	必填	描述
create_waf	false	否	部署 Azure WAF 策略（OWASP 3.2 加机器人保护）。创建后附加到 Application Gateway 或 Front Door。
waf_mode	Prevention	否	WAF 强制模式：Detection（仅记录）或 Prevention（阻止）。
create_diagnostics	false	否	为 AKS、Key Vault 和 PostgreSQL 部署 Log Analytics 工作区和诊断设置。
log_retention_days	90	否	Log Analytics 工作区保留天数。
create_bastion	false	否	部署一个跳板 VM，用于通过 az ssh vm 访问私有 AKS。
bastion_vm_size	Standard_B2s	否	堡垒主机的 VM SKU。
bastion_admin_ssh_public_key	""	否	用于紧急管理员访问堡垒主机的 SSH 公钥。
bastion_allowed_ssh_cidrs	["0.0.0.0/0"]	否	允许入站 SSH 到堡垒主机的 CIDR。生产环境限制为 VPN 或企业范围。

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

make setup-env 会将这些写入 secrets.auto.tfvars，Terraform 会将它们存储在 Azure Key Vault 中。切勿在 terraform.tfvars 中内联设置这些变量。

make setup-env 还管理 postgres_admin_password 和 langsmith_admin_email，记录在 PostgreSQL 和 LangSmith 应用部分。此表仅列出本参考中未出现在其他位置的敏感变量。

变量	描述
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 密钥。绝不能更改。

App 模块变量（Terraform 路径）

Terraform 路径（make init-app 然后 make apply-app）在 Terraform state 中管理 LangSmith Helm release、其 Kubernetes Secret 和 Workload Identity ServiceAccount，而不是通过 Helm shell 脚本。其变量位于 app/terraform.tfvars。将此路径用作 make init-values && make deploy 的替代方案。有关何时选择此路径，请参阅 Azure 部署指南。

make init-app 会从 infra 模块输出自动填充基础设施透传变量（subscription_id、resource_group_name、cluster_name、keyvault_name、storage_account_name、storage_container_name、workload_identity_client_id、langsmith_namespace、tls_certificate_source、ingress_controller 和 dns_label）。每个变量默认为 null，并在 plan 时失败，前置条件错误会指出缺少的内容。仅当你针对单独预配的基础设施运行 app 模块时才覆盖它们。

在 app/terraform.tfvars 中设置以下内容：

变量	默认值	必填	描述
sizing	production	否	资源规模配置文件：production、production-large、dev 或 none（chart 默认值）。
postgres_source	external	否	external（Azure Database for PostgreSQL）或 in-cluster（Helm）。与 infra 值保持一致。
redis_source	external	否	external（Azure Managed Redis）或 in-cluster（Helm）。与 infra 值保持一致。
hostname	null	否	LangSmith 主机名。未设置时从 dns_label 自动检测。
admin_email	admin@example.com	否	初始组织管理员电子邮件地址。
release_name	langsmith	否	Helm release 名称。
chart_version	""	否	LangSmith Helm chart 版本。空则使用最新版本。
helm_timeout	1200	否	Helm 安装和升级超时时间（秒）。
helm_force_update	false	否	每次 apply 时强制进行 Helm 升级，即使值未更改。
enable_agent_deploys	false	否	启用 LangSmith Deployment。
enable_agent_builder	false	否	启用 Agent Builder。需要 enable_agent_deploys = true。
enable_insights	false	否	启用 Insights。需要外部 ClickHouse。
enable_polly	false	否	启用 Polly AI 评估和监控。需要 enable_agent_deploys = true。
enable_usage_telemetry	false	否	启用扩展使用遥测报告。
tls_enabled_for_deploys	null	否	agent 部署端点是否使用 HTTPS。未设置时从 tls_certificate_source 自动检测。
clickhouse_host	""	当 enable_insights 时	ClickHouse 主机名或端点。
clickhouse_port	8123	否	ClickHouse HTTP 端口。
clickhouse_database	default	否	ClickHouse 数据库名称。
clickhouse_username	default	否	ClickHouse 用户名。
clickhouse_password	""	否	ClickHouse 密码。为需要身份验证的 ClickHouse 设置。
clickhouse_tls	true	否	为 ClickHouse 连接启用 TLS。

---