Kubernetes Namespaces

Introduction & Overview

Learn how Kubernetes namespaces work, which resources are namespaced, cross-namespace DNS, how to split a cluster, and fix a namespace stuck Terminating.

A namespace is a name-scoping boundary inside a cluster. Two Deployments can both be called api as long as they live in different namespaces, and RBAC, quotas and network policy can all be applied per namespace.

What a namespace is not is a security boundary on its own. Pods in different namespaces can reach each other over the network by default, and they share the same nodes and kernel.

What is namespaced and what is not

The PV/PVC split is the one that catches people: a PersistentVolumeClaim is namespaced but the PersistentVolume it binds is not. So a claim can only be used by Pods in its own namespace, while the underlying volume is a cluster resource.

Secrets being namespaced is the other frequent surprise. A registry credential created in default does nothing for a Pod in payments.

kubectl api-resources --namespaced=true | head
kubectl api-resources --namespaced=false

The built-in namespaces

Avoid default for anything real. It has no quota, no network policy and no meaningful RBAC, and things accumulate there until nobody knows what is safe to delete.

Working with them

Set a default so you stop typing -n:

Forgetting the namespace is the most common reason kubectl get pods reports "No resources found" when something is definitely running.

Label your namespaces. They are the handle for network policy selectors, quota reporting and cost allocation, and adding them later means reconstructing who owns what.

kubectl create namespace payments

# or declaratively, which is what you want in Git
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Namespace
metadata:
  name: payments
  labels:
    team: payments
    environment: production
EOF

Cross-namespace DNS

A Service's short name only resolves within its own namespace. Across namespaces you need the namespace segment:

A call that works from one namespace and fails from another is nearly always this.

Where you genuinely want to alias a Service from elsewhere, an ExternalName Service does it without hardcoding the FQDN in application config:

payments-api                                    # same namespace
payments-api.payments                           # from another namespace
payments-api.payments.svc.cluster.local         # fully qualified

What namespaces are actually good for

RBAC. A Role and RoleBinding grant permissions within one namespace, which is how you give a team full control of its own space and nothing else:

Note the roleRef points at a ClusterRole while the binding itself is namespaced, that is the normal pattern for reusing the built-in view, edit and admin roles per namespace.

Resource quotas. Without one, any namespace can consume the whole cluster:

Pair it with a LimitRange, because once a quota constrains a resource every Pod must specify it or be rejected.

Network policy. This is what turns a namespace into an actual boundary. By default all Pods can reach all Pods; a default-deny policy plus explicit allows changes that:

Network policies require a CNI that implements them. Calico, Cilium, and similar. On a CNI that does not, the policy is accepted and silently does nothing, which is a dangerous way to believe you are protected.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: payments-team
  namespace: payments
subjects:
  - kind: Group
    name: payments-engineers
roleRef:
  kind: ClusterRole
  name: edit           # built-in: read/write most things, no RBAC changes
  apiGroup: rbac.authorization.k8s.io

How to divide a cluster

Common patterns, with their trade-offs:

What does not work is one namespace for everything. You lose quotas, per-team RBAC and any meaningful network policy, and everything ends up in default.

Deleting, and the Terminating trap

This deletes everything inside it. Deployments, Services, Secrets, ConfigMaps, and PVCs. A PVC whose StorageClass has reclaimPolicy: Delete takes its data with it. Deleting a namespace is one of the most destructive single commands in Kubernetes.

Sometimes it hangs in Terminating indefinitely. The cause is virtually always a finalizer on a resource whose controller is gone, commonly a custom resource left behind after its operator was uninstalled:

The correct fix is to remove the blocking resources or reinstall the operator so its finalizers can run:

Force-removing the namespace's own finalizer through the API is the widely-circulated trick, and it does work, but it orphans any resources that had not been cleaned up, including cloud load balancers and volumes that will keep billing. Treat it as a last resort and check for leftovers afterwards.

kubectl delete namespace payments

Key takeaways

A team puts an internal admin service in its own namespace, assuming other teams cannot reach it. Is that assumption correct on a default cluster?

A namespace has been Terminating for an hour. Its conditions report "Some resources are remaining: widgets.example.com has 2 resource instances". What is the correct first action?