Azure Terraform 快速参考

面向 AKS 上自托管 LangSmith 的 Make targets、Terraform、kubectl、Azure CLI 和 Helm 命令。

面向使用 Azure Terraform 模块预配的 Azure LangSmith 部署进行日常操作的命令速查表。所有 make target 都在 modules/azure/ 下运行。运行 make help 查看内联摘要。

完整的部署演练请参见 Azure 部署指南。

部署概览

阶段	部署内容	命令
基础设施	AKS + Postgres + Redis + Blob + Key Vault + cert-manager + KEDA + ingress	`make apply`
集群凭据	来自 Key Vault 的 Kubeconfig + Kubernetes Secrets	`make kubeconfig && make k8s-secrets`
LangSmith（Helm 路径）	通过 shell 脚本部署 LangSmith Helm（~17 个 pod）	`make init-values && make deploy`
LangSmith（Terraform 路径）	在 Terraform state 中管理的 Secrets + SA + Helm release	`make init-app && make apply-app`
LangSmith Deployment 附加组件	host-backend、listener、operator。先将 `default_node_pool_min_count` 提升到 5	`make apply && make init-values && make deploy`
Agent Builder 附加组件	tool-server、trigger-server、agent-builder LGP	`make init-values && make deploy`
Insights + Polly 附加组件	Clio analytics、Polly eval agent	`make init-values && make deploy`

首次设置

bash

cd terraform/modules/azure

# 1. Generate terraform.tfvars (interactive wizard)
make quickstart

# 2. Bootstrap secrets (prompts on first run, reads from Key Vault on repeat)
make setup-env

# 3. Preflight (Azure CLI, RBAC, providers)
make preflight

# 4. Deploy infrastructure (~15 to 20 min)
#    Skip `make plan` on a fresh deploy — kubernetes_manifest needs a live cluster
make init
make apply

# 5. Cluster credentials + Kubernetes Secrets
make kubeconfig
make k8s-secrets

# 6. Generate Helm values from Terraform outputs
make init-values

# 7. Deploy LangSmith (~10 min)
make deploy

# 8. Health check
make status

或者一次性运行整个流程：

bash

make deploy-all      # apply → kubeconfig → k8s-secrets → init-values → deploy
make deploy-all-tf   # apply → init-values → init-app → apply-app (Terraform path)

日常运维

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

# Manage Key Vault secrets
make keyvault                                       # interactive menu
./infra/scripts/manage-keyvault.sh list             # all secrets with timestamps
./infra/scripts/manage-keyvault.sh get <secret>     # read a secret
./infra/scripts/manage-keyvault.sh set <key> <val>  # update a secret
./infra/scripts/manage-keyvault.sh validate         # check all required secrets exist
./infra/scripts/manage-keyvault.sh diff             # compare KV vs K8s secret
./infra/scripts/manage-keyvault.sh delete <key>     # soft-delete (recoverable 90 days)

附加组件

附加组件阶段（3 到 5）由 infra/terraform.tfvars 中的标志控制。设置这些标志后，重新运行 init-values && deploy。init-values.sh 会自动把对应的示例文件复制到 helm/values/。

hcl

# infra/terraform.tfvars
sizing_profile       = "production"   # minimum | dev | production | production-large
enable_deployments   = true           # LangSmith Deployment add-on (listener + operator + host-backend)
enable_agent_builder = true           # Agent Builder add-on (requires enable_deployments)
enable_insights      = true           # Insights / Clio analytics add-on
enable_polly         = true           # Polly AI eval add-on (requires enable_deployments)

WARNING

LangSmith Deployment 附加组件要求先将 default_node_pool_min_count = 5。operator 生成的 pod 需要节点余量；没有余量时，agent pod 会一直处于 Pending 状态。

规格配置

在 terraform.tfvars 中设置 sizing_profile，然后重新运行 make init-values && make deploy。

