LiteLLM Terraform Provider

This Terraform provider allows you to manage LiteLLM resources through Infrastructure as Code. It provides support for managing models, teams, team members, and API keys via the LiteLLM REST API.

Features

• Manage LiteLLM model configurations
• Associate models with specific teams
• Create and manage teams
• Configure team members and their permissions
• Set usage limits and budgets
• Control access to specific models
• Specify model modes (e.g., completion, embedding, image generation)
• Manage API keys with fine-grained controls
• Support for reasoning effort configuration in the model resource

Compatibility

• Terraform >= 1.1.0 (provider protocol 6.0)
• OpenTofu >= 1.6.0
• Go >= 1.24.0 for provider development
• Tested backend: exactly LiteLLM 1.104.0

The provider's global client baseline is Terraform 1.1.0 or OpenTofu 1.6.0. Terraform 1.0 is not supported because its ignore_changes planning behavior can erase the distinction between an omitted map and an explicitly empty map before the provider receives the configuration. The optional write-only attributes litellm_key.key_wo, litellm_key.send_invite_email, litellm_user.send_invite_email, and litellm_jwt_key_mapping.key_wo require Terraform or OpenTofu 1.11.0 or later only when they are configured.

Using the Provider

To use the LiteLLM provider in your Terraform configuration, you need to declare it in the terraform block:

terraform {
  required_version = ">= 1.1.0"

  required_providers {
    litellm = {
      source  = "registry.terraform.io/ncecere/litellm"
      version = ">= 2.0.1, < 3.0.0"
    }
  }
}

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

Run terraform init -upgrade (or tofu init -upgrade) after changing the version constraint. The published source is exactly registry.terraform.io/ncecere/litellm.

Correcting the provider binary's served address to that published source does not change protocol 6, provider or resource schemas, HCL types, state values, IDs, or import formats. Normal state created with the published ncecere/litellm source needs no migration. If development-only configuration actually recorded state under the unpublished registry.terraform.io/nicholas-cecere/litellm address, migrate it explicitly; the provider does not silently alias addresses:

terraform state replace-provider \
  registry.terraform.io/nicholas-cecere/litellm \
  registry.terraform.io/ncecere/litellm
# OpenTofu users can run the equivalent `tofu state replace-provider` command.

Then, you can use the provider to manage LiteLLM resources. Here's an example of creating a model configuration:

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
}

For full details on the litellm_model resource, see the model resource documentation.

Here's an example of creating an API key with various options:

resource "litellm_key" "example_key" {
  models               = ["gpt-4", "claude-3.5-sonnet"]
  allowed_routes       = ["/chat/completions", "/keys/*"]
  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-age=3600"]
  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"]
}

The litellm_key resource supports the following options:

• models: List of allowed models for this key
• allowed_routes / allowed_passthrough_routes: Restrict which LiteLLM proxy routes this key may call
• max_budget: Maximum budget for the key
• user_id and team_id: Associate the key with a user and team
• service_account_id: Create a team-owned service account key (defaults key_alias and injects metadata)
• max_parallel_requests: Limit concurrent requests
• tpm_limit and rpm_limit: Set tokens and requests per minute limits
• budget_duration: Specify budget duration (e.g., "monthly", "weekly")
• key_alias: Set a friendly name for the key
• duration: Set the key's validity period
• metadata: Add custom metadata to the key
• allowed_cache_controls: Specify allowed cache control directives
• soft_budget: Set a soft budget limit
• aliases: Define model aliases
• config: Set configuration options
• permissions: Specify key permissions
• model_max_budget, model_rpm_limit, model_tpm_limit: Set per-model limits
• guardrails: Apply specific guardrails to the key
• blocked: Flag to block/unblock the key
• tags: Add tags for organization and filtering

When team_id is set and models is omitted, the provider automatically allows the key to use all models in that team by sending ["all-team-models"] to the API.

For full details on the litellm_key resource, see the key resource documentation.

Available Resources

• litellm_model: Manage model configurations. Documentation
• litellm_key: Manage API keys. Documentation
• litellm_key_block: Block/unblock an API key. Documentation
• litellm_team: Manage teams. Documentation
• litellm_team_block: Block/unblock a team. Documentation
• litellm_team_member: Manage an individual team member. Documentation
• litellm_team_member_add: Manage a batch of team members. Documentation
• litellm_organization: Manage organizations. Documentation
• litellm_organization_member: Manage organization members. Documentation
• litellm_project: Manage projects (between teams and keys in the hierarchy). Documentation
• litellm_user: Manage users. Documentation
• litellm_budget: Manage reusable budgets and rate limits. Documentation
• litellm_tag: Manage tags for categorizing resources. Documentation
• litellm_access_group: Manage model access groups. Documentation
• litellm_unified_access_group: Manage access groups via the /v1/access_group API. Documentation
• litellm_fallback: Manage model fallback configuration. Documentation
• litellm_guardrail: Manage content-safety guardrails. Documentation
• litellm_prompt: Manage reusable prompt templates. Documentation
• litellm_agent: Manage LiteLLM Agents (A2A). Documentation
• litellm_search_tool: Manage web-search tool configurations. Documentation
• litellm_mcp_server: Manage MCP (Model Context Protocol) servers. Documentation
• litellm_credential: Manage credentials for secure authentication. Documentation
• litellm_vector_store: Manage vector stores for embeddings and RAG. Documentation
• litellm_jwt_key_mapping: Manage JWT string claim-to-existing-virtual-key mappings. Documentation

