Configure a CRD conversion webhook to support multiple API versions
domain: kubernetes.io · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Add a second version to the CRD spec and mark one version as the storage version with `storage: true`
Implement a conversion webhook server that handles `ConversionReview` requests converting between hub and spoke versions
Register the webhook in the CRD's `spec.conversion` block with `strategy: Webhook` and point it to the service and CA bundle
Map field renames or schema changes between versions in the conversion logic; use the hub version as an intermediate representation
Test conversion by creating a resource via the older API version and reading it back via the new version
Run `kubectl get <kind> --api-version <old-version>` and `--api-version <new-version>` to confirm both return valid objects
Known gotchas
The storage version must be able to round-trip all other versions without data loss; any field present in a spoke version must survive conversion to hub and back
Changing the storage version requires migrating existing objects in etcd; skipping this leaves objects stored in the old version schema, causing conversion errors
The conversion webhook must be available at all times when multiple CRD versions are served; downtime during upgrades causes API requests for non-storage versions to fail
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?