Terraform Kubernetes Provider v3.3.0: Breaking Namespace Validation Change and Plugin Framework Migration

Introduction

HashiCorp released terraform-provider-kubernetes v3.3.0 on October 1, 2026. This release ships one breaking change around kubernetes_namespace_v1 metadata validation, three bug fixes (including a security-relevant dependency bump), and continues the provider's migration from terraform-plugin-sdk/v2 to terraform-plugin-framework. No previous version was tracked for comparison, so this article covers the full 3.3.0 changelog as published.

What Is New

Breaking change: stricter label/annotation validation on kubernetes_namespace_v1

Starting in 3.3.0, resource.kubernetes_namespace_v1 validates that every entry in metadata.labels and metadata.annotations is a non-null string. Configurations that previously set individual map entries to null will now fail during terraform plan. The map itself can still be omitted or set to null entirely — only null entries within a populated map are rejected. (GH-2979)

This config now fails planning:

resource "kubernetes_namespace_v1" "example" {
  metadata {
    name = "example"
    labels = {
      "team" = null # rejected starting in 3.3.0
    }
  }
}

Fix by omitting the null entry or supplying a string value:

resource "kubernetes_namespace_v1" "example" {
  metadata {
    name = "example"
    labels = {
      "team" = "platform" # or drop the key entirely
    }
  }
}

kubernetes_namespace_v1 migrated to the Plugin Framework

The resource moved from terraform-plugin-sdk/v2 to terraform-plugin-framework, keeping the same resource name and configuration block syntax. moved blocks from the deprecated kubernetes_namespace resource continue to work. HashiCorp notes that configurations with explicitly empty metadata maps may see a one-time in-place update after upgrading. (GH-2979)

moved {
  from = kubernetes_namespace.example
  to   = kubernetes_namespace_v1.example
}

Two data sources were also migrated to the Plugin Framework in this release:

• data.kubernetes_all_namespaces (GH-2962)
• data.kubernetes_namespace_v1 (GH-2960)

Bug fixes

• data.kubernetes_namespace_v1 now reports a missing metadata.name as a validation error instead of failing later during the namespace lookup. (GH-2960)
• kubernetes_stateful_set_v1 no longer throws a "Missing Resource Identity After Update" error when wait_for_rollout = true and the StatefulSet is updated in place. (GH-2967)
• The provider bumped google.golang.org/grpc to v1.82.1 and golang.org/x/crypto to v0.52.0, resolving upstream security advisories in those dependencies. (GH-2959)

Upgrade Steps

Pin the provider version and re-initialize:

terraform {
  required_providers {
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 3.3.0"
    }
  }
}

terraform init -upgrade

Before applying, run a plan to catch any kubernetes_namespace_v1 configs with null label/annotation entries, and review any namespace resources with explicitly empty metadata maps for the one-time in-place update mentioned above:

terraform plan -out=upgrade.tfplan

If plan fails validation on a namespace resource, search your HCL for null values inside labels/annotations maps and remove or replace them as shown above.

Verify

Confirm the provider version in use and that the plan succeeds cleanly:

terraform providers
terraform version
terraform plan

For StatefulSets using wait_for_rollout = true, trigger an in-place update and confirm the apply completes without the previous "Missing Resource Identity After Update" error.

Conclusion

v3.3.0 is mostly maintenance work — dependency security bumps, a StatefulSet rollout bug fix, and continued migration of namespace-related resources/data sources to the Plugin Framework — but the stricter metadata.labels/metadata.annotations validation on kubernetes_namespace_v1 is a real breaking change that can fail existing plans. Audit namespace resources for null map entries before upgrading, and run a plan-only pass first in CI to catch regressions.