Terraform 纳管 AI 网关：把 LiteLLM 配置做成基础设施即代码

Terraform 纳管 AI 网关把 LiteLLM 配置做成基础设施即代码【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm当一家公司开始把 5 个、10 个甚至 50 个模型接入点收敛到统一的 AI 网关后面配置管理的痛点会迅速超过模型本身的选择问题谁在哪个团队名下、这把虚拟 Key 能访问哪些模型、预算上限是多少、Azure 的 api_version 是不是又被人手动改过——这些信息一旦散落在管理面板的点击和 YAML 文件里就会变成查得到但说不清来源的灰色地带。LiteLLM 给出的答案是用官方 Terraform Provider 把网关的全部管理面模型、团队、密钥、预算、Guardrail、MCP Server变成可评审、可回滚、可复现的声明式配置。本文结合仓库源码拆解这套 IaC 方案的完整链路。从 YAML 漂移到声明式Provider 的安装与认证LiteLLM 网关的传统配置方式是在litellm_settings与model_list中声明模型路由再通过管理 API 在运行期创建密钥和团队。两种配置源的边界一旦模糊就会出现配置文件和数据库状态互相覆盖的漂移问题。Terraform Provider 的意义在于把数据库里的管理面资源也纳入声明式管理——模型、团队、密钥、预算这些原本只在 UI 或 curl 里存在的对象现在有了与基础设施同等的生命周期。Provider 的官方发布源位于仓库内的 terraform/provider 目录其注册名称为BerriAI/litellm。安装与认证极其收敛只需要两个配置项——api_baseLiteLLM 实例地址与api_key管理密钥二者均支持通过环境变量LITELLM_API_BASE与LITELLM_API_KEY注入另有insecure_skip_verify用于自签名证书的开发场景。认证实现见 provider.go所有请求以x-api-key头发出并对日志中的敏感字段做了系统性脱敏client.go 中的redactSensitiveData会遮蔽api_key、secret、credential等字段。terraform { required_providers { litellm { source BerriAI/litellm version ~ 1.99.0 # 与运行的 LiteLLM Proxy 版本对齐 } } } provider litellm { api_base var.litellm_api_base api_key var.litellm_api_key }值得注意的是Provider 并没有自己的独立版本线——这是它与绝大多数 Terraform Provider 的关键差异后文会专门展开。三个核心资源model、team、key 的声明与编排Provider 当前暴露了 24 个资源与 30 个数据源见 provider.go 的ResourcesMap覆盖模型、团队、组织、成员、密钥、预算、标签、Guardrail、Prompt、Agent、MCP Server、Vector Store 等对象。其中litellm_model、litellm_team、litellm_key是搭建网关控制面的三件套。模型路由与计价的声明litellm_model把一个模型接入点描述为完整的路由单元字段定义见 resource_model.go。model_name是网关对外暴露的名字custom_llm_provider指定供应商base_model既承担路由键又承担计价键resource litellm_model gpt4 { model_name gpt-4-proxy custom_llm_provider openai model_api_key var.openai_api_key model_api_base https://api.openai.com/v1 base_model gpt-4 tier paid mode chat input_cost_per_million_tokens 30.0 output_cost_per_million_tokens 60.0 }实现上创建/更新逻辑resource_model_crud.go会把用户友好的每百万 token 成本换算成input_cost_per_token/output_cost_per_token写入litellm_params并在创建后以指数退避重试读取最多 5 次来消化代理侧的最终一致性延迟——这是把管理面 API 封装成幂等资源时最典型的工程细节。团队预算与权限的载体litellm_team把预算、限流、可访问模型、成员权限组织成一个治理单元。团队级max_budget/soft_budget、tpm_limit/rpm_limit、models白名单、team_member_permissions以及team_member_budget等继承式预算均可声明见 resource_team.go。团队与模型可以用引用直接编排形成清晰的依赖图resource litellm_team platform { team_alias platform-core models [litellm_model.gpt4.model_name] max_budget 1000.0 soft_budget 800.0 budget_duration monthly team_member_budget 100.0 team_member_permissions [request_model_access] }团队创建支持传入稳定的可读team_idForceNew属性避免 Provider 生成的 UUID 进入业务系统后难以关联。密钥写后即焚的安全模型litellm_key是这套方案中安全设计最值得称道的一环。虚拟 Key 的明文在terraform apply期间可用方便立即接入 Secret Manager但绝不落盘到 state资源 ID 使用明文密钥的 SHA-256 哈希token_idstate 中只保存不可用于鉴权的哈希值。这一行为需要 Terraform 1.11 的WriteOnly属性支持字段定义见 resource_key.goresource litellm_key billing { key_type llm_api models [litellm_model.gpt4.model_name] team_id litellm_team.platform.team_id max_budget 50.0 soft_budget 40.0 budget_duration monthly tpm_limit 1000 rpm_limit 60 key_alias billing-service duration 30d metadata { environment production } }配套的最佳实践是把明文密钥在 apply 期间直接转存至 Secret Managerresource aws_ssm_parameter litellm_key { name /myapp/litellm-key type SecureString value litellm_key.billing.key }密钥轮换也因此有了清晰的 IAM 式流程旧的litellm_key资源从 state 移除并重新 import以token_id为准新的密钥明文再次只出现在 apply 输出中。对于 JWT 形态的客户端litellm_jwt_key_mapping资源还能把client_id/azp/sub等 claim 映射到虚拟 Key让 JWT 客户端自动继承对应密钥的模型、预算与限流见 resource_jwt_key_mapping.go且映射可通过token_id直接引用同配置内创建的litellm_key。多云模型配置与细粒度治理LiteLLM 网关的核心价值是多云统一接入Provider 把这一能力原样搬进了 HCL。litellm_model针对不同供应商暴露了专属字段resource_model.go 与 types.goAzuremodel_api_baseapi_version指定部署端点与 API 版本AWS Bedrockaws_access_key_id/aws_secret_access_key/aws_region_name并支持aws_session_name/aws_role_name实现跨账号访问Vertex AIvertex_project/vertex_location/vertex_credentials其余供应商可通过additional_litellm_params透传任意非一等参数。additional_litellm_params的类型处理值得一提字符串true/false会被强转为布尔数字字符串解析为整数或浮点以[或{开头的字符串按 JSON 解析为对象/数组还提供了additional_drop_params从最终请求中剔除自动附加的参数如reasoningEffort。仓库中的 model_additional_params.tf 给出了完整示例resource litellm_model azure_with_drop_params { model_name gpt-5-mini-coder custom_llm_provider azure model_api_key var.azure_api_key model_api_base https://your-azure-endpoint.openai.azure.com/ api_version 2025-03-01-preview base_model gpt-5-mini tier paid mode completion additional_litellm_params { additional_drop_params [\reasoningEffort\] } }对 Azure Data Zone 这类路由名与计价键不同的部署Provider 提供了pricing_base_model属性路由仍走base_model计价却按pricing_base_model查价——把两个原本耦合的维度在声明层解耦避免计费错账。密钥的细粒度治理则围绕三个维度展开model_rpm_limit/model_tpm_limit控制单模型限流max_parallel_requests控制并发model_max_budget以 JSON 字符串声明按模型的预算{gpt-4o-mini: {budget_limit: 50, time_period: 30d}}并在 schema 层做了严格的字段校验与等价 JSON 的 diff 抑制。值得注意的是model_max_budget曾以map(number)形式存在但代理端会以 500 拒绝裸数字——这一破坏性变更被完整记录在 CHANGELOG.md 并伴随 schema 版本升级自动迁移旧 state。版本对齐与回滚策略这套 Provider 在运维上最反直觉、也最有价值的设计是版本即对齐从 LiteLLM 1.99.0 起Provider 的版本号与 LiteLLM 版本完全一致每一次 LiteLLM 发布dev、rc、stable都会在同一 commit 上构建并发布对应版本的 Provider见 RELEASING.md。也就是说1.99.0的 Provider 必然是与1.99.0的 Proxy 同源发布、并针对该 Proxy 的 API 做过审计的。terraform { required_providers { litellm { source BerriAI/litellm version ~ 1.99.0 # 与运行的 Proxy 版本严格对齐 } } }这一设计的直接收益是回滚的确定性升级网关版本时同步升级 Provider出问题时把二者一起钉回旧版本即可不存在新 Provider 调用旧 Proxy API的兼容性窗口。反之旧版~ 0.4约束不会自动获得任何后续发布——因为0.x版本线在0.4.0已终止继续使用旧约束等于放弃所有修复。更关键的是这份对齐不是靠文档自觉而是被 CI 强制执行的仓库内的tools/endpointaudit见 coverage.go会在每次变更时把 Provider 实际调用的每个管理端点与 Proxy 生成的 OpenAPI schema 做静态比对——schema 中每一个管理端点都必须被某个资源或数据源覆盖或携带理由进入 allowlist反向亦然过期的 allowlist 条目会直接导致 CI 失败。这意味着 Provider 与 LiteLLM API 之间的漂移在合入前就会被拦截管理面 API 的任何破坏性变更都无法静默进入 Provider。对于不想自己维护 Provider 状态的人来说仓库还提供了完整的部署栈terraform/litellm/awsECS Fargate Aurora Postgres ElastiCache S3 ALB与terraform/litellm/gcpCloud Run Cloud SQL Memorystore GCS 全局 HTTPS LB两个自包含模块将 LiteLLM 拆分为 gateway4000、backend4001、ui3000三个组件部署支持proxy_config类型化输入与按组件的 Secret 注入还内置了一次性 Prisma 迁移任务。模块刻意不声明provider块以便调用方用count/for_each/depends_on自由编排甚至直接以 HCP Terraform no-code 方式一键部署。至此网关本身和网关里的配置都成了 Terraform 管理的对象——AI 网关的基础设施即代码闭环才算真正合拢。小结LiteLLM 的 Terraform Provider 把 AI 网关从配置靠 YAML、治理靠点击、密钥靠手抄的运维形态推进到了与数据库、缓存、负载均衡同一套生命周期的管理方式。模型路由、团队预算、虚拟密钥三者的声明式编排天然形成依赖图WriteOnly密钥与哈希化 state 解决了 IaC 最头疼的敏感信息泄露问题而Provider 版本 LiteLLM 版本 端点审计 CI的组合拳则为频繁迭代的 AI 基础设施提供了其他网关生态少见的回滚安全感。对于正在把多个模型供应商收拢进企业网关的团队这可能是把网关配置从运维负担变成工程资产的最直接路径。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考