docs-2984: document Calico Ingress Gateway namespace mode - #2873
Merged
Conversation
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the Calico Ingress Gateway move to a namespaced deployment model (controller in calico-system, per-Gateway proxy/Service/load balancer in the Gateway namespace) across Calico OSS and Calico Enterprise docs, including an upgrade/migration guide and release note callouts for the breaking change.
Changes:
- Adds a new “Upgrade to namespaced gateways” migration guide and links it from sidebars.
- Updates “About”, “Create”, and “Customize” Ingress Gateway docs to reflect the new topology and operational guidance (default-deny NetworkPolicy example, updated verification commands, merged gateways note).
- Adds breaking-change entries to OSS and Enterprise release notes linking to the migration guide.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| sidebars-calico.js | Adds the new migration guide to the OSS Ingress Gateway sidebar. |
| sidebars-calico-enterprise.js | Adds the new migration guide to the Enterprise Ingress Gateway sidebar. |
| calico/release-notes/index.mdx | Adds a breaking-change release note entry linking to the migration guide. |
| calico/networking/ingress-gateway/migrate-to-namespaced-gateways.mdx | New OSS migration guide describing the namespace-mode upgrade impact. |
| calico/networking/ingress-gateway/customize-ingress-gateway.mdx | Updates OSS customization guidance for the new controller namespace and merged gateway behavior. |
| calico/networking/ingress-gateway/create-ingress-gateway.mdx | Updates OSS create flow and adds default-deny NetworkPolicy guidance for namespaced proxies. |
| calico/networking/ingress-gateway/about-calico-ingress-gateway.mdx | Adds OSS topology section describing where controller/proxy resources run. |
| calico-enterprise/release-notes/index.mdx | Adds a breaking-change release note entry linking to the migration guide. |
| calico-enterprise/networking/ingress-gateway/migrate-to-namespaced-gateways.mdx | New Enterprise migration guide including Enterprise-only per-namespace resources. |
| calico-enterprise/networking/ingress-gateway/customize-ingress-gateway.mdx | Updates Enterprise customization guidance for the new controller namespace and merged gateway behavior. |
| calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx | Updates Enterprise create flow and adds default-deny NetworkPolicy guidance for namespaced proxies (+ API server egress). |
| calico-enterprise/networking/ingress-gateway/about-calico-ingress-gateway.mdx | Adds Enterprise topology section describing where controller/proxy resources run and supporting resources created. |
|
|
||
| ::: | ||
|
|
||
| To make use of these customization fields, use `kubectl edit gatewayapi tigera-secure` to edit the YAML for the `GatewayAPI` resource, and add or modify the customization fields that you require. |
Collaborator
Author
There was a problem hiding this comment.
Fixed. The OSS page now uses default for the kubectl edit command and every GatewayAPI example on the page, matching the OSS install flow.
| 1. Patch the `GatewayAPI` resource to include the path of the custom Envoy configuration: | ||
| ```bash | ||
| kubectl patch gatewayapi tigera-secure --type='json' -p='[{"op": "replace", "path": "/spec/envoyGatewayConfigRef", "value": {"name": "custom-envoy-config", "namespace": "tigera-gateway"}}]' | ||
| kubectl patch gatewayapi tigera-secure --type='json' -p='[{"op": "replace", "path": "/spec/envoyGatewayConfigRef", "value": {"name": "custom-envoy-config", "namespace": "calico-system"}}]' |
Collaborator
Author
There was a problem hiding this comment.
Fixed. The patch command now targets default to match the OSS install flow.
| @@ -227,7 +234,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa | |||
| helm.sh/chart: gateway-helm-v1.5.0 | |||
| // highlight-next-line | |||
| name: custom-envoy-gateway-config | |||
Collaborator
Author
There was a problem hiding this comment.
Fixed. Renamed the example ConfigMap to custom-envoy-config so it matches the kubectl apply and kubectl patch commands.
| @@ -227,7 +234,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa | |||
| helm.sh/chart: gateway-helm-v1.5.0 | |||
| // highlight-next-line | |||
| name: custom-envoy-gateway-config | |||
Collaborator
Author
There was a problem hiding this comment.
Fixed. Renamed the example ConfigMap to custom-envoy-config so it matches the kubectl apply and kubectl patch commands.
ctauchen
force-pushed
the
docs-2984-namespaced-gateways
branch
5 times, most recently
from
July 24, 2026 11:51
f36a720 to
7dbc53c
Compare
ctauchen
marked this pull request as ready for review
July 24, 2026 11:53
Calico Ingress Gateway now runs the controller in calico-system and each gateway's proxy in the Gateway's own namespace (Calico Enterprise 3.24, Calico OSS v3.33). This is a breaking change on upgrade. - about: explain the namespaced topology and what the operator creates in each Gateway namespace (trust bundle; plus pull secret and WAF SA on Enterprise). - create: replace the obsolete tigera-gateway default-deny exclusion with a per-namespace reference NetworkPolicy; point verification at the Gateway namespace; add a short section on running gateways in multiple namespaces. - customize: note that merged gateways are not supported; correct the custom Envoy config commands to use calico-system. - add an upgrade/migration page and link it from the release notes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ctauchen
force-pushed
the
docs-2984-namespaced-gateways
branch
from
July 27, 2026 15:29
7dbc53c to
a2af104
Compare
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
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.
What
Documents the Calico Ingress Gateway namespace mode change (DOCS-2984 / PMREQ-832) for Calico Enterprise 3.24 and Calico OSS v3.33. The controller now runs in
calico-system, and each gateway's proxy,Service, and load balancer run in the same namespace as theGatewayresource. This is a breaking change on upgrade. There is no new API field — the behavior is mandatory, not opt-in.Changes
tigera-ca-bundleon both; plus atigera-pull-secretcopy andwaf-http-filterSA/RoleBinding on Enterprise).tigera-gatewaydefault-deny exclusion; added a per-namespace reference NetworkPolicy for default-deny clusters; verification now points at the Gateway namespace; added a short "deploy gateways in multiple namespaces" section.mergeGateways: true) are not supported (operator forcesfalse); corrected the custom Envoy config commands fromtigera-gatewaytocalico-system.migrate-to-namespaced-gateways.mdxupgrade guide + sidebar entries.Enterprise-only: the reference NetworkPolicy keeps a Kubernetes API server egress rule for the WAF/L7 sidecars. Calico Cloud is out of scope.
Verification
Content was verified empirically on a live OSS namespaced-mode install (kind + operator
master, which contains the implementation PRs): proxy + load balancer land in the Gateway namespace;tigera-ca-bundleis present and mounted by the proxy; the reference NetworkPolicy selectors resolve to the real proxy and controller pod labels. All changed pages build and render locally with no MDX or link errors.Follow-ups (not in this PR)
🤖 Generated with Claude Code