Profile	使用场景
`minimum`	成本停车、CI 冒烟测试、单用户演示。真实流量下预计会 OOM。
`dev`	用于本地开发、CI 流水线、集成测试、短期 POC 的轻量非生产环境。
`production`	生产环境的推荐选择。所有无状态组件多副本并启用 HPA。
`production-large`	基于扩容指南的高流量起点（~50 并发用户，~1000 追踪/秒）。

kubectl

bash

# Pod health
kubectl get pods -n langsmith
kubectl get pods -n langsmith -w
kubectl describe pod <pod-name> -n langsmith
kubectl logs <pod-name> -n langsmith --tail=100 -f
kubectl logs <pod-name> -n langsmith --previous --tail=50

# Backend logs (live)
kubectl logs -n langsmith deploy/langsmith-backend --tail=100 -f

# Ingress
kubectl get ingress -n langsmith
kubectl describe ingress -n langsmith

# NGINX LoadBalancer external IP
kubectl get svc ingress-nginx-controller -n ingress-nginx

# TLS
kubectl get certificate -n langsmith
kubectl get challenges -n langsmith
kubectl describe certificate <cert-name> -n langsmith
kubectl get clusterissuer

# Workload Identity
kubectl get serviceaccount langsmith-ksa -n langsmith -o yaml | grep annotation -A5

# Helm
helm status langsmith -n langsmith
helm history langsmith -n langsmith
helm get values langsmith -n langsmith

# LangSmith Deployment
kubectl get lgp -n langsmith
kubectl get crd | grep langchain

Azure CLI

bash

# Re-auth
az login
az account set --subscription <subscription-id>
az account show

# AKS
az aks list
az aks show --name <cluster> --resource-group <rg>
az aks get-credentials --name <cluster> --resource-group <rg>

# PostgreSQL
az postgres flexible-server list
az postgres flexible-server show --name <server> --resource-group <rg>

# Redis
az redis list
az redis show --name <cache> --resource-group <rg>

# Blob Storage
az storage account list
az storage container list --account-name <account>

# Key Vault
az keyvault list
az keyvault secret list --vault-name <vault>
az keyvault secret show --vault-name <vault> --name <secret> --query value -o tsv

# Application Gateway (AGIC)
az network application-gateway list

Terraform

bash

cd modules/azure/infra

terraform init
terraform plan        # skip on first run, see deploy notes
terraform apply
terraform apply -target=module.aks

terraform output
terraform output -raw aks_cluster_name
terraform output -raw keyvault_name
terraform output -raw storage_account_name

terraform state list

关键约束

全新部署时跳过 make plan。kubernetes_manifest 资源需要存活的集群 API。直接使用 make apply。
在 terraform destroy 之前先卸载 Helm。Azure Load Balancer 持有一个子网引用；留着它会阻止 VNet 删除。请先运行 make uninstall。
config.deployment.url 必须包含 https://。否则，operator 生成的 agent 会一直卡在 DEPLOYING。
LangSmith Deployment 附加组件需要 config.deployment.enabled: true。只设置 URL 而不设置 enabled: true 会静默跳过 listener 和 operator。
加密密钥在首次启用后绝不能更改。轮换 insights_encryption_key 或 polly_encryption_key 会永久破坏现有的加密数据。
首次启用 Polly 后重启前端。agentBootstrap 会在注册后创建 langsmith-polly-config；更早启动的 frontend pod 不会加载它。
letsencrypt（HTTP-01）仅适用于 nginx、istio（自管理）和 envoy-gateway。对于 istio-addon 或 agic，请配合自定义域名使用 dns01，或使用 none 仅走 HTTP。
Key Vault 在 destroy 后进入 90 天软删除。若 keyvault_purge_protection = false，可运行 az keyvault purge 立即收回该名称。

拆除

bash

make uninstall   # removes Helm release + LGP resources; prompts to delete namespace
make destroy     # destroys all Azure infrastructure via terraform destroy
make clean       # removes local secrets, config, helm values, and tfstate files

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织