kubectl api-resources --namespaced

Understanding Namespaced vs Cluster-Scoped Resources

The --namespaced flag on kubectl api-resources is one of the most useful filters for understanding Kubernetes resource organization. It clearly shows which resources live inside namespaces and which exist at the cluster level.

Namespaced Resources

Namespaced resources are isolated within a namespace boundary:

kubectl api-resources --namespaced=true
# NAME                        SHORTNAMES   APIVERSION   NAMESPACED   KIND
# configmaps                  cm           v1           true         ConfigMap
# endpoints                   ep           v1           true         Endpoints
# events                      ev           v1           true         Event
# pods                        po           v1           true         Pod
# secrets                                  v1           true         Secret
# services                    svc          v1           true         Service
# deployments                 deploy       apps/v1      true         Deployment
# replicasets                 rs           apps/v1      true         ReplicaSet
# statefulsets                sts          apps/v1      true         StatefulSet
# daemonsets                  ds           apps/v1      true         DaemonSet
# jobs                                     batch/v1     true         Job
# cronjobs                    cj           batch/v1     true         CronJob
# ingresses                   ing          networking   true         Ingress
# networkpolicies             netpol       networking   true         NetworkPolicy
# roles                                    rbac         true         Role
# rolebindings                             rbac         true         RoleBinding

Key characteristics:

• Must specify a namespace with -n or use the default namespace.
• Two resources with the same name can exist in different namespaces.
• RBAC is managed with Roles and RoleBindings.

Cluster-Scoped Resources

Cluster-scoped resources exist outside any namespace:

kubectl api-resources --namespaced=false
# NAME                       SHORTNAMES   APIVERSION   NAMESPACED   KIND
# namespaces                 ns           v1           false        Namespace
# nodes                      no           v1           false        Node
# persistentvolumes          pv           v1           false        PersistentVolume
# clusterroles                            rbac         false        ClusterRole
# clusterrolebindings                     rbac         false        ClusterRoleBinding
# storageclasses             sc           storage      false        StorageClass
# ingressclasses                          networking   false        IngressClass
# customresourcedefinitions  crd          apiextensions false       CustomResourceDefinition
# priorityclasses            pc           scheduling   false        PriorityClass

Key characteristics:

• No namespace required or accepted.
• Unique names across the entire cluster.
• RBAC requires ClusterRoles and ClusterRoleBindings.

The PV/PVC Distinction

A commonly misunderstood relationship:

# PersistentVolumes are cluster-scoped
kubectl api-resources --namespaced=false | grep persistentvolumes
# persistentvolumes    pv    v1    false    PersistentVolume

# PersistentVolumeClaims are namespaced
kubectl api-resources --namespaced=true | grep persistentvolumeclaims
# persistentvolumeclaims    pvc    v1    true    PersistentVolumeClaim

A PV exists at the cluster level and can be bound to a PVC in any namespace. Once bound, the PVC is accessible only within its namespace.

RBAC Implications

The namespaced/cluster distinction directly affects RBAC configuration:

# For namespaced resources, use Role + RoleBinding
kubectl create role pod-reader --verb=get,list,watch --resource=pods -n development
kubectl create rolebinding pod-reader-binding --role=pod-reader --user=jane -n development

# For cluster-scoped resources, use ClusterRole + ClusterRoleBinding
kubectl create clusterrole node-reader --verb=get,list,watch --resource=nodes
kubectl create clusterrolebinding node-reader-binding --clusterrole=node-reader --user=jane

A ClusterRole can also grant access to namespaced resources cluster-wide:

# Grant access to pods in ALL namespaces
kubectl create clusterrole all-pod-reader --verb=get,list,watch --resource=pods
kubectl create clusterrolebinding all-pods --clusterrole=all-pod-reader --user=jane

Namespace Isolation Patterns

Understanding scope is critical for multi-tenant clusters:

# Each team gets a namespace with resource quotas
kubectl create namespace team-a
kubectl create namespace team-b

# Namespaced resources are isolated per team
kubectl get pods -n team-a   # Only team-a's pods
kubectl get pods -n team-b   # Only team-b's pods

# But cluster-scoped resources are shared
kubectl get nodes            # All teams see the same nodes
kubectl get storageclasses   # Shared storage classes

Auditing Resource Scope

List all resources and their scope for documentation:

# Generate a complete scope reference
kubectl api-resources -o wide --sort-by=name | \
  awk 'NR==1 || /true/ {print "NS: "$0} NR==1 || /false/ {print "CL: "$0}'

# Export as CSV
kubectl api-resources --no-headers | awk '{print $1","$4","$5}' | sort

CRD Scope

Custom Resource Definitions can be either namespaced or cluster-scoped:

# Namespaced CRD
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
spec:
  scope: Namespaced  # or Cluster

# Check CRD scope
kubectl api-resources --api-group=myapp.example.com

Common Interview Questions

Q: Can a Service in namespace A route traffic to a Pod in namespace B? Yes, using the fully qualified DNS name: service.namespace-b.svc.cluster.local. But NetworkPolicies can block cross-namespace traffic.

Q: If I create a ConfigMap named "config" in namespace A and namespace B, are they the same? No. They are completely independent resources that happen to share a name. Changes to one do not affect the other.

Q: Why are Namespaces themselves cluster-scoped? Because namespaces define the boundaries for namespaced resources. They must exist outside any namespace to serve as the organizational unit.