Kubernetes explained
Kubernetes Namespaces: What They Do and Do Not Isolate
A Kubernetes namespace is a named scope inside one cluster. Names of most objects only need to be unique inside their namespace, and you can apply quotas and access rules per namespace. A namespace does not create a separate cluster and does not, by itself, stop pods in one namespace from talking to pods in another.
By Muhammad Soliman, Founder at SeaGit
·
Key takeaways
- Names must be unique within a namespace for a given kind, so two Deployments called api can live in staging and prod.
- Some objects are cluster-wide and never belong to a namespace: Nodes, PersistentVolumes and StorageClasses, for example.
- Network and workload isolation between namespaces needs NetworkPolicy and RBAC. The namespace name is only a label.
- Deleting a namespace deletes everything in it. A namespace stuck in Terminating has its own failure mode.
What a namespace scopes, and what it does not
The concept page says namespaces isolate groups of resources within a single cluster, and that name scoping applies to namespaced objects such as Deployments and Services. It does not apply to cluster-scoped objects. You can see the split on your own cluster with the api-resources command:
# Objects that live inside a namespace
kubectl api-resources --namespaced=true
# Objects that do not: Nodes, PersistentVolumes, Namespaces themselves
kubectl api-resources --namespaced=falseThe same Deployment name can exist in two namespaces without conflict. That is the main reason teams use namespaces: one cluster, several copies of the same app layout.
The four namespaces every cluster starts with
A new cluster has four namespaces. Knowing what each one holds prevents accidents, such as deploying application workloads into kube-system.
| Namespace | What the official docs say it holds |
|---|---|
| default | Where objects go when you do not name a namespace |
| kube-node-lease | Lease objects, one per node, used for kubelet heartbeats |
| kube-public | Readable by all clients, reserved mostly for cluster use |
| kube-system | Objects created by the Kubernetes system, such as the DNS add-on |
The default namespace is a convenience for first use. Most teams create their own namespaces for each environment or team and stop using default for real workloads.
Create a namespace and make it your default
A namespace is one command to create. Passing -n on every kubectl call is tedious, so most people set a default namespace on their kubeconfig context. Be careful with this: a context that points at prod makes a bare kubectl delete hit prod.
kubectl create namespace staging
# Make staging the default for the current context
kubectl config set-context --current --namespace=staging
# Confirm which context and namespace kubectl will use
kubectl config view --minify --output 'jsonpath={..namespace}'Decision rule: namespace per environment or per team?
- One namespace per environment (dev, staging, prod) suits a small team that shares one cluster and wants identical object names across environments.
- One namespace per team suits larger organisations where each team owns its quota and its access rules.
- Do not use a namespace to separate untrusted tenants by itself. Add NetworkPolicy, RBAC and quotas, or use separate clusters.
Quotas and access: the controls that make namespaces useful
A namespace is the unit you attach limits to. The official Secrets page points to resource quotas as the way to cap how many Secrets a namespace can hold, which is one example of a per-namespace control. RBAC roles are also scoped to a namespace when you use a Role and RoleBinding instead of a ClusterRole.
- Use a ResourceQuota to cap CPU, memory and object counts per namespace, so one team cannot starve another.
- Use a Role and RoleBinding for developers, so their access stops at their namespace.
- Use a NetworkPolicy to stop traffic between namespaces you want separate. The namespace itself does not block packets.
Deleting a namespace is destructive
Deleting a namespace removes every namespaced object inside it. That includes Deployments, Services, PersistentVolumeClaims and Secrets. Check the contents first:
# What would be removed
kubectl get all,secret,pvc,ingress -n staging
# Then, if you are sure
kubectl delete namespace stagingA namespace can also stay in Terminating after you delete it, when a finalizer on one of its objects never clears. That is a separate problem with its own fix, covered in the stuck-namespace guide linked below.