Namespace Management

This section provides guidance on managing Kubernetes namespaces throughout their lifecycle — creation, inspection, cleanup, and recovering namespaces that refuse to delete.

Overview

Namespaces partition a cluster into logical units for teams, environments, and applications. Most namespace operations are routine, but deletion in particular can go wrong in well-known ways: resources with finalizers, stuck controllers, or orphaned custom resources can leave a namespace in Terminating indefinitely. The guides in this section cover both the everyday operations and the systematic recovery procedures.

Key Topics

Cleanup Procedures

The Cleanup Procedures guide covers:

Standard namespace deletion and how to verify it completed
Identifying stuck resources and resources holding finalizers
Force-removal methods, from per-resource finalizer patches to clearing the namespace’s own finalizers
Special cases: persistent volumes, webhook configurations, and service account tokens

Follow the cleanup guide when a namespace needs to go and won’t.

Troubleshooting

The Troubleshooting guide covers:

Diagnosing namespaces stuck in Terminating state
Finding which resources and finalizers are blocking deletion
Resolving quota, limit-range, and RBAC issues scoped to a namespace
Recovering from partial deletions

See the troubleshooting guide for symptom-by-symptom solutions.

Common Commands

Frequently used commands for namespace operations:

# List namespaces with status
kubectl get namespaces

# Create a namespace
kubectl create namespace <namespace>

# Describe a namespace (status, conditions, quotas)
kubectl describe namespace <namespace>

# Delete a namespace (normal path)
kubectl delete namespace <namespace>

# Check why a namespace is stuck terminating
kubectl get namespace <namespace> -o json | jq '.status.conditions'

# List everything still alive in a namespace
kubectl api-resources --verbs=list --namespaced -o name \
  | xargs -n 1 kubectl get --show-kind --ignore-not-found -n <namespace>

# Set the namespace for the current context
kubectl config set-context --current --namespace=<namespace>

Namespace Lifecycle

A namespace moves through two phases:

Active — accepting and running resources normally.
Terminating — deletionTimestamp is set; Kubernetes deletes contained resources, waits for their finalizers, then removes the namespace’s own kubernetes finalizer. Anything that blocks a contained resource’s cleanup blocks the whole namespace — which is why finalizers are the first thing to check when deletion hangs.

Best Practices

Delete workloads (Deployments, StatefulSets, ArgoCD Applications) before deleting their namespace, so controllers can clean up in order
Check for resources with finalizers before deletion rather than after it hangs
Never remove a finalizer without understanding what cleanup it was protecting — orphaned external resources (volumes, load balancers) are the usual cost
Use labels on namespaces (team, environment) so bulk operations and policies stay manageable
Prefer namespace-scoped RBAC over cluster-wide grants for team access