A Custom Resource Definition (CRD) extends Kubernetes by defining a new resource type that the cluster can store and manage. It lets operators model custom objects through the API. Security teams should control who can create or modify CRDs, review the controllers that act on them, and watch for malformed definitions that could expand privileges or destabilise the cluster.
How a CRD fits into the Kubernetes API
A CRD is Kubernetes’ extension point for adding a new API object without changing the core platform. Once the CRD is registered, the API server recognises that resource kind, stores its instances, and exposes them like native objects. That means teams can model domain-specific state in Kubernetes terms, then use standard workflows such as create, update, list, watch, and delete.
The important design point is that a CRD is not just a schema file. It becomes part of the cluster’s control surface, so the definition itself influences what the API accepts and how other components interpret the object. In practice, the CRD plus the controller that reconciles it behave like a custom control loop around a new cluster resource.
Because this is an API extension mechanism, the operational question is not only “can Kubernetes store it?” but also “who is allowed to define or change the contract?” The Kubernetes Security Guide is useful here because CRDs sit inside broader cluster hardening, admission, and control-plane governance concerns.
What usually makes CRDs powerful and fragile at the same time
CRDs are attractive because they let teams encode platform policy, deployment state, or application-specific workflows directly into the cluster. That reduces glue code and makes automation easier, but it also means the cluster now depends on the quality of the custom resource contract and the controller behaviour behind it. A poorly designed CRD can create confusing object lifecycles, unclear ownership, or reconciliation loops that are hard to diagnose.
The security angle is that a CRD can widen the blast radius of mistakes. If the resource schema is too permissive, if admission checks are weak, or if the controller assumes trusted input, attackers or careless operators may be able to create objects that trigger privileged actions, consume excessive resources, or destabilise the control plane. This is especially true when the CRD is used to drive automation that touches secrets, networking, workloads, or cloud credentials.
CRDs also introduce ecosystem risk because their real behaviour depends on the controller and any webhooks, operators, or sidecars that process them. A secure definition on paper is not enough if the reconciler interprets fields too broadly or fails open when input is malformed. For that reason, teams should treat CRDs as governed interfaces, not as harmless configuration metadata.
What security teams should verify before trusting a CRD
Start by checking who can create, update, or delete the CRD itself, not just who can create custom objects from it. Changing the definition can alter validation, storage shape, and the set of fields that other automation trusts. Review whether those permissions are limited to a small administrative group and whether changes are audited.
Then examine the controller path. Confirm what privileges the controller runs with, what Kubernetes objects it can touch, and whether it validates every field it consumes. If the controller can create Pods, bind roles, mutate network policy, or call external services, the CRD becomes part of a privilege-bearing workflow, not merely an API convenience.
Finally, validate failure handling. A mature CRD implementation should reject malformed definitions, fail closed when reconciliation cannot trust input, and make status conditions clear enough to detect drift. If those signals are weak, the team will often learn about the problem only after the controller has already acted on bad state.
Risk and Threat Considerations
CRDs expand the cluster attack surface because they create another API contract that may be abused if permissions, validation, or controller logic are weak. The main risk is not the definition alone, but the combination of writable schema, powerful reconciliation logic, and broad cluster access.
Failure mechanism: An attacker or mistaken operator introduces a CRD or custom object that is accepted by the API server but interpreted unsafely by the controller, allowing privilege expansion, workload manipulation, or cluster instability.
Impact: The result can be unauthorized actions, unexpected automation side effects, denial of service, or a path from a benign-looking custom object into privileged cluster behaviour.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
NIST SP 800-53 Rev 5 and CIS Controls v8 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | AC-6 — Least Privilege | CRDs and controllers must run with minimal permissions to limit cluster impact. |
| CM-6 — Configuration Settings | CRD schema and controller settings directly shape accepted cluster state and behavior. | |
| AU-2 — Event Logging | CRD changes and reconciler actions need auditability for investigation and drift detection. | |
| Recommendation — Constrain CRD administrators and controllers to the minimum permissions needed. Standardise and review CRD and controller configuration before rollout. Log CRD creation, modification, and reconciliation activity for later review. | ||
| CIS Controls v8 | 5 — Account Management | Administrative control over who can alter CRDs is an access-governance issue. |
| 16 — Application Software Security | CRD controllers are custom software that must be validated for unsafe input handling. | |
| Recommendation — Restrict CRD and operator administration to approved accounts only. Assess controller code and webhook logic for unsafe assumptions about custom resources. | ||
Practitioner Guidance
What to prioritise: Treat CRD governance as part of control-plane security. The first questions are who can change the definition, what the controller can do, and whether the custom object’s fields are actually constrained to the intended business use.
What to verify: Review the CRD schema, the controller permissions, and the admission path together. If any one of those is loosely controlled, the resource should be treated as a high-risk extension rather than a routine platform feature.
Common mistake: Teams often secure the custom objects while leaving the CRD itself, the operator logic, and the reconciliation permissions too broad. That creates a gap where the platform appears governed, but the effective authority sits in the controller path.
Practitioner takeaway: A CRD is safe only when the API contract, the controller’s privileges, and the validation model are governed as one system; otherwise the extension point becomes a security boundary you cannot actually trust.