用 Terraform 在 Azure 上部署 LangSmith

用 LangChain Terraform 模块在 Azure AKS 上预配自托管 LangSmith 的端到端演练。

用公开的 Terraform 模块把 LangSmith 部署到 Azure。以代码方式管理部署，让你能跨订阅为 LangSmith 环境做版本控制、审查和复现，而非在 Azure 门户里点点点。

安装分两个阶段运行：

基础设施：Terraform 预配 AKS、Postgres、Redis、Blob 存储、Key Vault、cert-manager、KEDA 和 ingress。
应用：Helm 针对集群安装 LangSmith chart。

基础安装之后，通过设置标志并重新部署来启用三个可选附加组件（LangSmith Deployment、Agent Builder，以及 Insights 和 Polly）。

%%{init: {'flowchart': {'nodeSpacing': 25, 'rankSpacing': 30}}}%%
graph TB
    subgraph stage1["Set up infrastructure"]
        direction LR
        Start["make setup-env<br/>secrets to secrets.auto.tfvars"]
        TF["terraform apply<br/>(3 stages)"]
        Infra["AKS · PostgreSQL · Redis<br/>Blob · Key Vault<br/>Managed Identity"]
        Bootstrap["Bootstrap workloads<br/>cert-manager · KEDA<br/>ingress-nginx"]
        Start --> TF --> Infra -->|AKS ready| Bootstrap
    end
    subgraph stage2["Deploy the application"]
        direction LR
        Secrets["make kubeconfig + k8s-secrets<br/>Key Vault to<br/>langsmith-config-secret"]
        Deploy["make init-values + deploy<br/>helm install langsmith"]
        DNS["deploy.sh sets dns_label<br/>+ Let's Encrypt cert"]
        Running["LangSmith running<br/>all pods healthy"]
        Secrets --> Deploy --> DNS --> Running
    end
    stage1 --> stage2

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef neutral fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33

    class Start trigger
    class TF,Bootstrap,Secrets,Deploy,DNS process
    class Infra neutral
    class Running output

    style stage1 fill:none,stroke:#40668D,stroke-width:1px
    style stage2 fill:none,stroke:#40668D,stroke-width:1px

前置条件

必需工具

工具	版本	用途
Azure CLI（`az`）	2.50	身份验证、查询 Azure 资源、管理 AKS 凭据
Terraform	1.5	运行基础设施模块
`kubectl`	最新	检查 AKS 集群
Helm	3.12	安装并管理 LangSmith chart

bash

brew install azure-cli kubectl helm
brew tap hashicorp/tap && brew install hashicorp/tap/terraform

az --version
terraform version
kubectl version --client
helm version

必需的 Azure RBAC

运行 Terraform 的身份在订阅上需要以下角色：

角色	用途
`Contributor`	创建并管理所有 Azure 资源
`User Access Administrator`	为 Key Vault、Blob、cert-manager 托管身份创建角色指派

Owner 包含两者。单独的 Contributor 不够，因为角色指派需要 User Access Administrator。

身份验证

bash

az login
az account set --subscription <your-subscription-id>
az account show

你还需要一个 LangSmith 许可密钥（联系我们的销售团队），以及一个 dns_label（Azure 子域，无需 DNS 设置）或一个自定义 langsmith_domain。

快速开始

TIP

make 目标、必需变量和常见约束的精简速查表，见 Azure 快速参考。

要从零到运行中的 LangSmith 实例走最快的路径：

bash

# 1. Clone the public modules
git clone https://github.com/langchain-ai/terraform.git
cd terraform/modules/azure

# 2. Generate terraform.tfvars interactively
make quickstart

# 3. Bootstrap secrets (writes infra/secrets.auto.tfvars, chmod 600, gitignored)
make setup-env

# 4. Validate environment
make preflight

# 5. Provision infrastructure (~15 to 20 min)
make init
make apply

# 6. Get cluster credentials and push secrets into the cluster
make kubeconfig
make k8s-secrets

# 7. Deploy LangSmith via Helm (~10 min)
make init-values
make deploy

或一次性运行步骤 5 到 7：

bash

make deploy-all   # apply → kubeconfig → k8s-secrets → init-values → deploy

下面的小节详细讲述每个阶段。

预配基础设施

Terraform 预配以下 Azure 资源：

