Azure Terraform 快速参考

命令备忘单，用于针对使用 Azure Terraform 模块部署的 Azure LangSmith 进行日常运维操作。所有 make 目标均从 modules/azure/ 目录运行。运行 make help 可获取内联摘要。完整的部署演练，请参阅 Azure 部署指南。

部署概览

阶段	部署内容	命令
基础设施	AKS + Postgres + Redis + Blob + Key Vault + cert-manager + KEDA + ingress	`make apply`
集群凭据	Kubeconfig + 来自 Key Vault 的 Kubernetes Secrets	`make kubeconfig && make k8s-secrets`
LangSmith (Helm 路径)	通过 shell 脚本部署的 LangSmith Helm (~17 pods)	`make init-values && make deploy`
LangSmith (Terraform 路径)	在 Terraform state 中管理的 Secrets + SA + Helm 发布	`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`

初次设置

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

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

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

日常运维

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/ 目录。

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

LangSmith Deployment 插件需要先设置 default_node_pool_min_count = 5。Operator 生成的 Pod 需要节点预留空间；否则，代理 Pod 将无限期处于 Pending 状态。

规格配置

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

配置文件	适用场景
`minimum`	成本节省、CI 冒烟测试、单用户演示。在真实流量下可能会遇到 OOM。
`dev`	用于本地开发、CI 管道、集成测试、短期 POC 的轻量级非生产环境。
`production`	推荐用于生产环境。在所有无状态组件上实现多副本并启用 HPA。
`production-large`	基于规模指南的高流量起点（约 50 并发用户，约 1000 traces/sec）。

kubectl

# 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

# 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

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 负载均衡器持有子网引用；保留它会阻止 VNet 删除。请先运行 make uninstall。
config.deployment.url 必须包含 https://。没有它，operator 生成的代理将一直卡在 DEPLOYING 状态。
LangSmith Deployment 插件需要 config.deployment.enabled: true。仅设置 URL 而不设置 enabled: true 会静默跳过 listener 和 operator。
加密密钥在首次启用后绝不能更改。轮换 insights_encryption_key 或 polly_encryption_key 将永久损坏现有加密数据。
首次启用 Polly 后需要重启前端。agentBootstrap 在注册后创建 langsmith-polly-config；更早启动的前端 Pod 无法获取它。
letsencrypt (HTTP-01) 仅适用于 nginx、istio (自管理) 和 envoy-gateway。对于 istio-addon 或 agic，请使用 dns01 配合自定义域，或对于仅 HTTP 的情况使用 none。
Key Vault 在销毁后进入 90 天软删除状态。如果设置了 keyvault_purge_purge_protection = false，可以运行 az keyvault purge 以立即回收该名称。

拆卸

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

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

部署概览

初次设置

日常运维

插件

规格配置

kubectl

Azure CLI

Terraform

关键约束

拆卸

​部署概览

​初次设置

​日常运维

​插件

​规格配置

​kubectl

​Azure CLI

​Terraform

​关键约束

​拆卸

部署概览

初次设置

日常运维

插件

规格配置

kubectl

Azure CLI

Terraform

关键约束

拆卸