A Custom Resource Definition extends the Kubernetes API with new resource types that are specific to an application or platform need. In this context, CRDs can store security findings as first-class cluster objects, making risk data queryable, shareable, and manageable through standard Kubernetes workflows instead of separate reporting systems.
What a Kubernetes Custom Resource Definition Does
A custom resource Definition extends the Kubernetes API so teams can add application-specific object types that behave like native resources, with the same discovery, validation, storage, and workflow benefits as built-in objects.
That matters because CRDs turn Kubernetes from a fixed platform into an extensible control plane. Once a CRD exists, clusters can store and process domain objects, such as policy records, deployment metadata, or security findings, through standard API operations instead of separate tooling.
For security-minded teams, the key point is not just that CRDs are “custom objects,” but that they become part of the cluster’s trusted API surface. The design choice shifts where data lives, who can read or modify it, and how consistently it is governed alongside workloads and configuration.
How CRDs Fit Into the Kubernetes API Model
CRDs work by registering a new schema with the Kubernetes API server. Once registered, the new resource type can be created, listed, watched, updated, and deleted with ordinary Kubernetes mechanisms, and controllers can reconcile against it just as they do with Pods or Deployments.
This API-native model is what makes CRDs powerful. They can express custom lifecycle states, ownership relationships, and operational metadata in a way that fits Kubernetes conventions, which is why they are often used for operators, policy engines, and platform automation.
The benefit is consistency, but the trade-off is that the CRD becomes part of the cluster’s control plane complexity. Poorly designed schemas, versioning decisions, or controller behavior can create brittle dependencies, especially when a CRD is used to store information that many tools or teams rely on.
Why Security Teams Use CRDs for Findings and Policy
Security programs often use CRDs to make findings or policy objects queryable inside the cluster instead of exporting them into a separate system. That can simplify correlation, automation, and reporting because the data follows the same access patterns and operational workflows as other Kubernetes resources.
When a finding is represented as a first-class object, it can be tagged, filtered, watched, and acted on by controllers or admission workflows. That makes CRDs useful for platform security, compliance metadata, deployment guardrails, and internal security state that benefits from being close to the workload it describes.
The same advantage can also make CRDs sensitive. If the object schema exposes too much detail, or if access is too broad, the cluster may become a distributed store for security-relevant data that is easier to query than to protect.
Lifecycle, Versioning, and Operational Boundaries
CRDs are not just schema declarations, they are lifecycle artifacts. Their usefulness depends on version compatibility, conversion behavior, controller support, and clear ownership for the data they define. A CRD that is adopted widely but poorly maintained can become a long-lived dependency across platforms and teams.
Because CRDs are custom by design, the platform team must decide whether a resource is meant to be purely informational, strongly governed, or actively reconciled. That decision shapes how much validation, change control, and cleanup logic is needed when the resource schema evolves or the underlying controller changes.
In practice, the healthiest CRDs are those with a narrowly defined purpose and a clear contract. They should be treated as part of platform architecture, not as an informal storage shortcut for arbitrary metadata.
Risk and Threat Considerations
CRDs expand the Kubernetes attack surface because any custom object that stores security, policy, or operational state can be exposed through the API if authorization is too broad or validation is too weak. If the object becomes a source of truth, compromise of that object can influence decisions made by controllers, automation, or operators.
Failure mechanism: Weak schema design, overly permissive RBAC, or controller trust in untrusted CRD content can allow tampering, data leakage, or unsafe automation triggered by malicious or malformed objects.
Impact: Attackers or insiders may alter policy state, hide findings, poison automation inputs, or extract sensitive cluster metadata, which can undermine both security response and operational integrity.
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, CIS Controls v8, CSA Cloud Controls Matrix, OWASP ASVS and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | CM-2 — Baseline Configuration | CRDs change cluster configuration and must be governed as managed configuration items. |
| AC-6 — Least Privilege | CRD access is governed by who may read or mutate cluster objects and custom findings. | |
| SA-11 — Developer Testing and Evaluation | CRD schemas and controllers require validation to prevent unsafe object processing. | |
| Recommendation — Inventory CRDs as managed configuration items and control schema changes through baseline review. Restrict CRD read and write permissions to the smallest set of trusted roles. Test CRD schemas and controllers before deployment to catch validation and logic flaws. | ||
| CIS Controls v8 | CIS-4 — Secure Configuration of Enterprise Assets and Software | CRDs are part of Kubernetes software configuration and need hardened, reviewed definitions. |
| CIS-6 — Access Control Management | CRDs may store governed data, so access to create or modify them must be tightly managed. | |
| Recommendation — Harden CRD definitions and review cluster configuration changes before promotion. Limit CRD modification rights and review who can access custom objects. | ||
| CSA Cloud Controls Matrix | IAM — Identity & Access Management | CRDs often carry policy, findings, or control data that depends on Kubernetes access governance. |
| Recommendation — Map CRD access to cloud identity controls and separate readers from writers. | ||
| OWASP ASVS | V13 — Configuration | CRDs behave like platform configuration objects whose structure and defaults affect security. |
| Recommendation — Validate CRD configuration defaults and reject unsafe schema changes. | ||
| NIST CSF 2.0 | PR.AA-05 — Least Privilege Access is Managed | Custom resources must be exposed under least-privilege access rules in the cluster. |
| Recommendation — Apply least-privilege access to CRD creation, update, and read permissions. | ||
Practitioner Guidance
Governance implication: Treat every CRD as a governed API contract, not an ad hoc data bucket. Define ownership, versioning expectations, and the minimum privileges required to read or mutate the resource, especially when the object carries security findings or policy decisions.
What to watch for: Be cautious when a CRD starts to carry sensitive or decision-making data for other systems. At that point, the resource needs the same scrutiny you would apply to any other trusted control-plane object, including schema validation, access review, and lifecycle cleanup.
Related resources from NHI Mgmt Group
- What breaks when a Kubernetes controller does not watch for custom resource definition changes in real time?
- Why do mutable custom resource definitions create a confused deputy risk in Kubernetes?
- Why do per-resource secrets operators break down as Kubernetes clusters grow?
- What breaks when security tools keep using string-based configuration and flat resource references in Kubernetes?
