k8s-compat-matrix

name: k8s-compat-matrix description: Manages the Kubernetes compatibility matrix data and React component. Use when adding/removing K8s versions, updating conformance test results, or documenting known issues.

Kubernetes Compatibility Matrix Skill

Overview

Manages the Kubernetes compatibility matrix — a data-driven React component backed by static/api/k8s-compatibility.json. This skill handles adding/removing K8s versions, updating cell statuses based on conformance test results, and documenting known issues with footnotes.

When to Use This Skill

Trigger this skill when:

• User says "add K8s version", "new kubernetes version", "update compatibility matrix"
• User says "prune", "remove EOL version" for the K8s matrix
• User provides conformance test results to update cell statuses
• User says "mark known issue" or provides a partial failure to document
• Linear issue references updating the K8s compatibility matrix

Files

Statuses

Workflow: Add New Kubernetes Version

1. Run the CLI tool:

   node scripts/generate-compatibility-matrix.js --add <version>
   

   This adds a row and column. Diagonal cell = tested, all others = compatible.

2. Adjust cells based on conformance test results. Change cell values in static/api/k8s-compatibility.json:

   • Pass → leave as "compatible" or change to "tested"
   • Fail → change to {"status": "known-issue", "note": N} (see known issues below)

3. Validate:

   node scripts/generate-compatibility-matrix.js
   

4. Build to verify rendering:

   npm run build
   

5. Commit, push, open PR.

Workflow: Prune EOL Version

The matrix should only contain Kubernetes versions that are actively supported upstream. Check the official release calendar at https://kubernetes.io/releases/ for current EOL dates.

When adding a new version, always check at the same time whether any existing versions have passed their EOL date. If so, prune them in the same PR.

For each EOL version:

node scripts/generate-compatibility-matrix.js --prune <version>

Removes row, column, and all references. Repeat for each EOL version, then validate and commit.

Workflow: Document Known Issue

When a conformance test reveals a partial failure (specific API broken, not full incompatibility):

1. In static/api/k8s-compatibility.json, find the notes array. Add a new entry:

   {
     "id": <next_integer>,
     "text": "Description of the limitation. See [relevant docs](/docs/vcluster/path/to/page) for details."
   }
   

2. Change affected cell(s) from a string to an object:

   {"status": "known-issue", "note": <matching_id>}
   

3. Multiple cells can reference the same note ID.

4. Validate:

   node scripts/generate-compatibility-matrix.js
   

JSON Schema

static/api/k8s-compatibility.json
├── lastUpdated: "YYYY-MM-DD" (auto-set by CLI on --add/--prune)
├── kubernetesVersions: ["1.35", "1.34", ...] (descending order)
├── matrix: [
│     { host: "1.35", vcluster: {
│         "1.35": "tested",
│         "1.34": "compatible",
│         "1.31": {"status": "known-issue", "note": 1}
│     }}
│   ]
├── notes: [{ id: 1, text: "description with link" }]
└── statuses: {
      tested: { emoji, label, description },
      compatible: { emoji, label, description },
      known-issue: { emoji, label, description }
    }

Cell values: either a status string or {"status": "<name>", "note": <id>}.

Validation

The CLI validates:

• kubernetesVersions count matches matrix row count
• Every row has entries for all versions
• All status strings exist in statuses object
• All note references point to existing note IDs
• statuses has at least tested and compatible

CI runs this automatically on any PR that touches the JSON.

Testing

Playwright tests in tests/specs/k8s-compatibility-matrix.spec.js verify:

• Table renders with correct structure (header rows, data rows, version labels)
• Legend displays all three statuses
• Known-issue cells have superscript footnote markers
• Footnote text appears below the table
• Table accessible on mobile viewport

Run locally:

cd tests && npm install
TEST_BASE_URL=http://localhost:3000 npx playwright test specs/k8s-compatibility-matrix.spec.js --project=local

Note: tests target /docs/vcluster/next/ path. After a version is cut, update MATRIX_PATH in the test spec.

Troubleshooting

Validation fails: Run node scripts/generate-compatibility-matrix.js locally to see exact errors. Common causes: missing cell entry, invalid status name, dangling note reference.

Table shows stale data in dev server: Clear caches and restart:

npx docusaurus clear && npm run start

Known-issue footnotes don't render: Verify cell is an object {"status": "known-issue", "note": N} not just the string "known-issue". Check notes array has matching id.

Wrong matrix shape after --add: Versions sort numerically (1.9 < 1.10 < 1.35). Check kubernetesVersions ordering.

Do Not

• Edit the component JSX unless the rendering logic needs to change
• Add statuses without updating both the statuses object and the component
• Mark cells as tested without evidence from conformance tests
• Modify versioned docs copies of the matrix page (they use the old HTML table)