Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Kubernetes namespaces: organize and isolate your resources logically

By updated

Improve this page

Logo Kubernetes

A namespace splits a Kubernetes cluster into distinct name spaces: a name only makes sense inside its namespace, so two resources with the same name can coexist in two namespaces, and access rights as well as quotas are attached to a namespace. In this lesson, you create two namespaces, you place the same objects in them, you check what stays separate (names, Secrets) and what does not (the network, the Nodes), then you place the protections that fill these gaps.

Prerequisites: the demo cluster from First cluster and the lessons Deployments and Services.

What you will learn

  • Create a namespace with a command and with a manifest
  • Name the initial namespaces of a cluster and say what each one holds
  • Work in a namespace with -n, then change the default namespace
  • Prove what a namespace isolates and what it does not
  • Place the protections of a team namespace: quotas, limits, NetworkPolicy, RBAC

How do you create a namespace?

Two gestures create a namespace. The kubectl create namespace command is enough for a test. A manifest lets you add labels and can be versioned. Create team-dev with the command and team-qa with a manifest that carries the label equipe: qa:

Terminal window
kubectl create namespace team-dev
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Namespace
metadata:
name: team-qa
labels:
equipe: qa
EOF
kubectl get namespaces --show-labels
namespace/team-dev created
namespace/team-qa created
NAME STATUS AGE LABELS
default Active 25s kubernetes.io/metadata.name=default
kube-node-lease Active 25s kubernetes.io/metadata.name=kube-node-lease
kube-public Active 25s kubernetes.io/metadata.name=kube-public
kube-system Active 25s kubernetes.io/metadata.name=kube-system
local-path-storage Active 21s kubernetes.io/metadata.name=local-path-storage
team-dev Active 0s kubernetes.io/metadata.name=team-dev
team-qa Active 0s equipe=qa,kubernetes.io/metadata.name=team-qa

The cluster already contains namespaces that you did not create, visible in the list above. The first four exist in every Kubernetes cluster and each has a specific role; the fifth, local-path-storage, is added by kind to provide local storage:

NamespaceWhat it holds
defaultResources created without specifying a namespace
kube-systemThe cluster components (DNS, network proxy, network plugin)
kube-publicData readable without authentication, such as the cluster-info ConfigMap
kube-node-leaseOne small object per node, which signals that the node is alive

Check what kube-system and kube-node-lease contain:

Terminal window
kubectl get pods -n kube-system
kubectl get leases -n kube-node-lease
NAME READY STATUS RESTARTS AGE
coredns-559f6c778d-2l2jl 1/1 Running 0 16s
coredns-559f6c778d-vvk7n 1/1 Running 0 16s
etcd-demo-control-plane 1/1 Running 0 22s
kindnet-4q7pm 1/1 Running 0 15s
kindnet-gzng6 1/1 Running 0 16s
kindnet-kgx26 1/1 Running 0 15s
kindnet-whn28 1/1 Running 0 15s
kube-apiserver-demo-control-plane 1/1 Running 0 22s
kube-controller-manager-demo-control-plane 1/1 Running 0 22s
kube-proxy-9sdgz 1/1 Running 0 15s
kube-proxy-lr7v9 1/1 Running 0 16s
kube-proxy-s6clb 1/1 Running 0 15s
kube-proxy-tn2kz 1/1 Running 0 15s
kube-scheduler-demo-control-plane 1/1 Running 0 22s
NAME HOLDER AGE
demo-control-plane demo-control-plane 23s
demo-worker demo-worker 15s
demo-worker2 demo-worker2 15s
demo-worker3 demo-worker3 15s

The two commands list the cluster components (CoreDNS, etcd, the API server, the kindnet network plugin, kube-proxy) and one Lease object per node, the small object described in the table. Do not create your applications in kube-system: it belongs to the cluster and you risk disturbing its components.

What does a namespace separate?

A namespace first separates names: two objects of the same type and the same name can exist if they are in two different namespaces. Create an api Deployment in each of the two namespaces, then list them together with the -A option (all namespaces):

Terminal window
kubectl create deployment api --image=nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb -n team-dev
kubectl create deployment api --image=nginx:1.30.5@sha256:9bf97bd7714f5e24c1ccd545ecb9eb5435cb6d109c97cebb15e7e455e0239edb -n team-qa
kubectl rollout status deployment/api -n team-dev
kubectl rollout status deployment/api -n team-qa
kubectl get deployments -A -l app=api
deployment.apps/api created
deployment.apps/api created
Waiting for deployment "api" rollout to finish: 0 of 1 updated replicas are available...
deployment "api" successfully rolled out
Waiting for deployment "api" rollout to finish: 0 of 1 updated replicas are available...
deployment "api" successfully rolled out
NAMESPACE NAME READY UP-TO-DATE AVAILABLE AGE
team-dev api 1/1 1 1 12s
team-qa api 1/1 1 1 12s

