用 Terraform 管理 LiteLLM：LiteLLM Terraform Provider 架构解析与完整实操指南

用 Terraform 管理 LiteLLMLiteLLM Terraform Provider 架构解析与完整实操指南【免费下载链接】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本文以 LiteLLM 仓库terraform/provider/README.md的官方文档为主线结合仓库中的 Go 源码provider.go、端点审计工具endpointaudit与发布说明RELEASING.md系统讲解如何用 Terraform 以代码方式管理 LiteLLM Proxy 的模型、团队、密钥等全部管理面资源。读完本文你将能够正确声明并配置 provider、编写litellm_model与litellm_key资源、理解Provider 版本即 LiteLLM 版本的锁定策略并掌握端点漂移审计与本地开发构建的完整工作流。Provider 能管理什么资源全景LiteLLM Terraform Provider 允许你通过 Infrastructure as Code 管理 LiteLLM 资源支持通过 LiteLLM REST API 管理模型、团队、团队成员、API 密钥、用户、组织、预算、标签、项目、护栏guardrails、提示词、Agent、搜索工具、访问组、回退fallbacks、MCP 服务器、凭据与向量存储并为它们提供只读数据源。README 中列出的核心能力包括管理 LiteLLM 模型配置将模型与特定团队关联创建与管理团队配置团队成员及其权限设置用量限制与预算控制对特定模型的访问指定模型模式如 completion、embedding、image generation使用细粒度控制管理 API 密钥在 model 资源中支持 reasoning effort 配置从源码 provider.go 的ResourcesMap可以看到当前实际注册的可写资源共 25 个比 README 表格覆盖得更全资源名用途资源名用途litellm_model模型配置litellm_user用户litellm_team团队litellm_budget预算litellm_organization组织litellm_tag标签litellm_organization_member组织成员litellm_project项目litellm_organization_member_add批量添加组织成员litellm_fallback回退链litellm_team_member团队成员litellm_key_block/litellm_team_block封禁密钥/团队litellm_team_member_add批量添加团队成员litellm_access_group/litellm_unified_access_group访问组litellm_keyAPI 密钥litellm_guardrail/litellm_prompt护栏 / 提示词litellm_mcp_serverMCP 服务器litellm_agent/litellm_search_toolAgent / 搜索工具litellm_credential凭据litellm_jwt_key_mappingJWT 声明到虚拟密钥的映射DataSourcesMap中注册了33 个只读数据源litellm_credential、litellm_vector_store、litellm_fallback、单数/复数形式的litellm_*_s等可用于在 Terraform 配置中读取现有对象的状态。README 中重点标注了litellm_credential与litellm_vector_store两个数据源完整文档位于 docs/data-sources/ 目录每个对象均有单数/复数两份文档如 credential.md、vector_store.md。源码归属terraform/provider 是唯一事实来源README 明确了代码归属规则仓库中的terraform/provider/目录是 Provider 的唯一事实来源source of truth公开的BerriAI/terraform-provider-litellm仓库只是一个薄发布镜像供公共 Terraform Registry 摄取不应向其提 PR。所有变更都落在本仓库中CI 在这里构建 Provider、运行测试并静态审计 Provider 调用的每一个端点对照 Proxy 生成的 OpenAPI 模式tools/endpointaudit/确保 Provider 不会与 LiteLLM API 静默漂移。该审计还会反向运行作为覆盖率门禁模式中的每一个管理端点必须被某个资源或数据源覆盖或出现在tools/endpointaudit/coverage_allowlist.txt的允许列表中过期的允许列表条目会让 CI 失败。这一机制的实现可以对照源码理解main.go 用 Go 的go/ast解析器静态提取源码中对fmt.Sprintf构造路径的 HTTP 调用把%s、%d、%v格式动词归一化为{param}占位符见 normalizePath从而把源码中的端点调用还原为与 OpenAPI 模式可比对的路径集合coverage.go 定义了管理端点的判定前缀表access_group、agent、budget、cache、config、credentials、fallback、guardrails、key、model、organization、project、prompts、router、team、user、vector_store等只有落在这些前缀下的路径才纳入覆盖率检查coverage_allowlist.txt 中每一条豁免都要写明理由文件头注释强调该文件相对于 schema 只能随时间收缩。当前豁免项分为几类只读分析/消费报表如GET /key/spend/report、Admin UI 辅助端点如GET /router/fields、命令式一次性操作如POST /key/regenerate、POST /cache/flushall、已有资源在别处管理的功能的替代方法/路径如PATCH /model/{model_id}/update以及标注 known gap 的真实覆盖缺口如 cache settings 资源、pass-through endpoint 资源——这些条目会在对应资源落地时删除。版本策略Provider 版本就是 LiteLLM 版本这是使用本 Provider 时最重要的一条规则Provider 版本即 LiteLLM 版本。每一个 LiteLLM 发布dev、rc 与 stable都会以与 Proxy 相同的版本号发布 Provider并且构建自同一个 commit——因此1.99.0的 Provider 就是随1.99.0的 Proxy 一起发布、并针对该 Proxy 的 API 完成端点审计的版本。最佳实践是把 Provider 固定到你 Proxy 实际运行的版本线version ~ 1.99.0预发布版本1.99.0-rc.1、1.99.0-dev.1同样会发布但 Terraform 只有在精确固定版本号时才会选中它们。需要注意的历史版本0.1.0至0.4.0早于这套版本体系属于独立的一条版本线。它们仍留在 Registry 中但**~ 0.4约束永远不会命中其他发布**——要继续接收更新必须重新固定到对应的 LiteLLM 版本号。结合 RELEASING.md 可以看到发布流水线的完整链路发布流水线解析出要发布的 commitdev 取mainHEADrc/stable 取mainHEAD 或运维指定的 SHA后把该 commit 的terraform/provider/目录 rsync 到镜像仓库并打上vlitellm version标签例如v1.99.0、v1.99.0-rc.1、v1.99.0-dev.1标签推送触发镜像侧的 goreleaser 工作流完成多平台构建、GPG 签名校验和与 GitHub Release公共 Terraform Registry 随后把该 GitHub Release 摄取为 Provider 版本。由于版本号就是 LiteLLM 版本号它不承担 SemVer 的破坏性变更信号职责——破坏性变更改由CHANGELOG.md和 Registry 文档公告。镜像仓库是 push-only 的标签不可变goreleaser 失败的版本通过重跑该标签的 Release 工作流恢复而不是重新打标签。声明与连接 Provider环境要求来自 README Requirements 一节Terraform 0.13.xGo 1.16仅开发需要在terraform块中声明 Providerterraform { required_providers { litellm { source BerriAI/litellm version ~ 1.99.0 # the LiteLLM version your proxy runs } } } provider litellm { api_base var.litellm_api_base api_key var.litellm_api_key }从 provider.go 的 Provider 级 Schema 可以看到三个配置项的精确语义配置项类型必填环境变量回退说明api_basestring是LITELLM_API_BASELiteLLM API 的基础 URLapi_keystring是LITELLM_API_KEY认证用 API 密钥标记为SensitiveTerraform 输出中隐藏insecure_skip_verifybool否默认falseLITELLM_INSECURE_SKIP_VERIFY跳过 TLS 证书校验仅限开发环境或自签名证书场景ConfigureFuncproviderConfigure把这三项组装成ProviderConfig再交给NewClient构造统一的 HTTP 客户端所有资源与数据源共用该客户端。由于三项都支持EnvDefaultFunc在 CI 中完全可以用环境变量注入凭据而不必写入 HCL。litellm_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 reasoning_effort medium # Optional: low, medium, or high input_cost_per_million_tokens 30.0 output_cost_per_million_tokens 60.0 }结合 model 资源文档必填参数只有三个model_nameAPI 调用中识别模型配置的名称、custom_llm_provider底层 LLM 提供方如openai、anthropic、azure、bedrock与base_model提供方侧的真实模型标识如gpt-4、claude-3-sonnet-20240229。其余关键参数mode模型用途合法值包括completion、embedding、image_generation、chat、moderation、audio_transcription、audio_speech、reranktierfree或paid默认freetpm/rpm该模型的每分钟 token / 请求数限额reasoning_effortlow/medium/high三档推理强度thinking_enabled默认false与thinking_budget_tokens默认1024仅在 thinking 开启时生效计费字段input_cost_per_million_tokens与output_cost_per_million_tokensProvider 会换算成每 token 成本再发给 API图像模型还有input_cost_per_pixel/output_cost_per_pixel音频模型有input_cost_per_second/output_cost_per_secondpricing_base_model与路由解耦的独立计费 key——当路由/部署名与成本表 key 不一致时例如以azure/gpt-4.1路由、实际是 Data Zone 档位的 Azure 部署可设pricing_base_model us/gpt-4.1-2025-04-14使其按对应档位计费vertex_project/vertex_location/vertex_credentialscustom_llm_provider vertex时的 Vertex AI 三件套team_id把模型关联到特定团队additional_litellm_params任意附加参数的 map(string)会被合并进发送给 API 的litellm_params对象专为未暴露为一级参数的提供方专属或实验性选项设计。仓库中的 examples/model_additional_params.tf 给出了一份可直接参照的完整示例展示了additional_litellm_params的类型强制转换规则additional_litellm_params { use_fine_tune true # 转为布尔 true max_context 16384 # 转为整数 16384 temperature_scale 0.75 # 转为浮点 0.75 experimental_feature enabled # 保持字符串 complex_config {\nested\: {\value\: 42}} # 解析为 JSON 对象 additional_drop_params [\reasoningEffort\] # 移除最终参数中的 reasoningEffort }转换规则是字符串true/false转为布尔数字字符串先按整数解析、失败再按浮点解析16384→ 163840.75→ 0.75以[或{开头的字符串按 JSON 解析无法转换的保持字符串非字符串值原样透传。特殊的additional_drop_params键以 JSON 数组字符串形式指定要在发送前从最终litellm_params中删除的参数且该键本身不会出现在最终 payload 中。文档同时提示远端 API 可能不回显所有自定义参数Provider 会在配置存在时于 state 中保留additional_litellm_params。AWS Bedrock 与跨账号访问README Notes 中特别提到Provider 现支持通过 model 资源的aws_session_name与aws_role_name参数实现 AWS 跨账号访问。完整写法resource litellm_model bedrock_claude { model_name bedrock-claude-proxy custom_llm_provider bedrock base_model anthropic.claude-3-sonnet-20240229-v1:0 tier paid mode chat # AWS configuration with cross-account access aws_access_key_id var.aws_access_key_id aws_secret_access_key var.aws_secret_access_key aws_region_name us-east-1 aws_session_name litellm-cross-account-session aws_role_name arn:aws:iam::123456789012:role/LiteLLMCrossAccountRole input_cost_per_million_tokens 3.0 output_cost_per_million_tokens 15.0 }Anthropic 与 Azure 的直接接入示例resource litellm_model claude { model_name claude-proxy custom_llm_provider anthropic model_api_key var.anthropic_api_key base_model claude-3-sonnet-20240229 tier paid mode chat input_cost_per_million_tokens 3.0 output_cost_per_million_tokens 15.0 } resource litellm_model azure_gpt4 { model_name azure-gpt4-proxy custom_llm_provider azure model_api_key var.azure_openai_key model_api_base var.azure_openai_endpoint api_version 2023-12-01-preview base_model gpt-4 tier paid mode chat input_cost_per_million_tokens 30.0 output_cost_per_million_tokens 60.0 }导入已有模型模型配置可以用模型 ID 导入注意 ID 在创建时生成与model_name不同terraform import litellm_model.gpt4 model-idlitellm_key 资源细粒度 API 密钥管理README 给出的 API 密钥创建示例展示了该资源的完整参数面resource litellm_key example_key { models [gpt-4, claude-3.5-sonnet] max_budget 100.0 user_id user123 team_id team456 max_parallel_requests 5 tpm_limit 1000 rpm_limit 60 budget_duration monthly key_alias prod-key-1 duration 30d metadata { environment production } allowed_cache_controls [no-cache, max-age3600] soft_budget 80.0 aliases { gpt-4 gpt4 } config { default_model gpt-4 } permissions { can_create_keys true } model_max_budget { gpt-4 50.0 } model_rpm_limit { claude-3.5-sonnet 30 } model_tpm_limit { gpt-4 500 } guardrails [content_filter, token_limit] blocked false tags [production, api] }README 对每个选项的说明完整保留如下models该密钥允许访问的模型列表max_budget密钥的最大预算user_id/team_id把密钥关联到用户与团队max_parallel_requests限制并发请求数tpm_limit/rpm_limit每分钟 token 数与请求数上限budget_duration预算周期如monthly、weeklykey_alias密钥的友好名称duration密钥有效期metadata自定义元数据allowed_cache_controls允许的缓存控制指令soft_budget软预算上限aliases模型别名映射config配置项permissions密钥权限model_max_budget、model_rpm_limit、model_tpm_limit按模型设置限额guardrails为该密钥应用特定护栏blocked封禁/解封开关tags用于组织与过滤的标签。对照 resource_key.go 的 Schema 定义还有几个源码层面值得注意的细节key字段被声明为WriteOnly: true且Sensitive: true——它只写入、不回显token_id是Computed字段即创建后从 API 返回的真实标识spend是Computed字段消费金额由远端计算不在配置中维护除 README 所列外Schema 还包含budget_id关联预算对象、enforced_params强制参数列表、allowed_routes允许的路由列表等更细的控制项多个数值字段max_budget、max_parallel_requests、tpm_limit、rpm_limit、soft_budget同时标记了Optional与Computed即不设置时以服务端默认值为准并回填到 state。本地开发项目结构与 MakefileREADME 描述的 Provider 源码组织结构以terraform/provider/为准源码目录litellm/下每个资源对应resource_*.go与*_test.go文件对terraform-provider-litellm/ ├── litellm/ │ ├── provider.go │ ├── resource_model.go │ ├── resource_model_crud.go │ ├── resource_team.go │ ├── resource_team_member.go │ ├── resource_key.go │ ├── resource_key_utils.go │ ├── types.go │ └── utils.go ├── main.go ├── go.mod ├── go.sum ├── Makefile └── ...对照仓库实际内容litellm/ 目录中每个资源都遵循resource_*.goSchemaresource_*_crud.go增删改查逻辑resource_*_test.go验收测试的三件套命名例如 resource_model_crud.go、resource_key_utils.go数据源同样是data_source_*.go 测试文件。开发流程按 README 说明克隆包含本目录的仓库进入terraform/provider/目录执行make install构建并安装 Provider。Makefile 提供的一组命令与源码一一对应命令作用实际执行make build构建 Providergo build -o terraform-provider-litellmmake install构建并安装默认目标安装到~/.terraform.d/plugins/registry.terraform.io/local/litellm/1.0.0/${OS_ARCH}/make test运行测试套件go test ./...make fmt格式化代码go fmt ./...make vet静态检查go vet ./...make lintgolangci-lintgolangci-lint runmake clean清理构建产物与已安装 Provider删除二进制与本地插件目录注意 Makefile 中NAMESPACElocal、OS_ARCHdarwin_amd64make install走的是本地插件开发目录local/litellm适合开发期配合dev_overrides使用正式分发的 Provider 源是 Registry 中的BerriAI/litellm。提 PR 前建议在本地先跑make test与make build这也是 RELEASING.md 对贡献者的要求变更以 PR 形式落入BerriAI/litellm附带CHANGELOG.md的[Unreleased]条目CI 会执行gofmt、go vet、构建、测试与端点漂移审计随后由下一次 LiteLLM 发布夜间的 dev 发布通常一天内自动带上。安全实践与注意事项综合 README Notes、model 资源文档的安全说明与 Provider Schema使用本 Provider 时应遵循以下准则敏感值优先走环境变量或密钥管理系统不要把 API 密钥、AWS 凭据硬编码在 HCL 文件里api_key等字段支持LITELLM_API_KEY等环境变量回退敏感属性在 state 中仍是明文model_api_key、aws_secret_access_key等 Sensitive 字段只是从 Terraform 输出中隐藏state 文件里仍是明文存储。文档建议将提供方密钥存入litellm_credential资源、在 model 资源中通过litellm_credential_name引用并保护 state 后端Provider 版本必须与 Proxy 版本保持同步见上文 Versioning 一节否则可能出现Provider 调用的端点在该 Proxy 版本上不存在或行为不同的漂移问题——这正是端点审计机制要在 CI 中拦截的所有示例配置已统一整合进 docs/ 目录便于组织与维护完整资源参数请以 docs/resources/ 下对应文档为准本项目遵循 Apache License 2.0 许可见 LICENSE。小结LiteLLM 的 Terraform Provider 把 Proxy 的整个管理面——模型注册、团队与组织、密钥与预算、护栏与访问组、MCP 服务器与向量存储——纳入了声明式管理。它的三个工程特点是选型时值得记住的其一Provider 版本与 LiteLLM 版本锁定、同 commit 构建并针对该版本 API 完成审计固定到 Proxy 版本线是唯一正确的用法其二tools/endpointaudit的静态端点审计 只可收缩的覆盖率允许列表从 CI 层面保证了 Provider 与 Proxy API 不漂移其三资源面覆盖 25 个可写资源与 33 个只读数据源配合additional_litellm_params的参数透传与类型强制转换能力足以把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考