LiteLLM Terraform Provider 版本演进全解：从 0.x 独立版本线到与 LiteLLM 锁步发布的版本史与升级实践

本文以仓库中 terraform/provider/CHANGELOG.md 为核心，完整梳理 LiteLLM Terraform Provider 从 1.0.0 初始发布到 0.x 版本线终结、再到"Provider 版本 = LiteLLM 版本"这一新发布模型的全部演进记录。读完你不仅能掌握未发布（Unreleased）批次中新增的十多种资源与数据源、关键安全修复（API 密钥不再落盘到 State）的迁移方法，还能结合 源码 与 发布流程文档 理解版本约束（~> 1.99.0）背后的锁步发布机制。

变更记录的格式与阅读方式

该 Provider 的变更日志采用 Keep a Changelog 格式组织：每个版本一个 ## [x.y.z] 标题，版本内部按 Added / Fixed / Changed / Breaking Changes 分节。文件开头的说明段落确立了两条最重要的阅读规则（见 CHANGELOG.md）：

1. 0.4.0 之前，Provider 拥有自己的独立版本线，版本号直接取自文件中的标题；
2. 从当前版本开始，Provider 改为按 LiteLLM 版本发布——每个 LiteLLM 发布通道（dev、rc、stable）都会发布一个与 Proxy 来自同一 commit 的 Provider。文件里的历史标题不再驱动任何发布，只是记录"什么变了、哪个 LiteLLM 版本线首次携带它"。因此，任何会破坏既有配置或 State 的变更，都必须在日志中显式、醒目地声明，因为版本号本身已经不能再承担"是否破坏兼容"的信号作用。

这也直接决定了使用者的操作习惯：升级 Provider 时不能只看 terraform plan，必须同步阅读 CHANGELOG 的 [Unreleased] 与对应 LiteLLM 版本条目。

Unreleased：待发布批次的完整变更清单

[Unreleased] 一节是本文档信息密度最高的部分，按 Added / Fixed / Changed 三组完整继承如下。

新增资源与数据源

JWT 密钥映射（litellm_jwt_key_mapping）：这是该批次最核心的新资源，用于管理 Proxy 的"JWT 声明到虚拟密钥"映射——由某个声明（client_id、azp、sub）识别出的 JWT 客户端将被映射到一个虚拟密钥，从而继承该密钥的模型白名单、预算与速率限制。支持 description 与 is_active 属性，可以对已映射的密钥原地轮换；当声明名或声明值变化时资源强制替换（ForceNew）。从源码 resource_jwt_key_mapping.go 可以看到对应的 schema 设计：

• jwt_claim_name / jwt_claim_value：必填、ForceNew，两者联合唯一，且 jwt_claim_name 必须与 Proxy JWT 配置中的 virtual_key_claim_field 一致；
• key：必填且 Sensitive。注释里明确说明"Proxy 只存储密钥的哈希且从不返回，因此该属性上的漂移无法被检测，Terraform 只跟踪配置值"；
• is_active：可选，默认 true，非激活的映射在 JWT 认证时被忽略；
• created_at / updated_at / created_by / updated_by：均为 Computed，由 Proxy 回填。

其余新增资源（每个都带同名单数/复数数据源，形成 litellm_x + litellm_xs 的对称结构）：

资源	用途	要点
litellm_user	内部管理用户	含 litellm_user / litellm_users 数据源
litellm_budget	可复用预算对象	含单数/复数数据源
litellm_tag	消费与路由标签	含单数/复数数据源
litellm_project	项目管理	含单数/复数数据源
litellm_guardrail	护栏	litellm_params 标记为 Sensitive，永不回读到 State
litellm_prompt	Prompt 模板	含单数/复数数据源
litellm_agent	A2A 智能体	含单数/复数数据源
litellm_search_tool	搜索工具	含单数/复数数据源
litellm_access_group / litellm_unified_access_group	访问组（两种模型）	各配单数/复数数据源
litellm_fallback	按模型的 fallback（general、上下文窗口、内容策略）	含数据源
litellm_key_block / litellm_team_block	管理既有 key 与 team 的封禁状态	删除资源即解除封禁
既有资源的补全数据源	litellm_key/litellm_keys、litellm_team/litellm_teams、litellm_model/litellm_models、litellm_organization/litellm_organizations、litellm_mcp_server/litellm_mcp_servers	支撑只读引用

