tigera · ctauchen · Jul 22, 2026
@@ -47,6 +47,24 @@ 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.
+
+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.

@@ -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,69 @@ 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: <gateway-name>
+     namespace: <gateway-namespace>
+   // highlight-end
    spec:
    // highlight-next-line
      gatewayClassName: tigera-gateway-class
      ...
    ```
-   Replace `<gateway-name>` with a name for your gateway.
+   Replace `<gateway-name>` with a name for your gateway, and `<gateway-namespace>` 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 <gateway-namespace>
+   ```
+
+1. If the `Gateway` namespace uses a [global default deny policy](../../network-policy/beginners/kubernetes-default-deny.mdx), apply a network policy 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: <gateway-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 `<gateway-namespace>` with the namespace where you created the `Gateway`.
+   This policy also covers the Web Application Firewall and Layer 7 log collector sidecars, which need DNS and the Kubernetes API server.
+   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'
@@ -92,6 +135,17 @@ You need to do the following:
     ```
     Replace `<gateway-name>` with the name of your `Gateway` resource.
 
+## Deploy gateways in multiple namespaces
+
+You can repeat these steps in any namespace.
+Each `Gateway` you create gets its own proxy, `Service`, and load balancer in its own namespace.
+
+Deploy a gateway per namespace when you want each team or application to own and secure its own gateway — with its own network policy and RBAC — without sharing a namespace with others.
+To route to backends in another namespace, use a `ReferenceGrant`.
+Because each gateway uses its own load balancer, plan for one external address per gateway.
+
+To apply Web Application Firewall policy across gateways in different namespaces, see [Multi-tenant WAF setup](../../threat/gateway-waf/multi-tenant-setup.mdx).
+
 ## Additional resources
 
 * [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/)

@@ -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 > <custom-envoy-configuration>.yaml
+   kubectl get configmap envoy-gateway-config -n calico-system -o yaml > <custom-envoy-configuration>.yaml
    ```
    Replace `<custom-envoy-configuration>` 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

@@ -0,0 +1,36 @@
+---
+description: Upgrade an existing Calico Ingress Gateway to the namespaced deployment model, where each gateway's proxy runs in the gateway's own namespace.
+title: Upgrade to namespaced gateways
+---
+
+# Upgrade to namespaced gateways
+
+In earlier releases, Calico Ingress Gateway ran every gateway proxy in a single shared `tigera-gateway` namespace.
+Starting in this release, the gateway controller runs in `calico-system`, and each gateway's proxy runs in the same namespace as its `Gateway` resource.
+This is a breaking change for existing gateways.
+
+## What changes when you upgrade
+
+- Your `Gateway` resources keep working. You do not edit them.
+- Each gateway's proxy, `Service`, and load balancer move from `tigera-gateway` to the namespace of the `Gateway` resource. Expect a short interruption to ingress traffic while the proxy restarts and its load balancer is reassigned.
+- The operator removes the resources it owned in `tigera-gateway`. The `tigera-gateway` namespace itself is left in place, in case you put your own resources there.
+- In each namespace that holds a `Gateway`, the operator automatically creates the resources the gateway needs: a `tigera-ca-bundle` ConfigMap, a copy of the `tigera-pull-secret`, and a `waf-http-filter` ServiceAccount and RoleBinding for the Web Application Firewall and Layer 7 log collector sidecars. You do not create these yourself.
+
+## After you upgrade
+
+1. Move any network policy that allowed the proxy in `tigera-gateway` to the namespace of the `Gateway`. For a starting policy, see the default-deny step in [Create an ingress gateway](create-ingress-gateway.mdx).
+1. Update monitoring, RBAC, and external DNS that referenced the old `tigera-gateway` namespace or the old load balancer address.
+1. If you used merged gateways (`mergeGateways: true`) to share one load balancer, note that merged gateways are no longer supported. Each gateway now gets its own load balancer. Plan for one external address, DNS record, and certificate per gateway.
+
+There is no per-gateway migration command. The move happens automatically when you upgrade.
+
+## Downgrade
+
+Downgrading to a release that uses the shared `tigera-gateway` namespace is not an automated path.
+If you must downgrade, roll back the operator and then manually remove the Calico Ingress Gateway resources from the `calico-system` namespace.
+
+## Additional resources
+
+* [Create an ingress gateway](create-ingress-gateway.mdx)
+* [Customizing your ingress gateway](customize-ingress-gateway.mdx)
+* [Multi-tenant WAF setup](../../threat/gateway-waf/multi-tenant-setup.mdx)
@@ -19,6 +19,20 @@ This version of Calico Enterprise is based on [Calico Open Source $[openSourceVe
 
 ## New features and enhancements
 
+### Calico Ingress Gateway now uses a namespaced deployment model
+
+Calico Ingress Gateway now runs the gateway controller in `calico-system` and runs each gateway's proxy in the same namespace as its `Gateway` resource.
+This lets namespace owners apply their own network policy and RBAC to their gateway proxies.
+
+:::warning[Breaking change]
+
+On upgrade, existing gateway proxies move from the `tigera-gateway` namespace to the namespace of each `Gateway` resource, which briefly interrupts ingress traffic.
+Merged gateways (`mergeGateways: true`) are no longer supported, so each gateway gets its own load balancer.
+Move any network policy, monitoring, RBAC, and external DNS that referenced `tigera-gateway`.
+For steps, see [Upgrade to namespaced gateways](../networking/ingress-gateway/migrate-to-namespaced-gateways.mdx).
+
+:::
+
 ### Deprecated and removed features
 
 ## Technology Preview features

@@ -47,6 +47,22 @@ 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.
+
+The operator also creates a supporting resource 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.
+
+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.

@@ -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/get-started/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 `default`:
 
    ```bash
@@ -60,22 +56,62 @@ 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: <gateway-name>
+     namespace: <gateway-namespace>
+   // highlight-end
    spec:
    // highlight-next-line
      gatewayClassName: tigera-gateway-class
      ...
    ```
-   Replace `<gateway-name>` with a name for your gateway.
+   Replace `<gateway-name>` with a name for your gateway, and `<gateway-namespace>` 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 <gateway-namespace>
+   ```
+
+1. If the `Gateway` namespace uses a [global default deny policy](../../network-policy/get-started/kubernetes-default-deny.mdx), apply a network policy 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: <gateway-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 `<gateway-namespace>` 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'
@@ -92,6 +128,15 @@ You need to do the following:
     ```
     Replace `<gateway-name>` with the name of your `Gateway` resource.
 
+## Deploy gateways in multiple namespaces
+
+You can repeat these steps in any namespace.
+Each `Gateway` you create gets its own proxy, `Service`, and load balancer in its own namespace.
+
+Deploy a gateway per namespace when you want each team or application to own and secure its own gateway — with its own network policy and RBAC — without sharing a namespace with others.
+To route to backends in another namespace, use a `ReferenceGrant`.
+Because each gateway uses its own load balancer, plan for one external address per gateway.
+
 ## Additional resources
 
 * [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/)