Study guide
2.6 Custom Resource Definitions (CRDs) & Operators
Certified Kubernetes Administrator CKA
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: CKA Exam Environment & Cluster Architecture
1.1 CKA Exam Mechanics, Scoring & Remote Terminal Environment 1.2 Kubernetes Control Plane & Worker Node Components 1.3 etcd Architecture, Clustering & Raft Consensus 1.4 Initializing Clusters with Kubeadm 1.5 Highly Available (HA) Control Plane Topologies 1.6 Cluster Lifecycle & Step-by-Step Upgrades 1.7 etcd Snapshot Backup and Restore Procedures
2 Chapter 2: Cluster Extensions, Packaging & RBAC
2.1 Kubernetes TLS Certificates & PKI Infrastructure 2.2 Managing Kubeconfig Files, Users, & Contexts 2.3 Installing Cluster Components with Helm & Kustomize 2.4 Role-Based Access Control (RBAC): Roles & RoleBindings 2.5 ClusterRoles & ClusterRoleBindings 2.6 Custom Resource Definitions (CRDs) & Operators 2.7 Pod Security Standards (PSS) & Admission Controllers
3 Chapter 3: Workloads, Lifecycle & Pod Scheduling
3.1 Pod Lifecycle, Multi-Container Patterns & Init Containers 3.2 Deployments: Rolling Updates, Rollouts & Rollbacks 3.3 DaemonSets & StatefulSets Architecture 3.4 Batch Workloads: Jobs & CronJobs 3.5 Managing ConfigMaps & Sensitive Data with Secrets 3.6 Resource Requests, Limits & Namespace ResourceQuotas 3.7 NodeSelectors, Node Affinity & Anti-Affinity 3.8 Node Taints & Pod Tolerations 3.9 Autoscaling: Horizontal Pod Autoscaler (HPA) & Custom Metrics
4 Chapter 4: Services, Networking & Ingress Architecture
4.1 Kubernetes IP-per-Pod Model & CNI Plugins (Flannel, Calico, Cilium) 4.2 Services Deep Dive: ClusterIP, NodePort, LoadBalancer & EndpointSlices 4.3 Kube-Proxy Service Dataplane: iptables, nftables, IPVS & eBPF 4.4 CoreDNS Configuration, Resolution & Custom Forwarding 4.5 NetworkPolicies: Ingress, Egress & Default-Deny Isolation 4.6 Ingress Architecture, Controllers & Path-Based Routing 4.7 Gateway API: GatewayClass, Gateway, HTTPRoute & Traffic Splitting 4.8 External Traffic Ingress: NodePort, Cloud LoadBalancers & MetalLB
5 Chapter 5: Storage Architecture & Persistent Volumes
5.1 Ephemeral Volumes, EmptyDir, HostPath & Config Volumes 5.2 PersistentVolumes (PV) & PersistentVolumeClaims (PVC) Lifecycle 5.3 StorageClasses, Dynamic Provisioning & VolumeBindingModes 5.4 Storage Access Modes, Reclaim Policies & Volume Expansion 5.5 Container Storage Interface (CSI) Architecture & Drivers 5.6 StatefulSet VolumeClaimTemplates & Persistent Storage Workflows
6 Chapter 6: Advanced Troubleshooting, Monitoring & Maintenance
6.1 Systematic Kubernetes Troubleshooting Methodology 6.2 Node Failure, Kubelet Diagnostics & Systemd Services 6.3 Control Plane Failures, Static Pods & Component Logs 6.4 etcd Troubleshooting, Quorum Loss & Database Defragmentation 6.5 Pod Startup Failures, CrashLoopBackOff & OOMKilled Diagnostics 6.6 Workload Scheduling Failures & Resource Constraint Resolution 6.7 Container & Node Logging Architecture, Journalctl & Fluentd 6.8 Metrics Server, Resource Utilization & Kubectl Top 6.9 Service, Endpoint & Ingress Connectivity Troubleshooting 6.10 Storage Failures: PVC Pending, Mount Failures & Multi-Attach Errors 6.11 NetworkPolicy Isolation & CoreDNS Resolution Diagnostics
2.6 Custom Resource Definitions (CRDs) & Operators
Key Takeaways Explain This Topic AI
A CustomResourceDefinition registers a new API resource; custom objects then use kubectl, API discovery, authentication, authorization, admission, and etcd like built-in objects.
Each CRD version declares served and storage flags, and exactly one version must be the storage version used for newly persisted objects.
The Operator pattern combines a custom resource with a controller that repeatedly reconciles observed state toward the declared desired state.
Install and troubleshoot in dependency order: CRD, controller and RBAC, then custom resource; inspect discovery, conditions, Events, and controller logs.
Deleting a CRD also deletes its stored custom resources, so export data and understand finalizers, conversions, and ownership before removal or upgrade.
Last updated: August 2026
2.6 Custom Resource Definitions (CRDs) & Operators
Kubernetes can add new resource types without modifying the core API server binary. A CustomResourceDefinition (CRD) registers the API path, names, scope, versions, and validation schema for a new type. A custom resource (CR) is one object of that type. An Operator combines custom resources with a controller that encodes operational knowledge in a reconciliation loop.
1. CRD, Custom Resource, and Controller
- Component Responsibility
- CRD Defines and serves a new Kubernetes API type
- Custom resource Declares desired state using that new type
- Custom controller Watches resources and reconciles actual state
- Operator CRD/custom resource plus domain-specific controller behavior
Creating a CRD gives the new type standard Kubernetes API behavior: discovery, CRUD operations, watch, authentication, RBAC authorization, admission, labels, annotations, and finalizers. A CRD alone stores structured desired state; it does not create Deployments, databases, or external infrastructure unless a controller watches it.
- 2. Reading a CRD Manifest apiVersion: apiextensions.k8s.io/v1
- kind: CustomResourceDefinition
metadata:
name: backups.platform.example.com
spec:
- group: platform.example.com
- scope: Namespaced
names:
- plural: backups
- singular: backup
- kind: Backup
shortNames:
- bkp
versions:
- name: v1
- served: true
- storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
required:
- targetPVC
properties:
targetPVC:
type: string
retentionDays:
- type: integer
- minimum: 1
subresources:
status: {}
The CRD name must be <plural>.<group> . Namespaced resources live in one namespace; Cluster resources do not. Every listed version says whether the API server serves it and whether it is the storage version. Exactly one version must have storage: true . Multiple served versions may require a conversion strategy so clients see a coherent schema while stored objects migrate.
The structural OpenAPI schema rejects invalid types and can require fields, constrain numbers, or define nested objects. The status subresource lets the controller report observed state separately from the user's desired spec .
3. Create and Discover Custom Resources
After the CRD is Established, a custom object can be created like any built-in resource: apiVersion: platform.example.com/v1
kind: Backup
metadata:
- name: nightly-orders
- namespace: data
spec:
- targetPVC: orders-data
- retentionDays: 14
- Useful discovery commands: kubectl get crd backups.platform.example.com
- kubectl wait --for=condition=Established crd/backups.platform.example.com
- kubectl api-resources --api-group=platform.example.com
- kubectl explain backup.spec
- kubectl get backups -A
- kubectl get backup nightly-orders -n data -o yaml
If the API server returns “no matches for kind,” verify that the CRD exists, the apiVersion group/version is served, discovery has refreshed, and the Kind spelling matches.
- 4. Operator Reconciliation and Finalizers
- A controller watches desired state and acts until observed state matches it: Backup CR created
- > controller observes generation
- > validates referenced PVC
- > creates Job / snapshot request
- > records status.conditions and observedGeneration
- > requeues on changes or failures
Controllers must be idempotent: running reconciliation again should converge rather than duplicate work. They commonly use owner references so Kubernetes garbage collection removes dependent objects with their owner. A finalizer delays deletion while a controller performs external cleanup. If a CR remains Terminating , inspect metadata.finalizers , controller health, RBAC, and logs before removing a finalizer manually; forced removal can orphan cloud resources or data.
5. Installation and Upgrade Order
A reliable installation order is:
Apply the CRD and wait for the Established condition.
Install the controller Deployment, ServiceAccount, and RBAC.
Confirm the controller is Available and review its logs.
Create custom resources only after their API is served.
Inspect each CR's status.conditions , Events, generated children, and controller logs.
Helm charts can place CRDs in a top-level crds/ directory so they are installed before templated resources. Helm deliberately treats CRD lifecycle cautiously; do not assume a normal chart upgrade or uninstall will safely migrate or remove CRDs and their data. Follow the component owner's upgrade path.
For multi-version upgrades, add the new served version and conversion support, migrate stored objects, update the storage version, verify status.storedVersions , and only then stop serving an old version. Deleting a CRD deletes its custom-resource data from the API, so export or back up required objects first.
- 6. Operator Troubleshooting Runbook kubectl get crd <name> -o yaml
- kubectl get deployment -n <operator-namespace>
- kubectl auth can-i --as=system:serviceaccount:<ns>:<sa> get <resource> -A
- kubectl logs -n <operator-namespace> deployment/<controller>
- kubectl describe <custom-resource> <name> -n <namespace>
- kubectl get events -n <namespace> --sort-by=.metadata.creationTimestamp
Separate failure layers: the CRD may not be Established, the controller may be unavailable, RBAC may deny watches or writes, admission may reject generated objects, a finalizer may block deletion, or the custom resource may reference a missing dependency. Conditions and controller logs usually reveal which layer failed.