LiteLLM Terraform 数据源 `litellm_users` 实战指南:分页拉取与管理控制台用户 📅 发布时间:2026/9/9 23:25:03 👁 浏览次数: LiteLLM Terraform 数据源litellm_users实战指南分页拉取与管理控制台用户【免费下载链接】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/litellmlitellm_users是官方 LiteLLM Terraform Provider 提供的只读数据源用于从 LiteLLM Proxy 的服务端分页检索用户列表并支持按角色、邮箱、团队等多维度的服务端过滤。通过本文你将掌握该数据源的完整参数语义、分页与排序机制、底层对/user/list接口的调用方式以及如何在真实 Terraform 工程中将其与团队、密钥等资源联动实现可复用的用户感知基础设施编排。一、数据源定位为什么需要litellm_usersLiteLLM Proxy 将不同 LLM 供应商统一到一套 OpenAI 风格接口之上并承担认证、预算、限流等职责。使用 Proxy 的组织通常会为内部人员创建大量用户internal_user和 API Key并把这些用户挂到不同团队、绑定不同模型与预算。当这些对象数量增多后管理员需要一种可编程的查询能力在 Terraform 编排中读取当前存在哪些用户、余额是否超标、归属哪个团队、各自持有哪些 Key。这正是litellm_users数据源的职责它不是创建或修改用户那是litellm_user资源的事而是只读地、按页地读取用户集合并把过滤逻辑尽量下推到服务端执行而不是在本地全量拉取后再过滤。它与单用户数据源litellm_user的差异在于数据源用途入参返回形态litellm_user按user_id精确读取单个用户user_id必填单个用户的完整属性含budget_duration、metadata、max_parallel_requests、model_max_budget等详情litellm_users分页浏览/批量检索用户集合角色、邮箱、团队、分页、排序当前页用户数组users、ids、total、total_pages两者在 Terraform Provider 中位于同一实现文件 data_source_user.go并在 provider.go 中完成注册。二、使用方式与完整示例litellm_users的全部入参均为可选最基础的用法是直接分页浏览internal_user角色的用户。官方文档提供的示例如下data litellm_users internal { role internal_user page 1 page_size 100 } output internal_user_ids { value data.litellm_users.internal.ids }该数据源可用在几乎任何 HCL 上下文中。下面给出一个更贴近生产场景的组合示例——先读取所有internal_user角色用户再据此为每个用户输出其邮箱、团队归属与已消费额度# 供应商与认证配置既可用环境变量 LITELLM_API_BASE / LITELLM_API_KEY # 也可在 provider 块中显式声明 api_base 与 api_key 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 } data litellm_users internal { role internal_user sort_by created_at sort_order desc } # 输出该页所有 user_id output user_ids { value data.litellm_users.internal.ids } # 逐条读取每个用户的核心信息 output users_report { value [ for u in data.litellm_users.internal.users : { id u.user_id email u.user_email role u.user_role teams u.teams spend u.spend max_budget u.max_budget key_count u.key_count } ] } # 统计信息过滤条件命中的用户总数 output matching_user_total { value data.litellm_users.internal.total }运行terraform plan/terraform apply后Provider 会在每次读取refresh/plan阶段访问 LiteLLM Proxy 管理 API并把结果写入 Terraform State。注意本数据源只读不会对 Proxy 上的用户做任何增删改适合用于output、for_each派生配置或作为其他资源引用的输入条件。三、参数参考Argument Reference数据源的 Schema 定义位于 data_source_user.go全部参数均为可选含义如下参数类型默认值说明rolestring无按用户在 Proxy 上的角色过滤例如internal_user等具体取值以你的 Proxy 部署中实际分配的角色为准user_idsstring无逗号分隔的用户 ID 列表用于按 ID 精确圈定查询范围user_emailstring无按邮箱部分匹配过滤用户partial email matchteamstring无按用户所属的团队 IDteam id过滤pagenumber1要获取的页码page_sizenumber25每页用户数量最大 100sort_bystring无排序字段例如user_id、user_email、created_atsort_orderstring无排序方向取值为asc或desc3.1 服务端过滤与本地返回的区别从实现上看userListQuery函数会将上述所有过滤/排序参数编码为 URL query string 并逐项透传给服务端见 data_source_user.gofunc userListQuery(d *schema.ResourceData) string { query : url.Values{} for _, key : range []string{role, user_ids, user_email, team, sort_by, sort_order} { if v, ok : d.GetOk(key); ok { query.Set(key, v.(string)) } } query.Set(page, strconv.Itoa(d.Get(page).(int))) query.Set(page_size, strconv.Itoa(d.Get(page_size).(int))) return query.Encode() }page与page_size始终会被显式写入查询串不传时落入 Schema 默认值1与25而其余过滤条件只有在确实设置过d.GetOk时才加入。也就是说过滤是在 LiteLLM Proxy 侧完成的Provider 只负责解析服务端返回的分页结果——这决定了total、total_pages等聚合字段反映的是匹配过滤条件的全部用户而不是先拉全量再做本地筛选。3.2 与单用户数据源的取舍如果你已经确切知道某个user_id并且需要读取更丰富的用户字段如budget_duration、metadata、model_max_budget、max_parallel_requests用litellm_user更直接——它精确命中/user/info接口并返回单个用户的完整信息litellm_users则更适合我需要一份名单 / 需要按条件圈选一批人的场景。四、返回属性参考Attribute Reference除过滤参数外数据源还提供以下计算属性Computed即完全由服务端返回推导属性类型说明userslist(object)当前请求页返回的用户数组每个元素包含下方列出的子字段idslist(string)当前页所有用户的user_id列表方便直接for/outputtotalnumber匹配当前过滤条件的用户总数跨页总计total_pagesnumber按当前page_size计算出的总页数users数组中的每个用户对象包含如下字段与 docs/data-sources/users.md 的 Attribute Reference 一一对应亦见源码中的嵌套 Schema data_source_user.go子字段类型说明user_idstring用户 IDuser_emailstring用户邮箱user_aliasstring用户的描述性名称user_rolestring用户在 Proxy 上的角色teamslist(string)该用户所属的团队 ID 列表modelslist(string)允许该用户调用的模型列表max_budgetnumber用户最大预算USDspendnumber用户当前已消费额度USDtpm_limitnumber每分钟 Token 数限制Tokens Per Minuterpm_limitnumber每分钟请求数限制Requests Per Minutekey_countnumber该用户拥有的 API Key 数量created_atstring用户创建时间戳4.1 类型映射细节来自源码的提示Provider 在解析服务端返回时对字段做了显式类型归一化见 data_source_user.go字符串字段user_id、user_email、user_alias、user_role、created_at仅在服务端返回 string 时写入浮点字段max_budget、spend仅当服务端按 JSON number 返回时写入整数字段tpm_limit、rpm_limit、key_count服务端常以 number 形式返回Provider 会将其转换为 Go 的int再写入 Terraform state列表字段teams、models直接透传服务端返回的数组。因此在 HCL 中访问u.teams、u.models时应按 list(string) 处理可用join(,, u.teams)或length(u.teams)等而u.spend、u.max_budget可直接参与数值比较或预算告警判断。五、数据源 ID 与分页心智模型一个值得注意的细节是数据源的 ID 规则。在dataSourceLiteLLMUsersRead中每次读取都会把当前查询串设置为资源 IDdata_source_user.god.SetId(fmt.Sprintf(users?%s, query)) d.Set(users, users) d.Set(ids, ids) d.Set(total, listResp.Total) d.Set(total_pages, listResp.TotalPages)含义是ID 本次分页快照的过滤条件。只要过滤参数不变数据源的 state 就稳定对应同一份查询视图一旦修改role/team/page/sort_*等参数查询串随之变化Terraform 会识别为不同数据集并触发重新读取。需要处理超过一页的数据比如用户总数超过page_size时推荐的 IaC 姿势是利用total_pages判断是否需要翻页或把page_size直接调到最大 100 以减少请求轮次。六、底层调用链与测试验证6.1 端点与请求构造该数据源在 HTTP 层面对应 LiteLLM Proxy 管理接口GET /user/list端点常量定义见 data_source_user.goconst endpointUserList /user/list实际的网络请求由 Provider 统一的 HTTP 客户端发出client.go认证方式是请求头x-api-key: 你的 LiteLLM admin key读取逻辑在 data_source_user.go 中func dataSourceLiteLLMUsersRead(d *schema.ResourceData, m interface{}) error { client : m.(*Client) query : userListQuery(d) resp, err : MakeRequest(client, GET, fmt.Sprintf(%s?%s, endpointUserList, query), nil) if err ! nil { return fmt.Errorf(failed to list users: %w, err) } defer resp.Body.Close() if err : handleResponse(resp, listing users); err ! nil { return err } var listResp userListResponse if err : json.NewDecoder(resp.Body).Decode(listResp); err ! nil { return fmt.Errorf(error decoding user list response: %w, err) } // ... }响应体结构userListResponse包含users、total、total_pages三段data_source_user.go与文档中 Attribute Reference 的users/total/total_pages完全对齐。若请求失败例如 admin key 权限不足、代理不可达handleResponse会返回错误并终止 plan/apply从而把 Proxy 侧的异常尽早暴露在 Terraform 流程内。6.2 单元测试对契约的固定Provider 仓库为这一行为编写了单元测试。在 data_source_user_test.go 中测试断言请求必须命中GET /user/list第 63 行用httptest起一个模拟 Proxy返回两个用户及total: 52、page_size: 50、total_pages: 2的分页响应随后调用dataSourceLiteLLMUsersRead验证users长度为 2、首个用户的user_id/spend/tpm_limit/key_count的类型与取值正确、第二个用户的teams为[team-x]、ids为[u-1,u-2]、total为 52。这组断言与上文第四节的类型映射说明互为印证文档即 Schema、Schema 即测试契约。6.3 版本与审计机制按照 terraform/provider/README.md 的说明本 Provider 的版本号与 LiteLLM Proxy 主版本保持同号发布例如1.99.0且terraform/provider/tools/endpointaudit/会对照 Proxy 生成的 OpenAPI schema 对 Provider 调用的每个端点做静态审计防止 Provider 与 LiteLLM API 静默漂移。因此在使用本数据源时建议把required_providers的version固定到与你实际运行的 Proxy 版本一致的主线如~ 1.99.0避免 Schema 字段或端点行为不一致。七、进阶用法与最佳实践7.1 巡检预算超标用户结合role、sort_order与users[*].spend/max_budget可在 Terraform 中直接生成一份消费审计清单data litellm_users audit { role internal_user page_size 100 sort_by spend sort_order desc } output over_budget_users { value [ for u in data.litellm_users.audit.users : u.user_email if u.max_budget 0 u.spend u.max_budget ] }7.2 用for_each派生单用户详情当名单本身需要二次精确查询例如想拿到批量模式下不返回的budget_duration/metadata时可把litellm_users的结果作为litellm_user的输入集合data litellm_users internal { role internal_user page 1 page_size 100 } data litellm_user detail { for_each toset(data.litellm_users.internal.ids) user_id each.value } output emails { value { for id, d in data.litellm_user.detail : id d.user_email } }注意for_each要求each.value是可用作集合键的字符串因此先取ids再转为toset是最稳妥的桥接方式。7.3 注意事项小结page_size上限为 100服务端对更大值会做约束超出一页请按页遍历user_ids是逗号分隔的字符串而非 HCL list若想从 list 转换可用join(,, var.user_ids)sort_by的可用字段取决于 Proxy/user/list实现文档与源码示例给出的是user_id、user_email、created_at这类常见列litellm_users与litellm_user一样只做读取不会对用户产生任何变更可安全放入 plan 频率很高的共享模块。八、关联文档与源码地图以下文件可直接在仓库中继续深入研读本文对应的官方参考文档terraform/provider/docs/data-sources/users.md单用户数据源参考terraform/provider/docs/data-sources/user.mdProvider 使用与供应商认证说明terraform/provider/docs/index.md数据源 Schema、查询构造与读取实现terraform/provider/litellm/data_source_user.go覆盖GET /user/list请求契约与字段解析的单元测试terraform/provider/litellm/data_source_user_test.go数据源在 Provider 中的注册位置terraform/provider/litellm/provider.goProvider 版本策略、端到端审计机制与开发命令terraform/provider/README.md【免费下载链接】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),仅供参考