Terraform 管理 LiteLLM 凭据(Credential)资源:从配置、CRUD 到安全实践 Terraform 管理 LiteLLM 凭据Credential资源从配置、CRUD 到安全实践【免费下载链接】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 中litellm_credential资源为核心原始文档见 terraform/provider/docs/resources/credential.md系统讲解如何在 LiteLLM Proxy 上集中管理 API Key、Token 等敏感认证信息并演示其如何被模型与向量库等资源安全引用。读完本文你将掌握litellm_credential的完整参数语义、Terraform 声明式写法、底层 CRUD 调用链、terraform import方式以及必须遵守的状态文件安全红线。为什么需要独立的 Credential 资源在 LiteLLM Proxy 的治理模型里模型model、向量库vector store等资源在发起真实请求时都需要携带各类云厂商与 AI 提供商的密钥。若把密钥直接内联在模型的litellm_params中会造成以下问题同一份密钥被多个资源重复粘贴后续轮换需要逐处修改密钥与非敏感配置混在一起难以审计、容易误提交缺少统一的加密存储与读取入口。为此LiteLLM Proxy 提供了 可复用凭据reusable credential机制把 API key、token 等敏感信息单独存为一条凭据记录再通过凭据名被其他资源引用。Provider 文档的定位说明是Manages a LiteLLM credential for storing sensitive authentication information. Credentials can be used to securely store API keys, tokens, and other sensitive data that can be referenced by models and vector stores.即litellm_credential用于存储敏感认证信息可被模型与向量库引用。对应的 litellm_credential Resource 文档 即本主题权威参考。资源字段说明Argument Referencelitellm_credential提供 4 个可配置参数在 resource_credential.go 中的 schema 定义与文档一致字段类型必填说明Schema 关键行为credential_namestring必填凭据名称作为该凭据的全局唯一标识Required ForceNew创建后不可就地改名Terraform 用它作为资源 IDcredential_valuesmap(string)必填敏感值集合如api_key、token、aws_secret_access_key等TypeMap Sensitive不出现在日志/输出中model_idstring可选与该凭据关联的模型 IDOptional仅用于将凭据与某个模型建立关联credential_infomap(string)可选额外的非敏感元信息如provider、region、purposeTypeMap建议只放描述性字段唯一导出的只读属性Attribute是credential_name——它同时充当资源主键在读取与导入时被当作 ID 使用。在设计上Provider 刻意将敏感值与非敏感信息拆成两张 mapcredential_values真正会被用于认证的密钥材料声明为 Sensitivecredential_info描述性元数据哪个云、哪个区域、什么用途用于可读性与检索不参与密钥认证。官方示例逐段详解场景一基础 OpenAI 凭据resource litellm_credential openai_cred { credential_name openai-api-key model_id gpt-4 credential_info { provider openai region us-east-1 purpose chat-completions } credential_values { api_key var.openai_api_key org_id var.openai_org_id } }该例展示了最典型的用法credential_name全局唯一model_id标记该凭据服务的是哪个模型这里为gpt-4credential_values通过变量var.openai_api_key、var.openai_org_id注入真实密钥避免在.tf中硬编码。场景二Anthropic 凭据resource litellm_credential anthropic_cred { credential_name anthropic-api-key credential_info { provider anthropic purpose text-generation } credential_values { api_key var.anthropic_api_key } }Anthropic 凭据结构更简单无需model_id密钥仅api_key一项。可见credential_info/credential_values都是开放字典具体键值由目标 provider 决定——这正体现了通用凭据容器的定位。场景三Pinecone 向量库凭据resource litellm_credential pinecone_cred { credential_name pinecone-production credential_info { provider pinecone environment production region us-east-1 } credential_values { api_key var.pinecone_api_key index_name document-embeddings } }向量库场景下credential_values中不仅包含api_key还可携带index_name这类与向量索引寻址相关的值。可见凭据不仅用于 LLM 供应商也同样用于 Pinecone 等向量存储后端。场景四凭据被向量库资源引用resource litellm_vector_store example { vector_store_name my-vector-store custom_llm_provider pinecone litellm_credential_name litellm_credential.pinecone_cred.credential_name vector_store_description Example vector store using Pinecone vector_store_metadata { environment production team ai-team } }这是凭据复用价值最直观的体现litellm_vector_store通过litellm_credential_name litellm_credential.pinecone_cred.credential_name引用上一步创建的凭据形成资源间依赖Terraform 会自动保证先创建凭据再创建向量库。litellm_credential是litellm_vector_store的独立前置资源vector store 的资源文档中同样有完整的多 provider 示例可参见 vector_store 资源文档。值得注意vector store 文档还明确提示不要把密钥放进litellm_params应存入litellm_credential再通过litellm_credential_name引用——与 credential 资源的设计意图完全一致。场景五多 Provider 凭据AWS Bedrock Azure OpenAI# AWS Bedrock credential resource litellm_credential aws_bedrock { credential_name aws-bedrock-cred credential_info { provider aws service bedrock region us-east-1 } credential_values { aws_access_key_id var.aws_access_key_id aws_secret_access_key var.aws_secret_access_key aws_region us-east-1 } } # Azure OpenAI credential resource litellm_credential azure_openai { credential_name azure-openai-cred credential_info { provider azure service openai } credential_values { api_key var.azure_openai_key api_base var.azure_openai_endpoint api_version 2023-12-01-preview } }该例演示如何在一份配置中同时管理多家云凭据AWS 场景需要aws_access_key_id/aws_secret_access_key/aws_regionAzure OpenAI 场景则需要api_key/api_base/api_version。密钥统一以var.*形式从外部注入。底层原理Terraform CRUD 与 Proxy REST API 的映射litellm_credential不是本地模拟资源而是一个围绕 LiteLLM Proxy REST API 的远程资源封装。要真正掌握它需要理解 Provider 侧每个生命周期函数对应哪个 HTTP 端点。核心 CRUD 实现在 resource_credential_crud.goTerraform 生命周期Provider 函数请求说明创建resourceLiteLLMCredentialCreatePOST /credentials请求体由CredentialRequest结构化见 types.go读取刷新resourceLiteLLMCredentialReadGET /credentials/by_name/{name}?model_id按名称查询model_id非空时追加 query 参数404 视为不存在并清空 ID更新resourceLiteLLMCredentialUpdatePATCH /credentials/{name}就地更新凭据内容删除resourceLiteLLMCredentialDeleteDELETE /credentials/{name}删除后清空 ID若返回credential_not_found视为幂等成功导入ImportStatePassthroughContext—直接把导入参数作为 ID见 resource_credential.go服务端端点在 litellm/proxy/credential_endpoints/endpoints.py 中实现标签为credential management。其创建端点注释明确标注[BETA] endpoint. This might change unexpectedly.说明该接口仍处于演进期端点内部先入库、再把凭据重载进内存litellm.credential_list确保新凭据对后续请求即刻生效。与路由路径保持一致的是数据库模型Proxy 使用 Prisma 的LiteLLM_CredentialsTable见 litellm/proxy/schema.prisma其中credential_name String unique是唯一键、credential_values Json保存加密后的敏感值、credential_info Json?保存元数据并记录created_by/updated_by便于审计。这解释了为什么credential_name必须全局唯一它同时是 REST 查询主键与数据库唯一约束。几个值得注意的实现细节读取不回读敏感值。在 resourceLiteLLMCredentialRead 中Provider 只把credential_name与credential_info写回 Terraform state注释明确说明出于安全原因不从响应中设置credential_valuesAPI 可能不返回敏感值我们希望保留 state 中已有的内容。这与 Proxy 侧加密存储的设计相辅相成敏感值只进不出写入后永远以 state 中记录的版本为准。数据源不暴露密钥。Provider 还提供了对应的 data source读取实现见 data_source_credential.go用于查询已存在的凭据元信息。其 schema 注释同样强调出于安全原因data source 不暴露credential_values——因此你可以在.tf中安全引用data.litellm_credential.*.credential_name做依赖编排但无法也不应从中取回明文密钥。创建/更新后带指数退避的补偿读取。由于服务端采用先落库、再重载内存的异步刷新模型创建/更新后立即读取可能遇到短暂的 404。Provider 因此实现了retryCredentialReadresource_credential_crud.go最多重试 5 次退避从 1 秒翻倍至上限 10 秒当读取将 ID 清空瞬时 404时先恢复原 ID 再按credential_not_found重试。单元测试 resource_credential_crud_test.go 覆盖了首读成功、多次重试后成功、重试耗尽、非可重试错误如 500立即失败、ID 恢复等多个分支——这些测试也反向印证了 provider 的读写时序语义。模型侧同样通过凭据名引用。在模型资源的 schema 与 CRUD 中resource_model.go 与 resource_model_crud.golitellm_credential_name会被写入模型的litellm_params。因此凭据体系完整覆盖两条引用链模型model - credential与向量库vector store - credential。将已存在的凭据纳入 Terraform 管理Import如果凭据已在 Proxy 上通过 UI/CLI/API 创建可以用 import 命令将其纳入 Terraform 管理无需重建terraform import litellm_credential.example credential-name参数即凭据名称与资源credential_name对应。命令执行后 Terraform 会调用读取逻辑GET /credentials/by_name/{name}把现有凭据同步进 state同样地credential_values不会被回读需保证 .tf 中声明的credential_values与实际一致避免后续 apply 时产生非预期 diff。安全注意事项务必逐条核对文档在 Security Considerations 中给出了四条必须遵守的约束这里结合实现逐一展开1. 敏感字段不会出现在输出与日志中。credential_values在 schema 中标记为Sensitive: trueresource_credential.goTerraform 会在 plan/apply 输出与 provider 日志中做掩码处理降低密钥意外泄漏到 CI 日志或终端记录的风险。2. 敏感值不读回保存在 state 中。由于 Proxy 出于安全考虑不返回明文读取时也不回填Terraform 必须把配置中的credential_values持久化在 state 内才能支持后续 diff 与更新。这意味着 state 是这些密钥在 Terraform 侧的唯一事实来源。3. 凡标为Sensitive的属性state 中仍是明文。Terraform 的Sensitive标记只影响展示层不代表加密存储。state 文件以及 plan 文件等衍生产物中实际以明文保存这些值任何能读取 state 的人都能还原出密钥。因此必须使用加密的远程后端如 S3 KMS、Terraform Cloud/Enterprise 加密存储等保存 state对 state 的读取权限做严格的最小化授权防止生产 state 被开发机随意下载审慎对待 plan 文件等同样可能夹带敏感值的中间产物。4. 密钥优先经变量从 Secret Manager 注入而非硬编码。本主题全部示例都采用var.openai_api_key这类变量引用配合 CI 的 secret 环境变量、Vault 等密钥管理系统取值切勿把真实密钥直接写死在.tf源码中否则会随代码库一同扩散。此外服务端在写入前会对credential_values做加密处理endpoints.py 中通过encrypt_value_helper逐项加密后再落库因此真正存进 Proxy 数据库的是密文——即便这一层保护存在Terraform state 一侧的明文风险仍须由使用者自行管控。小结推荐的最佳实践组合所有 LLM/向量库供应商的密钥统一抽象为litellm_credential一个 provider 一个资源实例命名带环境语义如openai-api-key、pinecone-production非敏感描述信息放入credential_info敏感材料放入credential_values密钥一律经var.*注入模型与向量库一律通过litellm_credential_name引用凭据禁止在litellm_params等字段内散落明文密钥存量凭据用terraform import litellm_credential.example credential-name纳入管理state 强制使用加密远程后端并收紧访问控制对 plan 等衍生产物同样警惕轮换密钥时只需修改对应litellm_credential的credential_values并terraform apply服务端会通过 PATCH 端点完成更新并重载内存凭据列表引用方无需改动。通过这套组合可以在 Terraform 中实现密钥的集中存储、声明式管理、引用解耦与最小暴露为生产环境的多模型、多向量库治理打下安全基座。【免费下载链接】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),仅供参考