Reference Documentation

Design docs, concept definitions, and references for APIs and CLIs.

Edit This Page


Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces.

When to Use Multiple Namespaces

Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all. Start using namespaces when you need the features they provide.

Namespaces provide a scope for names. Names of resources need to be unique within a namespace, but not across namespaces.

Namespaces are a way to divide cluster resources between multiple uses (via resource quota).

In future versions of Kubernetes, objects in the same namespace will have the same access control policies by default.

It is not necessary to use multiple namespaces just to separate slightly different resources, such as different versions of the same software: use labels to distinguish resources within the same namespace.

Working with Namespaces

Creation and deletion of namespaces is described in the Admin Guide documentation for namespaces

Viewing namespaces

You can list the current namespaces in a cluster using:

$ kubectl get namespaces
default       <none>    Active
kube-system   <none>    Active

Kubernetes starts with two initial namespaces:

Setting the namespace for a request

To temporarily set the namespace for a request, use the --namespace flag.

For example:

$ kubectl --namespace=<insert-namespace-name-here> run nginx --image=nginx
$ kubectl --namespace=<insert-namespace-name-here> get pods

Setting the namespace preference

You can permanently save the namespace for all subsequent kubectl commands in that context.

First get your current context:

$ export CONTEXT=$(kubectl config view | awk '/current-context/ {print $2}')

Then update the default namespace:

$ kubectl config set-context $CONTEXT --namespace=<insert-namespace-name-here>
# Validate it
$ kubectl config view | grep namespace:

Namespaces and DNS

When you create a Service, it creates a corresponding DNS entry. This entry is of the form <service-name>.<namespace-name>.svc.cluster.local, which means that if a container just uses <service-name> it will resolve to the service which is local to a namespace. This is useful for using the same configuration across multiple namespaces such as Development, Staging and Production. If you want to reach across namespaces, you need to use the fully qualified domain name (FQDN).

Not All Objects are in a Namespace

Most kubernetes resources (e.g. pods, services, replication controllers, and others) are in some namespace. However namespace resources are not themselves in a namespace. And low-level resources, such as nodes and persistentVolumes, are not in any namespace. Events are an exception: they may or may not have a namespace, depending on the object the event is about.


Create Issue Edit This Page