资源	类型	用途
Resource Group	`azurerm_resource_group`	所有资源的容器
Virtual Network	`azurerm_virtual_network`	隔离网络（10.0.0.0/17）
AKS Cluster	`azurerm_kubernetes_cluster`	Kubernetes，所有工作负载在此运行
Ingress Controller	Helm	外部负载均衡器 + TLS 终止（默认 nginx）
PostgreSQL Flexible Server	`azurerm_postgresql_flexible_server`	组织配置、运行元数据（外部层级）
Azure Managed Redis	`azapi_resource`（Microsoft.Cache/redisEnterprise）	追踪摄取队列、pub/sub（外部层级）
Blob Storage	`azurerm_storage_account`	原始追踪对象，始终必需
Managed Identity	`azurerm_user_assigned_identity`	供 pod 到 Blob 认证的 Workload Identity
Azure Key Vault	`azurerm_key_vault`	存储所有 LangSmith 机密
cert-manager	Helm	自动化的 TLS 证书管理
KEDA	Helm	面向 worker 的事件驱动自动伸缩

克隆并配置

bash

git clone https://github.com/langchain-ai/terraform.git
cd terraform/modules/azure

所有后续命令都从 modules/azure/ 运行。运行 make help 查看完整目标列表。

用交互式向导生成 terraform.tfvars：

bash

make quickstart

向导运行一个 10 节的问卷，涵盖配置、订阅、命名、网络、AKS 规格、ingress 控制器、DNS/TLS、后端服务、Key Vault、规格配置和安全附加组件。每节都含解释性上下文、成本估算和取舍。重跑是安全的；现有值在每个提示处预选。按 Enter 以保留它们。

更想手动编辑：

bash

cp infra/terraform.tfvars.example infra/terraform.tfvars
vi infra/terraform.tfvars

最少必需的值：

hcl

# Identity
subscription_id = "<your-azure-subscription-id>"

# Location
location = "eastus"

# Naming + tagging
identifier  = "-prod"      # suffix on all resource names
environment = "prod"

# Deployment tier, production recommended
postgres_source   = "external"   # Azure DB for PostgreSQL
redis_source      = "external"   # Azure Managed Redis
clickhouse_source = "in-cluster" # use "external" + LangChain Managed for production

# DNS + TLS (HTTPS via Let's Encrypt on a free Azure subdomain)
dns_label              = "langsmith-prod"   # → langsmith-prod.eastus.cloudapp.azure.com
tls_certificate_source = "letsencrypt"
letsencrypt_email      = "ops@example.com"

# Sizing
sizing_profile = "production"   # minimum | dev | production | production-large

WARNING

集群内 ClickHouse 以单个 pod 运行，无复制或备份，仅限开发/POC。生产请用 LangChain Managed ClickHouse。

INFO

Blob 存储始终必需，无论层级。追踪载荷必须发到 Azure Blob，绝不发到 ClickHouse。

所有变量见 Azure 变量参考。

Bootstrap 机密

bash

make setup-env

setup-env.sh 写入 infra/secrets.auto.tfvars（已 gitignore，chmod 600）。Terraform 会自动拾取这个文件；无需 shell 导出。

首次运行： 提示填 PostgreSQL 密码、LangSmith 许可密钥、admin 密码和 admin 邮箱。在本地生成 api_key_salt、jwt_secret 和四个 Fernet 加密密钥。
后续运行： 从 Azure Key Vault 读取那六个生成的机密（api_key_salt、jwt_secret 和四个 Fernet 密钥）。除非环境中设了 LANGSMITH_PG_PASSWORD、LANGSMITH_LICENSE_KEY、LANGSMITH_ADMIN_PASSWORD 和 LANGSMITH_ADMIN_EMAIL，否则会重新提示填 PostgreSQL 密码、许可密钥、admin 密码和 admin 邮箱。

WARNING

绝不提交 secrets.auto.tfvars。它已被 gitignore。在任何机器上用 make setup-env 重新生成。

预检

bash

make preflight

验证 Azure CLI 身份验证、活动订阅、11 个必需的资源提供商、RBAC（Contributor + User Access Administrator）、terraform.tfvars 和 secrets.auto.tfvars 的存在，以及 PATH 上的 terraform/kubectl/helm。

Apply

NOTE

在一个干净的订阅上预配 Azure 云基础需要 15 到 20 分钟。不要打断 apply。

bash

make init
make apply   # ~15 to 20 min on first run

NOTE

在全新部署上跳过 make plan。kubernetes_manifest 资源在 plan 期间需要一个活动的集群 API，而它尚不存在。make apply 在三个内部阶段处理资源排序：Azure 基础设施（含 AKS）→ Kubernetes bootstrap（命名空间、机密、cert-manager、KEDA）→ ClusterIssuer 和其余清单。

集群凭据与 Kubernetes Secrets

make apply 完成后，取得集群凭据并把机密推入集群：

bash

make kubeconfig    # fetches AKS credentials, merges into ~/.kube/config
make k8s-secrets   # Key Vault → langsmith-config-secret in the langsmith namespace

make k8s-secrets 从 Key Vault 读取 8 个机密，创建或更新 langsmith-config-secret。重跑安全；用 --dry-run=client | kubectl apply 就地更新。

验证基础设施

bash

# All nodes Ready
kubectl get nodes

# Bootstrap components, all Running
kubectl get pods -n cert-manager     # 3 pods
kubectl get pods -n keda             # 3 pods
kubectl get pods -n ingress-nginx    # 2 pods (if using nginx)

# NGINX LoadBalancer, save the EXTERNAL-IP
kubectl get svc ingress-nginx-controller -n ingress-nginx

# Workload Identity ServiceAccount, should have client-id annotation
kubectl get sa langsmith-ksa -n langsmith \
  -o jsonpath='{.metadata.annotations}'

# Terraform outputs
terraform -chdir=infra output

# Key outputs consumed by Helm scripts
terraform -chdir=infra output -raw keyvault_name
terraform -chdir=infra output -raw storage_account_name
terraform -chdir=infra output -raw storage_container_name
terraform -chdir=infra output -raw storage_account_k8s_managed_identity_client_id

部署 LangSmith

使用两条受支持的部署路径之一：

路径	命令	何时使用
Helm 路径（默认）	`make init-values && make deploy`	交互式输出、kubeconfig 刷新、preflight 检查。最适合首次部署和第 2 天的重新部署。
Terraform 路径	`make init-app && make apply-app`	Helm release + Kubernetes Secrets + Workload Identity SA 管理在 Terraform 状态中。最适合 GitOps 和 CI/CD 流水线。

Helm 路径（推荐）

生成 Helm values

bash

cd terraform/modules/azure
make init-values

make init-values 读取 terraform output 和 terraform.tfvars，生成一个填好所有字段的 helm/values/values-overrides.yaml：

config.hostname，你的 FQDN（来自 dns_label 或 langsmith_domain）。
config.initialOrgAdminEmail，第一个 org admin 账户。
config.existingSecretName: langsmith-config-secret，机密引用。
config.blobStorage，存储账户名 + 容器 + Workload Identity client ID。
给 8 个 ServiceAccount（backend、platform-backend、queue、ingest-queue、host-backend、listener、agent-builder-tool-server、agent-builder-trigger-server）的 Workload Identity 注解。
Ingress + TLS 块（cert-manager 注解、TLS secret 名）。
Postgres 和 Redis 外部机密引用（当 postgres_source = "external" / redis_source = "external" 时）。

也会把规格 overlay 和任何已启用的附加组件 overlay 从 helm/values/examples/ 复制到 helm/values/。

INFO

admin 邮箱从 terraform.tfvars 中的 langsmith_admin_email（在 make setup-env 期间设置）读取，并自动写入 values-overrides.yaml。无需手动编辑。

部署

bash

make deploy   # ~10 min

make deploy 做以下事情：

验证 values-overrides.yaml 存在。
通过 az aks get-credentials 刷新 kubeconfig。
为 LoadBalancer 服务标注 service.beta.kubernetes.io/azure-dns-label-name，Azure 把 DNS 标签分配给公共 IP 需要它。
如果 tls_certificate_source = "letsencrypt"，创建 letsencrypt-prod cert-manager ClusterIssuer（幂等）。
运行 preflight 检查（工具、集群连通性、Helm 仓库）。
验证 langsmith-config-secret 存在；缺失时从 Key Vault 自动创建。
构建并记录 values 链。
在继续之前自动恢复任何卡住的 pending-upgrade Helm release。
运行 helm upgrade --install langsmith langchain/langsmith --timeout 20m。
等待核心 deployment 滚动上线。
用 Workload Identity client ID 标注 langsmith-ksa ServiceAccount。
打印访问 URL 和登录凭据的位置。

