A CustomResourceDefinition, or CRD, extends Kubernetes with new API objects beyond the built-in resource types. It lets teams define custom schemas and controllers for application-specific workflows. Because CRDs become part of the cluster control plane, weak permissions or unsafe mutation paths can turn ordinary configuration into a privileged attack surface.
Expanded Definition
A CustomResourceDefinition, or CRD, is the Kubernetes mechanism for adding a new API type that the cluster understands and stores like a native object. It defines the object schema, validation rules, and API surface for a custom workload, platform capability, or operator-managed workflow.
CRDs are not just application metadata. Once installed, they extend the cluster’s control plane, so the object type itself becomes part of cluster governance. That is the key boundary: a CRD defines what can exist; its controller defines what the cluster does with it. A CRD may be used for anything from backup orchestration to policy automation, but it should not be confused with a simple ConfigMap or a custom application data model.
Guidance-vs-consensus note: there is broad agreement that CRDs should be treated as privileged platform constructs, but implementation patterns vary. Some teams tightly restrict who can create or modify them, while others allow broader platform engineering access and rely on admission, validation, and controller hardening. The common misunderstanding is to treat a CRD as “just another app object” rather than a control-plane extension.
Examples and Use Cases
CRDs appear when teams need Kubernetes to model domain-specific resources in a native way rather than through external scripts or ad hoc APIs.
- An operator installs a CRD for database clusters so teams can request replicas, backups, and failover through Kubernetes objects.
- A security platform defines a CRD for policy exceptions, letting an admission controller reconcile approved deviations across namespaces.
- A platform team creates a CRD for scheduled jobs with richer lifecycle states than a standard CronJob can express.
- A network automation system uses a CRD to declare routes, certificates, or load balancer intent, then a controller enforces the desired state.
The implementation tradeoff is convenience versus blast radius. A CRD can simplify operations by giving teams a clean API, but every new field, transition, and controller action also creates another place where malformed input or unsafe permissions can affect the cluster.
For readers comparing machine-facing controls across identity and platform governance, the OWASP Non-Human Identity Top 10 is useful context when CRD-driven automation depends on service accounts, tokens, or other non-human access paths.
Security Implications
CRDs become security-sensitive because they expand the attack and failure surface of the Kubernetes API. If a CRD is too permissive, poorly validated, or backed by a controller that trusts object fields too much, ordinary object creation can trigger privileged behavior inside the cluster.
Mismanagement can lead to excessive write access, controller abuse, escalation through dangerous reconciliation logic, or accidental denial of service when malformed objects cause repeated reconcile loops. Since CRDs can influence real infrastructure state, errors often affect more than one namespace and may spread through automation that assumes the CRD is trustworthy.
A common practitioner observation is that the CRD definition and the controller are inseparable from a security standpoint. Securing only the controller while leaving the custom API broadly writable still leaves a path for abuse. The reverse is also true: a restrictive schema does not fully protect the cluster if the controller performs privileged actions based on weakly validated intent.
Domain and Governance Relevance
In Kubernetes governance, CRDs sit at the point where platform extensibility becomes control-plane authority. That makes ownership, change control, and review discipline more important than they are for ordinary application configuration. The practical question is not whether a CRD is useful, but who can define it, who can modify it, and what cluster-level capabilities it can indirectly trigger.
For identity and non-human access, CRDs matter because many operators and controllers run with service accounts, cloud credentials, or other machine identities. If the CRD governs privileged automation, then the identity behind the controller must be treated as part of the trust boundary, not as an implementation detail. In that sense, CRDs are a governance issue for both platform teams and identity owners.
Where CRDs are used for infrastructure or policy orchestration, the safest interpretation is to treat them as controlled API extensions with security review, versioning discipline, and explicit ownership. They are most effective when the organisation recognises that extensibility in Kubernetes also means extensibility in authority.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 and MITRE ATT&CK address the attack and risk surface, while CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| CIS Controls v8 | 5 — Account Management | CRD controllers often rely on privileged accounts and service identities. |
| 6 — Access Control Management | CRDs can become a privileged API surface if write access is too broad. | |
| 16 — Application Software Security | CRD schemas and controllers introduce custom code and validation risk. | |
| Recommendation — Restrict and review accounts that can create or mutate CRDs and their controllers. Enforce least-privilege access to CRD creation, update, and deletion paths. Validate CRD schemas and harden controller logic before exposing new resource types. | ||
| OWASP Non-Human Identity Top 10 | NHI-01 — Inventory and Ownership of Non-Human Identities | CRD automation often runs through service accounts and other machine identities. |
| NHI-04 — Secrets and Credential Management | CRD-managed automation may depend on tokens, keys, or certificates. | |
| NHI-05 — Authorization and Permission Boundaries | CRD objects can trigger privileged actions if permission boundaries are weak. | |
| Recommendation — Inventory controller identities and assign clear ownership for every CRD-backed automation path. Protect and rotate credentials used by CRD controllers and reconciler workflows. Constrain what CRD-based automation can do and verify its effective permissions. | ||
| NIST CSF 2.0 | PR.AC — Identity Management, Authentication, and Access Control | CRDs become risky when cluster access and mutation rights are not tightly governed. |
| PR.PT — Protective Technology | CRD admission and controller safeguards are protective technologies for the control plane. | |
| Recommendation — Apply strong access control to who can define, modify, and operate CRDs. Use admission controls and validation to block unsafe CRD objects and mutations. | ||
| MITRE ATT&CK | T1611 — Escape to Host | Unsafe controllers or privileged workloads tied to CRDs can contribute to node-level compromise paths. |
| Recommendation — Map CRD abuse paths to attacker movement opportunities and monitor for privilege expansion. | ||
