Create a `CustomResourceDefinition` manifest with `apiVersion: apiextensions.k8s.io/v1`
Set `spec.group`, `spec.names` (kind, plural, singular), and `spec.scope` (Namespaced or Cluster)
Under `spec.versions[].schema.openAPIV3Schema`, define a `properties` object with types and required fields
Add `x-kubernetes-preserve-unknown-fields: true` only where freeform data is legitimately needed; avoid it globally
Include `spec.versions[].subresources.status: {}` if the resource uses a status subresource
Apply with `kubectl apply` and verify with `kubectl get crd <name>` and `kubectl explain <kind>.spec`
Known gotchas
apiextensions.k8s.io/v1 requires a schema for every version; the v1beta1 default of accepting arbitrary fields is gone and missing schemas will cause API server rejection
Setting `required` at the top-level `spec` means the API server validates on admission, not just at apply time — test with a minimal CR before deploying
`x-kubernetes-preserve-unknown-fields: true` at the root disables all pruning and validation for that subtree, undermining schema safety
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp