skip to content

What does a Kubernetes namespace actually scope, and which resources, such as Nodes, PersistentVolumes and CRDs, sit outside every namespace?

level: juniorimportance: must knowfreq 72%

answer

  1. names are unique per namespace
  2. machines and storage are cluster-wide
  3. a CRD's scope field decides
  4. api-resources has a filter flag
  5. NAMESPACED column

basics

~10 s

A Kubernetes namespace scopes object names and most workload objects: Pods, Services, Secrets, ConfigMaps, PVCs. Nodes, PersistentVolumes, StorageClasses, ClusterRoles, CRDs and Namespaces themselves are cluster-scoped. Run kubectl api-resources --namespaced=false to list them.

solid answer

~40 s

A namespace is a name scope. Two objects of the same kind can share a name if they live in different namespaces, and most everyday objects are namespaced: Pods, Deployments, Services, ConfigMaps, Secrets, ServiceAccounts, PersistentVolumeClaims, Roles and RoleBindings. Some resources describe the whole cluster, so they are **cluster-scoped** and have no `metadata.namespace`: `Node`, `PersistentVolume`, `StorageClass`, `ClusterRole`, `ClusterRoleBinding`, `PriorityClass`, `CustomResourceDefinition` and `Namespace` itself, which is why namespaces cannot nest. A custom resource is namespaced or cluster-scoped depending on its CRD's `spec.scope`. You don't have to memorise the split: `kubectl api-resources --namespaced=false` lists the cluster-scoped types, `--namespaced=true` lists the rest, and the `NAMESPACED` column shows both.

code

bash · 4 lines
bash
kubectl api-resources --namespaced=false
kubectl api-resources --namespaced=true -o name
kubectl get pv
kubectl get pvc -n records-dev

go deeper

for a junior

Recall the everyday namespaced objects and a handful of cluster-scoped ones: Node, PersistentVolume, StorageClass, ClusterRole, CRD and Namespace. Know the kubectl api-resources filter.

for a middle

Explain why each cluster-scoped type is cluster-wide, how a CRD's spec.scope decides its objects' scope, and how a PersistentVolume's claimRef points into one namespace.

for a senior

Show that you use the split operationally: sweeping every namespaced type with api-resources, and knowing which objects a namespace owner can never control alone.

for a principal

Frame namespaces as a naming and attachment point rather than a wall, and name which cluster-scoped objects stay shared when you design how teams split a cluster.

## What a namespace is A **namespace** in Kubernetes is a named partition inside one cluster's API. It does one precise job: it gives object **names** a scope. Inside the namespace `records-dev`, only one Deployment can be called `portal`, but `records-review` can hold its own Deployment called `portal` without a clash. The rule is per resource type, so a Service and a Deployment in the same namespace may share a name. The namespace also shows up in the API path. A namespaced object lives under a path such as `/api/v1/namespaces/records-dev/pods/portal-7c9d4`, while a cluster-scoped object lives directly under its type, such as `/api/v1/nodes/dev-laptop`. A namespace name must be a valid DNS label: lowercase letters, digits and hyphens, at most 63 characters. ## The namespaced vs cluster-scoped split Every resource type is registered as either **namespaced** or **cluster-scoped**. The table shows common examples. | Namespaced (carry `metadata.namespace`) | Cluster-scoped (no namespace) | |---|---| | `Pod`, `Deployment`, `StatefulSet`, `Job` | `Node` | | `Service`, `EndpointSlice`, `Ingress` | `PersistentVolume`, `StorageClass` | | `ConfigMap`, `Secret`, `ServiceAccount` | `CustomResourceDefinition` | | `PersistentVolumeClaim` | `ClusterRole`, `ClusterRoleBinding` | | `Role`, `RoleBinding`, `NetworkPolicy` | `PriorityClass`, `IngressClass`, `RuntimeClass` | | `ResourceQuota`, `LimitRange`, `Event`, `Lease` | `Namespace`, `CertificateSigningRequest` | | | `ValidatingWebhookConfiguration`, `APIService` | The reasoning follows what the object describes: - **Machines and shared infrastructure** are cluster-wide. A `Node` is a machine every namespace schedules onto; a `PersistentVolume` is a piece of storage that a claim in some namespace binds to; a `StorageClass` is a provisioning recipe anyone can use. - **API extensions** are cluster-wide. A `CustomResourceDefinition` adds a new type to the whole API server, so it cannot belong to one tenant. - **Namespaces themselves** are cluster-scoped objects. That is why namespaces do not nest: there is no namespace inside a namespace. - **Workloads, their configuration and their claims** are namespaced, because those are what teams own. ## Custom resources: the CRD decides A CRD is always cluster-scoped, but the **custom objects** it defines can be either. The CRD's `spec.scope` field takes `Namespaced` or `Cluster`. A `Namespaced` CRD produces objects that live in namespaces; a `Cluster` CRD produces cluster-wide objects. So "is this custom resource namespaced?" is answered by reading its CRD, or simply by `kubectl api-resources`. ## How to check instead of memorising `kubectl api-resources` prints every type the API server serves, with a `NAMESPACED` column. Its flags narrow the output: 1. `kubectl api-resources --namespaced=false` lists only cluster-scoped types, including the ones added by CRDs and aggregated APIs on this particular cluster. 2. `kubectl api-resources --namespaced=true` lists only namespaced types. 3. Adding `-o name` prints bare resource names, handy for scripting a sweep of every namespaced type in one namespace. The split also explains some everyday kubectl behaviour: - `kubectl get pv -n records-dev` returns the same list as `kubectl get pv`: the namespace flag does not apply to a cluster-scoped type. - `kubectl get pvc -A` (short for `--all-namespaces`) lists claims across every namespace, with a `NAMESPACE` column. - `kubectl delete namespace records-review` removes the namespaced objects inside it but leaves cluster-scoped objects, such as a PersistentVolume that a claim there used, to their own rules. - A PersistentVolume's `spec.claimRef` names **both** the namespace and the name of the claim it is bound to, because the volume sits outside every namespace and must point into one. ## What a namespace does not do A namespace scopes names and gives other controls something to attach to, but it is **not an isolation boundary by itself**: - Pods in different namespaces can still talk to each other over the network unless a NetworkPolicy, enforced by the network plugin, says otherwise. - All namespaces share the same Nodes, the same kernel on each node and the same cluster-scoped objects. - Anyone bound to a ClusterRole through a ClusterRoleBinding can use its permissions in every namespace. Access control, quotas and network rules are what make a namespace behave like a tenant boundary; the namespace is the handle they attach to. Those controls are themselves split by scope: a `Role` and `RoleBinding` live in one namespace, while a `ClusterRole` and `ClusterRoleBinding` do not, which is exactly why cluster-scoped objects need a separate owner. On a single-node laptop cluster this is easy to see: the portal in `records-dev` and a copy in `records-review` run on the same machine and use the same `StorageClass`, and only their names are separated.

  • Why can Kubernetes namespaces not be nested inside each other?
    A `Namespace` is itself a cluster-scoped object, so it has no `metadata.namespace` to place it inside another namespace. The API has exactly one level of scoping: an object is either in one namespace or cluster-wide. Hierarchy has to be modelled with naming conventions, labels or an add-on controller that copies policy between namespaces, not with the core API.
  • A PersistentVolume is cluster-scoped but its claim is namespaced. How does Kubernetes link them?
    The PersistentVolume's `spec.claimRef` records the claim's namespace and name, so a cluster-wide volume can point into exactly one namespace. The PersistentVolumeClaim records the bound volume's name in `spec.volumeName`. Once bound, no claim in another namespace can use that volume, even with the same claim name.
  • Does `kubectl get nodes -n records-dev` show only the nodes used by that namespace?
    No. `Node` is cluster-scoped, so the namespace flag does not apply and the command lists every node in the cluster. To see where a namespace's pods run, list its pods with `kubectl get pods -n records-dev -o wide` and read the `NODE` column.

A namespace is like a folder on a shared drive: two folders can each hold a file called report, but the disk, the printer and the drive's settings belong to everyone.

saying these in an interview costs you the question

  • PersistentVolumes belong to the namespace of the claim that uses them
  • Namespaces can be nested to model teams and sub-teams
  • Every Kubernetes object, including Nodes, lives in some namespace
  • Custom resources are always cluster-scoped because the CRD is
  • A namespace isolates network traffic and nodes on its own