INFO

为什么是 --timeout 20m？langsmith-backend-auth-bootstrap Job 作为一个 post-install 钩子运行数据库迁移和组织初始化。首次安装这最多耗时 5 分钟。没有长超时，Helm 可能报告失败，即使安装最终会成功。

TIP

在第二个终端里观察 pod：

bash

# macOS
brew install watch
watch kubectl get pods -n langsmith

# Without watch
while true; do clear; kubectl get pods -n langsmith; sleep 3; done

如果你完成了 Helm 路径，跳到验证部署。下面的 Terraform 路径是 Helm 路径的一种替代，而非额外的步骤。

Terraform 路径

当你想把 Helm release、Kubernetes Secrets 和 Workload Identity ServiceAccount 管理在 Terraform 状态中时，用这条路径。

bash

# Copy and configure app vars
cp app/terraform.tfvars.example app/terraform.tfvars
vi app/terraform.tfvars   # set admin_email at minimum

# Pull infra outputs into app/infra.auto.tfvars.json + terraform init
make init-app

# Deploy Helm release + K8s Secrets + WI ServiceAccount via Terraform
make apply-app

app/terraform.tfvars 中的功能开关：

hcl

sizing                = "production"   # dev | production | production-large | none
enable_agent_deploys  = true           # LangSmith Deployment add-on
enable_agent_builder  = true           # Agent Builder add-on (requires agent_deploys)
enable_insights       = true           # Insights / ClickHouse add-on
enable_polly          = true           # Polly add-on (requires agent_deploys)

通过 Terraform 端到端（基础设施 + 应用）：

bash

make deploy-all-tf   # apply → init-values → init-app → apply-app

验证部署

bash

# All pods Running or Completed (~17 pods)
kubectl get pods -n langsmith

# Ingress host + TLS assigned
kubectl get ingress -n langsmith

# TLS certificate issued
kubectl get certificate -n langsmith   # READY: True

# Helm release status
helm list -n langsmith

预期的 pod 状态（约 ~5 分钟后全部 Running）：

txt

langsmith-ace-backend-xxxxx              1/1   Running     0   5m
langsmith-backend-xxxxx                  1/1   Running     0   5m
langsmith-backend-auth-bootstrap-xxxxx   0/1   Completed   0   5m
langsmith-backend-ch-migrations-xxxxx    0/1   Completed   0   5m
langsmith-backend-migrations-xxxxx       0/1   Completed   0   5m
langsmith-clickhouse-0                   1/1   Running     0   5m
langsmith-frontend-xxxxx                 1/1   Running     0   5m
langsmith-ingest-queue-xxxxx             1/1   Running     0   5m
langsmith-platform-backend-xxxxx         1/1   Running     0   5m
langsmith-playground-xxxxx               1/1   Running     0   5m
langsmith-queue-xxxxx                    1/1   Running     0   5m

打开 https://<HOSTNAME>，用 Key Vault 里的 admin 邮箱和密码登录：

bash

az keyvault secret show \
  --vault-name $(terraform -chdir=infra output -raw keyvault_name) \
  --name langsmith-admin-password \
  --query value -o tsv

Values 链

make deploy 按以下顺序应用 Helm values 文件（冲突时最后一个文件胜出）：

txt

1. helm/values/values.yaml                              ← base values (chart defaults)
2. helm/values/values-overrides.yaml                    ← hostname, WI client-id, auth, postgres/redis
3. helm/values/langsmith-values-sizing-<profile>.yaml   ← resource requests + HPA settings
4. (add-on files when enable_* flags are set)

helm/values/ 中的所有文件都被 gitignore（生成的或含活动机密）。源模板在 helm/values/examples/ 中，由 make init-values 复制。

第 2 天运营

bash

make status         # 10-section health check
make status-quick   # skip Key Vault + K8s secret queries (faster)
make deploy         # re-deploy after any Helm value changes
make init-values    # re-generate values after Terraform changes
make kubeconfig     # refresh cluster credentials
make k8s-secrets    # re-create langsmith-config-secret from Key Vault

启用附加组件

每个附加组件都由 infra/terraform.tfvars 中的一个标志门控。设置该标志，重跑 make init-values 以重新生成 values，然后重跑 make deploy。

