CRDs, schemas, and conversion
Define a small API with validation and an explicit version contract.
What you will understand
- Separate a CRD API registration from an operator implementation.
- Explain structural schemas, pruning, validation and status.
- Plan served/storage version changes without data loss.
Builds on: Finalizers, garbage collection, and API evolution, Informers, caches, and workqueues
Mental model: adding an API does not add behavior
A CustomResourceDefinition registers a resource type with the Kubernetes API server. Clients can discover it, validate instances against its schema, and store those instances through normal API mechanisms. The CRD does not itself create Deployments, provision databases or run cleanup code. An operator supplies that behavior by reconciling custom resources. Keeping those responsibilities separate makes it possible to diagnose a rejected specification independently from a controller that cannot fulfill an accepted specification.
The local API is WebApp in group labs.kv.example, version v1alpha1, with namespaced instances addressed as webapps. Its spec has a replica count and a page message. The downloadable CRD constrains replicas to a small positive range and limits message length. These checks reject invalid input early; they do not prove enough node capacity exists or that the message is suitable for every possible production application.
API registration precedes reconciliation
The Python operator reads the instance and applies ordinary Kubernetes children.
The CRD becomes Established and the API can discover webapps.labs.kv.example.
- WebApp CRD to API serverregister type
Read the complete visual sequence
- Register the type
The CRD becomes Established and the API can discover webapps.labs.kv.example.
- Store an instance
A valid WebApp spec is accepted even when no operator process is running.
- Apply structural schema rules
The structural schema validates replicas and message types and bounds. Unknown fields are normally pruned unless preservation is explicitly enabled for that subtree, so read the stored object back rather than assume a misspelled field was retained.
- Supply behavior separately
The Python operator reads the instance and applies ordinary Kubernetes children.
Invalid desired input
The schema rejects an out-of-range replica count before reconciliation.
- Client sends replicas zero
The teaching schema requires a positive count within its configured range.
- Validation rejects write
The invalid instance is not stored as the new desired state.
- Operator cannot fix absent intent
No new valid intention reaches the controller; correct the request rather than restart its children.
About this model
The concrete lab uses a single namespaced v1alpha1 API and a host-run polling controller.
Walkthrough: a schema is a compatibility contract
A structural OpenAPI schema describes known fields, types and list/map behavior. Unknown fields are generally pruned unless preservation is explicitly configured for the relevant subtree. This can surprise a client that sends a misspelled field and then assumes it was retained. Use strict server-side validation where appropriate and read the stored object back. A nested required list applies when its parent exists; require spec at the schema root if the controller cannot handle its absence. Defaults and validation rules become part of the API contract, so changing them can alter future writes and the controller’s interpretation of existing objects.
The status subresource separates observed state from desired spec. The lab status reports observedGeneration and readyReplicas. observedGeneration tells you which desired generation was processed; it is not automatically a Ready condition. If the controller updates observedGeneration immediately after inspecting an unready Deployment, readiness can still be zero. Production APIs often add conditions with reason, message, status and transition time to describe blocked or progressing states precisely.
Representation, storage, and observed generation
The controller writes status through its subresource. observedGeneration can advance before readyReplicas reaches the target.
The client uses a served representation whose schema defines fields and validation.
- Versioned client to Schema / conversionversioned object
Read the complete visual sequence
- Serve a version
The client uses a served representation whose schema defines fields and validation.
- Persist with a storage contract
The API uses the designated storage version; adding a version alone does not rewrite old objects.
- Report observations separately
The controller writes status through its subresource. observedGeneration can advance before readyReplicas reaches the target.
Conversion unavailable
An API that depends on a conversion webhook has an availability dependency.
- New client requests conversion
A multi-version extension requires representation conversion for this request.
- Webhook cannot respond
The required conversion path is unavailable; the request may fail even though data still exists.
- Do not remove old storage blindly
Recover the conversion path and verify migration before disabling older stored representations.
About this model
The lab has one version and no conversion webhook; the failure branch models a future multi-version API.
Versioning requires a second distinction. Multiple versions may be served, while exactly one version is designated for storage. Conversion maps representations; it does not execute an upgrade of the user’s external database. A conversion webhook must preserve information needed to round-trip safely and be available whenever conversion is required. Setting a new storage version does not rewrite all existing stored objects by itself. Plan storage migration and verify storedVersions before removing an old version.
This instance is valid only after applying the lab’s complete CRD. The bounds belong to the CRD schema, not to comments in an instance manifest.
apiVersion: labs.kv.example/v1alpha1
kind: WebApp
metadata:
name: m16
namespace: kv-lab
labels:
lab: m16
spec:
replicas: 1 # CRD accepts 1 through 5 in this teaching API.
message: hello-from-webapp
# Run from the downloaded m16 directory.
kubectl --context kind-kv-lab apply -f crd.yaml
kubectl --context kind-kv-lab wait --for=condition=Established crd/webapps.labs.kv.example --timeout=60s
kubectl --context kind-kv-lab -n kv-lab apply -f resources.yaml
kubectl --context kind-kv-lab explain webapp.spec
kubectl --context kind-kv-lab -n kv-lab get webapp m16 -o yaml
Practice: test the API before the controller
Open the m16 local exercise. Read crd.yaml, then apply only the CRD and custom resource before running the Python operator. Expect the WebApp to exist without a generated Deployment until reconciliation runs. This is direct evidence that API registration and behavior are separate. Try an out-of-range replica count using server-side dry run and expect schema rejection. Restore the valid input before continuing to the next lesson.
Compare the submitted manifest with the object returned by the API. Note apiVersion, generation, UID and the absence or presence of status. Inspect the CRD’s versions and storedVersions fields. This single-version example has no conversion webhook and proves no multi-version migration behavior. A production migration needs old-client fixtures and round-trip tests as well as a schema that accepts the new fields.
Pitfalls: API deletion is data deletion
Removing the operator Deployment leaves custom resources stored but unreconciled. Deleting the CRD removes the API and can delete its stored instances. Treat that as a separate destructive action, not routine controller restart cleanup. Overly broad preserve-unknown-fields settings make validation and field ownership less predictable. Conversely, tightening a schema without examining stored objects can make legitimate updates fail. Review the behavior of both old and new clients before changing a shared API.
Check your understanding
The CRD is Established and a WebApp exists. Why is there no web server?
The CRD only registers storage and validation for the custom API. The operator must reconcile the WebApp into a Deployment and ConfigMap, after which normal workload controllers and kubelets still need to make the Pods ready.
Next, run the small controller and inspect exactly which objects it owns. Start with one reconcile pass so partial progress is visible.
Go to the source
Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise