Regenerate the operator API reference for drifted doc versions by ctauchen · Pull Request #2942 · tigera/docs

ctauchen · 2026-08-20T20:08:26Z

Regenerates the operator API reference where it had drifted, and fixes the Calico Cloud generator config. Four files change: three _api.mdx files and one config.yaml.

I ran the repo's per-version target for all twelve product trees off main, one at a time, and committed only what the generator produced.

Regenerated:

calico, from operator master. Adds CNIInstallMode, CNISpecVersion, the Gateway API WAF extension, Fluent Bit DaemonSet types, the calico-node startup probe, calicoRunHostPath and calicoLibHostPath, and the FelixIPIPOnly routing mode.
calico-enterprise, from operator master. Renames the Fluentd types to Fluent Bit, and adds OpenTelemetry collector types, the WAF extension, and the CNI install-mode and spec-version enums.
calico-enterprise 3.23-2, from operator v1.42.4. Adds the calico-webhooks Deployment types, ClusterRoutingMode, and a Goldmane metricsPort, and updates the container-name enum and the nonPrivileged deprecation text.

No drift: Calico 3.29, 3.30, and 3.32, and Calico Enterprise 3.21-2 and 3.22-2.

Not included:

Calico 3.31 is regenerated in DOCS-2967: Regenerate the Calico 3.31 Installation API reference #2941, alongside the 3.31.7 release.
Both Calico Cloud trees. The config fix in this PR unblocks them, but they pin the operator as master rather than a tag, so their reference cannot be reproduced from a fixed input. Regenerating them would commit whatever master held today.
Calico Enterprise 3.24-1. Regenerating it re-adds 486 lines of compliance API that DOCS-2992 removed. See the flags below.

Flags:

The generator relinks DSCP and Duration to anchors it emits no sections for, undoing part of commit ec7d290, which unlinked them for DOCS-2979. I restored those links to their unlinked form, so this PR does not reintroduce broken anchors. It will recur on every regeneration, so the durable fix belongs in the templates or in the post-processing step.
KubernetesPatchSpec links to a missing anchor in the calico and calico-enterprise files. That one already dangles on main, so I left it alone.
The ignoreTypes entry that suppresses the compliance API is written as ^Compliance, in calico-enterprise and in calico-enterprise 3.24-1. The generator matches those patterns against the package-qualified type name, so a leading ^ never matches and the entry does nothing. Dropping the ^ suppresses the types as intended. That needs its own ticket, alongside DOCS-2992, because it changes what a 3.24-1 regeneration produces.
The Calico Cloud config had a stray double quote that made the generator abort before doing any work. I fixed it and confirmed the generator then runs and renders. Nothing else in that config changed.

Regenerated with make <product-dir>__operator_reference against the operator version each tree pins in releases.json. Regenerated: * calico (next, operator master): adds CNIInstallMode, CNISpecVersion, Gateway API WAF extension, Fluent Bit DaemonSet types, calico-node startup probe, calicoRunHostPath and calicoLibHostPath, and the FelixIPIPOnly cluster routing mode. * calico-enterprise (next, operator master): renames the Fluentd DaemonSet types to Fluent Bit, adds the OpenTelemetry collector types, the Gateway API WAF extension, and the CNI install mode and spec version enums. * calico-enterprise 3.23-2 (operator v1.42.4): adds the calico-webhooks Deployment types, ClusterRoutingMode, the Goldmane metrics port, and updates several container name enums and the nonPrivileged deprecation note. Left alone, with no operator drift: calico 3.29, 3.30 and 3.32, and calico-enterprise 3.21-2 and 3.22-2. Calico 3.31 is being regenerated separately. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

netlify · 2026-08-20T20:08:31Z

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

Name	Link
🔨 Latest commit	`392f510`
🔍 Latest deploy log	https://app.netlify.com/projects/calico-docs-preview-next/deploys/6a875f92f5dd7e000881c053
😎 Deploy Preview	https://deploy-preview-2942--calico-docs-preview-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

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

netlify · 2026-08-20T20:08:33Z

✅ Deploy Preview succeeded!

Name	Link
🔨 Latest commit	`392f510`
🔍 Latest deploy log	https://app.netlify.com/projects/tigera/deploys/6a875f9142bf980008f004aa
😎 Deploy Preview	https://deploy-preview-2942--tigera.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 74 (🟢 up 18 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
🤖 Make changes	Run an agent on this branch

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

