From 24d86b9eb093a2edccbfd67bd4cc1f6225fbb553 Mon Sep 17 00:00:00 2001 From: vara Date: Fri, 14 Aug 2026 13:14:54 -0700 Subject: [PATCH 1/3] PMREQ-821: Document UI access through Calico Ingress Gateway Enterprise: add a Calico Ingress Gateway tab to the web console access page, alongside ingress, load balancer, port forwarding, and OpenShift routes, plus a row in the options table. Covers the GatewayAPI prerequisite, the hostname and optional gateway namespace and class, and the OIDC requirement that managerDomain match the hostname. Open source: document exposing Whisker the same way, next to the existing port-forwarding instructions, including that Whisker has no authentication of its own and that Calico restricts access to the gateway's proxy pods while the field is set. --- .../operations/cnx/access-the-manager.mdx | 66 +++++++++++++++++++ calico/observability/view-flow-logs.mdx | 57 ++++++++++++++++ 2 files changed, 123 insertions(+) diff --git a/calico-enterprise/operations/cnx/access-the-manager.mdx b/calico-enterprise/operations/cnx/access-the-manager.mdx index 331e8b3a68..9128df1b3d 100644 --- a/calico-enterprise/operations/cnx/access-the-manager.mdx +++ b/calico-enterprise/operations/cnx/access-the-manager.mdx @@ -28,6 +28,7 @@ For security, the $[prodname] web console is not exposed outside of the cluster | Load balancer | Configure your cluster with a service load balancer controller to implement the external load balancer. See [Kubernetes loadbalancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) | Ensure the $[prodname] web console receives a HTTPS (TLS) connection (not unencrypted HTTP). If you require TLS termination at your load balancer, you must use a load balancer that supports transparent HTTP/2 proxying, or re-originate a TLS connection from your load balancer to the $[prodname] web console. If you do not require TLS termination, configure your proxy to “pass thru” the TLS to the $[prodname] web console. | | Port forwarding | Forward traffic from a local port to the Kubernetes API server, where it is proxied to the web console. This approach is **not recommended for production**, but is useful if you do not have a load balancer or ingress infrastructure configured, or you need to get started quickly. | n/a | | OpenShift routes | Use OpenShift routes to expose a service by giving it an externally-reachable hostname (for example, `www.example.com`) . | n/a | +| $[prodname] Ingress Gateway | Expose the web console through $[prodname] Ingress Gateway by setting `spec.ingressGateway` on the `Manager` resource. The operator creates and manages the Gateway, route, and TLS certificate for you. | Requires the `GatewayAPI` resource to be installed. If your cluster uses OIDC, the `Authentication` resource's `managerDomain` must match the hostname you choose. | ## How to @@ -176,6 +177,71 @@ Access the $[prodname] web console in your browser using the URL with clusternam + + +Instead of creating an ingress or load balancer yourself, you can let the operator expose the web console through [$[prodname] Ingress Gateway](../../networking/ingress-gateway/about-calico-ingress-gateway.mdx). The operator creates the Gateway, the route to the web console, and a TLS certificate for the hostname you choose, and it removes them again when you turn the feature off. + +**Before you start** + +- Install $[prodname] Ingress Gateway by applying a `GatewayAPI` resource. See [Create an ingress gateway](../../networking/ingress-gateway/create-ingress-gateway.mdx). +- On bare metal clusters, make sure an IP pool is available for the gateway's load balancer address. + +1. Set a hostname on the `Manager` resource: + + ```bash + kubectl patch manager tigera-secure --type merge \ + -p '{"spec":{"ingressGateway":{"hostname":"manager.example.com"}}}' + ``` + + To place the Gateway in a namespace of your choosing, add `gatewayNamespace`. The operator creates the namespace if it does not exist: + + ```yaml + spec: + ingressGateway: + hostname: manager.example.com + gatewayNamespace: my-gateway-namespace + ``` + + If your `GatewayAPI` resource defines more than one gateway class, also set `gatewayClassName` to choose one. + +1. Wait for the Gateway to be programmed and read its address: + + ```bash + kubectl get gateway -n calico-system calico-manager-gateway + ``` + + ```bash title="Expected output" + NAME CLASS ADDRESS PROGRAMMED + calico-manager-gateway tigera-gateway-class 198.51.100.10 True + ``` + +1. Point your hostname at that address in DNS. + +:::note + +If your cluster uses OIDC, set the `Authentication` resource's `managerDomain` to the same hostname. The two must match, or the operator reports the $[prodname] web console as degraded: + +```bash +kubectl patch authentication tigera-secure --type merge \ + -p '{"spec":{"managerDomain":"https://manager.example.com"}}' +``` + +Your identity provider also needs to accept `https:///dex/callback` and `https:///login/oidc/callback` as redirect URLs. + +::: + +### Log in to the $[prodname] web console + +Access the $[prodname] web console in your browser at the hostname you configured. For example: `https://manager.example.com`. + +To stop using the gateway, remove the field. The operator deletes everything it created for it: + +```bash +kubectl patch manager tigera-secure --type json \ + -p '[{"op":"remove","path":"/spec/ingressGateway"}]' +``` + + ## Additional resources diff --git a/calico/observability/view-flow-logs.mdx b/calico/observability/view-flow-logs.mdx index 5725d6b45c..20c9736a7b 100644 --- a/calico/observability/view-flow-logs.mdx +++ b/calico/observability/view-flow-logs.mdx @@ -122,6 +122,63 @@ Port forwarding the Whisker service is a simple and secure method to view your f You may not see any flows at the beginning. But in a few moments, as the console receives data, you'll begin to see a list of flow logs. +### Expose the web console with Calico Ingress Gateway + +Port forwarding is fine for a quick look, but it only works from a workstation with `kubectl` access. To give a team a stable URL, expose Whisker through [Calico Ingress Gateway](../networking/ingress-gateway/about-calico-ingress-gateway.mdx). The operator creates the Gateway, the route to Whisker, and a TLS certificate for the hostname you choose, and it removes them again when you turn the feature off. + +***Prerequisites*** + +* Calico Ingress Gateway is installed, meaning a `GatewayAPI` resource exists on the cluster. See [Create an ingress gateway](../networking/ingress-gateway/create-ingress-gateway.mdx). +* On bare metal clusters, an IP pool is available for the gateway's load balancer address. + +***Procedure*** + +1. Set a hostname on the `Whisker` resource: + + ```bash + kubectl patch whisker default --type merge \ + -p '{"spec":{"ingressGateway":{"hostname":"whisker.example.com"}}}' + ``` + + To place the Gateway in a namespace of your choosing, add `gatewayNamespace`. The operator creates the namespace if it does not exist: + + ```yaml + spec: + ingressGateway: + hostname: whisker.example.com + gatewayNamespace: my-gateway-namespace + ``` + + If your `GatewayAPI` resource defines more than one gateway class, also set `gatewayClassName` to choose one. + +1. Wait for the Gateway to be programmed and read its address: + + ```bash + kubectl get gateway -n calico-system calico-whisker-gateway + ``` + + ```bash title="Expected output" + NAME CLASS ADDRESS PROGRAMMED + calico-whisker-gateway tigera-gateway-class 198.51.100.10 True + ``` + +1. Point your hostname at that address in DNS, then open `https://whisker.example.com` in your browser. + The gateway serves a self-signed certificate, so your browser shows a security warning the first time. + Accept the warning to continue. + +:::note + +Whisker has no built-in authentication. Anyone who can reach the hostname can read your flow logs, so expose it only on a network you trust, or put your own authentication in front of it. + +::: + +While `spec.ingressGateway` is set, Calico restricts which pods may reach Whisker: only this gateway's proxy pods are allowed in. Removing the field deletes everything the operator created for the gateway: + +```bash +kubectl patch whisker default --type json \ + -p '[{"op":"remove","path":"/spec/ingressGateway"}]' +``` + ## Additional resources * To use flow logs in your own scripts or applications, see [Flow logs API](../observability/flow-logs-api.mdx). From fc5871d7af87b1cb01fa1b41e0102f0c878b1126 Mon Sep 17 00:00:00 2001 From: vara Date: Wed, 2 Sep 2026 23:29:14 -0700 Subject: [PATCH 2/3] PMREQ-821: Use a placeholder for the gateway address in the CIG docs Replace the sample IP in the kubectl get gateway output with so readers do not copy a literal address. --- .../operations/cnx/access-the-manager.mdx | 10 +++++----- calico/observability/view-flow-logs.mdx | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/calico-enterprise/operations/cnx/access-the-manager.mdx b/calico-enterprise/operations/cnx/access-the-manager.mdx index 9128df1b3d..fdf2f56b1d 100644 --- a/calico-enterprise/operations/cnx/access-the-manager.mdx +++ b/calico-enterprise/operations/cnx/access-the-manager.mdx @@ -28,7 +28,7 @@ For security, the $[prodname] web console is not exposed outside of the cluster | Load balancer | Configure your cluster with a service load balancer controller to implement the external load balancer. See [Kubernetes loadbalancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) | Ensure the $[prodname] web console receives a HTTPS (TLS) connection (not unencrypted HTTP). If you require TLS termination at your load balancer, you must use a load balancer that supports transparent HTTP/2 proxying, or re-originate a TLS connection from your load balancer to the $[prodname] web console. If you do not require TLS termination, configure your proxy to “pass thru” the TLS to the $[prodname] web console. | | Port forwarding | Forward traffic from a local port to the Kubernetes API server, where it is proxied to the web console. This approach is **not recommended for production**, but is useful if you do not have a load balancer or ingress infrastructure configured, or you need to get started quickly. | n/a | | OpenShift routes | Use OpenShift routes to expose a service by giving it an externally-reachable hostname (for example, `www.example.com`) . | n/a | -| $[prodname] Ingress Gateway | Expose the web console through $[prodname] Ingress Gateway by setting `spec.ingressGateway` on the `Manager` resource. The operator creates and manages the Gateway, route, and TLS certificate for you. | Requires the `GatewayAPI` resource to be installed. If your cluster uses OIDC, the `Authentication` resource's `managerDomain` must match the hostname you choose. | +| Calico Ingress Gateway | Expose the web console through Calico Ingress Gateway by setting `spec.ingressGateway` on the `Manager` resource. The operator creates and manages the Gateway, route, and TLS certificate for you. | Requires a `GatewayAPI` resource on the cluster. If your cluster uses OIDC, the `Authentication` resource's `managerDomain` must match the hostname you choose. | ## How to @@ -177,13 +177,13 @@ Access the $[prodname] web console in your browser using the URL with clusternam - + -Instead of creating an ingress or load balancer yourself, you can let the operator expose the web console through [$[prodname] Ingress Gateway](../../networking/ingress-gateway/about-calico-ingress-gateway.mdx). The operator creates the Gateway, the route to the web console, and a TLS certificate for the hostname you choose, and it removes them again when you turn the feature off. +Instead of creating an ingress or load balancer yourself, you can let the operator expose the web console through [Calico Ingress Gateway](../../networking/ingress-gateway/about-calico-ingress-gateway.mdx). The operator creates the Gateway, the route to the web console, and a TLS certificate for the hostname you choose, and it removes them again when you turn the feature off. **Before you start** -- Install $[prodname] Ingress Gateway by applying a `GatewayAPI` resource. See [Create an ingress gateway](../../networking/ingress-gateway/create-ingress-gateway.mdx). +- Enable Calico Ingress Gateway by creating a `GatewayAPI` resource. See [Create an ingress gateway](../../networking/ingress-gateway/create-ingress-gateway.mdx). - On bare metal clusters, make sure an IP pool is available for the gateway's load balancer address. 1. Set a hostname on the `Manager` resource: @@ -212,7 +212,7 @@ Instead of creating an ingress or load balancer yourself, you can let the operat ```bash title="Expected output" NAME CLASS ADDRESS PROGRAMMED - calico-manager-gateway tigera-gateway-class 198.51.100.10 True + calico-manager-gateway tigera-gateway-class True ``` 1. Point your hostname at that address in DNS. diff --git a/calico/observability/view-flow-logs.mdx b/calico/observability/view-flow-logs.mdx index 20c9736a7b..19305e9b29 100644 --- a/calico/observability/view-flow-logs.mdx +++ b/calico/observability/view-flow-logs.mdx @@ -128,7 +128,7 @@ Port forwarding is fine for a quick look, but it only works from a workstation w ***Prerequisites*** -* Calico Ingress Gateway is installed, meaning a `GatewayAPI` resource exists on the cluster. See [Create an ingress gateway](../networking/ingress-gateway/create-ingress-gateway.mdx). +* Calico Ingress Gateway is enabled, which means a `GatewayAPI` resource exists on the cluster. See [Create an ingress gateway](../networking/ingress-gateway/create-ingress-gateway.mdx). * On bare metal clusters, an IP pool is available for the gateway's load balancer address. ***Procedure*** @@ -159,7 +159,7 @@ Port forwarding is fine for a quick look, but it only works from a workstation w ```bash title="Expected output" NAME CLASS ADDRESS PROGRAMMED - calico-whisker-gateway tigera-gateway-class 198.51.100.10 True + calico-whisker-gateway tigera-gateway-class True ``` 1. Point your hostname at that address in DNS, then open `https://whisker.example.com` in your browser. From 840cad7d61ba3693506e7a728b0a97ffd5e39cf5 Mon Sep 17 00:00:00 2001 From: vara Date: Wed, 2 Sep 2026 23:51:18 -0700 Subject: [PATCH 3/3] PMREQ-821: Address review on the CIG web console docs Clarify that managerDomain is the hostname with the https:// scheme and its host must match spec.ingressGateway.hostname. Note that the Gateway lives in calico-system unless gatewayNamespace is set. Reword the Whisker flow-table wait, and make the sensitive-data callout a warning. --- calico-enterprise/operations/cnx/access-the-manager.mdx | 6 +++--- calico/observability/view-flow-logs.mdx | 9 ++++----- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/calico-enterprise/operations/cnx/access-the-manager.mdx b/calico-enterprise/operations/cnx/access-the-manager.mdx index fdf2f56b1d..3fc80d469e 100644 --- a/calico-enterprise/operations/cnx/access-the-manager.mdx +++ b/calico-enterprise/operations/cnx/access-the-manager.mdx @@ -28,7 +28,7 @@ For security, the $[prodname] web console is not exposed outside of the cluster | Load balancer | Configure your cluster with a service load balancer controller to implement the external load balancer. See [Kubernetes loadbalancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) | Ensure the $[prodname] web console receives a HTTPS (TLS) connection (not unencrypted HTTP). If you require TLS termination at your load balancer, you must use a load balancer that supports transparent HTTP/2 proxying, or re-originate a TLS connection from your load balancer to the $[prodname] web console. If you do not require TLS termination, configure your proxy to “pass thru” the TLS to the $[prodname] web console. | | Port forwarding | Forward traffic from a local port to the Kubernetes API server, where it is proxied to the web console. This approach is **not recommended for production**, but is useful if you do not have a load balancer or ingress infrastructure configured, or you need to get started quickly. | n/a | | OpenShift routes | Use OpenShift routes to expose a service by giving it an externally-reachable hostname (for example, `www.example.com`) . | n/a | -| Calico Ingress Gateway | Expose the web console through Calico Ingress Gateway by setting `spec.ingressGateway` on the `Manager` resource. The operator creates and manages the Gateway, route, and TLS certificate for you. | Requires a `GatewayAPI` resource on the cluster. If your cluster uses OIDC, the `Authentication` resource's `managerDomain` must match the hostname you choose. | +| Calico Ingress Gateway | Expose the web console through Calico Ingress Gateway by setting `spec.ingressGateway` on the `Manager` resource. The operator creates and manages the Gateway, route, and TLS certificate for you. | Requires a `GatewayAPI` resource on the cluster. If your cluster uses OIDC, set the `Authentication` resource's `managerDomain` to `https://` followed by the hostname you choose (for example, `https://manager.example.com`). | ## How to @@ -204,7 +204,7 @@ Instead of creating an ingress or load balancer yourself, you can let the operat If your `GatewayAPI` resource defines more than one gateway class, also set `gatewayClassName` to choose one. -1. Wait for the Gateway to be programmed and read its address: +1. Wait for the Gateway to be programmed and read its address. The Gateway is in `calico-system` unless you set `gatewayNamespace`: ```bash kubectl get gateway -n calico-system calico-manager-gateway @@ -219,7 +219,7 @@ Instead of creating an ingress or load balancer yourself, you can let the operat :::note -If your cluster uses OIDC, set the `Authentication` resource's `managerDomain` to the same hostname. The two must match, or the operator reports the $[prodname] web console as degraded: +If your cluster uses OIDC, set the `Authentication` resource's `managerDomain` to `https://` plus that hostname (as in the example below). The host must match `spec.ingressGateway.hostname`, or the operator reports the $[prodname] web console as degraded: ```bash kubectl patch authentication tigera-secure --type merge \ diff --git a/calico/observability/view-flow-logs.mdx b/calico/observability/view-flow-logs.mdx index 19305e9b29..258669539d 100644 --- a/calico/observability/view-flow-logs.mdx +++ b/calico/observability/view-flow-logs.mdx @@ -119,8 +119,7 @@ Port forwarding the Whisker service is a simple and secure method to view your f 1. To open Calico Whisker, open your browser and go to `https://localhost:8443`. Calico Whisker uses a self-signed certificate, so your browser shows a security warning the first time. Accept the warning to continue. - You may not see any flows at the beginning. - But in a few moments, as the console receives data, you'll begin to see a list of flow logs. + The flow table populates as Whisker receives data, filling in within a few moments. ### Expose the web console with Calico Ingress Gateway @@ -151,7 +150,7 @@ Port forwarding is fine for a quick look, but it only works from a workstation w If your `GatewayAPI` resource defines more than one gateway class, also set `gatewayClassName` to choose one. -1. Wait for the Gateway to be programmed and read its address: +1. Wait for the Gateway to be programmed and read its address. The Gateway is in `calico-system` unless you set `gatewayNamespace`: ```bash kubectl get gateway -n calico-system calico-whisker-gateway @@ -166,9 +165,9 @@ Port forwarding is fine for a quick look, but it only works from a workstation w The gateway serves a self-signed certificate, so your browser shows a security warning the first time. Accept the warning to continue. -:::note +:::warning -Whisker has no built-in authentication. Anyone who can reach the hostname can read your flow logs, so expose it only on a network you trust, or put your own authentication in front of it. +Calico Whisker and Goldmane contain sensitive network and workload data. Anyone who can reach the gateway hostname can read your flow logs. Do not expose it externally without putting your own authentication in front of it. :::