Introduction

These Terraform resources all deal with Kubernetes ConfigMaps, but they do not represent exactly the same management scope. The main distinction is between resources that manage the whole ConfigMap object and the resource that manages only the data portion of an existing object.

kubernetes_config_map and kubernetes_config_map_v1

Both of these resources describe the ConfigMap object itself. In practice, the explicit v1 form follows the provider's newer naming style, where the Kubernetes API version appears in the resource name.

A full resource example looks like this:

1resource "kubernetes_config_map_v1" "app_config" {
2  metadata {
3    name      = "app-config"
4    namespace = "default"
5    labels = {
6      app = "demo"
7    }
8  }
9
10  data = {
11    LOG_LEVEL = "info"
12    REGION    = "ca-central-1"
13  }
14}

An older configuration might use the unversioned name:

1resource "kubernetes_config_map" "app_config" {
2  metadata {
3    name      = "app-config"
4    namespace = "default"
5  }
6
7  data = {
8    LOG_LEVEL = "info"
9  }
10}

Conceptually, both are full-object resources. They manage metadata, lifecycle, and the key-value content stored in the ConfigMap.

kubernetes_config_map_v1_data Is Narrower

kubernetes_config_map_v1_data is different because it does not claim ownership of the whole ConfigMap object. It targets the data field of an already-known ConfigMap.

1resource "kubernetes_config_map_v1_data" "app_config_data" {
2  metadata {
3    name      = "app-config"
4    namespace = "default"
5  }
6
7  data = {
8    FEATURE_FLAG = "enabled"
9    LOG_LEVEL    = "debug"
10  }
11}

That narrower scope matters when another tool or process already owns the rest of the object. For example, a Helm chart might create the ConfigMap and define labels or annotations, while Terraform updates only the entries under data.

Choose the Resource Based on Ownership

The correct choice is usually about ownership boundaries, not only naming preference.

Use a full ConfigMap resource when Terraform should own:

• creation and deletion of the ConfigMap
• metadata such as labels and annotations
• the actual data values

Use the data-only resource when Terraform should own:

• only the key-value entries in data
• updates to content without taking over the whole object lifecycle

This distinction reduces fights between tools. If Terraform thinks it owns the whole ConfigMap while Helm or another controller is also changing metadata, drift becomes inevitable.

Be Careful When Migrating Between Resource Types

Changing from kubernetes_config_map to kubernetes_config_map_v1, or from a full resource to the data-only resource, is not just a cosmetic edit. Terraform state also needs to match the new resource type.

If you switch resource types without planning the state transition, Terraform may attempt to recreate or re-adopt the object in an unexpected way. That can be disruptive in clusters where workloads depend on the ConfigMap.

So the migration question is:

• is this only a provider naming update
• or is Terraform's ownership model changing too

Those are different kinds of changes.

Common Pitfalls

• Assuming kubernetes_config_map_v1_data is just another spelling of the full ConfigMap resource.
• Managing the whole ConfigMap in Terraform when another tool already controls labels, annotations, or creation.
• Renaming resources from unversioned to versioned forms without thinking about Terraform state.
• Letting multiple tools rewrite the same ConfigMap without a clear ownership agreement.
• Treating the v1 suffix as a different Kubernetes object instead of a provider naming convention.

Summary

• 'kubernetes_config_map and kubernetes_config_map_v1 both represent the full ConfigMap object.'
• 'kubernetes_config_map_v1_data manages only the data field of an existing ConfigMap.'
• Choose the full resource when Terraform owns object lifecycle and metadata.
• Choose the data-only resource when Terraform should update content without taking over the whole object.
• When changing resource types, think about Terraform state and ownership boundaries, not only syntax.