Back to Blog


What is a namespace in Kubernetes?

When learning Kubernetes you'll come across the term namespace a lot. This article explains everything you need to know about namespaces and how it works.

Kubernetes Objects

Before we even start talking about namespaces, you really need to understand what Kubernetes objects are. Think of Kubernetes as an object database, something like MongoDB or DynamoDB. You can store objects in it, and you can retrieve them. There are many different types of objects that can be created, and they all have different purposes.

This is an example of Pod, a popular object in Kubernetes. Deployments, ConfigMaps and Services are just a few of the other ones.

apiVersion: v1
kind: Pod
  name: nginx
  namespace: payments
    - name: nginx
      image: nginx:1.14.2
        - containerPort: 80

Pods represent an instance of your application, they are the smallest unit of deployment in Kubernetes. If you're working on a large scale system, you'll likely have hundreds or thousands of pods, not to mention all the other objects that are usually necessary to run a production system. Before you realize it, you might be storing tens of thousands of objects in your Kubernetes database.

Things can get out of hand pretty quickly, and that's where namespaces come in.

Ok, so what is a namespace?

They are a way to group objects together, it's a logical partition of your Kubernetes database. You can think of them as a folder in your file system. You can have multiple folders, and each folder can contain multiple files. The same goes for namespaces, you can have multiple namespaces and each can contain multiple objects.

In the example above, did you notice the namespace field in the metadata? That's how we specify in which namespace a particular object belongs to.

But that's not the only way. You can also specify the namespace when you're creating the object. For example, if you're using the kubectl command line tool, you can do something like this:

kubectl create -f pod.yaml --namespace payments

Lastly, the namespace parameter can also be omitted, which is where the default namespace comes into play.

Default Namespace

Every cluster has a namespace called default, and that's where all the objects are created if you don't specify a namespace. It's generally advisable to avoid using the default namespace altogether, but just because it's called default, doesn't mean it has to be your default namespace. In kubectl you can change the default namespace using this command:

kubectl config set-context --current --namespace=payments

From this point on, all objects created without specifying a namespace will be created in the payments namespace.

It's a good practice to plan ahead and organize your objects into namespaces from the beginning, thus avoiding reworks down the line, which are a lot more complicated when there are objects created already. Check out the Namespaces Best Practices article for more information.

And how do I create a namespace?

So after going through all this, you're probably wondering how to create a namespace, and it's actually pretty simple. A namespace is just an object like any other, so you can describe your namespace in a YAML file and create it using kubectl.

apiVersion: v1
kind: Namespace
  name: payments
kubectl create -f namespace.yaml

Alternatively, you could also take a shortcut and create it directly from the CLI:

kubectl create namespace payments

Hierarchical Namespaces

At this stage, you might be wondering: what if I want to create a namespace inside another namespace?

Object Kinds in Kubernetes can either be namespace-scoped or cluster-scoped. Namespace-scoped objects can only be created in a namespace. Examples include Pods, Deployments, Services, and ConfigMaps. Cluster-scoped objects are defined at the cluster level and are not stored in a namespace. The Namespace kind is an example of a cluster-scoped kind.

So back to the question — no, you can't create a namespace inside another namespace.


Hopefully, by now, you should have a better understanding of what a namespace is and how to create them. If you're still confused, I recommend you to read the Namespaces Best Practices article, which goes into more detail about how to use namespaces in your Kubernetes cluster.

Tired of using Kubectl? 😓

Experience hassle-free Kubernetes management with a powerful GUI.

Screenshot of Aptakube showing a list of pods from 2 clusters in a single view