从 litellm 目录 的文件组织看，每个资源都遵循 resource_*.go + *_test.go（以及部分 resource_*_crud.go）的拆分模式，数据源文档集中在 docs/data-sources/ 下，覆盖了 access_group、budget、guardrail、project、prompt、search_tool、tag、user、fallback、organization 等全部新增类型，与 CHANGELOG 的声明一一对应。

既有资源的新增参数：

• litellm_key 新增：budget_id、enforced_params、allowed_routes、allowed_passthrough_routes、rpm_limit_type、tpm_limit_type、prompts、organization_id、project_id；
• litellm_team 新增两组参数——本批次的 soft_budget、tags、soft_budget_alerting_emails（与 /team/new 和 /team/update 已接受的参数对齐，其中 soft_budget_alerting_emails 会放在 metadata 下传递，Proxy 从那里读取），以及更早批次的 model_aliases、guardrails、prompts、team_member_budget、team_member_budget_duration、team_member_rpm_limit、team_member_tpm_limit、team_member_key_duration、model_rpm_limit、model_tpm_limit、allowed_passthrough_routes、rpm_limit_type、tpm_limit_type。

导入支持：terraform import 扩展到 litellm_team、litellm_model、litellm_organization、litellm_mcp_server、litellm_vector_store 以及上述每一个新资源，存量 Proxy 实例可以渐进式纳入 IaC 管理。

修复项（Fixed）

这一节的修复集中在"读回 State 的准确性"，直接决定漂移（drift）检测是否有效：

• team：Read 现在会解码 /team/info 实际返回的 team_info 信封（envelope），团队属性从 Proxy 刷新，而不是每次都回落到上一份 State；
• key：Read 现在会解包 /key/info 实际返回的 info 信封；此前读操作什么都没映射回 State，key 上的漂移从未被检测过；
• key：更新不再发送空的 budget_duration（Proxy 会拒绝并返回 400）；此前任何对未配置 budget_duration 的 key 的更新都会直接失败。这与早期版本（0.3.9）中 BudgetDuration 缺少 omitempty 导致"Invalid duration format"的问题一脉相承，属于跨多个版本的顽疾修复；
• key：配置中显式提供的 key 值（write-only）现在会转发到 /key/generate；此前被静默丢弃，Proxy 总是自行生成随机密钥。

安全修复：明文密钥不再进入日志与 State

Unreleased 中最重要的安全条目：litellm_key 数据源与 litellm_key_block 资源在构造请求 URL 和资源 ID 之前，会把原始 sk- 密钥归一化为 SHA-256 token 哈希，使明文密钥不再出现在反向代理访问日志、Terraform plan 输出或 State ID 中。

这一实现可以直接在源码中验证：utils.go 中的 hashedKeyToken 函数对输入执行 sha256.Sum256 并生成 token 形式；data_source_key.go 的注释明确写着"按 SHA-256 token 哈希查询，原始 key 绝不出现"；resource_key_block.go 则接受"原始 sk- 值或其 SHA-256 哈希"作为输入并在内部归一化。测试用例（data_source_key_test.go）还专门断言"必须按哈希查询 /key/info，绝不能用原始 sk- 值"。

Changed：版本模型切换