LangSmith Deployment

启用 LangSmith Deployment，让你能直接从 LangSmith UI 部署和管理作为 API 服务器的 agent。这增加三个新 pod。

Pod	角色	Workload Identity
`langsmith-host-backend`	LangSmith Deployment 控制平面 API。管理部署生命周期，把状态存在共享的 PostgreSQL 中。	是
`langsmith-listener`	监视 host-backend，在 Kubernetes 中创建和更新 `LangGraphPlatform` CRD。	是
`langsmith-operator`	协调 CRD。创建按部署的 Deployment、StatefulSet 和 Service。	否

先扩节点池

在启用之前，把 default_node_pool_min_count 调到至少 5。operator 按需生成 agent 部署 pod，需要节点余量：

hcl

# infra/terraform.tfvars
default_node_pool_min_count = 5      # operator pods need headroom
enable_deployments          = true

WARNING

没有足够的节点容量，operator 生成的 agent pod 会无限期停在 Pending 状态。先扩节点池，再启用。

应用、重新生成 values、部署

bash

cd terraform/modules/azure
make apply          # scale up node pool (~5 min)
make init-values    # picks up enable_deployments = true → generates add-on overlay
make deploy         # rolls out host-backend + listener + operator

make init-values 把 LangSmith Deployment 附加组件 overlay（langsmith-values-agent-deploys.yaml）追加到 values 链。它自动注入：

yaml

config:
  deployment:
    enabled: true                          # REQUIRED, without this listener and operator are skipped silently
    url: "https://<your-hostname>"         # must match config.hostname (with protocol)
    tlsEnabled: true                       # set based on tls_certificate_source

WARNING

config.deployment.url 必须包含 https://。 缺协议会让 operator 部署的 agent 无限期卡在 DEPLOYING 状态。这个 URL 由 make init-values 自动注入。不要在 overlay 文件里手动设置它；它会在下次运行被覆盖。

WARNING

config.deployment.enabled: true 是必需的。 只设 config.deployment.url 而不设 enabled: true，会让 chart 静默跳过创建 listener 和 operator。没有错误，它们永不出现。

验证

bash

# All three pods Running
kubectl get pods -n langsmith | grep -E "host-backend|listener|operator"

# LangSmith Deployment CRDs registered
kubectl get crd | grep langchain

# List LangSmith Deployments (empty on first deploy, populated when you create a deployment)
kubectl get lgp -n langsmith

预期：langsmith-host-backend、langsmith-listener 和 langsmith-operator 都 Running。总 pod 数：约 ~20 Running + 3 Completed jobs。

KEDA 已随基础设施一起安装。带 enable_deployments = true 时，operator 为每个 agent 部署的 worker 队列创建 KEDA ScaledObject 资源。worker pod 空闲时缩到零，并基于 Redis 队列深度扩容。

Agent Builder

提供从 LangSmith UI 对 LangGraph agent 的可视化 AI 辅助创建与管理。无需 terraform apply；运行 make init-values && make deploy。

前置条件： LangSmith Deployment 启用（enable_deployments = true）。没有它就启用 Agent Builder 会导致一个 preflight 错误。

Pod	类型	角色
`langsmith-agent-builder-tool-server`	静态	MCP 工具执行服务器，为 AI 提供代码/文件编辑工具
`langsmith-agent-builder-trigger-server`	静态	Webhook 接收器和计划触发引擎
`langsmith-agent-bootstrap`	Job（Completed）	通过 operator 注册随附的 Agent Builder agent，运行一次
`agent-builder-<hash>` + queue + redis + `lg-<hash>-0`	动态（operator 管理）	Agent Builder 部署，由 operator 在 bootstrap Job 运行时创建

启用：

hcl

# infra/terraform.tfvars
enable_deployments   = true    # required prerequisite
enable_agent_builder = true

bash

cd terraform/modules/azure
make init-values    # appends langsmith-values-agent-builder.yaml to values chain
make deploy         # rolling update, ~10 min for bootstrap Job to complete

make init-values 把 Agent Builder 附加组件 overlay（langsmith-values-agent-builder.yaml）追加到 values 链。该 overlay 启用 Agent Builder UI 和支持服务，设 backend.agentBootstrap.enabled: true（那个把 Agent Builder 注册为一个 LangSmith Deployment 并创建所需 ConfigMap 的 post-install job），并把 agent worker pod 资源设为保守值（1 到 2 CPU、512 MiB 到 1 GiB 内存）而非 chart 默认的 4 到 8 GiB 内存。

