docs(gateway): fix default-deny step for namespaced mode - #2802
Open
electricjesus wants to merge 1 commit into
Open
docs(gateway): fix default-deny step for namespaced mode#2802electricjesus wants to merge 1 commit into
electricjesus wants to merge 1 commit into
Conversation
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the “Create an ingress gateway” documentation (OSS and Enterprise) to align default-deny guidance with Gateway API namespaced mode, where gateway dataplane proxies run in the Gateway’s namespace rather than tigera-gateway.
Changes:
- Replaces the outdated instruction to exclude
tigera-gatewayfrom global default-deny policies. - Documents that the Operator allows the proxy’s own traffic via
calico-systemtier policy, and that users must allow proxy-to-backend connectivity.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| calico/networking/ingress-gateway/create-ingress-gateway.mdx | Updates default-deny step to reflect namespaced-mode proxy placement and required backend connectivity allowance. |
| calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx | Same documentation correction for the Enterprise docs path and resource naming. |
Comment on lines
+33
to
+37
| you do not need to allow the gateway proxy's own traffic. The Tigera Operator allows it through a | ||
| policy in the `calico-system` tier. You do need to allow the gateway proxy to reach your backend | ||
| workloads. The proxy pods carry the label `gateway.envoyproxy.io/owning-gateway-name`, so you can | ||
| select them in an egress rule. Without that rule, the gateway is reachable but returns `503` because | ||
| the proxy cannot connect to the backend. |
Comment on lines
+33
to
+37
| you do not need to allow the gateway proxy's own traffic. The Tigera Operator allows it through a | ||
| policy in the `calico-system` tier. You do need to allow the gateway proxy to reach your backend | ||
| workloads. The proxy pods carry the label `gateway.envoyproxy.io/owning-gateway-name`, so you can | ||
| select them in an egress rule. Without that rule, the gateway is reachable but returns `503` because | ||
| the proxy cannot connect to the backend. |
electricjesus
marked this pull request as ready for review
July 29, 2026 15:35
Collaborator
|
Waiting on operator change and testing before review. |
… cover tigera#2873 replaced the obsolete tigera-gateway namespace exclusion with a reference NetworkPolicy that users apply in each Gateway namespace. That policy allows DNS and the gateway controller hop itself. With tigera/operator#4970 the operator renders calico-system.envoy-gateway-proxy, which already allows inbound traffic to the proxy plus proxy egress to DNS and to the controller on 18000 and 18002. The reference policy would duplicate rules the operator now owns. What the operator's policy deliberately does not cover is the backend hop. It ends its egress rules with a Pass so the user keeps control of which backends the proxy may reach. Under default deny that hop stays denied, and the gateway returns 503 after the upstream connect timeout. So the step now covers only the user's part: - proxy egress to the backend, and backend ingress from the proxy. Both are needed, because default deny applies to the backend pod too. - on Enterprise, egress to the Kubernetes API server, for the log collector that runs in the proxy pod. The example selects proxies by k8s-app == "calico-gateway-api-proxy", the Calico-owned label that #4970 stamps on the proxy pod template.
electricjesus
force-pushed
the
seth/gateway-default-deny-doc-fix
branch
from
August 19, 2026 10:47
2aed725 to
77fc8f6
Compare
3 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (10)
calico/networking/ingress-gateway/create-ingress-gateway.mdx:111
- This policy is intended to apply to the backend pods, so it should be created in the backend workload namespace (not the Gateway namespace).
namespace: <gateway-namespace>
calico/networking/ingress-gateway/create-ingress-gateway.mdx:120
- If the backend pods are in a different namespace than the Gateway, the backend ingress policy needs a namespaceSelector on the source to match the proxy pods' namespace (Calico selectors are namespace-scoped without it).
source:
selector: 'k8s-app == "calico-gateway-api-proxy"'
calico/networking/ingress-gateway/create-ingress-gateway.mdx:122
- The placeholder guidance should include the backend namespace now that the example policies reference it.
Replace `<gateway-namespace>` with the namespace where you created the `Gateway`, and `<your-backend-selector>` with a selector that matches your backend pods.
calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx:126
- This backend ingress policy should be created in the backend workload namespace, not the Gateway namespace; otherwise it will not select backend pods outside the Gateway namespace.
namespace: <gateway-namespace>
calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx:137
- The placeholder guidance should mention
<backend-namespace>since the example policies need it to work when backends are not in the Gateway namespace.
Replace `<gateway-namespace>` with the namespace where you created the `Gateway`, and `<your-backend-selector>` with a selector that matches your backend pods.
calico/networking/ingress-gateway/create-ingress-gateway.mdx:89
- This instruction implies both policies should be created in the Gateway namespace, but the backend ingress policy must live in the backend workload namespace (or be a GlobalNetworkPolicy) when backends are not in the Gateway namespace; otherwise it will not select the backend pods.
This issue also appears on line 111 of the same file.
Apply a network policy in the `Gateway` namespace that allows both directions of that hop:
calico/networking/ingress-gateway/create-ingress-gateway.mdx:105
- A namespaced Calico NetworkPolicy's destination selector is scoped to its namespace unless you add a namespaceSelector. As written, this egress rule will only match backends in the Gateway namespace, which is not typical for gateways.
This issue also appears in the following locations of the same file:
- line 119
- line 122
destination:
selector: '<your-backend-selector>'
calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx:98
- This instruction currently implies a single policy in the Gateway namespace is sufficient, but the backend ingress allow must be created in the backend workload namespace (or as a GlobalNetworkPolicy) when backends are outside the Gateway namespace.
This issue also appears on line 126 of the same file.
Apply a network policy in the `Gateway` namespace:
calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx:120
- As written, this egress destination selector will only match backend pods in the Gateway namespace. If your backends run in another namespace, add a namespaceSelector so the rule matches them.
This issue also appears on line 137 of the same file.
destination:
selector: '<your-backend-selector>'
calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx:135
- When the proxy and backends are in different namespaces, include a namespaceSelector on the source so this ingress rule matches the proxy pods' namespace.
source:
selector: 'k8s-app == "calico-gateway-api-proxy"'
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.
Product Version(s):
Calico Enterprise 3.24 and Calico Open Source v3.33, the versions where the gateway proxy runs in the Gateway's own namespace. Only the unversioned pages are touched. Older snapshots predate namespaced mode and are left alone.
Issue:
tigera/operator#4970
Link to docs preview:
Both links point at the
calico-docs-preview-nextbuild. Thetigerapreview still serves the old text on thenextroutes, so it is not the one to read for this PR.SME review:
DOCS review:
Additional information:
This PR started out as a fix for the old step that told users to exclude the
tigera-gatewaynamespace. #2873 already fixed that, so this is now a smaller follow-up on top of it.#2873 added a reference NetworkPolicy that users apply in each Gateway namespace. It allows DNS and the hop to the gateway controller. With tigera/operator#4970 the operator renders
calico-system.envoy-gateway-proxy, which already allows those two things, plus inbound traffic to the proxy. So the reference policy would ask users to write rules the operator now owns.What the operator's policy leaves alone on purpose is the backend hop. Its egress rules end in a
Pass, which hands the decision to the user's own tier so they stay in control of which backends the proxy can reach. Under default deny that hop is denied, and the gateway returns503after Envoy's upstream connect timeout.So the step now covers only the user's part:
The example selects proxies by
k8s-app == "calico-gateway-api-proxy", the Calico-owned label that #4970 stamps on the proxy pod template. The page used to use Envoy Gateway's ownapp.kubernetes.io/name == "envoy".Both policies go in the
defaulttier atorder: 10, so they sit aftercalico-systemand take effect before a default-deny.This should merge in the same release as tigera/operator#4970. The text describes what the operator does once that lands.
Merge checklist: