feat(vcluster-yaml): prototype kubectl-doc interactive schema explorer#2322
Open
Piotr1215 wants to merge 5 commits into
Open
feat(vcluster-yaml): prototype kubectl-doc interactive schema explorer#2322Piotr1215 wants to merge 5 commits into
Piotr1215 wants to merge 5 commits into
Conversation
Evaluate the kubectl-doc KubeSchemaDoc explorer (sttts/kubectl-doc, Apache-2.0) as an interactive reference for vcluster.yaml, the highest-value target being large config pages like controlPlane (5,425 lines / 357 fields today) where the generated accordion reference is too long to scan. kubectl doc cannot ingest the vcluster JSON Schema directly; it takes a CRD or cluster OpenAPI. The adapter here converts one schema section into a synthetic structural CRD that kubectl doc -f accepts, then keeps the generated KubeSchemaDocument payload. The vendored React component renders it client-side, SSR-safe via a BrowserOnly wrapper. Verified rendering the real sync.toHost.pods section in this site at /docs/kubectl-doc-prototype. Recommendation is augment, not replace: the explorer is client-only, so it loses the server-rendered HTML, search indexing, per-field deep links, and no-JS access the accordions provide. See hack/vcluster/schema-explorer/EVALUATION.md. Prototype only: not wired into any sidebar or the config-reference pipeline. Closes DOC-1512
✅ Deploy Preview for vcluster-docs-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
…el in evaluation the prior draft implied the explorer payload is generated from a schema file committed to this repo. it is not: the source of truth is the released chart/values.schema.json in loft-sh/vcluster (generated upstream from the go config), and the configsrc copies here are per-release snapshots, not the source. rewrites section 5 to ride the existing handle-source-release.yml -> run-generator.sh (vcluster-released) path with per-version target folders and a diff drift gate, and names the recommended production path (direct payload emission reusing the hack/platform/util walker). adds the algolia docsearch indexing caveat that grounds the augment-not-replace verdict.
the vendored side-overlay detail card is position:fixed at top:80px with a maximal z-index, so it renders over the docusaurus top nav. daryl flagged this on the deploy preview. scope a site-side override (higher specificity than the runtime-injected rule, desktop-only so mobile sticky layout is untouched) that pushes the card below --ifm-navbar-height and drops it under the navbar stacking context, so the nav is never covered. stopgap; final polish stays with the design team.
first real-page rollout of the kubectl-doc explorer as an additional view, per daryl + piotr: keep the generated accordions as the default, indexed reference and add an Explorer tab beside them. the explorer lazy-mounts only when its tab scrolls into view, so config pages that include it do not all pay the 87kb runtime on load. adds generate-payloads.mjs: the section -> payload automation. it drives the real kubectl-doc renderer (faithful lines[] tokens, no hand-rolled tokenizer) and strips the synthetic k8s frame (apiVersion/kind/metadata/spec) back to the section root, rewriting paths to real vcluster.yaml dotted paths so the detail panel shows copy-paste-ready sync.toHost.* values. verified on the next docs build: tabs render, Reference carries the 390 accordion fields for search indexing, Explorer mounts on view with correct paths and deep-link hashes, zero console errors. wiring this into the release pipeline (run-generator.sh vcluster-released) is the next step.
The delimiter rows in the EVALUATION.md comparison table and the kubectl-doc README vendored-files table used tight pipes (|---|---|), while their header and body rows were spaced (| col |). markdownlint MD060 (table-column-style) enforces consistent pipe spacing, so reviewdog posted six inline review comments on the PR. Because the vale job is the only lint gate that fails CI and reviewdog markdownlint uses the github-pr-review reporter, the checks stayed green while the PR carried the comments. Space the delimiter pipes to match each table.
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.
Content Description
Adds an interactive, YAML-shaped schema explorer for
vcluster.yaml(kubectl-docKubeSchemaDoc, sttts/kubectl-doc, Apache-2.0) and surfaces it as an additional view on thesync/to-hostconfig reference page, beside the existing accordions. Includes the section-to-payload generator and a full evaluation. DOC-1512.Summary
The big config pages are where the accordion reference strains (
controlPlaneis 5,425 lines / 357 fields). The explorer renders the schema as the YAML you actually write, with a details panel, folding, and an in-tree filter. Following review from the docs team, it ships as an augmentation: the generated accordions stay the default, indexed reference, and an "Explorer (beta)" tab sits next to them.kubectl doccannot ingest the vcluster JSON Schema directly (it takes a Kubernetes CRD or cluster OpenAPI), so a generator converts a schema section to a synthetic CRD, runs the real kubectl-doc renderer, and strips the k8s frame back to the section root.Key Changes
vcluster/configure/vcluster-yaml/sync/to-host/README.mdx:## Config referenceis now a<Tabs>with Reference (accordions, default) and Explorer (beta). First real-page rollout.hack/vcluster/schema-explorer/generate-payloads.mjs: section-to-payload automation. Drives kubectl-doc (faithfullines[]tokens, no hand-rolled tokenizer), stripsapiVersion/kind/metadata/specand rewrites paths to real dotted paths (sync.toHost.*).src/components/kubectl-doc/: vendoredKubeSchemaDoc(v0.2.9, Apache-2.0), SSR-safe wrapper,MountWhenVisible(lazy-mount on tab open), navbar positioning override, and the generatedsync/to-hostpayload undervcluster/_partials/config/.hack/vcluster/schema-explorer/EVALUATION.md: findings for all acceptance criteria, source-of-truth/versioning, go/no-go, risks.How it stays current
The source of truth is
chart/values.schema.jsoninloft-sh/vcluster(generated upstream from the Go config). Theconfigsrc/vcluster/<version>/copies here are per-release snapshots, not the source. Regeneration mechanism (decided): drive the real kubectl-doc renderer per section, so payloads are faithful by construction. The next step wiresgenerate-payloads.mjsinto the existing release automation (handle-source-release.ymltorun-generator.sh,vcluster-releasedcase) with per-version output and agit diff --exit-codedrift gate, exactly like the accordion partials. That is the one change that touches a release workflow, so it lands as a separate, clearly-scoped follow-up.Verification
Verified on the
nextdocs build (/docs/vcluster/next/configure/vcluster-yaml/sync/to-host): both tabs render, Reference carries all 390 accordion fields (server-rendered, search-indexed), Explorer lazy-mounts on view, field paths and deep-link hashes are correct (sync.toHost.configMaps), zero console errors.Risks / caveats
vcluster), which crawls rendered HTML, so explorer-only fields are not in site search or Google. Mitigated by keeping the accordions as the default, indexed tab.kubectl-doc-runtime.js), pinned and Apache-2.0, provenance recorded. Lazy-mounted so only pages with the tab load it, and only when opened.oneOf/anyOf/allOfcollapse in the CRD adapter is lossy; the pilot section (sync.toHost) is union-free. Audit before extending to sections with unions.Dependencies
None.
TODO
generate-payloads.mjsintorun-generator.sh(vcluster-released) with acheck-generateddrift gate and thego install kubectl-doc@v0.2.9step.control-plane,sync/from-host) once the pilot is approved.Preview Link
Internal Reference
Closes DOC-1512
AI review: mention
@claudein a comment to request a review or changes. See CONTRIBUTING.md for available commands.@netlify /docs