验证：

bash

# Static pods Running, bootstrap Job Completed
kubectl get pods -n langsmith | grep -E "tool-server|trigger-server|Bootstrap"

# Operator-managed dynamic pods (4 pods, api-server, queue, redis, postgres StatefulSet)
kubectl get pods -n langsmith | grep agent-builder

# Operator-managed LangSmith Deployment for Agent Builder
kubectl get lgp -n langsmith

预期：3 个静态 pod（tool-server、trigger-server、bootstrap Job）+ 4 个动态 pod。总计：约 ~26 pod。make deploy 之后，LangSmith UI 导航中会出现一个 Agent Builder 部分。

WARNING

在 agentBootstrap 完成后滚动前端。 agentBootstrap Job 创建前端为 Polly UI 读取的 langsmith-polly-config ConfigMap。如果前端在 bootstrap 完成时正在运行，Polly 会显示 "Unable to connect to LangGraph server"。修复：

bash

kubectl rollout restart deployment langsmith-frontend -n langsmith

WARNING

加密密钥从 langsmith-config-secret 读取。 不要在 values-overrides.yaml 里内联设 config.agentBuilder.encryptionKey。chart 通过 existingSecretName 从 langsmith-config-secret 读取它。内联设置会覆盖机密引用并造成不匹配。

langsmith-agent-builder-tool-server 和 langsmith-agent-builder-trigger-server 都需要 Workload Identity 来访问 Azure Blob 存储。它们的联合凭据已预注册在 modules/k8s-cluster/main.tf 中；无需额外设置。

Insights 与 Polly

两个功能，都需要 LangSmith Deployment。它们彼此独立；可以只启用其一而不启用另一个。

Insights： AI 驱动的追踪分析（Clio）。在 LangSmith 追踪中浮现模式和异常。Clio 在首次 UI 调用时通过 operator 作为一个动态 LangGraph 部署。不增加新的静态 pod。
Polly： AI 驱动的评估与监控 agent。作为一个动态的、operator 管理的 LangGraph 部署运行。overlay 启用 Polly（顶层 polly.enabled: true）；operator 管理其资源。

无需 terraform apply；运行 make init-values && make deploy。

hcl

# infra/terraform.tfvars
enable_deployments = true    # required prerequisite
enable_insights    = true    # Insights / Clio analytics
enable_polly       = true    # Polly AI evaluation agent

启用其一：

hcl

enable_insights = true    # Insights only
# or
enable_polly    = true    # Polly only

bash

cd terraform/modules/azure
make init-values    # appends insights + polly add-on overlays to the values chain
make deploy         # rolling update, ~5 min

make init-values 基于 terraform.tfvars 中的 clickhouse_source 追加附加组件 overlay：

clickhouse_source = "in-cluster"，生成一个最小 overlay（只含顶层 insights.enabled: true）。Helm chart 内部化管理 ClickHouse。
clickhouse_source = "external"，生成一个带 clickhouse.external.enabled: true 和一个 langsmith-clickhouse 机密引用的完整 overlay。在部署之前用 ClickHouse 主机和凭据创建这个机密。

WARNING

不要为集群内 ClickHouse 手动复制 Insights 示例文件。 示例 helm/values/examples/langsmith-values-insights.yaml 有 clickhouse.external.enabled: true 和 existingSecretName: langsmith-clickhouse。当使用集群内 ClickHouse 时手动复制它会因该机密不存在而引发 CreateContainerConfigError。始终用 make init-values 生成正确的文件。

验证：

bash

# ClickHouse already running from base install
# Insights and Polly deploy as dynamic pods when first invoked from the UI
kubectl get pods -n langsmith | grep -E "clickhouse|polly|clio"

# Watch for dynamic pods on first Insights use
kubectl get pods -n langsmith -w

# Confirm Insights is enabled in Helm values
helm get values langsmith -n langsmith | grep -A3 insights
# Expected: enabled: true

WARNING

加密密钥在首次启用后绝不能更改。 insights_encryption_key 和 polly_encryption_key 在首次启用后绝不能更改。更改其中任一会永久损坏所有现有加密数据。没有恢复路径。这些密钥存在 Key Vault 中，绝不自动轮换。