The two api coexist without conflict, and the NAMESPACE column tells them apart (team-dev and team-qa, each at 1/1). Without the -n option, kubectl works in default: the two Deployments are therefore not there. To avoid repeating -n team-dev in every command, change the default namespace of the context, then restore it:

Terminal window
kubectl config set-context --current --namespace=team-dev
kubectl config view --minify --output 'jsonpath={..namespace}'
echo
kubectl get deployments
kubectl config set-context --current --namespace=default
Context "kind-demo" modified.
team-dev
NAME READY UP-TO-DATE AVAILABLE AGE
api 1/1 1 1 12s
Context "kind-demo" modified.

A Secret created in one namespace does not exist in the other. The cle Secret is created in team-dev; reading it from team-qa fails with NotFound, and the failure is intended:

Terminal window
kubectl create secret generic cle --from-literal=valeur=exemple -n team-dev
kubectl get secret cle -n team-dev
kubectl get secret cle -n team-qa
secret/cle created
NAME TYPE DATA AGE
cle Opaque 1 0s
Error from server (NotFound): secrets "cle" not found

ConfigMaps, ServiceAccounts, Roles and quotas behave the same way: they belong to a namespace. Access rights (RBAC) and quotas are therefore attached to it, and that is what makes a namespace useful for a team.

What does a namespace not separate?

A namespace is not a network security boundary. Expose the api Deployment of team-qa through a Service, then call it from a Pod of team-dev using its DNS name completed with the namespace (api.team-qa, as in the lesson Services):

Terminal window
kubectl expose deployment api --port=80 -n team-qa
kubectl run client -n team-dev --image=busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4 --restart=Never -- sleep 3600
kubectl wait -n team-dev --for=condition=Ready pod/client --timeout=60s
kubectl exec -n team-dev client -- wget -qO- http://api.team-qa | head -n 4
service/api exposed
pod/client created
pod/client condition met
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>

The call succeeds and returns the beginning of the Nginx welcome page: a Pod in one namespace reaches a Service in another without any obstacle. The cluster network does not distinguish namespaces as long as no NetworkPolicy restricts it.

A reminder about the name used: the short name api only resolves in the namespace of the client, so it does not designate the team-qa Service from team-dev. The name <service>.<namespace>, or <service>.<namespace>.svc.cluster.local, works from any namespace. The gesture is demonstrated in the section How do you reach a Service by its DNS name? of the Services lesson.

Conversely, some resources belong to no namespace, because they describe the whole cluster:

Terminal window
kubectl api-resources --namespaced=false | grep -E '^(nodes|namespaces|persistentvolumes) '
kubectl get nodes
namespaces ns v1 false Namespace
nodes no v1 false Node
persistentvolumes pv v1 false PersistentVolume
NAME STATUS ROLES AGE VERSION
demo-control-plane Ready control-plane 38s v1.37.0
demo-worker Ready <none> 30s v1.37.0
demo-worker2 Ready <none> 30s v1.37.0
demo-worker3 Ready <none> 30s v1.37.0
Two namespaces, team-dev and team-qa, each isolate their ServiceAccounts, Secrets, ConfigMaps, Pods, Roles and ResourceQuota; their Pods remain reachable from one another because the network is not isolated by default, and both use the shared resources of the cluster: Nodes, PersistentVolumes, StorageClasses, ClusterRoles, IngressClasses.Kubernetes clusterNamespace team-devNetwork NOT isolatedby defaultNamespace team-qaShared resources (cluster-wide)ServiceAccountsSecretsConfigMapsPodsRoles /RoleBindingsResourceQuotaPodsSecretsConfigMapsServiceAccountsRoles /RoleBindingsResourceQuotaNodesPersistentVolumesStorageClassesClusterRolesIngressClassesusesuses
Source · SVG
Esc to close, + and − to zoom, scroll to move around. 100 %

The diagram sums up the two findings: inside each namespace, the objects are separated; between the two, the network stays open, and the Nodes and volumes are shared.

Which protections should you add to a team namespace?

A newly created namespace has no limit: describe confirms it.

Terminal window
kubectl describe namespace team-dev
Name: team-dev
Labels: kubernetes.io/metadata.name=team-dev
Annotations: <none>
Status: Active
No resource quota.
No LimitRange resource.

