Sign In

Curriculum 10: Working with Namespaces

Namespace Scoping

10 min · 15 XP

Namespace Scoping

Not every Kubernetes resource lives inside a namespace. Understanding the difference between namespaced and cluster-scoped resources is essential for organizing your cluster correctly.

Namespaced Resources

Most resources you work with daily are namespaced. They belong to exactly one namespace and are isolated from resources in other namespaces. Examples include:

  • Pods
  • Deployments
  • Services
  • ConfigMaps
  • Secrets
  • Jobs

When you run kubectl get pods -n staging, you only see pods in the staging namespace.

Cluster-Scoped Resources

Cluster-scoped resources exist at the cluster level and are not tied to any namespace. Examples include:

  • Nodes
  • Namespaces themselves
  • PersistentVolumes
  • ClusterRoles
  • ClusterRoleBindings
  • StorageClasses
  • IngressClasses

These resources are shared across the entire cluster.

Discovering Resource Scope

Use kubectl api-resources with the --namespaced flag to see which category a resource falls into:

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

# List all cluster-scoped resources
kubectl api-resources --namespaced=false

You can also filter by API group:

# Show only resources in the apps group
kubectl api-resources --api-group=apps --namespaced=true

Why Scoping Matters

Scoping affects how you query and manage resources:

# Namespaced: you must specify a namespace
kubectl get deployments -n production

# Namespaced: view across ALL namespaces
kubectl get pods --all-namespaces
kubectl get pods -A

# Cluster-scoped: no namespace needed
kubectl get nodes
kubectl get persistentvolumes

Trying to pass -n on a cluster-scoped resource does nothing -- the flag is silently ignored.

Common Gotcha

A frequent mistake is creating a Role (namespaced) when you meant to create a ClusterRole (cluster-scoped), or vice versa. If RBAC permissions are not working, check whether you matched the correct scope.

Key Takeaways

  • Most daily resources (Pods, Deployments, Services) are namespaced
  • Infrastructure resources (Nodes, PVs, ClusterRoles) are cluster-scoped
  • Use kubectl api-resources --namespaced=true/false to discover scope
  • Use -A or --all-namespaces to query namespaced resources across every namespace
  • The -n flag is silently ignored on cluster-scoped resources