[Unreleased] 的 Changed 节宣告了本文档的主线事件：Provider 现按 LiteLLM 版本发布，与 Proxy 同 commit 构建，随每个 LiteLLM 发布（dev、rc、stable）一起发布。0.x 版本线在 0.4.0 处终结；~> 0.4 这样的约束将永远收不到新发布，因此必须重新钉住你 Proxy 运行的 LiteLLM 版本（例如 ~> 1.99.0）。既有 0.x 版本仍保留在 Registry 中且校验有效。

0.4.0 与更早 0.x 版本线的关键记录

0.4.0（2026-08-06）：最后一次独立版本线发布

• Fixed：
  • organization：对 /organization/update 与 /organization/member_update 发送 PATCH 而非 POST，与 LiteLLM Proxy 实际提供的方法一致——此前组织和组织成员更新会以 405 失败；
  • team_member：更新载荷中纳入 role，既有 litellm_team_member 的角色变更现在会真正生效，而不是被静默丢弃。
• Changed：
  • 源码归属迁移：Provider 的事实源（source of truth）迁到 BerriAI/litellm 仓库的 terraform/provider/ 目录，独立仓库变成发布镜像。Monorepo 中的 CI 会静态审计 Provider 调用的每一个端点并对照 Proxy 的 OpenAPI schema，该审计实现在 tools/endpointaudit/（含 main.go、coverage.go 与 coverage_allowlist.txt），并且以反向方式作为覆盖率门禁运行：schema 中的每个管理端点必须被某个资源或数据源覆盖，或写入带注释的允许清单，过期的允许清单项会让 CI 失败。这就是 Provider"不会与 LiteLLM API 静默漂移"的机制保障（详见 README.md）；
  • mcp_server、vector_store：env 与 litellm_params 标记为 Sensitive，从 plan/apply 输出中脱敏，且不再从 API 回读到 State——配置值是唯一权威，如果 Proxy 返回值与配置不同，该漂移不再在 refresh 时呈现。使用这两个资源时要把配置当作唯一事实来源；
  • 依赖更新：grpc 与 golang.org/x 模块。

0.3.0（2026-07-13）：pricing_base_model

litellm_model 新增可选的 pricing_base_model 属性，独立于路由设置 model_info.base_model（成本表查找键）。路由名与计价键不一致的部署（例如路由为 azure/gpt-4.1、但按 us/gpt-4.1-2025-04-14 计价的场景）可以正确计费而不破坏路由；未设置时行为不变，base_model 同时驱动路由与计价。该条目注明是在"镜像仓库完成迁移之前发布"后回填到 Monorepo 变更日志的。

0.2.x 系列：修复与指针类型

• 0.2.2（2026-05-13）：UpdateKey 载荷纳入 tags，既有 key 的标签变更在更新时生效而非被静默丢弃；
• 0.2.1（2026-04-13）：team、organization 的 tpm_limit、rpm_limit、max_budget 改用指针类型，避免这些字段未配置时每次 terraform plan 都出现零值 diff——这是 Terraform SDK v2 中"可选数值字段必须用指针区分未设置与零值"的典型实践；
• 0.2.0（2026-04-03）：0.x 版本线中唯一的重破坏版本，下文专节展开。

0.2.0 重破坏变更：API 密钥不再存储到 Terraform State

这是整份变更日志中最值得精读的一条 Breaking Change（对应 0.2.0 条目），核心动机是安全：State 文件常被存储在 S3、Terraform Cloud 等后端，即使静态加密，原始密钥仍有暴露风险。该版本将其彻底消除：

1. key 属性变为 write-only——在 terraform apply 期间可用（便于管道送入密钥管理器），但永不持久化到 State；
2. 资源 ID 从原始密钥值改为 SHA-256 哈希（token_id）——可安全存储于 State 且无法用于认证；
3. 要求 Terraform 1.11+（write-only 属性是较新 SDK 能力）。

源码中可以直接看到这一设计：resource_key.go 里 key 字段声明为 Optional + WriteOnly + Sensitive，token_id 为 Computed，而 Read 中 d.Set("token_id", d.Id()) 表明资源 ID 本身就是 token_id（SHA-256 哈希）。