The regeneration relinked DSCP and Duration to anchors the generator emits no sections for. Commit ec7d290 unlinked them on purpose, for DOCS-2979, so this restores them in all three regenerated files. KubernetesPatchSpec is left as it is, because that link already dangles on main. The Calico Cloud generator config had a stray double quote on the DexDeploymentInitContainer line, which made the generator abort before doing any work, for both Calico Cloud trees. One character. With it fixed, the generator runs and renders. The regenerated output for Calico Cloud is not in this PR. Both cloud trees pin the operator as master rather than a tag, so their reference cannot be reproduced from a fixed input. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR regenerates the operator CRD API reference pages (reference/installation/_api.mdx) for Calico (next), Calico Enterprise (next), and Calico Enterprise v3.23-2 to bring the generated API docs back in sync with the operator versions pinned by each release.

Changes:

Regenerated Calico (next) operator API reference to include new enums/fields (e.g., CNI spec version/install mode, cluster routing mode updates, Fluent Bit and OpenTelemetry-related types, Gateway API WAF extension).
Regenerated Calico Enterprise (next) operator API reference with Fluentd → Fluent Bit rename, OpenTelemetry types, CNI enums, Gateway API extensions, and related schema updates.
Regenerated Calico Enterprise v3.23-2 operator API reference with additional deployment types, updated enums/fields, and refreshed descriptions matching operator v1.42.4.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
calico/reference/installation/_api.mdx	Regenerated Calico (next) operator API reference content, adding new types/enums and updated field docs.
calico-enterprise/reference/installation/_api.mdx	Regenerated Calico Enterprise (next) operator API reference, including Fluent Bit migration and OpenTelemetry/Gateway API updates.
calico-enterprise_versioned_docs/version-3.23-2/reference/installation/_api.mdx	Regenerated v3.23-2 operator API reference to match the pinned operator version and fix drifted schema docs.

Suppressed comments (9)

calico-enterprise/reference/installation/_api.mdx:1497

This links to #index, but the file does not include an Index section/header, so the anchor is broken.

- [Index](#index)

calico-enterprise/reference/installation/_api.mdx:2224

These link Duration to #duration, but the file does not include a Duration section/header, so the anchors are broken.

| `interval` _[Duration](#duration)_ | Interval at which metrics should be scraped. If not specified Prometheus' global scrape interval is used. |
| `scrapeTimeout` _[Duration](#duration)_ | Timeout after which the scrape is ended. If not specified, the Prometheus global scrape timeout is used unless it is less than `Interval` in which the latter is used. |

calico-enterprise/reference/installation/_api.mdx:3659

This links DSCP to #dscp, but the file does not include a DSCP section/header, so the anchor is broken.

| `dscpMark` _[DSCP](#dscp)_ | (Optional) DSCPMark define the value of the DSCP mark done by Felix and recognised by Istio CNI for Transparent NetworkPolicies. |

calico-enterprise/reference/installation/_api.mdx:5941

This links to #tlspassthroughroute, but the file does not include a TLSPassThroughRoute section/header, so the anchor is broken.

- [TLSPassThroughRoute](#tlspassthroughroute)

calico-enterprise_versioned_docs/version-3.23-2/reference/installation/_api.mdx:2628

These link Duration to #duration, but the file does not include a Duration section/header, so the anchors are broken.

| `interval` _[Duration](#duration)_ | Interval at which metrics should be scraped. If not specified Prometheus' global scrape interval is used. |
| `scrapeTimeout` _[Duration](#duration)_ | Timeout after which the scrape is ended. If not specified, the Prometheus global scrape timeout is used unless it is less than `Interval` in which the latter is used. |

calico-enterprise_versioned_docs/version-3.23-2/reference/installation/_api.mdx:1913

This links to #index, but the file does not include an Index section/header, so the anchor is broken.

- [Index](#index)

calico-enterprise_versioned_docs/version-3.23-2/reference/installation/_api.mdx:4007

This links DSCP to #dscp, but the file does not include a DSCP section/header, so the anchor is broken.

| `dscpMark` _[DSCP](#dscp)_ | (Optional) DSCPMark define the value of the DSCP mark done by Felix and recognised by Istio CNI for Transparent NetworkPolicies. |

calico-enterprise_versioned_docs/version-3.23-2/reference/installation/_api.mdx:5868

This links to #tlspassthroughroute, but the file does not include a TLSPassThroughRoute section/header, so the anchor is broken.

- [TLSPassThroughRoute](#tlspassthroughroute)

calico-enterprise_versioned_docs/version-3.23-2/reference/installation/_api.mdx:5886

This links to #tlsterminatedroute, but the file does not include a TLSTerminatedRoute section/header, so the anchor is broken.

- [TLSTerminatedRoute](#tlsterminatedroute)

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.


 _Appears in:_
- DashboardsJob
+- [DashboardsJob](#dashboardsjob)



 _Appears in:_
- TLSTerminatedRoute
+- [TLSTerminatedRoute](#tlsterminatedroute)



 _Appears in:_
- DashboardsJob
+- [DashboardsJob](#dashboardsjob)


 | --- | --- |
-| `name` _string_ | Name is an enum which identifies the calico-node-windows DaemonSet container by name.<br />Supported values are: calico-node-windows |
-| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#resourcerequirements-v1-core)_ | (Optional) Resources allows customization of limits and requests for compute resources such as cpu and memory. If specified, this overrides the named calico-node-windows DaemonSet container's resources. If omitted, the calico-node-windows DaemonSet will use its default value for this container's resources. If used in conjunction with the deprecated ComponentResources, then this value takes precedence. |
+| `name` _string_ | Name is an enum which identifies the calico-node-windows DaemonSet container by name.<br />Supported values are: node, felix, confd calico-node-windows is allowed because it was previously allowed. |


Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (3)

calico-enterprise_versioned_docs/version-3.23-2/reference/installation/_api.mdx:940

The supported-values sentence is missing punctuation between the listed values and the follow-up note about the legacy name, which makes the enum list ambiguous.

| `name` _string_ | Name is an enum which identifies the calico-node-windows DaemonSet container by name.<br />Supported values are: node, felix, confd calico-node-windows is allowed because it was previously allowed. |

calico/reference/installation/_api.mdx:1229

The WAF field description opens a parenthetical ("(Coraza WASM …") but never closes it, which makes the sentence hard to parse in the rendered docs.

| `waf` _[WAFExtensionSpec](#wafextensionspec)_ | (Optional) WAF enables and configures the Tigera Web Application Firewall (Coraza WASM when WAF.State is nil, and when WAF.State is "Disabled", the operator does not render the WAF env vars or RBAC on calico-kube-controllers.  Set WAF.State = "Enabled" to turn the feature on.  See design `tigera/designs#25` (PMREQ-384) for the full surface. |

calico-enterprise/reference/installation/_api.mdx:2390

The WAF field description opens a parenthetical ("(Coraza WASM …") but never closes it, which makes the sentence hard to parse in the rendered docs.

| `waf` _[WAFExtensionSpec](#wafextensionspec)_ | (Optional) WAF enables and configures the Tigera Web Application Firewall (Coraza WASM when WAF.State is nil, and when WAF.State is "Disabled", the operator does not render the WAF env vars or RBAC on calico-kube-controllers.  Set WAF.State = "Enabled" to turn the feature on.  See design `tigera/designs#25` (PMREQ-384) for the full surface. |

ctauchen requested a review from a team as a code owner August 20, 2026 20:08

Copilot AI lite review requested due to automatic review settings August 20, 2026 20:08

Copilot started reviewing on behalf of ctauchen August 20, 2026 20:08 View session

Copilot AI reviewed Aug 20, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 20, 2026 20:12

Copilot AI reviewed Aug 20, 2026

View reviewed changes

ctauchen merged commit a16d236 into main Aug 20, 2026
12 checks passed

ctauchen deleted the api-ref-audit branch August 20, 2026 20:15

Copilot started reviewing on behalf of ctauchen August 20, 2026 23:10 View session

Navigation Menu

Uh oh!

Regenerate the operator API reference for drifted doc versions - #2942

Regenerate the operator API reference for drifted doc versions#2942
ctauchen merged 2 commits into
mainfrom
api-ref-audit

ctauchen commented Aug 20, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

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 Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Aug 20, 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 Aug 20, 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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ctauchen commented Aug 20, 2026 •

edited

Loading

netlify Bot commented Aug 20, 2026 •

edited

Loading

netlify Bot commented Aug 20, 2026 •

edited

Loading