Best Practices for Kubernetes Namespaces

13 June 2022 by Cameron Pavey

Namespaces are a vital feature of Kubernetes. They allow you to separate uniquely named resources into logical groups, though names don’t need to be unique between different namespaces. Namespaces can enforce separation between different deployment environments, as well as divide a cluster’s resources between multiple users and groups of users using resource quotas.

There are multiple benefits to using namespaces, but using them improperly can also cause difficulties with your Kubernetes projects. That’s why it’s so important to understand how to use namespaces well. In this guide, you’ll learn some best practices to follow for using namespaces.

About the List

Keep in mind that the following list isn’t exhaustive or objective. Best practices are generally a good place to start, especially if you’re new to the subject matter, but they’re rarely unbreakable rules. There will always be situations in which it makes sense to try something else.

With that in mind, here are some recommended best practices to follow.

Use Semantic, Scalable Names

Names are important, but it’s widely acknowledged that naming things well is challenging, especially in the context of computer science. Kubernetes namespaces are no different. It’s too easy to give them bad names, inconsistent names, or names that don’t assist with clear communication.

When you only have one namespace, you might be tempted to name it after whatever application will live within it. For example, if you have a bookstore application, you might call the namespace bookstore. When you create more namespaces for deployment environments like develop and testing, though, you’ll have bookstore, bookstore-develop, and bookstore-testing. This can quickly expand as you introduce more environments, more applications, or more use cases for your namespaces.

You need to come up with and stick to a scalable naming convention. If you create production, develop, and testing to represent your deployment environments, all applications will go into one of these namespaces instead of different namespaces per application.

You can also leverage other Kubernetes features like labels to distinguish between resources within a given namespace. If you label your resources with their respective application names, versions, and other necessary metadata, your namespaces stay clean and scalable while still allowing you to filter and search for particular resources as needed.

Don’t Put Everything in the Default Namespace

Kubernetes comes with a few namespaces out of the box. One of these is the aptly named default namespace, where Kubernetes places resources when another one isn’t specified. Try to avoid using this namespace much, if at all. It makes much more sense to use semantically named namespaces in production and other live environments than to just dump all of your resources into default.

You can easily make assumptions about what developers will be doing with their machines, but your assumptions can just as easily be wrong. Consider a scenario where a developer creates a postgres pod in their default namespace, possibly for personal projects or experiments. This resource could conflict with your application if deployed alongside it. If your application needs a pod with the same name, being in a different namespace will avoid this conflict.

It’s a good idea to treat all environments, whether local or remote, with the same care when creating namespaces, because this helps ensure idempotency in your deployment builds.

Leverage Role-Based Access Control

Kubernetes offers the ability to enforce role-based access control (RBAC) authorization as a means of controlling which users can access resources. RBAC can work with either the ClusterRole resource type, which is scoped to the entire cluster, or the Role resource type, which is scoped to a specific namespace. This means that you can limit the resources a user is allowed to access, either globally or within a particular namespace.

Because you can issue cluster-wide roles, you can restrict who is allowed to create new namespaces, among other resources. This helps you avoid a namespace “explosion” in which self-servicing users create resources in an uncontrolled fashion, making it harder for you to administer the cluster.

Know When to Use Multiple Namespaces

Without a set namespace strategy, you might be tempted to use namespaces in suboptimal ways. This could mean putting everything in the default namespace, as mentioned above, or the other extreme of using too many namespaces when it doesn’t make sense to do so.

The official Kubernetes documentation suggests that you only use namespaces when you need the features they offer, not simply for the sake of using them. Small teams of users, for instance, are unlikely to need namespaces. This approach can help reduce the overhead of dealing with yet another construct.

At the same time, namespaces can be beneficial even for small teams. One textbook example is using namespaces for different deployment environments, such as production, develop, or testing. Each of these environments would likely be running more or less the same application, but you wouldn’t want to share resources between them.

Multiple namespaces can also make sense in an organization with distinct workgroups. This could be teams, or collections of teams, who work on different projects that seldom overlap from a DevOps perspective. If the workgroups are separated, users can work together with relative freedom while isolated from unrelated groups. This helps ensure that the resources and constraints of one group don’t affect any others.

 Know What Belongs in a Namespace

Namespaces are primarily a separation mechanism, but there are some intricacies to keep in mind when using them so that you don’t run into any surprises. One important thing to note is that namespace scoping doesn’t apply to all resources; it’s only available for namespaced objects such as pods, deployments, or services, and not for cluster-wide resources like StorageClasses, nodes, or PersistentVolumes. This is a key concept for naming Kubernetes resources, so your mental model of how things fit together must be accurate.

For a complete list of resources that are and are not namespaced, run the following commands:

# namespaced resources
kubectl api-resources --namespaced=true

# non-namespaced resources
kubectl api-resources --namespaced=false

Limit Resource Usage for Specific Namespaces

If you’re running multiple namespaces on a cluster with limited resources, it might make sense to limit the resource usage of specific namespaces. For example, if you’re running namespaces for production, develop, and testing, you’d want production to have access to more resources than the others—maybe even unlimited resources. But you wouldn’t want testing or develop to consume so many resources that performance in production is degraded.

You can solve this through the application of resource quotas. If you run the aforementioned command to see all namespaced API resources, you’ll note that ResourceQuotas is among them. This means that each namespace can have its own quota that limits the amount of resources it can use from the node. The Kubernetes documentation offers this example of a simple ResourceQuota:

apiVersion: v1
kind: ResourceQuota
metadata:
  name: mem-cpu-demo
spec:
  hard:
    requests.cpu: "1"
    requests.memory: 1Gi
    limits.cpu: "2"
    limits.memory: 2Gi

This ResourceQuota would enforce these restrictions on all pods in the namespaces. This is one method for dividing cluster resources between multiple user groups, proving that namespaces can serve as a powerful mechanism for achieving various outcomes.

Know When It’s Time to Add More Clusters

One of the key benefits of namespaces is that they provide a mechanism for separation. Resources in one namespace are generally isolated from resources in other namespaces. Sometimes this isolation level isn’t enough, and you need to leverage different separation mechanisms, such as separate clusters.

That might be the right solution if you serve an application in multiple geographic regions. You *could* make other namespaces for each region, but that isn’t ideal, since the cluster will still be chiefly located in a single physical region. In cases like this, it’s better for the resources to be physically closer to users to reduce latency as well as to address various data sovereignty issues.

The better solution might be to have separate clusters for each geographic region in which each cluster contains similarly named namespaces. This approach gives you all the benefits of a rigid separation between regions and the scalable naming and discoverability of consistent namespace names.

Namespaces are a key concept in Kubernetes and any business that uses Kubernetes is likely to deal with them in one way or another. This is why it’s essential for you to understand their strengths and limitations.

If you know when to create a new namespace, use an existing one, or rely on a different construct altogether, you’ll be better able to use this powerful feature and your Kubernetes workflows will improve.

Share this article

About the author

Picture of Cameron Pavey

Cameron Pavey

Technical writer

Cameron is a full-stack dev living and working in Melbourne. He's committed himself to the never-ending journey of understanding the intricacies of quality code, developer productivity, and job satisfaction.

Related articles