Back to Blog

How to create namespaces in Kubernetes: the complete guide

By Brian Galura -

Thanks to its portability and extensibility, Kubernetes is considered a highly reliable open-source container orchestration system for developers that manage containerized workloads and services. Popularly known as K8s, the platform enables scalability through the automation of boring software deployment and management tasks.

However, with scalability in a multi-purpose environment, containerized applications need better management. This is where you might need one or multiple namespaces in Kubernetes.

If you’re still asking the question ‘what is a Kubernetes namespace’, or if you need more clarity on the topic, read on as we cover all that you need to know about creating namespaces in Kubernetes.

Table of Contents

What is Namespace in Kubernetes?

How is Namespace Different from a Virtual Cluster?

Fast Facts: Kubernetes Namespaces

Default Namespaces in Kubernetes

When Do You Need Multiple Namespaces?

When Should You NOT Use Namespaces?

Enabling Pod-to-Pod Communication across Kubernetes namespaces

A Suggestion Before you Create Namespaces

How to create Namespace in Kubernetes?

Controlling your Namespace

How to Get Started with Kubernetes and its Namespaces in a Simpler Way?


What is Namespace in Kubernetes?

In Kubernetes, a namespace is a means of organizing a complex cluster into a simpler sub-cluster. This helps distinct teams and sub-teams to share a single Kubernetes cluster without clashes.

As a cluster grows, the potential for collisions among resource names increases. Namespaces provide a way to overcome this problem, as they help to isolate resources in different groups while retaining them within the same cluster. With this, resource names have to be unique for each namespace instead of for each cluster.

To understand this concept better, think of 2 teams from your organization using the same cluster.

A new employee from one team may accidentally edit a critical resource belonging to another team due to similarity in names. Using distinct namespaces, you can define the scope of your resources, group them into 2 separate parts, and offer a more hassle-free development environment to both teams.

What is included in a Kubernetes Namespace?

You may add several services, replication controllers, pods, etc. in your namespaces to limit their scope. Run this command to see what your namespaces can be comprised of:

kubectl api-resources --namespaced=true

What is excluded from a Kubernetes Namespace?

The visibility or accessibility of cluster-wide objects, such as - PersistentVolumes, StorageClass, and Nodes, cannot be limited using a namespace. To check which all objects cannot be restricted through namespaces, use this command:

kubectl api-resources --namespaced=false

How is a namespace different from a virtual cluster?

If namespaces represent different teams within an organization, a virtual cluster represents a building where different organizations have their offices.

A virtual cluster offers a higher degree of isolation within the same cluster. Not isolated to services and pods, you can also bundle PersistentVolumes, Nodes, and cluster roles while defining the scope of a virtual cluster. The latter components remain shared when grouped using a namespace.


Fast facts: Kubernetes Namespaces

  • Cannot be nested within one another

  • Characterized by ‘labels’ to distinguish among slightly differing resources

  • Offers a means to categorize resources by teams

  • Helps avoid name collisions

  • Separates environments for better navigability, access-limitation, and management

  • Can be allotted a ‘storage quota’

  • May contain multiple virtual clusters

  • Comprises unique Kubernetes resources

Default Namespaces in Kubernetes

Kubernetes has 4 preloaded namespaces`:

  • default

Until your resources are grouped in a namespace, they are a part of a ‘default’ namespace. So, for all resources that are not included in any namespace in your Kubernetes command, you must use the reference ‘default’.

  • kube-system

All system-created Kubernetes components are added to this namespace. So, it is suggested that you should not add your resources to it.

  • kube-public:

Authenticated or not, everyone with access to the cluster will be able to read the resources of this namespace. It is created automatically and if required, you can change its conventional visibility.

  • kube-node-lease

Lease objects related to each of the nodes in the cluster are kept in this namespace. The purpose of these leases is to help the control plane discover node failures faster. For this, they send the heartbeat data to the Kubernetes control plane.

When do you need multiple namespaces?

Namespaces remain logically distinct within the same cluster, so it is important to create and use them wisely in order not to increase the complexity of your cluster and achieve nothing.

In practice, one namespace (default) is sufficient for small teams or projects.

However, when dealing with multiple containerized applications or multiple teams for your project(s), maintaining multiple namespaces is a perfect way to isolate the work environment. With Kubernetes namespaces, you can provide cleaner and more specific resource-sets to your teams or projects.

Creating multiple namespaces is a good idea in a number of situations:


Multiple teams working on the same cluster could end up clashing as they expand on the cluster. So, how can teams avoid this situation?

A good level of isolation for projects and microservices can be achieved by creating namespaces. This will allow your teams to name their resources without worrying about the names selected by other teams for their resources. This also eliminates the problem of one team’s operations clashing with another.


As applications increase in complexity, it can become difficult to distinguish between staging (development), live (deployment), and testing components. In these cases, you can achieve a better level of organization by dividing clusters into namespaces based on their purpose. This prevents instances where live projects are being updated while the code is in testing, etc.


In an organization, you might want to force access restrictions on users and processes without using multiple clusters. For example, if you want to offer varying levels of permissions for a set of resources to different people in the organization, namespaces allow you to achieve this.


To define resource quota for your teams in order to ensure fair distribution of resources within the cluster, multiple namespaces can be used. You can define policies about memory utilization or CPU usage in order to control your resources better.


Imagine your development team places projects of different clients in one cluster. You might want to separate these projects to achieve better searchability and organization. Creating multiple namespaces would be the ideal solution to achieving this.


If a particular project requires handling more Kubernetes API calls, it is better to assign a separate namespace to it. This will help the system perform operations faster and improve the performance of the containerized application.

When should you NOT use namespaces?

  • For geographical server partitioning. For example, if you want one server allocated to your US-based clientele, and another for your EU clientele, partitioning using namespaces won’t help.

  • Where increased security is required. As namespaces may have shared components that are visible to other namespaces too, they should not be used in instances that are security-critical, e.g. in billing situations.

  • Where more resources are required in the future. For a higher level of configurability, you might need to add more nodes or other such resources in the future. In such cases, it is better to use separate clusters or separate virtual clusters.

Enabling Pod-to-Pod communication across Kubernetes namespaces

Distinct namespaces, and pods sharing the same namespaces can be configured to communicate with each other seamlessly. To achieve this, you will have to utilize the expanded DNS addresses with the namespace’s name prefixed to the service name. For example, the service named ‘deploy’ in the namespace ‘game’ will be called ‘game.deploy’.

To set lightweight restrictions (of a lower level in comparison to firewalls) on accessing the services, you may set network policies accordingly.

A suggestion before you create namespaces

If you have created namespaces with names similar to public top-level domains, services with tiny DNS names in these namespaces may overlap with your public DNS. So, all workloads from all the different namespaces (with the trailing dot missing), will be redirected towards those services instead of the public DNS.

To avoid this problem, avoid using a name similar to top-level domains for your namespaces. Third-party security controls (admission webhooks, for example) can warn you and block the creation of namespaces with a name similar to these domains.

Alternatively, you must enable user-level restrictions for each of your namespaces as needed.

How to create Namespace in Kubernetes

To create a namespace, named “ssconvox”, you can use this code:

apiVersion: v1
kind: Namespace
  name: "ssconvox"

You can add this code in a ‘.yaml’ file named “namespace.yml” and run this command -

$ kubectl create –f namespace.yml

Controlling your Namespace

Other essential commands for working with Kubernetes namespaces are:

  • Seeing the list of available namespaces
$ kubectl get namespace
  • Renaming

Namespaces CANNOT be renamed, so you must carefully name them in the very beginning.

  • Switch between namespaces
kubectl config set-context --current --namespace=ssconvoxtwo
  • Getting details about a particular namespace
$ kubectl describe namespace ssconvox
  • Getting the lists of pods in the current namespace
$ kubectl get pods --namespace=ssconvox
  • Delete the namespace ‘ssconvox’
$ kubectl delete namespace ssconvox

Note: As deleting a namespace runs the garbage collection over services, pods, and everything that is present in a namespace, you must be extra-cautious before deleting your namespaces.

How to get started with Kubernetes and quickly create namespaces

If you’ve read this far but actually haven’t managed to get started with Kubernetes, this is the toughest part of the process - but don’t worry, we have you covered. The good news is that Convox (a PaaS solution for Kubernetes-based deployments) can help you get started with Kubernetes in just a few clicks.

Even if you’re signed up to a different PaaS but don’t know how to help your team achieve optimal operational efficiency through Kubernetes, Convox can help you understand the operational benefits of a migration from your existing PaaS.

Convox lets you use a better GUI while shipping all the infrastructure for Kubernetes from one platform. As it is production-ready with zero downtime, you need not worry about the underlying components of your Kubernetes configuration with it.

For namespace creation in Kubernetes, just install Convox CLI to get started and follow the process outlined above. Convox will create separate namespaces for each new application.


Creating multiple namespaces in Kubernetes is the way to go when you need to classify and run multiple environments in a cluster. With individual namespaces, you can define access restrictions, usage quotas, and isolated resources for a bunch of services and pods. However, you must learn everything about the scope and suitability of namespaces before you start using them. This is why we have covered the subject in its totality. We hope that this article has helped you answer the question of what is a namespace in Kubernetes and how to create a namespace when you need it.

Using Kubernetes with Convox already or wanting to switch? Get started with Convox, install Convox CLI, and create namespaces now.