Available Data Sources

Single-item lookups:

• litellm_model (docs), litellm_key (docs), litellm_team (docs), litellm_organization (docs), litellm_project (docs), litellm_user (docs), litellm_budget (docs), litellm_tag (docs), litellm_access_group (docs), litellm_unified_access_group (docs), litellm_prompt (docs), litellm_guardrail (docs), litellm_agent (docs), litellm_search_tool (docs), litellm_fallback (docs), litellm_mcp_server (docs), litellm_credential (docs), litellm_vector_store (docs), litellm_jwt_key_mapping (docs)

List data sources (return all items of a type):

• litellm_models (docs), litellm_keys (docs), litellm_teams (docs), litellm_organizations (docs), litellm_projects (docs), litellm_users (docs), litellm_budgets (docs), litellm_tags (docs), litellm_access_groups (docs), litellm_unified_access_groups (docs), litellm_prompts (docs), litellm_guardrails (docs), litellm_agents (docs), litellm_search_tools (docs), litellm_mcp_servers (docs), litellm_jwt_key_mappings (docs)

Development

Project Structure

The project is organized as follows:

terraform-provider-litellm/
├── internal/
│   └── provider/               # the provider implementation (registered in main.go)
│       ├── provider.go         # provider schema + resource/data-source registration
│       ├── client.go           # LiteLLM API HTTP client
│       ├── resource_*.go       # resource implementations and helpers
│       ├── datasource_*.go     # data-source implementations and helpers
│       └── *_test.go           # unit tests
├── docs/                       # resource & data-source documentation
├── internal_testing/           # docker compose LiteLLM + smoke-test configs
├── main.go                     # provider entrypoint
├── go.mod
├── go.sum
├── Makefile
└── ...

Implementation and compatibility

This repository publishes a Terraform provider binary and its HCL interface; it is not a supported external Go library API. Provider implementation packages are internal details. The binary entry point in main.go serves only the Terraform Plugin Framework implementation in internal/provider.

The former top-level litellm/ Terraform Plugin SDKv2 implementation was left behind by the Framework migration and was never registered by the migrated provider binary. Removing that dead implementation does not require a state migration: the provider type name, registered resource and data-source type names, schema versions and types, state values and IDs, and import formats are unchanged. Provider source identity and the one development-only migration case are documented in Using the Provider.

The checked LiteLLM OpenAPI, hidden-route supplement, provider-operation golden, exact operation classification, separately reviewed pins, and offline Go verifier protect the provider's HTTP API boundary without adding any runtime Python or source dependency. See API contract maintenance for reproduction, upgrade review, and FastAPI/Pydantic limitations.

Building the Provider

1. Clone the repository:

git clone https://github.com/ncecere/terraform-provider-litellm.git

2. Enter the repository directory:

cd terraform-provider-litellm

3. Build and install the provider:

make install

The historical Go module identifier is retained for provider-build compatibility. This repository is distributed as a Terraform provider executable and does not expose a supported Go library API. Use registry.terraform.io/ncecere/litellm in Terraform or OpenTofu configurations rather than importing the Go module.

Development Commands

The Makefile provides several useful commands for development:

• make build: Builds the provider
• make install: Builds and installs the provider
• make test: Runs the test suite
• make fmt: Formats the code
• make vet: Runs go vet
• make contract-check: Verifies the checked LiteLLM API contract offline
• make contract-update: Regenerates the contract from the exact pinned upstream source
• make contract-diff: Reproduces and compares the pinned contract without modifying files
• make contract-update-atomicity-test: Verifies exclusive-writer locking plus rollback, permissions, signal/failure cleanup, concurrent interleavings, and stale-lock refusal
• make lint: Runs golangci-lint
• make clean: Removes build artifacts and installed provider

Testing

Unit tests

make test

Smoke tests (manual run against a local LiteLLM proxy) exercise real plan/apply/destroy for selected resources and data sources. Results are written to timestamped files under internal_testing/.smoke-logs/.

1. Start the proxy and DB: make local (runs docker compose up -d in internal_testing/).

2. Optionally follow logs: make logs.

3. Run smoke for one or more files (at least one of resources= or datasources= required, comma-separated):

   make smoke resources=model_minimal.tf
   make smoke datasources=keys_list.tf
   make smoke resources=model_minimal.tf,key_minimal.tf datasources=keys_list.tf,model.tf

   All listed files are applied in a single Terraform run (shared state). The harness builds the provider and copies its checked local test variables into an isolated private workspace.

4. Inspect the timestamped private log under internal_testing/.smoke-logs/.

See internal_testing/README.md for full details (Docker layout, directory structure, tfvars).

Contributing

Contributions are welcome! Please read our contributing guidelines first.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Notes

• Always use environment variables or secure secret management solutions to handle sensitive information like API keys and AWS credentials.
• Refer to the comprehensive documentation in the docs/ directory for detailed usage examples and configuration options.
• Make sure to keep your provider version updated for the latest features and bug fixes.
• The provider now supports AWS cross-account access with aws_session_name and aws_role_name parameters in the model resource.
• All example configurations have been consolidated into the documentation for better organization and maintenance.