feat(operator): generate standalone JSON Schema for CRDs - #1776
Draft
sylr wants to merge 5 commits into
Draft
Conversation
just generate now emits config/crd/schemas/v1alpha1_<kind>.json and v1alpha1_<kind>.spec.json alongside the existing CRD manifests, so IDEs (VS Code YAML, JetBrains) and external tooling can validate Cluster/Ledger/Backup/BackupRun/Credentials manifests without depending on the full apiextensions CRD wrapper. Confidence: high Scope-risk: narrow Directive: regenerate via `just generate` after changing api/v1alpha1 types; do not hand-edit config/crd/schemas/*.json Not-tested: JSON Schema draft-04 output has not been validated against every downstream consumer (e.g. redhat.vscode-yaml)
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueThanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## release/v3.0 #1776 +/- ##
================================================
+ Coverage 76.53% 76.56% +0.02%
================================================
Files 472 472
Lines 50104 50104
================================================
+ Hits 38348 38361 +13
+ Misses 8350 8330 -20
- Partials 3406 3413 +7
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
- README example applied the spec-only schema ($schema=...spec.json) to a full manifest; its root has no `spec` property, so `spec.replicas` etc. went unvalidated. Point full-manifest examples at the full resource schema instead, and clarify when .spec.json applies. - crdOpenAPISchema silently fell back to Versions[0] when no version was marked storage — fail loudly instead, per the repo's no-silent-fallback convention. - run() now clears stale *.json files from the output directory before writing, so a removed/renamed CRD doesn't leave orphaned committed schemas. Reviewed-by: codex (omc ask) Confidence: high Scope-risk: narrow Not-tested: multi-version CRDs with more than one served version still only publish the storage version's schema (no repo CRD currently has multiple versions)
Contributor
Author
|
Ran an independent Codex review ( Verdict: REQUEST CHANGES — 1 blocking, 2 non-blocking. All addressed in 6889ae3:
Added |
The generated config/crd/schemas/*.json files were previously only committed to the repo — nothing in CI published them anywhere (GoReleaser only builds ledger-server/ledgerctl; the operator Docker image and Helm charts are pushed separately to GHCR). Since release.yml drives the operator image/chart publish off the same tag as the GoReleaser GitHub release, attach the schemas there too, alongside the existing openapi.yml extra_files entry. Also fixes justfile's root-level `operator-generate` recipe, which duplicates misc/operator/justfile's `generate` recipe but had drifted out of sync (missing the schema-generation step added in 77b9156). Constraint: extra_files uploads happen only during the release (publish) pipe, which snapshot/dry-run builds always skip — verified via `goreleaser check` and a `--snapshot` build instead; the glob follows the same working pattern as the existing openapi.yml entry. Confidence: high Scope-risk: narrow Not-tested: actual asset upload to a real GitHub release (requires a real tag)
Merges release/v3.0 (which had moved to 004be98 since this branch was cut) so the Dirty CI check has a fresh base to diff against. QueryProfileThreshold's doc comment changed upstream in #1775; that's already reflected in config/crd/bases/*.yaml but the committed JSON schemas for Cluster were generated before that landed. Regenerated via `just generate` — only the two Cluster schema files changed, matching the description update exactly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
just generateinmisc/operatornow also emits standalone JSON Schema files underconfig/crd/schemas/:v1alpha1_<kind>.json(full CRD resource schema) andv1alpha1_<kind>.spec.json(spec-only) for Cluster, Ledger, Backup, BackupRun, and Credentials. A newgo run ./scripts/generate-json-schemasstep extracts theopenAPIV3Schemafrom the generated CRD manifests and writes it as draft-04 JSON Schema. README and justfile updated to document and wire the new step.Why
Standalone JSON Schema files let IDEs (VS Code YAML, JetBrains) and external tooling validate operator CRD manifests (e.g. via
# yaml-language-server: $schema=...) without needing the fullapiextensions.k8s.ioCRD wrapper.Product / operational motivation
N/A
Technical decision
N/A
Risk
LOW — additive, generator-only change scoped to
misc/operator. Generated output is committed (following the existing pattern forconfig/crd/bases/), does not touch reconciliation logic, FSM, or persisted state.Validation
bash scripts/agent-checkgo test ./scripts/...inmisc/operator(new generator test),just generatere-run end-to-end to confirm output matchesArchitecture / behavior impact
N/A — build-time/dev-tooling change only, no runtime behavior change.
Review focus
Whether draft-04 is the right JSON Schema dialect for downstream consumers, and whether committing generated schemas (vs. generating on demand) is the right tradeoff.
Known concerns
None