Config Partials Generator

Config Partials Generator Skill

Overview

Generates MDX config reference partials from vCluster JSON schema. The CI automation (sync-config-schema.yaml in vcluster repo) skips alpha releases, so manual generation is needed during alpha/early development phases.

When to Use This Skill

Trigger this skill when:

• User asks to "generate config partials", "update config reference", or "regenerate config docs"
• Linear issue mentions config generation or automation being down
• A new vCluster pre-release (alpha/beta) has schema changes not yet reflected in docs
• The vcluster/_partials/config/ files are stale compared to the vcluster schema

Prerequisites

• Local clone of vcluster repo (default: ~/loft/vcluster, adjust if different)
• Go toolchain installed (for running the generator)

Source Files

<VCLUSTER_REPO> defaults to ~/loft/vcluster. Confirm path before starting.

Automation Gap

The sync-config-schema.yaml workflow in the vcluster repo:

• Fires on release events
• Skips alpha and next releases (exits early)
• For beta releases: targets configsrc/vcluster/main/ and vcluster/_partials/config/
• For RC releases: targets versioned folder (e.g., configsrc/vcluster/0.33.0/)
• For stable releases: triggers config sync in vcluster-config repo

Manual generation fills the gap for alpha releases.

Workflow: Generate vCluster Partials

Step 1: Update vcluster repo

cd <VCLUSTER_REPO>
git fetch --tags
git checkout main && git pull origin main

Verify the latest tag: git tag --sort=-v:refname | head -5

Step 2: Copy schema files to configsrc

From the vcluster-docs repo root:

cp <VCLUSTER_REPO>/chart/values.yaml configsrc/vcluster/main/default_values.yaml
cp <VCLUSTER_REPO>/chart/values.schema.json configsrc/vcluster/main/vcluster.schema.json

For versioned docs (RC releases), replace main with X.Y.0:

mkdir -p configsrc/vcluster/X.Y.0/
cp <VCLUSTER_REPO>/chart/values.yaml configsrc/vcluster/X.Y.0/default_values.yaml
cp <VCLUSTER_REPO>/chart/values.schema.json configsrc/vcluster/X.Y.0/vcluster.schema.json

Step 3: Vendor Go modules

From the vcluster-docs repo root:

go mod tidy && go mod vendor

Step 4: Run the generator

For main/next docs:

go run hack/vcluster/partials/main.go configsrc/vcluster/main vcluster/_partials/config

For versioned docs:

go run hack/vcluster/partials/main.go configsrc/vcluster/X.Y.0 vcluster_versioned_docs/version-X.Y.0/_partials/config

Step 5: Review output

git diff --stat vcluster/_partials/config/

Expected warnings (safe to ignore):

• Skipping path "experimental/isolatedControlPlane" — deprecated path
• Skipping path "experimental/genericSync" — deprecated path
• Skipping path "controlPlane/distro/k3s" — removed in v0.33+
• Skipping path "controlPlane/distro/k0s" — removed in v0.33+

Step 6: Platform configsrc

Update the platform schema reference:

cp <VCLUSTER_REPO>/chart/values.schema.json configsrc/platform/main/vcluster.schema.json

Platform partials generator: Before running, check whether it preserves manual content:

gh pr view 1663 --json state --jq '.state'

If MERGED, safe to run:

go run hack/platform/partials/main.go configsrc/platform/main/vcluster.schema.json

If OPEN, do NOT run — the generator overwrites manually-added sections in API reference docs.

Step 7: Commit and open PR

git checkout -b chore/update-config-partials-vX.Y.Z
git add configsrc/ vcluster/_partials/config/
git commit -m "chore: generate vcluster config partials for X.Y alpha"
git push -u origin HEAD
gh pr create --title "chore: generate vcluster config partials for X.Y alpha" --body "..."

Output Files

The generator produces/updates MDX files under vcluster/_partials/config/:

• controlPlane.mdx — control plane top-level config
• controlPlane/distro.mdx — distro configuration (k8s, k3s, k0s, eks)
• controlPlane/backingStore.mdx — etcd/database backing store
• controlPlane/backingStore/database/embedded.mdx
• controlPlane/backingStore/database/external.mdx
• And many more nested partials matching the schema structure

Never Do

• Modify generated partials by hand — they get overwritten on next generation
• Run the platform generator without checking its manual-content-preservation status
• Modify files under vcluster_versioned_docs/ unless explicitly targeting a released version