From 7dbc53c084d19ede3b57f8f956d50376d26a81a8 Mon Sep 17 00:00:00 2001 From: Christopher Tauchen Date: Wed, 22 Jul 2026 11:21:36 +0100 Subject: [PATCH] docs-2984: document Calico Ingress Gateway namespace mode 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) --- .../about-calico-ingress-gateway.mdx | 19 +++++ .../create-ingress-gateway.mdx | 57 ++++++++++++-- .../customize-ingress-gateway.mdx | 15 +++- .../tutorial-ingress-gateway-canary.mdx | 74 +++++-------------- calico-enterprise/release-notes/index.mdx | 20 +++++ .../about-calico-ingress-gateway.mdx | 17 +++++ .../create-ingress-gateway.mdx | 50 +++++++++++-- .../customize-ingress-gateway.mdx | 15 +++- .../tutorial-ingress-gateway-canary.mdx | 74 +++++-------------- calico/release-notes/index.mdx | 20 +++++ 10 files changed, 225 insertions(+), 136 deletions(-) diff --git a/calico-enterprise/networking/ingress-gateway/about-calico-ingress-gateway.mdx b/calico-enterprise/networking/ingress-gateway/about-calico-ingress-gateway.mdx index 6bd5c103f3..2f6352964e 100644 --- a/calico-enterprise/networking/ingress-gateway/about-calico-ingress-gateway.mdx +++ b/calico-enterprise/networking/ingress-gateway/about-calico-ingress-gateway.mdx @@ -47,6 +47,25 @@ Administrators provision the gateway environment simply by defining a standard G For commercial deployments, Calico Ingress Gateway extends functionality by integrating directly with the Web Application Firewall (WAF). This feature allows operators to secure their ingress points against the OWASP Top 10 and other common vulnerabilities through simple configuration within the Calico management plane. +## Where Calico Ingress Gateway runs + +Calico Ingress Gateway uses a namespaced deployment model. +The Tigera Operator runs a single Envoy Gateway controller in the `calico-system` namespace. +When you create a `Gateway` resource, its proxy, `Service`, and load balancer are created in the **same namespace as the `Gateway`**. + +This model lets the owner of a namespace apply their own network policy and RBAC to the gateway's proxy pods. +Teams do not have to share a namespace, and they do not have to ask a cluster administrator to change a shared namespace on their behalf. +You can deploy a gateway in each namespace that needs one, so multiple teams each run and own a gateway in their own namespace. + +The operator also creates supporting resources in each namespace that holds a `Gateway`: + +- A `tigera-ca-bundle` ConfigMap, which the proxy mounts so that it trusts cluster and public certificate authorities. The proxy does not start until this ConfigMap is present. +- A copy of the `tigera-pull-secret`, so the namespace can pull the hardened gateway images. +- A `waf-http-filter` ServiceAccount and RoleBinding, used by the Web Application Firewall and Layer 7 log collector sidecars. + +Each `Gateway` gets its own load balancer. +Calico Ingress Gateway does not place more than one gateway behind a single load balancer. + ## Supported Gateway API resources Calico Ingress Gateway supports the following Gateway API resources. diff --git a/calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx b/calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx index f3316997c6..ee2b914fef 100644 --- a/calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx +++ b/calico-enterprise/networking/ingress-gateway/create-ingress-gateway.mdx @@ -29,10 +29,6 @@ You need to do the following: ## Create an ingress gateway -1. If you are using a [global default deny policy](../../network-policy/beginners/kubernetes-default-deny.mdx), - allow traffic through the gateway by adding the `tigera-gateway` namespace to the list of excluded namespaces in the - `namespaceSelector` field. - 1. To enable Gateway API support, create a `GatewayAPI` resource with the name `tigera-secure`: ```bash @@ -60,22 +56,68 @@ You need to do the following: You can define [additional gateway classes](customize-ingress-gateway.mdx#configure-multiple-gateway-classes), along with other customizations, in the `GatewayAPI` resource. ::: -1. Create a `Gateway` resource that is linked to `tigera-gateway-class`. +1. Create a `Gateway` resource that is linked to `tigera-gateway-class`, in the namespace where you want its proxy to run. ```yaml title='Example snippet of a Gateway resource with default gatewayClassName' apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: - // highlight-next-line + // highlight-start name: + namespace: + // highlight-end spec: // highlight-next-line gatewayClassName: tigera-gateway-class ... ``` - Replace `` with a name for your gateway. + Replace `` with a name for your gateway, and `` with the namespace where you want the gateway to run. You will refer to this gateway name for all services you want to use the gateway. + The proxy, its `Service`, and its load balancer are created in the same namespace as this `Gateway`. + To check that the proxy is running, list the pods in that namespace: + + ```bash + kubectl get pods -n + ``` + +1. If your cluster enforces a [global default deny policy](../../network-policy/beginners/kubernetes-default-deny.mdx), apply a network policy in the `Gateway` namespace that lets the proxy pods reach the gateway controller, the Kubernetes API server, and DNS. + Without it, the proxy cannot start. + + ```yaml + apiVersion: projectcalico.org/v3 + kind: NetworkPolicy + metadata: + name: allow-tigera-gateway-proxy + namespace: + spec: + selector: 'app.kubernetes.io/name == "envoy"' + types: [Ingress, Egress] + ingress: + - action: Allow + egress: + - action: Allow # DNS + protocol: UDP + destination: + namespaceSelector: 'projectcalico.org/name == "kube-system"' + selector: 'k8s-app == "kube-dns"' + ports: [53] + - action: Allow # configuration from the gateway controller + protocol: TCP + destination: + namespaceSelector: 'projectcalico.org/name == "calico-system"' + selector: 'app.kubernetes.io/name == "gateway-helm"' + ports: [18000] + - action: Allow # Kubernetes API server + protocol: TCP + destination: + services: + name: kubernetes + namespace: default + ``` + Replace `` with the namespace where you created the `Gateway`. + Add egress rules for your own backends as needed. + 1. Create a gateway routing resource that refers to your `Gateway` resource as `.spec.parentRefs`: ```yaml title='Example snippet of an HTTPRoute resource' @@ -96,4 +138,5 @@ You need to do the following: * [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/) * [Envoy Gateway documentation](https://gateway.envoyproxy.io/docs/) +* [Multi-tenant WAF setup](../../threat/gateway-waf/multi-tenant-setup.mdx) * [Tutorial: Launch a canary deployment](tutorial-ingress-gateway-canary.mdx) diff --git a/calico-enterprise/networking/ingress-gateway/customize-ingress-gateway.mdx b/calico-enterprise/networking/ingress-gateway/customize-ingress-gateway.mdx index 30358a2faf..d6ba56403a 100644 --- a/calico-enterprise/networking/ingress-gateway/customize-ingress-gateway.mdx +++ b/calico-enterprise/networking/ingress-gateway/customize-ingress-gateway.mdx @@ -22,6 +22,13 @@ For example: For full details, see [the `GatewayAPI` reference documentation](../../reference/installation/api.mdx#gatewayapi). +:::note + +Merged gateways are not supported. +If a custom `EnvoyProxy` sets `mergeGateways: true`, the operator ignores that setting and uses `false` instead, so each `Gateway` gets its own proxy and load balancer. + +::: + 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. ### Customization examples @@ -112,7 +119,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa 1. Save a copy of the default Envoy configuration file: ```bash - kubectl get configmap envoy-gateway-config -n tigera-gateway -o yaml > .yaml + kubectl get configmap envoy-gateway-config -n calico-system -o yaml > .yaml ``` Replace `` with a name for your custom configuration. ```yaml title='Example of a default Envoy configuration' @@ -157,7 +164,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa app.kubernetes.io/version: v1.5.0 helm.sh/chart: gateway-helm-v1.5.0 name: envoy-gateway-config - namespace: tigera-gateway + namespace: calico-system ownerReferences: - apiVersion: operator.tigera.io/v1 blockOwnerDeletion: true @@ -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 - namespace: tigera-gateway + namespace: calico-system ``` 1. Apply the customized Envoy configuration: @@ -236,7 +243,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa ``` 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"}}]' ``` ## Additional resources diff --git a/calico-enterprise/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx b/calico-enterprise/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx index c88166e618..059933cdc0 100644 --- a/calico-enterprise/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx +++ b/calico-enterprise/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx @@ -49,7 +49,7 @@ You'll need to install a few tools to complete this tutorial: ## Step 1: Set up your environment -For this tutorial, you need access to a cluster with Calico Open Source 3.30 or later installed. +For this tutorial, you need access to a cluster with Calico Open Source 3.33 or later installed. We'll use `kind` to create this environment, but you can use any other supported Kubernetes distribution with a compatible version of $[prodname]. If you've already got a suitable environment, start the tutorial at [Step 2: Create the ingress gateway](#step-2-create-an-ingress-gateway). @@ -177,12 +177,19 @@ Once that is set up, you can create supported Gateway API resources, such as the "parametersRef": { "group": "gateway.envoyproxy.io", "kind": "EnvoyProxy", - "name": "envoy-proxy-config", - "namespace": "tigera-gateway" + "name": "tigera-gateway-class", + "namespace": "calico-system" } } ``` -1. Create a `Gateway` resource that is linked to the `tigera-gateway-class`. +1. Create a namespace to hold your gateway and application: + + ```bash + kubectl create namespace ingress-gateway-demo + ``` + +1. Create a `Gateway` resource in that namespace, linked to the `tigera-gateway-class`. + Its proxy runs in the same namespace as the `Gateway`. ```bash kubectl apply -f - < + namespace: + // highlight-end spec: // highlight-next-line gatewayClassName: tigera-gateway-class ... ``` - Replace `` with a name for your gateway. + Replace `` with a name for your gateway, and `` with the namespace where you want the gateway to run. You will refer to this gateway name for all services you want to use the gateway. + The proxy, its `Service`, and its load balancer are created in the same namespace as this `Gateway`. + To check that the proxy is running, list the pods in that namespace: + + ```bash + kubectl get pods -n + ``` + +1. If your cluster enforces a [global default deny policy](../../network-policy/get-started/kubernetes-default-deny.mdx), apply a network policy in the `Gateway` namespace that lets the proxy pods reach the gateway controller and DNS. + Without it, the proxy cannot start. + + ```yaml + apiVersion: projectcalico.org/v3 + kind: NetworkPolicy + metadata: + name: allow-tigera-gateway-proxy + namespace: + spec: + selector: 'app.kubernetes.io/name == "envoy"' + types: [Ingress, Egress] + ingress: + - action: Allow + egress: + - action: Allow # DNS + protocol: UDP + destination: + namespaceSelector: 'projectcalico.org/name == "kube-system"' + selector: 'k8s-app == "kube-dns"' + ports: [53] + - action: Allow # configuration from the gateway controller + protocol: TCP + destination: + namespaceSelector: 'projectcalico.org/name == "calico-system"' + selector: 'app.kubernetes.io/name == "gateway-helm"' + ports: [18000] + ``` + Replace `` with the namespace where you created the `Gateway`. + Add egress rules for your own backends as needed. + 1. Create a gateway routing resource that refers to your `Gateway` resource as `.spec.parentRefs`: ```yaml title='Example snippet of an HTTPRoute resource' diff --git a/calico/networking/ingress-gateway/customize-ingress-gateway.mdx b/calico/networking/ingress-gateway/customize-ingress-gateway.mdx index 741d0ac1fb..5032e43e8c 100644 --- a/calico/networking/ingress-gateway/customize-ingress-gateway.mdx +++ b/calico/networking/ingress-gateway/customize-ingress-gateway.mdx @@ -22,6 +22,13 @@ For example: For full details, see [the `GatewayAPI` reference documentation](../../reference/installation/api.mdx#gatewayapi). +:::note + +Merged gateways are not supported. +If a custom `EnvoyProxy` sets `mergeGateways: true`, the operator ignores that setting and uses `false` instead, so each `Gateway` gets its own proxy and load balancer. + +::: + 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. ### Customization examples @@ -112,7 +119,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa 1. Save a copy of the default Envoy configuration file: ```bash - kubectl get configmap envoy-gateway-config -n tigera-gateway -o yaml > .yaml + kubectl get configmap envoy-gateway-config -n calico-system -o yaml > .yaml ``` Replace `` with a name for your custom configuration. ```yaml title='Example of a default Envoy configuration' @@ -157,7 +164,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa app.kubernetes.io/version: v1.5.0 helm.sh/chart: gateway-helm-v1.5.0 name: envoy-gateway-config - namespace: tigera-gateway + namespace: calico-system ownerReferences: - apiVersion: operator.tigera.io/v1 blockOwnerDeletion: true @@ -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 - namespace: tigera-gateway + namespace: calico-system ``` 1. Apply the customized Envoy configuration: @@ -236,7 +243,7 @@ To use a custom Envoy configuration, you can modify and apply a copy of the defa ``` 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"}}]' ``` ## Additional resources diff --git a/calico/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx b/calico/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx index c47b12fc04..2fbaa46bae 100644 --- a/calico/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx +++ b/calico/networking/ingress-gateway/tutorial-ingress-gateway-canary.mdx @@ -48,7 +48,7 @@ You'll need to install a few tools to complete this tutorial: ## Step 1: Set up your environment -For this tutorial, you need access to a cluster with Calico Open Source 3.30 or later installed. +For this tutorial, you need access to a cluster with Calico Open Source 3.33 or later installed. We'll use `kind` to create this environment, but you can use any other supported Kubernetes distribution with a compatible version of $[prodname]. If you've already got a suitable environment, start the tutorial at [Step 2: Create the ingress gateway](#step-2-create-an-ingress-gateway). @@ -176,12 +176,19 @@ Once that is set up, you can create supported Gateway API resources, such as the "parametersRef": { "group": "gateway.envoyproxy.io", "kind": "EnvoyProxy", - "name": "envoy-proxy-config", - "namespace": "tigera-gateway" + "name": "tigera-gateway-class", + "namespace": "calico-system" } } ``` -1. Create a `Gateway` resource that is linked to the `tigera-gateway-class`. +1. Create a namespace to hold your gateway and application: + + ```bash + kubectl create namespace ingress-gateway-demo + ``` + +1. Create a `Gateway` resource in that namespace, linked to the `tigera-gateway-class`. + Its proxy runs in the same namespace as the `Gateway`. ```bash kubectl apply -f - <