Managing Custom Resource Definitions
1. Creating CRD
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata: { name: widgets.example.com }
spec:
group: example.com
scope: Namespaced
names: { plural: widgets, singular: widget, kind: Widget, shortNames: [wd] }
versions:
- name: v1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
required: [size]
properties:
size: { type: integer, minimum: 1, maximum: 10 }
color: { type: string, enum: [red, green, blue] }
subresources: { status: {} }
2. Listing CRDs
kubectl get crd
kubectl api-resources --api-group=example.com
3. Describing CRD Details
| Field | Info |
|---|
| Established | Discovery API serves it |
| NamesAccepted | Names not conflicting |
4. Defining CRD Versions
| Field | Effect |
|---|
| served | Version reachable via API |
| storage | Exactly one storage version |
| deprecated | Warn on use |
| conversion | None / Webhook (for multi-version) |
5. Setting CRD Scope
| scope | Detail |
|---|
| Namespaced | CR lives in a namespace |
| Cluster | Cluster-wide (e.g., ClusterIssuer) |
6. Configuring Validation Schema
| OpenAPI Feature | Use |
|---|
| required | Mandatory fields |
| enum / pattern | Constrain values |
| x-kubernetes-validations | CEL rules (1.28+ stable) |
| x-kubernetes-preserve-unknown-fields | Allow extra fields |
7. Using CRD Subresources
subresources:
status: {}
scale:
specReplicasPath: .spec.replicas
statusReplicasPath: .status.replicas
labelSelectorPath: .status.labelSelector
8. Setting Printer Columns
additionalPrinterColumns:
- { name: Size, type: integer, jsonPath: .spec.size }
- { name: Ready, type: string, jsonPath: .status.conditions[?(@.type=="Ready")].status }
- { name: Age, type: date, jsonPath: .metadata.creationTimestamp }
9. Creating Custom Resources
apiVersion: example.com/v1
kind: Widget
metadata: { name: my-widget }
spec: { size: 5, color: blue }
10. Understanding CRD Finalizers
| Behavior | Detail |
|---|
| Block delete | Object stuck in Terminating until finalizer removed |
| Force delete | kubectl patch ... -p '{"metadata":{"finalizers":[]}}' --type=merge |
11. Deleting CRDs
kubectl delete crd widgets.example.com
Warning: Deleting a CRD removes ALL custom resources of that kind cluster-wide.