[EV-6466]: Add Gateway WAF (per-route & namespaced) docs section#2758
Open
electricjesus wants to merge 15 commits into
Open
[EV-6466]: Add Gateway WAF (per-route & namespaced) docs section#2758electricjesus wants to merge 15 commits into
electricjesus wants to merge 15 commits into
Conversation
Add a Calico Enterprise docs section for the Gateway-API WAF feature (OWASP CRS via a Coraza WASM filter on Envoy Gateway): overview, concepts (families, global vs namespaced, merge order + enforcement), get-started (operator-native enable + quickstart), persona-oriented how-tos (CO baseline, AO attach/rules/validate, multi-tenant), and a CRD / Rego / SecRule-ID-range / status-condition reference, plus troubleshooting. - New section under threat/gateway-waf/ (16 pages) + sidebar category. - Deprecation note on deploying-waf-ingress-gateway (superseded by the new per-route/namespaced model). Refs: PMREQ-384, designs#25, cp#12137 (Rego engine, EV-6656). Docs: EV-6466.
❌ Deploy Preview for tigera failed. Why did it fail? →Built without sensitive environment variables
|
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Member
Author
|
Build status — ✅ The new
These are outside this PR's scope. Leaving the "Build completed successfully" checkbox unchecked until they're resolved (or confirmed handled by CI's build matrix). |
- Add WAF terms to the CalicoTerminology vocab (Rego, allowlist, the six WAF CRD kinds, and targetRefs/namespaceSelector/paranoiaLevel/ coreRuleSet/defaultAction/enforcementMode/SecLang). - Reword two "another's" possessives (Vale.Spelling false positive). - "walks through" -> "walks you through" (CalicoStyle.Walkthrough). Verified with scripts/vale-lint.sh --minAlertLevel=error: 0 errors.
The reviewdog/Vale gate fails on warnings too, and Vale.Terms flagged the bare acronym "CRS" as a miscasing of "CRs" (the custom-resources term). Replace the bare acronym in prose with "Core Rule Set"; code blocks and inline-code literals (e.g. the Rego rule messages) are left unchanged so examples stay accurate. Verified with scripts/vale-lint.sh: 0 errors, 0 warnings, 0 suggestions.
Replace the ASCII architecture diagram in the Gateway WAF overview with a Mermaid flowchart, and introduce @docusaurus/theme-mermaid to the repo (first Mermaid usage here). The repo builds with future.faster.ssgWorkerThreads, under which theme-mermaid's context hooks (useColorMode/useThemeConfig) throw during worker-thread SSG. So the diagram is rendered client-side via <BrowserOnly> + @theme/Mermaid, and markdown.mermaid is intentionally NOT enabled (it would auto-transform ```mermaid fences and crash SSG repo-wide). Verified BUILD_NEXT build: the gateway-waf pages render cleanly; the only build failure is pre-existing broken links in unrelated calico/calico-cloud next docs.
Member
Author
|
Heads-up for reviewers: this PR introduces Mermaid to the docs site for the first time.
|
Replace the overview's ASCII pipeline with a static SVG (static/img/calico-enterprise/gateway-waf-architecture.svg) and revert the Mermaid introduction. @docusaurus/theme-mermaid is incompatible with this repo's multi-docs-instance + yarn-berry setup: @docusaurus/theme-common (peer dep @docusaurus/plugin-content-docs: "*") is instantiated as two virtual copies, so the classic theme's <ColorModeProvider> and theme-mermaid's useColorMode() bind different React contexts -> ReactContextError during both worker-thread SSG and client render. The SVG carries descriptive alt text for accessibility.
Member
Author
|
Update — reverted the Mermaid introduction; the architecture diagram is now a static SVG.
Rather than repo-wide yarn |
Fix text overflow and tighten spacing flagged in review: widen the canvas to 940x360, split the admission-webhook caption to two lines, widen the input/process boxes so every label fits with margin, and clean up the pass/fail arrow routing. Same colour palette.
…ique reservation (EV-6757) The range page implied each namespace gets a private, collision-free block. Reword to say the range is the set of IDs your rules may use, note it isn't globally unique (two namespaces can map to the same block, harmlessly), and that tenant isolation comes from per-namespace engines plus the protected ranges.
Fold the concepts/, get-started/, how-to/, and reference/ subpages into single Overview, How it works, Get started, Common tasks, Reference, and Troubleshooting pages, flattening the section to match the threat/ layout. Content preserved; sidebar updated. Ref: EV-6466
Verbosity-only pass over Common tasks, Reference, How it works, and Troubleshooting: cut repeated narrative and duplicate YAML, keep one representative example per task. No facts, tables, field/rule/status-condition names, or meaning changed. ~10.0k -> ~8.5k words. Ref: EV-6466
…ditions - Gateway-WAF hits are recorded in tigera_secure_ee_waf (with gateway_name/gateway_namespace) but are not raised as Security Events on this release (intrusion-detection GatewayName filter); re-surfacing is a later-release item. - sectionName is supported: drop the "reserved for a future release" wording and the SectionNameNotYetSupported status reason. - Status-condition reasons corrected to match the reconciler: LicenseRequired (not LicenseBlocked); TargetNotFound and RenderTooLarge under Programmed; add Invalid/ValidationFailed/PluginNotFound under Accepted; drop UnsupportedTarget; Accepted=True reason is Accepted (not Reconciled). Ref: EV-6466 EV-6650 EV-6786
The deprecation note on deploying-waf-ingress-gateway.mdx linked to gateway-waf/how-to/attach-waf-to-a-route.mdx, which the 16->6 consolidation removed. Repoint it to the merged Common tasks section (#attach-waf-to-a-gateway-or-route). Ref: EV-6466
Per docs-team feedback, reorganize (not further shrink) the section: - Overview becomes the concepts home: absorbs How it works (resource model, singleton, inheritance, load order, guardrails) and the architecture diagram; the standalone How-it-works page is removed. - Get started slims to a signpost (prerequisites + enable -> tutorial -> tasks); the hands-on walkthrough moves to a new Tutorial page. - Enable/disable becomes its own page (Enable Gateway WAF). - Common tasks split into one page per task (set a baseline, attach WAF, write custom rules, validate config, multi-tenant); persona labels dropped, each gains a what/why lead. - Sidebar reordered to the new layout; inbound links (incl. the deprecation note) repointed. Ref: EV-6466
Gateway WAF is gated by the GatewayAPI CR (spec.extensions.waf.state), not the ApplicationLayer resource (that gates the legacy ext_proc WAF). Confirmed against tigera/operator origin/master (IsWAFGatewayExtensionEnabled). Drop the stale ApplicationLayer mention and let the Enable page own the mechanism. Ref: EV-6466
Restructure the Gateway WAF section per review: - make the category an empty expansion; move its landing content to overview - drop the Get started page; put prerequisites on each task page - add the tech-preview banner to every page - convert procedures to numbered steps (the tutorial is now one list) - rename the baseline page title to name the feature - move the plugin slot table to overview; trim the Rego example on the validation page
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.
Product Version(s):
Calico Enterprise (next / unreleased), tech preview. Not for Calico OSS or Calico Cloud.
Issue:
2026/PMREQ-384-per-route-namespaced-waf). Rego engine: calico-private#12137 (EV-6656).Link to docs preview:
SME review:
DOCS review:
Additional information:
Adds a Gateway WAF section under
calico-enterprise/threat/gateway-waf/. It documents the per-route and per-namespace WAF feature (OWASP CRS via a Coraza WASM filter on Envoy Gateway). The section is 11 task-based pages:GatewayAPI.spec.extensions.waf.state.It also adds a deprecation note to
threat/deploying-waf-ingress-gateway.mdx, which this feature supersedes.Notes for reviewers:
tigera_secure_ee_wafindex withgateway_nameandgateway_namespace. It does not show up as a Security Event on this release. The intrusion-detection GatewayName filter drops it by design. Bringing it back is a later-release item.WAFPolicy,GlobalWAFPolicy,WAFPlugin, and so on) from designs#25, not the olderWebApplicationFirewall*names.package waf/violations), not the prototype's CEL.sectionName(per-listener targeting) is documented as supported.kubectl wafplugin and the web UI/BFF (PMREQ-857) are out of scope here. They're called "coming" at most.deploying-waf-ingress-gatewaypage.Merge checklist: