Lesson 10 intermediate

Kubernetes Namespaces

What namespaces scope and what they do not, the built-in namespaces, cross-namespace DNS, RBAC, quotas and network policies per namespace, how to divide a cluster and how to delete safely.

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
NamespacedCluster-wide
Pods, Deployments, StatefulSets, JobsNodes
Services, IngressesPersistentVolumes
ConfigMaps, Secrets, ServiceAccountsStorageClasses
PersistentVolumeClaimsClusterRoles, ClusterRoleBindings
Roles, RoleBindingsCustomResourceDefinitions
ResourceQuotas, LimitRanges, NetworkPoliciesNamespaces 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

NamespacePurpose
defaultWhere objects go when you do not name a namespace
kube-systemControl plane and cluster add-ons. Do not deploy your apps here
kube-publicReadable by everyone, rarely used
kube-node-leaseNode 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

TaskCommand
Createkubectl create namespace <name>
Listkubectl get namespaces
Work in onekubectl get pods -n <name>
Across allkubectl get pods -A
Set the defaultkubectl config set-context --current --namespace=<name>
What is namespacedkubectl api-resources --namespaced=true
Everything insidekubectl get all -n <name>
Quota usagekubectl describe resourcequota -n <name>
Why deletion hangskubectl 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?

  1. The Pod reads the Secret from default anyway
  2. The container cannot start, because Pods only see Secrets in their own namespace
  3. Kubernetes copies the Secret into shop automatically
  4. The variable is set to an empty string
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?

  1. Delete the quota
  2. Give the namespace a higher quota
  3. Run the Pods in default instead
  4. Add a LimitRange that sets default requests for containers
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.

↑ ↓ navigate Enter open Esc close