Deploy k8s-schemas web page with OpenAPI JSON docs for kubeconform #97

New issue

Open

opened 2026-07-19 23:44:32 +00:00 by mcp-bot · 1 comment

mcp-bot commented

2026-07-19 23:44:32 +00:00

Member

Goal

Deploy a web page inside the Kubernetes cluster that serves all available Kubernetes CRD schemas as OpenAPI JSON, so that kubeconform can reference them for validation of custom resources.

Background

Currently, kubeconform only knows about built-in Kubernetes resource schemas. To validate CRDs from Helm charts, operators, and controllers installed in the cluster, we need to extract and serve their OpenAPI/JSON schemas dynamically.

Approach

Based on proven patterns from other homelabs:

CRD Extraction — Use the k8s-crd-extractor container image (ghcr.io/bjw-s-labs/k8s-crd-extractor) which:
- Queries the Kubernetes API for all CRDs (kubectl get crds)
- Converts each CRD's openAPIV3Schema to JSON via the datreeio/openapi2jsonschema.py script
- Outputs schemas organized by API group under ~/.datree/crdSchemas/
Serving the schemas — Use a lightweight HTTP server (e.g. wrangler deploy or similar static file server) to serve the generated schemas directory as a web-accessible endpoint.

Schema location — Serve at a path like /schemas/ that can be referenced by kubeconform's -schema-location flag, e.g.:

kubeconform -schema-location 'https://schemas.<domain>/{{ .Group }}/{{ .ResourceKind }}_{{ .ResourceAPIVersion }}.json'

Reference Implementations

Proposed Implementation

A Flux HelmRelease (or similar GitOps-deployed workload) that:

Runs k8s-crd-extractor as a periodic CronJob (e.g. hourly) to regenerate schemas
Serves the output via a static file server (e.g. ghcr.io/bjw-s-labs/wrangler deploy --assets)
Exposes via Ingress or LoadBalancer at a suitable subdomain (e.g. schemas.<domain>)
Includes RBAC with get/list/watch on customresourcedefinitions and apiservices

Acceptance Criteria

Schemas are extracted from the cluster on a schedule (CronJob)
Schemas are served over HTTP at a known URL
kubeconform can validate CR resources using the served schemas via -schema-location
New CRDs installed via Helm charts/operators are automatically picked up on the next extraction run

## Goal Deploy a web page inside the Kubernetes cluster that serves all available Kubernetes CRD schemas as OpenAPI JSON, so that `kubeconform` can reference them for validation of custom resources. ## Background Currently, `kubeconform` only knows about built-in Kubernetes resource schemas. To validate CRDs from Helm charts, operators, and controllers installed in the cluster, we need to extract and serve their OpenAPI/JSON schemas dynamically. ## Approach Based on proven patterns from other homelabs: 1. **CRD Extraction** — Use the [k8s-crd-extractor](https://github.com/bjw-s-labs/container-images/tree/main/apps/k8s-crd-extractor) container image (`ghcr.io/bjw-s-labs/k8s-crd-extractor`) which: - Queries the Kubernetes API for all CRDs (`kubectl get crds`) - Converts each CRD's `openAPIV3Schema` to JSON via the [datreeio/openapi2jsonschema.py](https://github.com/datreeio/CRDs-catalog/blob/main/Utilities/openapi2jsonschema.py) script - Outputs schemas organized by API group under `~/.datree/crdSchemas/` 2. **Serving the schemas** — Use a lightweight HTTP server (e.g. [wrangler deploy](https://developers.cloudflare.com/workers/wrangler/deploy/) or similar static file server) to serve the generated schemas directory as a web-accessible endpoint. 3. **Schema location** — Serve at a path like `/schemas/` that can be referenced by kubeconform's `-schema-location` flag, e.g.: ``` kubeconform -schema-location 'https://schemas.<domain>/{{ .Group }}/{{ .ResourceKind }}_{{ .ResourceAPIVersion }}.json' ``` ## Reference Implementations - [JJGadgets/Biohazard - k8s-schemas](https://github.com/JJGadgets/Biohazard/blob/main/kube/deploy/apps/k8s-schemas/app/hr.yaml) - [m00nwtchr/homelab-cluster - publish-k8s-schemas](https://github.com/m00nwtchr/homelab-cluster/blob/master/kubernetes/apps/default/publish-k8s-schemas/app/helmrelease.yaml) - [bjw-s-labs/k8s-crd-extractor Dockerfile](https://github.com/bjw-s-labs/container-images/blob/main/apps/k8s-crd-extractor/Dockerfile) - [datreeio/CRDs-catalog - crd-extractor.sh](https://github.com/datreeio/CRDs-catalog/blob/main/Utilities/crd-extractor.sh) - [datreeio/CRDs-catalog - openapi2jsonschema.py](https://github.com/datreeio/CRDs-catalog/blob/main/Utilities/openapi2jsonschema.py) ## Proposed Implementation A Flux HelmRelease (or similar GitOps-deployed workload) that: - Runs `k8s-crd-extractor` as a periodic CronJob (e.g. hourly) to regenerate schemas - Serves the output via a static file server (e.g. `ghcr.io/bjw-s-labs/wrangler deploy --assets`) - Exposes via Ingress or LoadBalancer at a suitable subdomain (e.g. `schemas.<domain>`) - Includes RBAC with `get/list/watch` on `customresourcedefinitions` and `apiservices` ## Acceptance Criteria - [ ] Schemas are extracted from the cluster on a schedule (CronJob) - [ ] Schemas are served over HTTP at a known URL - [ ] kubeconform can validate CR resources using the served schemas via `-schema-location` - [ ] New CRDs installed via Helm charts/operators are automatically picked up on the next extraction run

nogweii commented

2026-07-22 22:48:38 +00:00

Owner

https://sholdee.github.io/crd-schema-publisher/ seems like a great implementation of what I was hoping for as a single project rather than a bunch of scripts hacked together

No labels

No milestone

No project

No assignees

2 participants

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

ops/homelab#97

No description provided.

Rows
Columns