Kubernetes namespace

On this page 8

A Kubernetes namespace is a logical partition of a single cluster that gives a set of API objects its own name scope, so that two teams can each run a Service called web without collision. In Kubernetes and the wider Cloud discipline, namespaces are the primary unit of multi-tenancy, access control and quota enforcement, sitting between the cluster as a whole and the individual workloads it hosts.

Namespaces are not a security boundary on their own. They organize and scope resources, and they become meaningful isolation only when combined with role-based access control, network policies, resource quotas and admission controls. Understanding that distinction is the most important point for anyone designing a shared cluster.

How a namespace scopes cluster objects

A namespace scopes objects by making the namespace name part of each object’s identity. The API server stores a namespaced object under a key that includes its namespace, so a Pod named api in team-a and a Pod named api in team-b are entirely distinct records. Every request to a namespaced resource either names a namespace explicitly or falls back to the default namespace of the client context.

Not every resource kind lives inside a namespace. Cluster-scoped resources such as nodes, persistent volumes, storage classes and the namespaces themselves exist once for the whole cluster. Running kubectl api-resources --namespaced=false lists them. The table below shows how common resource kinds are scoped.

Resource kindScopePractical consequence
Pod, Deployment, ReplicaSetNamespacedNames must be unique only within one namespace
Service, Ingress, ConfigMapNamespacedVisible and addressable per namespace
Kubernetes SecretNamespacedA Pod can mount only Secrets from its own namespace
Role, RoleBindingNamespacedGrant permissions inside one namespace
Node, PersistentVolumeCluster-scopedShared by all namespaces
ClusterRole, StorageClassCluster-scopedDefined once, referenced from any namespace
Scope of common Kubernetes resource kinds

Namespaces also shape service discovery. The cluster DNS publishes each Service as service.namespace.svc.cluster.local, so a short name such as db resolves only within the caller’s own namespace, while the fully qualified name reaches a Service anywhere in the cluster.

Built-in namespaces and naming rules

Every new cluster starts with four system namespaces, each with a defined purpose. Workloads should rarely be placed in them, and the kube- prefix is reserved for Kubernetes components.

NamespacePurposeRecommended use
defaultTarget when no namespace is specifiedAvoid for production workloads
kube-systemControl plane add-ons such as DNS and proxiesPlatform team only
kube-publicReadable by all clients, including unauthenticated onesCluster discovery data only
kube-node-leaseLease objects for node heartbeatsNever modify manually
Namespaces created by default

Namespace names must follow the RFC 1123 DNS label format: lowercase alphanumeric characters or hyphens, starting and ending with an alphanumeric character, and at most 63 characters. Because the name becomes part of DNS records, a consistent naming convention such as team-environment pays off quickly in large clusters.

Building isolation on top of namespaces

Real tenant isolation comes from policies attached to a namespace, not from the namespace itself. Each mechanism below adds one layer, and a well-run shared cluster applies all of them through templates or a policy engine whenever a namespace is created.

ControlWhat it limitsWithout it
RBAC Role and RoleBindingWho may read or change objectsAny authorized user can touch any namespace
ResourceQuotaTotal CPU, memory, storage and object countsOne team can exhaust cluster capacity
LimitRangeDefault and maximum requests per containerPods run without requests and starve neighbors
NetworkPolicyPod-to-Pod and egress trafficAll Pods can reach all Pods across namespaces
Pod Security AdmissionPrivileged containers and host accessA workload can escape to the node
Controls that turn a namespace into a tenant boundary

Pod Security Admission is configured with namespace labels such as pod-security.kubernetes.io/enforce: restricted, which makes the namespace the natural place to declare a security level. Network policies, by contrast, are default-allow until at least one policy selects a Pod, so a default-deny policy per namespace is a common baseline.

Namespaces compared with clusters and labels

Choosing between namespaces, separate clusters and labels is a trade-off between isolation strength and operational cost. Namespaces are cheap and share one control plane; separate clusters isolate far more strongly but multiply upgrades, monitoring and spending; labels only group objects and enforce nothing.

ApproachIsolation strengthOperational costTypical fit
Labels and selectorsNone, grouping onlyVery lowOrganizing components of one application
Namespace per team or appSoft, policy-basedLowTrusted internal teams
Virtual clusterMedium, separate API serverModerateTenants needing their own cluster-scoped objects
Dedicated clusterStrong, separate control planeHighUntrusted tenants or strict compliance
Ways to separate workloads

The kernel remains shared in the namespace model, so a container escape on one node can affect Pods from other namespaces on that node. For hostile multi-tenancy, practitioners add sandboxed runtimes, dedicated node pools with taints, or separate clusters.

Designing a namespace strategy

A good namespace strategy mirrors ownership and lifecycle. The most common patterns are one namespace per team, one per application, or one per application and environment, and each choice determines how quotas, permissions and cost reports are aggregated.

  • Namespace per team simplifies RBAC and chargeback but mixes unrelated applications.
  • Namespace per application aligns with Helm releases and GitOps folders, which keeps deployments self-contained.
  • Namespace per environment inside one cluster is convenient for development and testing, but production usually deserves its own cluster.
  • Ephemeral namespaces for pull-request previews are created and deleted automatically by the build pipeline.

Deleting a namespace deletes everything inside it, which is both a convenience and a hazard. A namespace can also hang in the Terminating state when a finalizer cannot complete, typically because a custom resource controller has been removed first; the fix is to restore the controller rather than to strip finalizers blindly.

Common mistakes with namespaces

Most namespace problems come from treating the namespace as stronger than it is, or from forgetting which namespace a command targets.

  • Assuming namespaces block network traffic; they do not until NetworkPolicy objects exist and the network plugin enforces them.
  • Granting a ClusterRoleBinding where a RoleBinding was intended, which silently extends access to every namespace.
  • Running everything in default, which makes quotas, access reviews and cleanup much harder.
  • Forgetting to set --namespace or the context namespace, then applying manifests to the wrong place.
  • Expecting a Pod to mount a ConfigMap or Secret from another namespace, which the API does not allow.

In everyday language

Think of a cluster as a large shared office building and a namespace as one labeled floor. Each team gets a floor, and two teams can each have a room called meeting room without anyone getting confused, because the floor name is part of the address.

The floor sign alone does not lock any doors. To keep teams apart, the building manager also hands out keys, budgets and hallway rules. In Kubernetes, those are access permissions, resource quotas and network policies. The namespace organizes; the policies protect.

Seen in the real world

A mid-sized software company runs one production cluster of about 40 nodes for six product teams. The platform team creates a namespace per application, such as billing-api and search-frontend, from a template that adds a RoleBinding for the owning team, a ResourceQuota of 32 CPU cores and 64 GiB of memory, a LimitRange with sensible defaults, a default-deny NetworkPolicy and the restricted Pod Security level.

When a load test in the search team accidentally scaled to hundreds of replicas, the quota stopped new Pods at the namespace limit and the billing service kept its capacity. Monthly cost reports grouped by namespace also let finance assign cloud spending to each team. The result was fewer cross-team incidents and clear ownership without the overhead of six separate clusters.