fix(provider): resolve unknown values after apply for all resources

Fix 'Provider produced inconsistent result after apply' and 'unknown
values after apply' errors across all 19 resources. Fixes #53.

Code fixes:
- Unwrap nested API responses (key/info, team/team_info, etc.)
- Change IsNull() else-clause zeroing to IsUnknown() checks
- Only set API-injected defaults when user originally configured them
- Remove server-side runtime fields from resource schemas
- Add UseStateForUnknown plan modifiers for stable computed fields
- Fix organization update to use PATCH instead of POST
- Fix guardrail litellm_params to only store user-configured keys
- Fix search_tool to parse search_tool_info JSON before sending
- Expand mcp_server auth_type validator to include all API values

Documentation:
- Rewrite all 18 resource docs to match actual Go schemas
- Rewrite all 21 data source docs to match actual Go schemas
- Fix examples with outdated attribute names and values
- Remove YAML frontmatter, standardize code block language to hcl

Testing:
- All 12 unit tests pass
- All 19 resources verified via live integration testing

Author: Nicholas Cecere

CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.4] - 2026-02-11
+
+### Fixed
+- **All resources**: Resolved "Provider produced inconsistent result after apply" and "unknown values after apply" errors caused by three systemic bug patterns across the provider ([#53](https://github.com/ncecere/terraform-provider-litellm/issues/53)):
+
+  **Pattern 1 — API response nesting:** Read functions accessed fields from the top-level response, but the LiteLLM API nests data under wrapper keys (e.g., `/key/info` returns `{"info": {...}}`, `/vector_store/info` returns `{"vector_store": {...}}`). Added unwrapping logic to all affected resources and datasources.
+  - `litellm_key`, `litellm_team`, `litellm_organization` (resources and datasources)
+  - `litellm_vector_store`
+
+  **Pattern 2 — Else-clause zeroing (`!IsNull()` → `IsUnknown()`):** When the API didn't echo back a field, `else if !data.X.IsNull()` clauses zeroed out user-configured values to empty lists/maps, contradicting the planned value. Changed all such clauses to `else if data.X.IsUnknown()` so concrete config values are preserved.
+  - `litellm_organization`: `models`, `tags`, `metadata`, `model_rpm_limit`, `model_tpm_limit`
+  - `litellm_mcp_server`: `mcp_access_groups`, `args`, `env`, `credentials`, `allowed_tools`, `extra_headers`, `static_headers`, `tool_name_to_cost_per_query`
+  - `litellm_vector_store`: `vector_store_metadata`, `litellm_params`
+  - `litellm_key`: `model_rpm_limit`, `model_tpm_limit`
+  - `litellm_team`: `model_aliases`, `model_rpm_limit`, `model_tpm_limit`
+  - `litellm_model`: `access_groups`
+
+  **Pattern 3 — API-injected defaults appearing in state:** The API returns default values for fields the user never configured (e.g., `budget_id`, `alias`, `allow_all_keys`, `mcp_info`, server-injected metadata keys). These caused "was null, but now has value" errors. Fixed by only setting these fields in state when the user originally configured them.
+  - `litellm_key`: `budget_id`, `metadata` (filters server-injected `tpm_limit_type`/`rpm_limit_type`)
+  - `litellm_team`: `metadata` (same filtering)
+  - `litellm_organization`: `budget_id`
+  - `litellm_mcp_server`: `alias`, `description`, `command`, `allow_all_keys`, `authorization_url`, `token_url`, `registration_url`, `mcp_info` block
+  - `litellm_guardrail`: `default_on`, `litellm_params`
+  - `litellm_vector_store`: `litellm_params` (filters server-injected keys)
+
+- **`litellm_key`**: Fixed scalar `Optional+Computed` fields (`max_budget`, `tpm_limit`, `rpm_limit`, `max_parallel_requests`, `soft_budget`, `blocked`) remaining Unknown after apply when API returned null. Added explicit Unknown-to-Null resolution.
+- **`litellm_organization`**: Fixed `blocked` remaining Unknown after apply.
+- **`litellm_vector_store`**: Fixed create failing with "`where.vector_store_id`: A value is required" by generating a UUID client-side. Fixed create failing with `'litellm_params'` error by always sending `litellm_params` (even if empty) as the API requires it.
+- **`litellm_search_tool`**: Fixed create/update requests not wrapped in `{"search_tool": {...}}` as the API requires. Fixed response parsing to unwrap nested `"search_tool"` key.
+- **`litellm_tag`**: Fixed read function to handle changed API response format (`/tag/info` returns `{"tag-name": {...}}` map instead of array).
+- **`litellm_key_block`**, **`litellm_team_block`**: Added `UseStateForUnknown` plan modifiers for immutable computed attributes (`created_at`, `created_by`, `key`, `blocked`).
+
+### Removed
+- **All resources**: Removed server-side runtime metrics from resource schemas (`spend`, `updated_at`, `status`, `budget_reset_at`, `models_updated`) that change outside Terraform and cause perpetual drift. These remain available in datasources.
+
+### Added
+- Regression tests for key and team readback behavior with nested API responses.
+- Internal testing infrastructure (`internal_testing/`) with Docker Compose stack (LiteLLM proxy + Postgres 16) and Terraform test files for all 19 resources and 27 datasources.
+
 ## [1.0.3] - 2026-02-09
 
 ### Fixed

docs/data-sources/access_group.md

@@ -4,50 +4,27 @@ Retrieves information about a specific LiteLLM access group.
 
 ## Example Usage
 
-### Minimal Example
-
 ```hcl
 data "litellm_access_group" "existing" {
-  access_group_id = "premium-models"
-}
-```
-
-### Full Example
-
-```hcl
-data "litellm_access_group" "enterprise" {
-  access_group_id = "enterprise-tier"
+  access_group = "premium-models"
 }
 
-output "access_group_info" {
-  value = {
-    name    = data.litellm_access_group.enterprise.access_group_name
-    members = data.litellm_access_group.enterprise.members
-  }
+output "models_in_group" {
+  value = data.litellm_access_group.existing.model_names
 }
 
 # Create team with same model access
-resource "litellm_team" "enterprise_team" {
-  team_alias = "enterprise-users"
-  models     = data.litellm_access_group.enterprise.members
+resource "litellm_team" "premium_team" {
+  team_alias = "premium-users"
+  models     = data.litellm_access_group.existing.model_names
 }
 ```
 
 ## Argument Reference
 
-The following arguments are supported:
-
-* `access_group_id` - (Required) The unique identifier of the access group to retrieve.
+* `access_group` - (Required) The name of the access group to look up.
 
 ## Attribute Reference
 
-The following attributes are exported:
-
 * `id` - The unique identifier of the access group.
-* `access_group_id` - The access group ID.
-* `access_group_name` - The human-readable name.
-* `description` - Description of the access group.
-* `members` - List of model names included in this access group.
-* `metadata` - JSON string containing additional metadata.
-* `created_at` - Creation timestamp.
-* `updated_at` - Last update timestamp.
+* `model_names` - List of model names included in this access group.

docs/data-sources/access_groups.md

@@ -4,14 +4,6 @@ Retrieves a list of all LiteLLM access groups.
 
 ## Example Usage
 
-### Minimal Example
-
-```hcl
-data "litellm_access_groups" "all" {}
-```
-
-### Full Example
-
 ```hcl
 data "litellm_access_groups" "all" {}
 
@@ -20,20 +12,16 @@ output "access_group_count" {
 }
 
 output "access_group_names" {
-  value = [for g in data.litellm_access_groups.all.access_groups : g.access_group_name]
+  value = [for g in data.litellm_access_groups.all.access_groups : g.access_group]
 }
 
-# Find groups with GPT-4 access
+# Find groups containing a specific model
 locals {
   gpt4_groups = [
     for g in data.litellm_access_groups.all.access_groups : g
-    if contains(g.members, "gpt-4")
+    if contains(g.model_names, "gpt-4-proxy")
   ]
 }
-
-output "groups_with_gpt4" {
-  value = [for g in local.gpt4_groups : g.access_group_name]
-}
 ```
 
 ## Argument Reference
@@ -42,13 +30,7 @@ This data source has no required arguments.
 
 ## Attribute Reference
 
-The following attributes are exported:
-
 * `id` - Placeholder identifier.
 * `access_groups` - List of access group objects, each containing:
-  * `access_group_id` - The unique identifier.
-  * `access_group_name` - The human-readable name.
-  * `description` - Description.
-  * `members` - List of model names.
-  * `created_at` - Creation timestamp.
-  * `updated_at` - Last update timestamp.
+  * `access_group` - The access group name.
+  * `model_names` - List of model names in this access group.

docs/data-sources/budget.md

@@ -4,55 +4,40 @@ Retrieves information about a specific LiteLLM budget configuration.
 
 ## Example Usage
 
-### Minimal Example
-
 ```hcl
 data "litellm_budget" "existing" {
   budget_id = "monthly-budget"
 }
-```
-
-### Full Example
-
-```hcl
-data "litellm_budget" "production" {
-  budget_id = "production-budget"
-}
 
 output "budget_info" {
   value = {
-    max_budget      = data.litellm_budget.production.max_budget
-    soft_budget     = data.litellm_budget.production.soft_budget
-    budget_duration = data.litellm_budget.production.budget_duration
+    max_budget      = data.litellm_budget.existing.max_budget
+    soft_budget     = data.litellm_budget.existing.soft_budget
+    budget_duration = data.litellm_budget.existing.budget_duration
   }
 }
 
 # Use budget configuration for a new team
 resource "litellm_team" "new_team" {
   team_alias      = "new-department"
-  max_budget      = data.litellm_budget.production.max_budget * 0.5
-  budget_duration = data.litellm_budget.production.budget_duration
+  max_budget      = data.litellm_budget.existing.max_budget * 0.5
+  budget_duration = data.litellm_budget.existing.budget_duration
 }
 ```
 
 ## Argument Reference
 
-The following arguments are supported:
-
 * `budget_id` - (Required) The unique identifier of the budget to retrieve.
 
 ## Attribute Reference
 
-The following attributes are exported:
-
 * `id` - The unique identifier of the budget.
 * `budget_id` - The budget ID.
 * `max_budget` - Maximum budget amount.
 * `soft_budget` - Soft budget limit for alerts.
-* `budget_duration` - Budget reset duration (daily, weekly, monthly).
+* `budget_duration` - Budget reset duration (e.g., "daily", "weekly", "monthly").
 * `tpm_limit` - Tokens per minute limit.
 * `rpm_limit` - Requests per minute limit.
 * `max_parallel_requests` - Maximum parallel requests allowed.
 * `model_max_budget` - JSON string of per-model budget limits.
-* `created_at` - Creation timestamp.
-* `updated_at` - Last update timestamp.
+* `budget_reset_at` - Datetime when the budget is next reset.

docs/data-sources/budgets.md

@@ -4,14 +4,6 @@ Retrieves a list of all LiteLLM budget configurations.
 
 ## Example Usage
 
-### Minimal Example
-
-```hcl
-data "litellm_budgets" "all" {}
-```
-
-### Full Example
-
 ```hcl
 data "litellm_budgets" "all" {}
 
@@ -30,15 +22,6 @@ locals {
 output "high_value_budget_ids" {
   value = [for b in local.high_value_budgets : b.budget_id]
 }
-
-# Calculate total budget allocation
-locals {
-  total_budget = sum([for b in data.litellm_budgets.all.budgets : b.max_budget])
-}
-
-output "total_allocated_budget" {
-  value = local.total_budget
-}
 ```
 
 ## Argument Reference
@@ -47,13 +30,13 @@ This data source has no required arguments.
 
 ## Attribute Reference
 
-The following attributes are exported:
-
 * `id` - Placeholder identifier.
 * `budgets` - List of budget objects, each containing:
   * `budget_id` - The unique identifier.
   * `max_budget` - Maximum budget amount.
   * `soft_budget` - Soft budget limit.
+  * `max_parallel_requests` - Maximum parallel requests allowed.
+  * `tpm_limit` - Tokens per minute limit.
+  * `rpm_limit` - Requests per minute limit.
   * `budget_duration` - Budget reset duration.
-  * `created_at` - Creation timestamp.
-  * `updated_at` - Last update timestamp.
+  * `model_max_budget` - JSON string of per-model budget limits.

docs/data-sources/credential.md

@@ -1,18 +1,10 @@
----
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "litellm_credential Data Source - terraform-provider-litellm"
-subcategory: ""
-description: |-
-  Retrieves information about an existing LiteLLM credential.
----
-
 # litellm_credential (Data Source)
 
 Retrieves information about an existing LiteLLM credential. This data source allows you to reference credentials that were created outside of Terraform or in other Terraform configurations.
 
 ## Example Usage
 
-```terraform
+```hcl
 # Retrieve an existing credential by name
 data "litellm_credential" "existing_openai" {
   credential_name = "openai-production-key"
@@ -35,7 +27,7 @@ resource "litellm_model" "gpt4_with_existing_cred" {
 
 ## Example Usage with Model ID
 
-```terraform
+```hcl
 # Retrieve a credential associated with a specific model
 data "litellm_credential" "model_specific_cred" {
   credential_name = "claude-api-key"
@@ -54,7 +46,7 @@ resource "litellm_vector_store" "knowledge_base" {
 
 ## Example Usage for Cross-Reference
 
-```terraform
+```hcl
 # Get credential info to use in other resources
 data "litellm_credential" "shared_cred" {
   credential_name = "shared-api-key"
@@ -100,7 +92,7 @@ For security reasons, the `credential_values` (sensitive data like API keys) are
 ### 1. Cross-Stack References
 Use data sources to reference credentials created in other Terraform configurations or stacks:
 
-```terraform
+```hcl
 data "litellm_credential" "shared_openai" {
   credential_name = "openai-shared-key"
 }
@@ -119,7 +111,7 @@ resource "litellm_model" "gpt4" {
 ### 2. Conditional Logic
 Use credential information for conditional resource creation:
 
-```terraform
+```hcl
 data "litellm_credential" "optional_cred" {
   credential_name = var.credential_name
 }
@@ -136,7 +128,7 @@ resource "litellm_vector_store" "conditional_store" {
 ### 3. Validation and Verification
 Verify that required credentials exist before creating dependent resources:
 
-```terraform
+```hcl
 data "litellm_credential" "required_cred" {
   credential_name = "production-api-key"
 }
@@ -151,3 +143,4 @@ resource "litellm_model" "production_model" {
     credential_name = data.litellm_credential.required_cred.credential_name
   }
 }
+```

docs/data-sources/guardrail.md

@@ -4,44 +4,34 @@ Retrieves information about a specific LiteLLM guardrail configuration.
 
 ## Example Usage
 
-### Minimal Example
-
 ```hcl
 data "litellm_guardrail" "existing" {
-  guardrail_name = "content-safety"
-}
-```
-
-### Full Example
-
-```hcl
-data "litellm_guardrail" "safety_filter" {
-  guardrail_name = "content-safety-filter"
+  guardrail_id = "my-guardrail-id"
 }
 
 output "guardrail_info" {
   value = {
-    name   = data.litellm_guardrail.safety_filter.guardrail_name
-    config = data.litellm_guardrail.safety_filter.litellm_params
+    name       = data.litellm_guardrail.existing.guardrail_name
+    guardrail  = data.litellm_guardrail.existing.guardrail
+    mode       = data.litellm_guardrail.existing.mode
+    default_on = data.litellm_guardrail.existing.default_on
   }
 }
 ```
 
 ## Argument Reference
 
-The following arguments are supported:
-
-* `guardrail_name` - (Required) The name of the guardrail to retrieve.
+* `guardrail_id` - (Required) The unique identifier of the guardrail to retrieve.
 
 ## Attribute Reference
 
-The following attributes are exported:
-
 * `id` - The unique identifier of the guardrail.
 * `guardrail_id` - The guardrail ID.
-* `guardrail_name` - The guardrail name.
-* `litellm_params` - JSON string containing guardrail configuration.
-* `description` - Description of the guardrail.
-* `metadata` - JSON string containing additional metadata.
+* `guardrail_name` - Human-readable name for the guardrail.
+* `guardrail` - The guardrail integration type (e.g., "aporia", "bedrock", "lakera").
+* `mode` - When to apply the guardrail (e.g., "pre_call", "post_call", "during_call", or a JSON array of modes).
+* `default_on` - Whether the guardrail is enabled by default for all requests.
+* `litellm_params` - JSON string containing additional provider-specific parameters.
+* `guardrail_info` - JSON string containing additional guardrail metadata.
 * `created_at` - Creation timestamp.
 * `updated_at` - Last update timestamp.