Azure 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` 步骤可以从任何执行主机运行。在生产环境中，填入运维和 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 代理 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 灵活服务器（专用 VNet）。`in-cluster` 使用 Helm chart 管理的 Postgres Pod（仅适用于开发/演示）。
`redis_source`	`external`	否	`external` 配置 Azure 托管 Redis（专用 VNet）。`in-cluster` 使用 Helm chart 管理的 Redis Pod（仅适用于开发/演示）。
`clickhouse_source`	`in-cluster`	否	`in-cluster`（仅适用于开发/POC）或使用 LangChain 托管 ClickHouse 的 `external`，生产环境推荐。

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 跨可用区冗余高可用的备用可用区。留空则禁用 HA 备用。

Redis

变量	默认值	必需	描述
`amr_sku`	`Balanced_B0`	否	Azure 托管 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 运行器）。

密钥保管库

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

入口

变量	默认值	必需	描述
`ingress_controller`	`nginx`	否	入口控制器：`nginx`、`istio`（自管理 Helm）、`istio-addon`（Azure 托管的 Istio，Azure 上推荐）、`agic`（应用程序网关入口控制器）、`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"]`	否	应用程序网关专用子网的 CIDR。必须为 `/24` 或更大。仅当 `ingress_controller = "agic"` 时使用。
`agw_sku_tier`	`Standard_v2`	否	应用程序网关 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`	`""`	否	入口负载均衡器的公共 IP，供 DNS 模块用于 A 记录。通过 `kubectl get svc -n ingress-nginx` 获取。

DNS 和 TLS

变量	默认值	必需	描述
`dns_label`	`""`	否	入口负载均衡器的 Azure 公共 IP DNS 标签。结果为 `<label>.<region>.cloudapp.azure.com`。适用于 nginx、istio、istio-addon 和 envoy-gateway。留空则跳过。
`langsmith_domain`	`""`	否	LangSmith 的自定义主机名（例如 `langsmith.example.com`）。用于 Helm values 和入口 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 存储配置工作负载标识作用域。
`langsmith_release_name`	`langsmith`	否	Helm release 名称。用于工作负载标识联合凭据主体。
`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 覆盖层。

变量	默认值	必需	描述
`sizing_profile`	`production`	否	Helm 规模覆盖层：`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 加上机器人防护）。创建后附加到应用程序网关或 Front Door。
`waf_mode`	`Prevention`	否	WAF 执行模式：`Detection`（仅记录）或 `Prevention`（阻止）。
`create_diagnostics`	`false`	否	部署 Log Analytics 工作区以及 AKS、密钥保管库和 PostgreSQL 的诊断设置。
`log_retention_days`	`90`	否	Log Analytics 工作区保留期（天）。
`create_bastion`	`false`	否	部署一个跳板机，用于通过 `az ssh vm` 私有访问 AKS。
`bastion_vm_size`	`Standard_B2s`	否	跳板主机的 VM 规格。
`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`	用于基本身份验证会话的 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 密钥。绝对不能更改。

应用模块变量（Terraform 路径）

Terraform 路径（make init-app 然后 make apply-app）在 Terraform state 中管理 LangSmith Helm release、其 Kubernetes Secret 和工作负载标识 ServiceAccount，而不是通过 Helm shell 脚本。其变量位于 app/terraform.tfvars 中。可以使用此路径作为 make init-values && make deploy 的替代方案。有关何时选择此路径，请参考 Azure 部署指南。 make init-app 会自动从基础设施模块输出中填充基础设施传递变量（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，并在计划阶段因前置条件错误（指出缺少什么）而失败。仅当针对单独配置的基础设施运行应用模块时才覆盖它们。在 app/terraform.tfvars 中设置以下内容：

变量	默认值	必需	描述
`sizing`	`production`	否	资源规模配置文件：`production`、`production-large`、`dev` 或 `none`（chart 默认值）。
`postgres_source`	`external`	否	`external`（Azure Database for PostgreSQL）或 `in-cluster`（Helm）。请与基础设施的值保持一致。
`redis_source`	`external`	否	`external`（Azure 托管 Redis）或 `in-cluster`（Helm）。请与基础设施的值保持一致。
`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 升级，即使 values 未更改。
`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`	否	代理部署端点是否使用 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。

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

核心

网络

AKS

数据源

PostgreSQL

Redis

Blob 存储

密钥保管库

入口

DNS 和 TLS

LangSmith 应用

规模和附加组件标志

安全和审计

敏感变量（通过 `setup-env.sh` 设置）

应用模块变量（Terraform 路径）

​核心

​网络

​AKS

​数据源

​PostgreSQL

​Redis

​Blob 存储

​密钥保管库

​入口

​DNS 和 TLS

​LangSmith 应用

​规模和附加组件标志

​安全和审计

​敏感变量（通过 setup-env.sh 设置）

​应用模块变量（Terraform 路径）

核心

网络

AKS

数据源

PostgreSQL

Redis

Blob 存储

密钥保管库

入口

DNS 和 TLS

LangSmith 应用

规模和附加组件标志

安全和审计

敏感变量（通过 `setup-env.sh` 设置）

应用模块变量（Terraform 路径）