WARNING

在首次启用 Polly 后滚动前端。 如果启用后 Polly UI 显示 "Unable to connect to LangGraph server"，是因为前端在 bootstrap ConfigMap 就绪之前启动。修复：

bash

kubectl rollout restart deployment langsmith-frontend -n langsmith

附加组件概览

阶段	新 pod	总计 ~running
基础安装	核心 LangSmith（backend、frontend、queue、ingest-queue、clickhouse 等）	约 ~17
LangSmith Deployment	`host-backend`、`listener`、`operator`	约 ~20
Agent Builder	`tool-server`、`trigger-server`、`bootstrap` Job + 4 个动态 Agent Builder pod	约 ~26
Insights 和 Polly	无新静态 pod（Clio + Polly 在首次使用时动态出现）	静态约 ~22

Ingress 控制器

在 make apply 之前在 terraform.tfvars 中设 ingress_controller。完整的 TLS 兼容性矩阵，见 Azure 模块仓库中的 INGRESS_CONTROLLERS.md。

值	Terraform 安装什么	最适合
`nginx` （默认）	带 Azure LB 的 `ingress-nginx` Helm chart	标准部署。最简单的设置。
`istio-addon`	AKS Service Mesh 附加组件（Azure 管理的 Istio）	Azure 管理的 Istio mesh、多 dataplane、mTLS。
`istio`	`istio-base` + `istiod` + `istio-ingressgateway`	自管理 Istio。完整 mesh 和 sidecar 注入。
`agic`	Azure Application Gateway v2 + AKS 管理的 `ingress_application_gateway` 附加组件	企业 Azure、原生 L7 WAF、仅 HTTP 或 dns01 + 自定义域名。
`envoy-gateway`	`gateway-helm` OCI chart、Kubernetes Gateway API	Gateway API 原生、Ingress 的现代替代。

WARNING

letsencrypt（HTTP-01）只对 nginx、istio（自管理）和 envoy-gateway 有效。istio-addon 不创建 IngressClass，所以 ACME 求解器无法收到流量。用 agic 时，Application Gateway 会重写 ACME 质询路径，所以 HTTP-01 求解器失败。对这两者，用带自定义域名的 dns01，或仅 HTTP 用 none。

DNS 和 TLS

dns_label 给你一个免费的 Azure 子域，<label>.<region>.cloudapp.azure.com，无需域名注册或 DNS 区。deploy.sh 会自动为正确的 LoadBalancer 服务加标注。

快速开始默认（HTTP，零设置）：

hcl

dns_label              = "langsmith-prod"
tls_certificate_source = "none"

用 Let's Encrypt 添加 HTTPS（nginx、自管理 istio，或 envoy-gateway）：

hcl

dns_label              = "langsmith-prod"
tls_certificate_source = "letsencrypt"
letsencrypt_email      = "you@example.com"

自定义域名 + DNS-01（所有控制器，在防火墙后也能工作）：

hcl

langsmith_domain       = "langsmith.mycompany.com"
tls_certificate_source = "dns01"
letsencrypt_email      = "you@example.com"
create_dns_zone        = true
# After deploy: add ingress_ip = "<lb-ip>" and re-run make apply (creates A record)

dns01 流程：

make apply 创建 Azure DNS 区并输出 4 个 nameserver。
在你的注册商处，为该子域添加指向那 4 个 nameserver 的 NS 记录。
验证：dig NS langsmith.mycompany.com @8.8.8.8。
make deploy 通过 DNS-01 自动签发证书（Workload Identity 把 TXT 记录写入 Azure DNS）。
取得 LB IP，把 ingress_ip = "<ip>" 加到 terraform.tfvars，然后 make apply（创建 A 记录）。
make status 在每一步精确显示该添加哪些 NS 和 A 记录。

NOTE

为何用 NS 记录而非 CNAME： cert-manager 必须把 TXT 记录写到区中以证明所有权。那要求 Azure DNS 对该子域是权威的，而 NS 委派授予该权威。CNAME 只别名化流量，不转移 DNS 权威；DNS-01 质询会失败。

后续步骤

参考 Azure 变量和快速参考。
审阅 Azure 架构了解模块结构、流量走向和 Workload Identity。
出问题时，查 Azure 故障排除指南。
用 LangSmith Deployment 在 UI 中启用 agent 部署。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织