Gateway Lens is a diagnostic tool that watches Kubernetes Gateway API resources in a cluster and presents them as an interactive topology graph in a browser dashboard.
Requires Gateway API v1.6+ CRDs to be installed in the cluster.
There are two ways to run Gateway Lens: downloading and running the binary locally against a kubeconfig, or installing it into the cluster as a Pod.
Prerequisites:
- A kubeconfig pointing at a cluster with Gateway API v1.6+ CRDs installed
Download the latest binary for your platform from the Releases page, then run it:
# Linux/macOS example
tar -xzf gateway-lens_<version>_<os>_<arch>.tar.gz
chmod +x gateway-lens
./gateway-lens
# Open the dashboard
open http://localhost:8080Gateway Lens can run as a Pod inside the cluster it's watching, either via manifests or a Helm chart.
Provided in deploy/manifests.yaml:
kubectl apply -f deploy/manifests.yamlIf your cluster's Gateway API implementation defines its own extension CRDs
(policies, parametersRef/extensionRef targets), use the manifest for that
provider instead so RBAC covers those CRDs too, e.g.
deploy/manifests-nginx-gateway-fabric.yaml
for NGINX Gateway Fabric:
kubectl apply -f deploy/manifests-nginx-gateway-fabric.yamlProvided in charts/gateway-lens:
helm install gateway-lens oci://ghcr.io/nginxinc/charts/gateway-lensIf your cluster's Gateway API implementation defines its own extension CRDs,
set rbac.providers to its name so the chart's ClusterRole covers them
too, e.g. for NGINX Gateway Fabric:
helm install gateway-lens oci://ghcr.io/nginxinc/charts/gateway-lens --set rbac.providers={nginx-gateway-fabric}See charts/gateway-lens/README.md
for the full list of available providers.
Either option deploys Gateway Lens into the default namespace (or the
current namespace, for Helm), exposed via a ClusterIP Service named
gateway-lens on port 80. Port-forward to access the dashboard:
kubectl port-forward svc/gateway-lens 8080:80
open http://localhost:8080To expose it externally instead, create an HTTPRoute attached to a Gateway
in your cluster, pointing at the gateway-lens Service. If you access Gateway Lens
using a different path other than /, then you will need to specify that path in
the --base-path parameter. See the Configuration section for more details.
Gateway Lens is configured via CLI flags, regardless of whether it's run locally or in Kubernetes:
| Flag | Description | Default |
|---|---|---|
--port |
Port for the dashboard HTTP server | 8080 |
--log-level |
Log level (debug, info, error, panic) |
info |
--base-path |
URL path prefix the dashboard is served under, for deployments behind a reverse proxy or Gateway route mounted at a sub-path | (root path) |
--namespaces |
Comma-separated list of namespaces to watch (default: all) | (all) |
When running via the Helm chart, these flags are exposed as the explicit
port, logLevel, namespaces, and basePath values (see
charts/gateway-lens/README.md). For the plain manifests in
deploy/, edit the container's args
directly.
In addition to the interactive dashboard, Gateway Lens exposes the full
topology snapshot as raw JSON at the /api/data endpoint. This is the same
data the dashboard itself renders — nodes, edges, conditions, and annotations
for every watched Gateway API resource — so it's useful for scripting, piping
into jq, or feeding into your own tooling:
curl http://localhost:8080/api/data | jq .A separate /api/issues endpoint returns detected problems (negative
conditions and diagnostics) across all resources:
curl http://localhost:8080/api/issues | jq .See dashboard/README.md for the full
shape of both responses.
Prerequisites:
- Go 1.26+
- Node.js (LTS) and npm
- A kubeconfig pointing at a cluster with Gateway API v1.6+ CRDs installed
# Build the binary (installs dashboard deps, compiles dashboard + Go)
make build
# Run locally (reads kubeconfig from default location)
./bin/gateway-lens
# Open the dashboard
open http://localhost:8080Gateway Lens can also run as a container. Build the image and run it with access to a kubeconfig:
make imageThe Go process uses controller-runtime to watch Gateway API resources and
build a topology snapshot of nodes, edges, conditions, and annotations. A
built-in HTTP server exposes this snapshot at /api/data, detected issues at
/api/issues, and serves the compiled React dashboard at all other paths.
The dashboard frontend is a React + TypeScript application
built with Vite. It receives change notifications via Server-Sent Events and
fetches /api/data on demand, rendering the topology using React Flow with
automatic dagre layout.
To view all available make targets for development, run make help.
For frontend iteration with hot reload:
cd dashboard
VITE_API_BASE_URL=http://localhost:8080 npm run devThis runs the Vite dev server (default port 5173) proxying API calls to a
running gateway-lens process.
Please see the contributing guide for guidelines on how to best contribute to this project.
© F5, Inc. 2026