Introduction

To bring an existing Kubernetes namespace under Terraform management, define the namespace resource in configuration first, then import the live namespace into state. The key detail is that you import by the namespace name, not by a long provider-specific ID.

Decide Whether You Should Import It at All

Not every existing namespace should be managed by Terraform. If the namespace is a system namespace such as kube-system, or if another controller owns its lifecycle, importing it can create unnecessary drift fights.

Import the namespace when:

• you want Terraform to own that namespace going forward,
• the namespace is application-specific,
• and you can tolerate Terraform reconciling its metadata.

If you only need to read the namespace or deploy resources into it, a data source or a plain string variable may be enough.

Define the Resource First

Terraform import attaches remote infrastructure to an existing resource block. That means you must write the resource before the import command.

With the Kubernetes provider, a minimal configuration looks like this:

1terraform {
2  required_providers {
3    kubernetes = {
4      source = "hashicorp/kubernetes"
5    }
6  }
7}
8
9provider "kubernetes" {
10  config_path = "~/.kube/config"
11}
12
13resource "kubernetes_namespace_v1" "app" {
14  metadata {
15    name = "my-app"
16  }
17}

If your codebase still uses the older unversioned kubernetes_namespace resource, the import idea is the same.

Import by Namespace Name

Once the resource block exists and the provider can reach the cluster, import the namespace:

terraform init
terraform import kubernetes_namespace_v1.app my-app

The final argument is the Kubernetes namespace name. After the import succeeds, the live namespace is recorded in Terraform state under kubernetes_namespace_v1.app.

Reconcile the Configuration After Import

Import does not write the full configuration for you. It only updates state. The next step is:

terraform plan

If the live namespace has labels or annotations that your configuration does not declare, Terraform may plan to remove or replace metadata you did not intend to manage.

A common workflow is:

1. import the namespace,
2. inspect it with terraform state show,
3. add the labels and annotations you actually want Terraform to manage,
4. rerun terraform plan until the diff is intentional.

Example With Managed Labels

If the namespace should keep specific labels, declare them explicitly:

1resource "kubernetes_namespace_v1" "app" {
2  metadata {
3    name = "my-app"
4
5    labels = {
6      team = "platform"
7      env  = "production"
8    }
9  }
10}

That way Terraform knows those labels are part of the desired state rather than accidental live metadata.

When Another System Mutates Metadata

Some clusters add or mutate annotations automatically. If another controller keeps changing metadata that Terraform should not own, consider using lifecycle.ignore_changes.

1resource "kubernetes_namespace_v1" "app" {
2  metadata {
3    name = "my-app"
4  }
5
6  lifecycle {
7    ignore_changes = [
8      metadata[0].annotations,
9      metadata[0].labels,
10    ]
11  }
12}

That is a pragmatic compromise when you need Terraform to know the namespace exists but do not want metadata churn to dominate every plan.

Use a Data Source if You Only Need to Reference It

If the namespace was generated by cluster bootstrap tooling and should remain owned elsewhere, it may be better to reference it rather than import it. Import is for adopting ownership, not just for discovering the namespace name.

That distinction prevents a lot of unnecessary state management.

Common Pitfalls

The most common mistake is running terraform import before creating the matching resource block. Terraform needs a target address in configuration before it can attach imported state.

Another mistake is importing the namespace and then skipping the reconciliation step. Import alone does not make the configuration accurate.

Teams also often import namespaces that are controlled by other systems. That leads to endless drift and surprise plans.

Finally, be careful with system namespaces. Terraform ownership is best reserved for namespaces your application team actually controls.

Summary

• Define the namespace resource in Terraform before importing it.
• Import the namespace by name, for example terraform import kubernetes_namespace_v1.app my-app.
• Run terraform plan after import and reconcile labels or annotations intentionally.
• Use ignore_changes only when another system legitimately owns mutable metadata.
• If you only need to reference the namespace, consider a data source or variable instead of import.