k8s-schemas

This repository collects JSON schemas for the custom resource definitions, or CRDs, used by tools in the home-operations Kubernetes community. A CRD is the way an operator or add-on tells Kubernetes about a new kind of object it can manage. If you point a YAML editor at one of these schemas, the editor can offer autocomplete, hover documentation, and validation that matches what the cluster actually expects.

The schemas are published in two places. A browsable site lives at k8s-schemas.home-operations.com, and the same content is mirrored as a cosign-signed OCI artifact at ghcr.io/home-operations/k8s-schemas:latest. To use a schema in your manifests, you find the kind on the site, copy its URL, and paste a yaml-language-server comment at the top of your file. The Red Hat YAML extension for VS Code is given as the main example of a tool that picks up that comment.

The build is wired together with a few small pieces. Each upstream project has a vendir.yml file under sources, which pins a version and fetches its CRDs. The pulled-in CRDs are passed to a separate tool called crd-schema-publisher that renders the merged docs site. Renovate watches the source files and opens a pull request when an upstream cuts a new release.

Some operators do not ship their CRDs as static YAML; they only register them after the operator is running. KubeVirt and CDI are mentioned as examples. For those, the source folder also holds a kind.yaml file. The build spins up a throwaway local cluster with kind, applies the install manifest and a trigger custom resource, waits for the operator to become ready, and then dumps the resulting CRDs.

The contributing section walks through adding a new upstream. You check what the upstream actually publishes, pick a source type in the order githubRelease, git, or kind, drop a vendir.yml under sources nested by GitHub owner and repo, then run mise install and mise run all locally to render the site into out/site for a spot-check. Helm chart rendering is explicitly out of scope. When you open a pull request the workflow builds only the sources you changed, and on merge to main the site and OCI artifact are both rebuilt.