既有 litellm_key 资源的迁移步骤（原文档完整继承）：

1. 通过 LiteLLM UI 或 GET /key/info?key=<your-key> 查出每个密钥的 token_id；

2. 从 State 移除旧资源：

   terraform state rm litellm_key.example
   

3. 用 token_id 重新导入：

   terraform import litellm_key.example <token_id>
   

注意：升级后无法从 State 中取回原始密钥。迁移前必须确认密钥值已安全保存，或计划导入后轮换密钥。

安全最佳实践——由于密钥只在首次 terraform apply 时可用，建议直接管道进密钥管理器（原文档示例）：

resource "aws_ssm_parameter" "litellm_key" {
  name  = "/myapp/litellm-key"
  type  = "SecureString"
  value = litellm_key.example.key
}

0.1.x、0.3.x 与更早的模型参数演进

从 0.1.1 到 0.3.14 的条目记录了 litellm_model 资源参数能力的逐步扩展，也是理解当前 schema 的线索：

• 0.1.1（2026-02-11）：新增 audio_speech 与 rerank 两种模型模式（TTS 与语义重排序）；实现凭证读取的指数退避；成本字段仅在显式设置时下发；支持 litellm_credential_name；
• 0.3.14（2025-08-24）：additional_litellm_params 支持 JSON 字符串解析——以 { 或 [ 开头的值自动解析为对象/数组，兼容既有的字符串到类型转换，支持复杂嵌套参数配置；新增特殊参数 additional_drop_params（以 JSON 数组字符串指定，如 "additional_drop_params" = "[\"reasoningEffort\"]"），用于在提交 API 前从最终 litellm_params 中删除不想要的参数；
• 0.3.13（2025-08-24）：全量文档审计，补齐缺失的字段引用与默认值说明，新增可运行的 examples/ 目录（从 terraform/provider/examples/ 可以查看）；
• 0.3.12（2025-08-13）：模型资源新增 aws_session_name 与 aws_role_name，支持 Bedrock 跨账号访问场景；文档中向量存储部分收敛为 LiteLLM 官方支持的 Provider（Bedrock Knowledge Bases、OpenAI/Azure Vector Stores、Vertex AI RAG Engine、PG Vector）；
• 0.3.11 / 0.3.10：分别新增 litellm_credential（凭据，敏感值用 Terraform sensitive 处理）与 litellm_vector_store、litellm_mcp_server（支持 HTTP/SSE/stdio 传输、none/bearer/basic 认证、访问组与成本跟踪）；
• 0.3.9 → 0.3.6：一系列与"读回一致性"相关的修复——budget_duration 缺省时 omitempty（0.3.9）、模型创建后的事件一致性重试与延迟调优（0.2.8/0.2.9/0.3.0 早期）、从 Proxy 删除模型时 plan 应计划重建而非失败（0.3.6）；
• 0.2.4 → 0.2.7：thinking 能力（thinking_enabled 默认 false、thinking_budget_tokens 默认 1024）、merge_reasoning_content_in_choices，以及两者 State 保持的修复（0.2.7 修复了"每次都想 modify"的问题）；
• 0.2.2（2025-02-06）：reasoning_effort（low/medium/high）与 chat 模式；模型模式枚举扩展为 completion、embedding、image_generation、chat、moderation、audio_transcription；
• 1.0.0（2024-01-17）：Provider 初始发布，支持模型与团队/团队成员管理。

从日志的条目结构看，0.x 序列存在版本日期不完全单调的现象（例如 2025-08 的 0.3.14 早于 2026-02 的 0.1.1 条目），这正是"版本线已失去信息量"、必须切换到锁步版本的直接注脚。

新发布模型：Provider 版本 = LiteLLM 版本

结合 RELEASING.md 可以完整理解 CHANGELOG Changed 节所宣告的版本机制：

端到端发布流程：

1. 发布流水线解析待发布 commit（dev 取 main HEAD；rc/stable 取 main HEAD 或操作者指定 SHA）并通过审批门；
2. 组件化 terraform 作业把该 commit 的 terraform/provider/ 同步到镜像仓库，推送 v<litellm 版本> 标签（如 v1.99.0、v1.99.0-rc.1、v1.99.0-dev.1）；
3. 标签推送触发镜像仓库的 goreleaser 工作流：多平台构建、GPG 签名校验和、GitHub Release，全程无人值守；
4. 公共 Terraform Registry 从 GitHub Release 摄取该 Provider 版本。

版本号直译 LiteLLM 版本：稳定版 X.Y.Z、候选版 X.Y.Z-rc.N、夜航版 X.Y.Z-dev.N。它表达的是"该 Provider 与哪个 Proxy 一同发布、并被审计过"，不遵循 SemVer 的破坏性变更信号约定——破坏性变更只能靠 CHANGELOG 与 Registry 文档公告。0.1.0–0.4.0 属于该机制之前，保留在 Registry 的独立版本线上，~> 0.4 约束永远不会再收到新版本。

使用者侧的正确钉版方式（与 README.md 的 Using the Provider 节一致）：

terraform {
  required_providers {
    litellm = {
      source  = "BerriAI/litellm"
      version = "~> 1.99.0" # 你的 proxy 运行的 LiteLLM 版本
    }
  }
}

provider "litellm" {
  api_base = var.litellm_api_base
  api_key  = var.litellm_api_key
}

预发布版本（-rc、-dev 后缀）同样会发布，但只有精确钉住时才会被 Terraform 选中。

变更的落地路径（维护者视角，同样解释了为什么 Unreleased 条目重要）：变更须以 PR 形式落到 Monorepo 的 terraform/provider/ 并附 [Unreleased] 下的 CHANGELOG 条目，CI 运行 gofmt、go vet、构建、测试与端点漂移审计；本地可先跑 make test 与 make build（Makefile 还提供 fmt、vet、lint、clean）。次日夜航 dev 发布即可携带该变更，稳定版在下一次 stable 切版时到达。若发布需手工恢复（goreleaser 失败等），只能对既有标签重跑镜像仓库的 Release 工作流——标签不可变、发布拒绝覆盖既有标签。

升级与迁移要点小结

综合 CHANGELOG 全部条目，可以把该 Provider 的升级实践浓缩为五条可操作规则：

1. 先重钉版本：如果你的配置仍写 ~> 0.4 或任何 0.x 约束，把它改为 Proxy 实际运行的 LiteLLM 版本线（如 ~> 1.99.0）；0.x 线不会有任何新发布，但已发布版本仍可校验；
2. 重破坏变更看日志而非版本号：0.2.0 的密钥不落地 State、0.4.0 的 PATCH 方法与 env/litellm_params 不回读，都是版本号无法表达的兼容性变化，升级前逐条核对 [Unreleased] 与目标版本条目；
3. key 资源按 token_id 迁移：执行 terraform state rm + terraform import <token_id>，迁移前备份或计划轮换原始密钥；
4. mcp_server / vector_store 的配置是唯一权威：env、litellm_params 不回读，Proxy 侧改动不会反映到 plan；
5. 新资源批量纳管：借助本轮扩展的 terraform import 支持（team、model、organization、mcp_server、vector_store 及全部新资源），可以把存量 Proxy 实例渐进式迁入 IaC；涉及密钥的查询一律使用 SHA-256 token 哈希，让明文 sk- 密钥远离访问日志、plan 输出与 State ID。

以上结论均出自 terraform/provider/CHANGELOG.md 的原始条目，并以 README.md、RELEASING.md、litellm 资源源码 与 endpointaudit 工具 交叉印证，可作为该 Provider 版本选择、升级决策与安全迁移的完整依据。