explaingit

home-operations/k8s-schemas

★ 12YAMLAudience · ops devopsComplexity · 3/5ActiveSetup · moderate

TLDR

Collection of JSON schemas for Kubernetes CRDs used in home-ops clusters, published as a browsable site and signed OCI artifact for YAML editor autocomplete.

Mindmap

mindmap
  root((k8s-schemas))
    Inputs
      Upstream CRD releases
      vendir source files
      kind install manifests
    Outputs
      JSON schema site
      Signed OCI artifact
      Editor autocomplete
    Use Cases
      YAML autocomplete
      Manifest validation
      Operator schema export
    Tech Stack
      YAML
      vendir
      mise
      kind
      cosign

Things people build with this

USE CASE 1

Add CRD autocomplete and validation to a homelab YAML repo

USE CASE 2

Pin Kubernetes manifests against a signed schema OCI artifact

USE CASE 3

Publish JSON schemas for a custom operator that only registers CRDs at runtime

USE CASE 4

Track upstream CRD releases via Renovate-managed vendir files

Tech stack

YAMLvendirmisekindcosign

Getting it running

Difficulty · moderate Time to first run · 30min

Local builds need mise plus kind for operators that only register CRDs at runtime.

In plain English

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.

Copy-paste prompts

Prompt 1
Add a yaml-language-server comment to my VolSync manifest pointing at the right schema from k8s-schemas.home-operations.com
Prompt 2
Set up the Red Hat YAML extension in VS Code so my home-ops cluster manifests validate against k8s-schemas
Prompt 3
Write a vendir.yml entry under sources to pull in a new operator release and render the site locally with mise run all
Prompt 4
Show me how to consume the cosign-signed ghcr.io/home-operations/k8s-schemas OCI artifact in a CI pipeline
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.