The lines No resource quota. and No LimitRange resource. say that the Pods of this namespace can, together, consume all the resources of the cluster. Four protections complete the namespace, and each has its own lesson:

ProtectionWhat it limitsLesson
ResourceQuotaThe total resources and objects that the namespace can consumeResource Quotas
LimitRangeThe default and maximum resources of a containerResource Quotas
NetworkPolicyWho can talk to whom, between Pods and between namespacesNetwork Policies
RBACWho can read or modify what in the namespaceRBAC

This lesson does not teach any of these four protections: it places them, so that you know what a namespace alone does not do.

How do you navigate between several namespaces?

To see the Pods of all namespaces with the name of their namespace, the -o custom-columns option chooses the columns. Each column is written TITLE:path, columns are separated by a comma without a space, and the quotes keep the list in one piece:

Terminal window
kubectl get pods -A -o custom-columns="NAMESPACE:.metadata.namespace,NOM:.metadata.name"
NAMESPACE NOM
kube-system coredns-559f6c778d-2l2jl
kube-system coredns-559f6c778d-vvk7n
kube-system etcd-demo-control-plane
kube-system kindnet-4q7pm
kube-system kindnet-gzng6
kube-system kindnet-kgx26
kube-system kindnet-whn28
kube-system kube-apiserver-demo-control-plane
kube-system kube-controller-manager-demo-control-plane
kube-system kube-proxy-9sdgz
kube-system kube-proxy-lr7v9
kube-system kube-proxy-s6clb
kube-system kube-proxy-tn2kz
kube-system kube-scheduler-demo-control-plane
local-path-storage local-path-provisioner-75f7fc7dc5-9dmxz
team-dev api-698865cd4b-788v9
team-dev client
team-qa api-698865cd4b-45pmv

The everyday trap is creating a resource in the wrong namespace because -n was forgotten. The command kubectl config view --minify --output 'jsonpath={..namespace}' tells you which namespace you are working in. It returns an empty line as long as the context sets no namespace, and default after a set-context --current --namespace=default.

The tools kubens and kubectx (in French) shorten this namespace switch.

What happens when you delete a namespace?

Deleting a namespace deletes all the resources it contains. By default, the command waits for the deletion to finish: it only gives control back once the namespace is empty and deleted. With --wait=false, it gives control back immediately and the namespace stays visible in the Terminating state while its content disappears. A namespace that stays stuck in Terminating signals a resource that refuses to be deleted.

Delete team-qa and check what remains:

Terminal window
kubectl delete namespace team-qa
kubectl get namespace team-qa
kubectl get deployments -A -l app=api
namespace "team-qa" deleted
Error from server (NotFound): namespaces "team-qa" not found
NAMESPACE NAME READY UP-TO-DATE AVAILABLE AGE
team-dev api 1/1 1 1 26s

The api Deployment of team-qa disappeared with its namespace, and get namespace answers NotFound: the error is intended, it proves the deletion. System namespaces, such as kube-system, are not deleted lightly: their components keep the cluster running. Now clean up the rest:

Terminal window
kubectl delete namespace team-dev
namespace "team-dev" deleted

Put it into practice

The guided lab has you create two team namespaces, equipe-api and equipe-front, on a kind cluster. You deploy the api application (nginx, as in the lesson) and its Service in the first one, remembering -n so that nothing lands in default. Then, from a client Pod in the second, you reach api by its qualified name api.equipe-api and you observe that the short name fails: run this request with a short timeout, for example wget -T 3, so as not to wait. You record both results in ~/namespaces/releve.txt, under the keys reponse-nom-qualifie and nom-court. The validation replays both requests, and it rejects an application also left in default or a Service that would make the short name answer.

Key takeaways

  1. A namespace separates names and attaches rights and quotas; it separates neither the network nor the Nodes.
  2. Four namespaces exist in every cluster: default, kube-system, kube-public, kube-node-lease (kind adds one, local-path-storage).
  3. Without -n, kubectl works in the namespace of the context, default by default; kubectl config set-context --current --namespace=<name> changes it.
  4. A Secret, a ConfigMap or a Role of one namespace does not exist in another.
  5. A Pod reaches a Service in another namespace through <service>.<namespace>, as long as no NetworkPolicy forbids it.
  6. A new namespace has no limit: ResourceQuota, LimitRange, NetworkPolicy and RBAC are set up separately.
  7. Deleting a namespace deletes all of its content.

Test your knowledge

Seven questions to check that the essentials are in place: what a namespace isolates, what it does not isolate, and the protection that answers each gap.

Knowledge check

Check what you have learned with this interactive quiz

7 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer