DOCS-2970: Fail the build when a FelixConfig lookup key doesn't resolve by ctauchen · Pull Request #2820 · tigera/docs

ctauchen · 2026-07-03T11:27:06Z

Why

Follow-up hardening for the FelixConfiguration content fix (#2819, DOCS-2970).

The FelixConfig component degraded silently: when a group-name lookup missed, it rendered a small "No matching group found" paragraph that was easy to overlook. That's exactly how a prose/casing style sweep dropped iptablesRefreshInterval and 7 other groups from the reference page without anyone noticing until the Visa RCA (CI-2011).

Change

Turn the silent miss into a thrown error, so a broken lookup fails the Docusaurus build instead of shipping a page with missing fields:

if (!matchedGroup) {
  throw new Error(
    `FelixConfig: no group named '${name}' in config-params.json. ...`
  );
}

This guards against every cause — Vale-driven sweeps, manual edits, refactors, or a config-params.json regen that renames a group — not just the one that triggered DOCS-2970. Applied to all component copies (current + versioned_docs across calico, calico-enterprise, calico-cloud), since style sweeps edit versioned pages too.

Pre-flight verified: all 22 <FelixConfig> pages in the repo currently resolve against their sibling config-params.json, so this does not break the build once #2819 lands.

⚠️ Merge order

Stacks on #2819 — merge that first. This branch is based on #2819, so until it merges this PR's diff also shows the content fix; afterward it reduces to just the index.js guard. Merging this before #2819 would fail the build (the still-broken lookups on main).

🤖 Generated with Claude Code

…ne fields The felixconfig.mdx pages render field groups via the FelixConfig component, which matches a group by exact string: `jsonData.Groups.find((group) => group.Name === name)`. The group names come from config-params.json, which is auto-synced from the Felix source repos and must not be hand-edited. A prose/casing style sweep (573e3bb) rewrote the functional `name=` lookup keys as if they were prose (`Dataplane:` -> `Data plane:`, `...iptables dataplane` -> `...iptables data plane`, `Wireguard` -> `WireGuard`), so 8 groups -- including "Dataplane: iptables" and with it `iptablesRefreshInterval` -- no longer matched any generated group name and rendered "No matching group found", dropping their fields. Correct the `name=` lookup keys in the affected calico and calico-enterprise felixconfig.mdx files (current + versioned_docs) to exactly match each file's own config-params.json. Visible `####` headings are left as the restyled prose; only the lookup keys change. version-3.29's JSON already uses `Data plane:`, so only the WireGuard fix applies there. calico-cloud was untouched by the sweep. Surfaced during the Visa RCA (CI-2011). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

netlify · 2026-07-03T11:27:10Z

✅ Deploy Preview for calico-docs-preview-next ready!

Name	Link
🔨 Latest commit	`2a840c8`
🔍 Latest deploy log	https://app.netlify.com/projects/calico-docs-preview-next/deploys/6a479de6f5873100086099e4
😎 Deploy Preview	https://deploy-preview-2820--calico-docs-preview-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-07-03T11:27:11Z

✅ Deploy Preview succeeded!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`2a840c8`
🔍 Latest deploy log	https://app.netlify.com/projects/tigera/deploys/6a479de65bdcc90008a1f432
😎 Deploy Preview	https://deploy-preview-2820--tigera.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 87 (🟢 up 15 from production) Accessibility: 98 (no change from production) Best Practices: 92 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Pull request overview

This PR hardens the FelixConfig MDX component used across Calico OSS / Enterprise / Cloud docs so that an unresolved group-name lookup fails the Docusaurus build (instead of silently rendering an easy-to-miss “No matching group found” message). It also updates several name= lookup keys in felixconfig.mdx pages to match the exact group Name values in each version’s sibling config-params.json.

Changes:

Replace silent “no matching group” rendering with a thrown error in all FelixConfig component copies (current + versioned docs).
Update affected FelixConfig name='…' lookup keys in multiple felixconfig.mdx pages (current + versioned) to restore exact matches against generated config-params.json.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
calico/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico-enterprise/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico-enterprise/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico-enterprise_versioned_docs/version-3.23-2/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico-enterprise_versioned_docs/version-3.23-2/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico-enterprise_versioned_docs/version-3.22-2/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico-enterprise_versioned_docs/version-3.22-2/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico-enterprise_versioned_docs/version-3.21-2/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico-enterprise_versioned_docs/version-3.21-2/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico-cloud/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico-cloud_versioned_docs/version-22-2/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico_versioned_docs/version-3.32/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico_versioned_docs/version-3.32/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico_versioned_docs/version-3.31/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico_versioned_docs/version-3.31/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico_versioned_docs/version-3.30/reference/resources/felixconfig.mdx	Updates `FelixConfig` group lookup keys to match `config-params.json`.
calico_versioned_docs/version-3.30/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.
calico_versioned_docs/version-3.29/reference/resources/felixconfig.mdx	Updates the Wireguard lookup key to match `config-params.json`.
calico_versioned_docs/version-3.29/_includes/components/FelixConfig/index.js	Throws on unresolved group lookup to fail the build loudly.

 const FelixConfig = ({ configType, name }) => {
  const matchedGroup = jsonData.Groups.find((group) => group.Name === name);
  // Debugging logs

  if (!matchedGroup) {
-    return <p>No matching group found for '{name}'.</p>;
+    // Fail the build loudly rather than silently dropping the group's fields.
+    // `name` must exactly match a group Name in config-params.json, which is
+    // auto-synced from the Felix source repos. A prose/casing sweep once
+    // restyled these lookup keys and silently dropped fields (DOCS-2970).
+    throw new Error(
+      `FelixConfig: no group named '${name}' in config-params.json. The 'name' `
+      + `prop must exactly match a group Name in config-params.json; do not `
+      + `restyle it as prose.`
+    );


The node/felix configuration.mdx page (config-file/env-var view) also consumes the FelixConfig component, using double-quoted name attributes. In calico version-3.29 its config-params.json uniquely uses the "Data plane" spelling, so the page's "Dataplane: ..." lookup keys never matched -- a pre-existing mismatch the silent fallback was hiding. Align those 7 keys with 3.29's own config-params.json. Verified all 22 FelixConfig-consuming pages (both quote styles) now resolve. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The FelixConfig component previously degraded silently: when a group name lookup missed, it rendered a small "No matching group found" paragraph that was easy to overlook. That is exactly how a prose/casing style sweep dropped iptablesRefreshInterval and 7 other groups from the FelixConfiguration reference without anyone noticing until a customer RCA. Turn that silent miss into a thrown error so a broken lookup fails the Docusaurus build instead of shipping a page with missing fields. This guards against every cause -- Vale-driven sweeps, manual edits, refactors, or a config-params.json regen that renames a group -- not just the one that triggered DOCS-2970. Applied to all FelixConfig component copies (current + versioned_docs across calico, calico-enterprise, calico-cloud) since style sweeps edit versioned pages too. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings July 3, 2026 11:27

ctauchen requested a review from a team as a code owner July 3, 2026 11:27

Copilot started reviewing on behalf of ctauchen July 3, 2026 11:27 View session

Copilot AI reviewed Jul 3, 2026

View reviewed changes

ctauchen and others added 2 commits July 3, 2026 12:32

ctauchen force-pushed the harden-felixconfig-lookup branch from fe1308b to 2a840c8 Compare July 3, 2026 11:32

ctauchen merged commit 824537f into tigera:main Jul 3, 2026
11 checks passed

ctauchen deleted the harden-felixconfig-lookup branch July 3, 2026 12:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

DOCS-2970: Fail the build when a FelixConfig lookup key doesn't resolve#2820

DOCS-2970: Fail the build when a FelixConfig lookup key doesn't resolve#2820
ctauchen merged 3 commits into
tigera:mainfrom
ctauchen:harden-felixconfig-lookup

ctauchen commented Jul 3, 2026

Uh oh!

netlify Bot commented Jul 3, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Jul 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ctauchen commented Jul 3, 2026

Why

Change

⚠️ Merge order

Uh oh!

netlify Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for calico-docs-preview-next ready!

Uh oh!

netlify Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview succeeded!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Jul 3, 2026 •

edited

Loading

netlify Bot commented Jul 3, 2026 •

edited

Loading