A namespace is a named section of a cluster. It scopes object names (two teams can both have a Service called api) and it is the place where you attach policy: who can do what (RBAC), how much they can use (quotas) and who can talk to whom (network policies).
What a namespace is not: a security wall on its own. Pods in different namespaces share the same nodes and kernel, and by default they can reach each other over the network.
What is namespaced and what is not
$ kubectl api-resources --namespaced=true
$ kubectl api-resources --namespaced=false
| Namespaced | Cluster-wide |
|---|---|
| Pods, Deployments, StatefulSets, Jobs | Nodes |
| Services, Ingresses | PersistentVolumes |
| ConfigMaps, Secrets, ServiceAccounts | StorageClasses |
| PersistentVolumeClaims | ClusterRoles, ClusterRoleBindings |
| Roles, RoleBindings | CustomResourceDefinitions |
| ResourceQuotas, LimitRanges, NetworkPolicies | Namespaces themselves |
Two consequences that catch people out: a PVC is namespaced, but the PV it binds to is not. And a Secret in default is invisible to a Pod in shop: Pods can only use Secrets and ConfigMaps from their own namespace.
The built-in namespaces
| Namespace | Purpose |
|---|---|
default | Where objects go when you do not name a namespace |
kube-system | Control plane and cluster add-ons. Do not deploy your apps here |
kube-public | Readable by everyone, rarely used |
kube-node-lease | Node heartbeat objects |
Avoid default for real workloads. Give every app or team its own namespace from the start.
Working with namespaces
Create one imperatively or, better, with a manifest that carries labels:
apiVersion: v1
kind: Namespace
metadata:
name: shop
labels:
team: commerce
environment: production
$ kubectl apply -f namespace.yaml
namespace/shop created
$ kubectl get namespaces
NAME STATUS AGE
default Active 41d
kube-node-lease Active 41d
kube-public Active 41d
kube-system Active 41d
shop Active 5s
$ kubectl get pods -n shop
$ kubectl get pods -A
$ kubectl config set-context --current --namespace=shop
Label namespaces from day one. Network policies, admission rules and cost reports all select namespaces by label.
Calling a Service in another namespace
The short name only works inside the same namespace. From elsewhere, add the namespace:
$ kubectl exec -n checkout deploy/checkout -- curl -s http://shop-api.shop/healthz
ok
The fully qualified form is shop-api.shop.svc.cluster.local. If you do not want apps to hardcode another team’s namespace, create an ExternalName Service as a local alias:
apiVersion: v1
kind: Service
metadata:
name: shop-api
namespace: checkout
spec:
type: ExternalName
externalName: shop-api.shop.svc.cluster.local
What namespaces are good for
Access control
A RoleBinding in a namespace grants permissions only there. You can reuse the built-in edit ClusterRole instead of writing your own rules:
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: commerce-team-edit
namespace: shop
subjects:
- kind: Group
name: commerce-engineers
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: edit
apiGroup: rbac.authorization.k8s.io
Resource quotas
A ResourceQuota caps the total a namespace can request:
apiVersion: v1
kind: ResourceQuota
metadata:
name: shop-quota
namespace: shop
spec:
hard:
requests.cpu: "16"
requests.memory: 32Gi
pods: "60"
Watch out: once a quota covers CPU or memory, every new Pod in that namespace must declare those requests, or it is rejected. Add a LimitRange with default values alongside the quota (lesson 11 shows one).
Network isolation
A NetworkPolicy with an empty Pod selector applies to every Pod in the namespace. This one denies all incoming traffic until you allow specific flows:
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: default-deny-ingress
namespace: shop
spec:
podSelector: {}
policyTypes:
- Ingress
NetworkPolicies only work if your network plugin enforces them, as Calico and Cilium do. With a plugin that does not, the policy is accepted and silently does nothing.
How to divide a cluster
- One namespace per team or service: the usual choice, with clean boundaries for RBAC and quotas.
- One namespace per environment in one cluster: cheap, but dev and prod share nodes and incidents. Use a separate cluster for production.
- One namespace per developer or pull request: great for preview environments, as long as something deletes them automatically.
- Everything in one namespace: an anti-pattern. You cannot give anyone narrow permissions or limits.
Deleting, and the Terminating trap
kubectl delete namespace shop deletes everything inside it, including PVCs. With a Delete reclaim policy, that destroys the disks too. Double-check the context first.
Sometimes a namespace stays Terminating forever. The usual cause is a finalizer on a resource whose controller no longer exists, often a custom resource from an operator that was uninstalled first.
$ kubectl get namespace shop -o json | jq '.status.conditions[] | select(.status=="True") | .message'
"Some resources are remaining: backups.example.io has 2 resource instances"
"Some content in the namespace has finalizers remaining: backups.example.io/finalizer in 2 resource instances"
The proper fix is to reinstall the operator so it can clean up, or delete the leftover resources. As a last resort, remove the finalizer from the stuck object:
$ kubectl patch backup nightly -n shop --type=merge -p '{"metadata":{"finalizers":null}}'
Forcing the namespace itself through can leave cloud load balancers and disks behind that keep costing money, so avoid it.
Quick reference
| Task | Command |
|---|---|
| Create | kubectl create namespace <name> |
| List | kubectl get namespaces |
| Work in one | kubectl get pods -n <name> |
| Across all | kubectl get pods -A |
| Set the default | kubectl config set-context --current --namespace=<name> |
| What is namespaced | kubectl api-resources --namespaced=true |
| Everything inside | kubectl get all -n <name> |
| Quota usage | kubectl describe resourcequota -n <name> |
| Why deletion hangs | kubectl get namespace <name> -o json and read status.conditions |
Exercise
A Pod in namespace shop uses Secret db-pass as an environment variable, but that Secret only exists in default. What happens?
Show answer
Answer: B. Secret and ConfigMap references are always resolved in the Pod’s namespace. The Pod reports CreateContainerConfigError until the Secret exists in shop.
Exercise
You add a ResourceQuota for requests.cpu to a namespace, and Pods without CPU requests are now rejected. What is the best fix?
Show answer
Answer: D. A quota on a resource makes declaring it mandatory. A LimitRange fills in defaults for containers that leave it out, so existing manifests keep working.
Key takeaways
- Namespaces scope names and policy, not the network.
- PVCs, Secrets and ConfigMaps are namespaced; PVs and StorageClasses are not.
- Cross-namespace DNS needs the namespace:
service.namespace. - Keep real workloads out of
default, and label namespaces from the start. - Pair every ResourceQuota with a LimitRange.
- NetworkPolicies need a network plugin that enforces them.
- Deleting a namespace deletes its PVCs; a stuck Terminating namespace is almost always a finalizer.
FAQ
Is a namespace a security boundary?
Only partly. It scopes RBAC, but the network is open by default and Pods share nodes. Combine NetworkPolicies, Pod Security Standards and RBAC, and use separate clusters for untrusted tenants.
Which resources are not namespaced?
Nodes, PersistentVolumes, StorageClasses, ClusterRoles, ClusterRoleBindings, CustomResourceDefinitions and Namespaces. kubectl api-resources --namespaced=false lists all of them for your cluster.
Should environments be namespaces or separate clusters?
Namespaces work well for development and staging. Production usually deserves its own cluster, so a mistake or an overloaded node in staging cannot affect customers.
Why does kubectl say “No resources found” when my app is running?
You are looking in the wrong namespace. Add -n <namespace>, use -A to search all of them, or set a default namespace on your context.