Introduction

A CustomResourceDefinition is cluster-wide because it does not represent one application object. It extends the Kubernetes API itself by defining a new kind, schema, and endpoint shape for the entire cluster.

A CRD Defines a Type, Not Just an Instance

This distinction is the key idea:

• a custom resource is an instance of a type
• a CRD defines the type itself

That puts a CRD in the same conceptual category as adding a new API resource to the cluster. Since the API server cannot have two competing definitions for the same kind depending on namespace, the definition must live at cluster scope.

For example, if you define a BackupPolicy CRD, you are teaching the cluster what BackupPolicy means everywhere, not just inside one namespace.

Namespaced Instances Are Still Possible

A point that confuses many people is that CRDs are cluster-scoped even though the custom resources created from them can still be namespaced.

A simplified CRD spec shows the difference:

1apiVersion: apiextensions.k8s.io/v1
2kind: CustomResourceDefinition
3metadata:
4  name: backups.example.com
5spec:
6  group: example.com
7  names:
8    kind: Backup
9    plural: backups
10    singular: backup
11  scope: Namespaced
12  versions:
13    - name: v1
14      served: true
15      storage: true
16      schema:
17        openAPIV3Schema:
18          type: object

Here the CRD itself is cluster-wide, but it defines a custom resource named Backup whose instances are namespaced.

That separation is intentional.

Why Namespace-Scoped CRDs Would Be Problematic

Imagine if each namespace could define its own version of the same kind name or schema. The cluster would then face questions such as:

• which schema should the API server expose for that kind
• how should shared clients discover the type
• how would controllers watch the resource consistently across namespaces
• what would RBAC and validation even mean for one API kind with different definitions

The Kubernetes API must remain globally coherent. Cluster-scoped CRDs preserve that coherence.

API Discovery Is a Cluster Concern

Kubernetes clients, controllers, and tools rely on API discovery. When a new CRD is installed, the cluster advertises a new resource type through its API discovery endpoints.

That process makes sense only if the type definition is global at the cluster level. Otherwise, clients would need namespace-dependent type systems, which would make discovery, validation, and controller code much harder.

Operators Depend on This Model

Operators often watch custom resources across several namespaces or even cluster-wide. A single CRD schema lets the operator reason about one stable resource shape.

That stability is especially important for:

• admission validation
• schema evolution
• code generation
• controller watches
• RBAC and documentation

If the type definition were namespace-specific, many operator patterns would become far more complicated.

Cluster Scope Does Not Mean Everyone Can Use It

Another common misunderstanding is that a cluster-scoped CRD definition means every user can freely create or edit those resources. Access is still controlled by RBAC.

The type is visible at cluster scope, but permissions determine who can create or manage instances and where they can do so.

So cluster-wide definition and cluster-wide access are not the same thing.

Common Pitfalls

The most common mistake is confusing a CRD with a custom resource instance. The definition is global even when the instances are namespaced.

Another issue is assuming cluster scope means a loss of isolation. In practice, namespaces, RBAC, and namespaced custom resources still provide the isolation most applications need.

People also underestimate how important API discovery consistency is. Kubernetes tooling assumes a resource kind has one coherent definition across the cluster.

Finally, do not choose scope: Cluster in the CRD spec unless the resource instances themselves truly need to be cluster-level objects. That setting affects the custom resources, not the CRD’s own scope.

Summary

• A CRD is cluster-wide because it defines a new API type for the whole cluster.
• The custom resources created from that CRD can still be namespaced.
• Cluster-scoped type definitions keep schema, discovery, and controller behavior consistent.
• Namespace-scoped CRD definitions would make API discovery and validation far more complicated.
• Cluster-wide definition does not remove RBAC or namespace-based access control.