What is a namespace in Kubernetes?

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
metadata:
  name: nginx
  namespace: payments
spec:
  containers:
    - name: nginx
      image: nginx:1.14.2
      ports:
        - 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.

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.

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.

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
metadata:
  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

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.