Dashboard

The Nantian Gateway dashboard is a Next.js admin UI deployed alongside the control plane. It provides a web interface for inspecting gateway state, viewing route configurations, and monitoring data plane connections without needing kubectl or the admin API directly.

The dashboard connects to the control plane’s Admin API for observability and resource management. Operators can inspect gateway state, view route configurations, monitor data plane connections, and manage Gateway API and custom resources through the UI — all without needing kubectl directly.

Enabling the Dashboard

The dashboard is enabled by default in the Helm chart. These values control its deployment:

dashboard:
  enabled: true
  replicas: 1
  authSecret: ""
  authExistingSecret: ""
  serviceAccount:
    name: ""
    annotations: {}
  image:
    repository: nantian/dashboard
    tag: ""
    pullPolicy: IfNotPresent
  resources: {}
  nodeSelector: {}
  tolerations: []
  affinity: {}
  podAnnotations: {}
  networkPolicy:
    enabled: false
  ingress:
    enabled: false
    className: ""
    hosts: []
    tls: []

Core Values

Value	Default	Description
`dashboard.enabled`	`true`	Toggles the dashboard Deployment and Service.
`dashboard.replicas`	`1`	Number of dashboard pod replicas. More than one is rarely useful since the dashboard is stateless and the admin API it queries runs on the control plane.
`dashboard.serviceAccount.name`	`""`	Custom service account name. When empty, the chart generates one from the release name.

Accessing the Dashboard

Once deployed, the dashboard Service listens on port 3000 as nantian-gw-dashboard in the release namespace.

Port-forward for local access:

kubectl port-forward -n nantian-gw svc/nantian-gw-dashboard 3000:3000

Then open http://localhost:3000 in your browser.

Ingress for cluster access:

To expose the dashboard through an Ingress, set dashboard.ingress.enabled: true and configure hosts and tls:

dashboard:
  ingress:
    enabled: true
    className: nginx
    hosts:
      - dashboard.nantian.example.com
    tls:
      - hosts:
          - dashboard.nantian.example.com
        secretName: dashboard-tls

The dashboard doesn’t serve HTTPS on its own: terminate TLS at the Ingress layer.

Authentication

The dashboard login page accepts a bearer token. Where that token comes from depends on the control plane’s authentication mode.

Static token mode (default)

When controlplane.config.adminAuth.authMode is "static" (the default), the control plane accepts a single pre-configured bearer token. Set it via adminAuth.bearerToken in the control plane configuration. The dashboard passes this token through to the control plane’s Admin API.

Kubernetes token mode (recommended for production)

When controlplane.config.adminAuth.authMode is "kubernetes", the control plane validates tokens against the Kubernetes TokenReview API. This lets operators authenticate using Kubernetes ServiceAccount tokens.

Create a ServiceAccount and bind it to the control plane’s ClusterRole:

kubectl create sa dashboard-operator -n nantian-gw
kubectl create clusterrolebinding dashboard-operator \
  --clusterrole=nantian-gw-controlplane \
  --serviceaccount=nantian-gw:dashboard-operator

Generate a token and enter it on the login page:

kubectl create token dashboard-operator -n nantian-gw

The token is validated by the control plane via the Kubernetes TokenReview API. The control plane ServiceAccount needs permission to create tokenreviews (granted automatically by the Helm chart).

Tokens have a limited lifetime (default 1 hour for kubectl create token). Create a new token when the old one expires.

Retrieving the auto-generated token (when no token is configured)

If you did not set authSecret, authExistingSecret, or a static bearerToken, and authMode is "static" with no token configured, the dashboard runs in read-only mode without authentication. This is fine for local development and port-forward access behind a firewall.

If you set authSecret or authExistingSecret in the dashboard Helm values, the dashboard uses that for session authentication. The Helm chart also auto-generates a random secret named <release>-dashboard-auth:

kubectl get secret -n nantian-gw nantian-gw-dashboard-auth \
  -o jsonpath='{.data.auth-secret}' | base64 -d
echo

Data plane access

The dashboard authenticates against the control plane admin API using the bearer token you supply at login. The data plane admin API, however, is secured with a separate bearer token (see Dataplane configuration → adminAuth).

Because the dashboard’s server-side proxy (BFF) calls the data plane admin on your behalf — for /v1/summary and diagnostics — it needs that data plane token. If it is missing, data plane diagnostics are limited and the dashboard shows:

Traffic and dataplane diagnostics are limited because the current dashboard session cannot access dataplane /v1/summary.

The Helm chart handles this automatically when it manages the data plane admin token: the dashboard Deployment receives a DATAPLANE_BEARER_TOKEN environment variable sourced from the data plane admin auth Secret (<release>-dataplane-admin-auth, key token). No extra configuration is needed in this case.

When the data plane admin uses an inline token (dataplane.config.adminAuth.bearerToken) instead of the chart-managed Secret, set DATAPLANE_BEARER_TOKEN explicitly — either through a custom Secret mounted into the dashboard, or by pointing the data plane admin auth at a Secret the dashboard can also reference.

Env var	Source	Purpose
`DATAPLANE_BEARER_TOKEN`	data plane admin auth Secret	Authenticates the dashboard BFF proxy to the data plane admin API.
`CONTROLPLANE_ADMIN_URL`	chart-computed in-cluster URL	Control plane admin API base URL.
`DATAPLANE_ADMIN_URL`	chart-computed in-cluster URL	Data plane admin API base URL.

Dependencies

The dashboard depends on the control plane’s Admin API being reachable. The Admin API is served by the control plane Deployment on port 18081 (Service: nantian-gw-controlplane-admin). If the control plane pod isn’t running or the admin API isn’t healthy, the dashboard will show connection errors.

See the Admin API reference for the endpoints the dashboard queries.

NetworkPolicy

When dashboard.networkPolicy.enabled is true, the chart creates a Kubernetes NetworkPolicy that allows the dashboard pod to reach the control plane admin API. Customize this if your cluster has additional network restrictions.

Using the Dashboard

After logging in, the dashboard presents a sidebar navigation organized into three plugin groups. Which items appear depends on the capabilities your control plane exposes (see Experimental Features).

Overview Page

The default landing page shows a high-level summary of your gateway fleet:

KPI cards: total gateways, HTTP/gRPC/stream routes, connected data plane nodes, and request rate
Listener health donut: distribution of healthy, degraded, and unhealthy listeners across all gateways
Node status donut: connected vs. disconnected data plane nodes
Traffic card: current request volume from the data plane
Snapshot info: current snapshot version, generation, and age

Gateways

The Gateways page lists all managed Gateway API Gateway resources.

List view: KPI cards (total, accepted, not accepted), search bar, batch select/delete
Create: form-based gateway creation (name, namespace, listener configuration)
Detail view: tabs for listeners, routes, backend policies, and status conditions
Edit: modify existing gateway configuration

Routes

The Routes page provides a unified view of all route kinds:

Filterable list: filter by kind (HTTPRoute, GRPCRoute, TCPRoute, TLSRoute, UDPRoute), namespace, and status
Search: free-text search across route names
Create: dedicated forms for each route kind with YAML editing support
Detail view: route spec, rules, backend refs, and status conditions

Nodes

The Nodes page shows all connected data plane instances:

Connection status: connected, disconnected, or draining
Readiness: ready vs. not-ready
ACK state: last acknowledged snapshot version for each node
Drift detection: nodes whose snapshot version differs from the current control plane snapshot

Diagnostics

Aggregates warnings and errors from the control plane, infrastructure layer, and data plane into a single view. Useful for troubleshooting configuration issues, missing CRDs, or connectivity problems.

Observability

Prometheus-powered metrics dashboard with time-series charts:

P95/P99 latency: histogram of request latency
RPS: requests per second over time
Success rate: percentage of successful (non-5xx) responses
Time range selector: presets from 5m to 7d

Requires a Prometheus instance configured in Settings.

Circuit Breaker

Displays backends with active circuit breaker state, enriched with Prometheus metrics:

Inflight request count
Rejected request count
Health status

Backend TLS Policies

Manage BackendTLSPolicy resources:

List: all BackendTLSPolicies with target backend references
Create: form-based or YAML-based creation
Detail: CA certificate, SAN validation, and status conditions

Backend LB Policies

Manage BackendLBPolicy resources for session persistence and load balancing configuration:

List: all BackendLBPolicy resources
Create: configure session persistence mode, TTL, and load balancing algorithm
Detail: policy spec and status

Reference Grants

Manage cross-namespace ReferenceGrant resources:

List: all ReferenceGrants
Create: specify from/to namespace and resource type
Detail: grant spec and status

AI Gateway Features

When the AI gateway is enabled, the sidebar shows an AI section with:

AI Overview: total services, tokens consumed, requests, latency, and active model distribution
AI Services: manage AI service configurations (model, provider, rate limits)
AI Token Policies: rate limit policies for AI tokens
AI Cost: cost tracking by model, time range, and trend view
AI Traces: request traces with model, duration, token count, and status
AI Usage: token usage charts and trends

Wasm Plugins

Manage Wasm plugins deployed to the data plane:

List: all registered Wasm plugins
Create: upload or configure Wasm plugin (name, file, configuration)
Detail: plugin spec, execution metrics, and status

Settings

Configure dashboard integrations:

Prometheus: set the Prometheus URL for observability charts
LLM: configure LLM endpoint for the AI Chatbot feature
Export/Import: download or upload the full gateway configuration as YAML
Alerts: configure alert rules and notification channels

AI Chatbot

A streaming chat interface that lets you inspect gateway state and diagnose issues using natural language. The chatbot queries the control plane’s RAG (Retrieval-Augmented Generation) system, which indexes gateway resources, node status, and snapshot data.

The chatbot is available from the sidebar when the AI features are enabled.

Global Search

The search bar at the top of the sidebar performs a cross-resource search across:

Gateways (by name, namespace)
Routes (by name, kind, hostname)
Reference Grants, Backend TLS Policies, Backend LB Policies
Data plane nodes (by ID, address)
Diagnostics entries

Results are scored by relevance and grouped by resource type.

Common Tasks

Task	Steps
View all routes for a gateway	Navigate to the gateway detail page and open the Routes tab
Check node drift	Go to Nodes and look for version mismatches
Create an HTTPRoute	Navigate to Routes → Create → HTTPRoute
Delete multiple gateways	Use the batch select checkboxes on the Gateways page
Export configuration	Go to Settings → Export
Monitor AI costs	Navigate to AI → Cost
Troubleshoot data plane connectivity	Check Diagnostics and Nodes pages

Environment Variables

Variable	Required	Default	Description
`AUTH_SECRET`	Yes	—	NextAuth encryption key. Generate with `openssl rand -base64 32`.
`CONTROLPLANE_ADMIN_URL`	No	`http://localhost:18081`	Control plane admin API base URL.
`DATAPLANE_ADMIN_URL`	No	`http://localhost:19080`	Data plane admin API base URL.
`DATAPLANE_BEARER_TOKEN`	No	—	Bearer token for data plane admin API access.
`DASHBOARD_ENABLE_HSTS`	No	`false`	Enable HSTS response header.
`AUTH_TRUST_HOST`	No	—	Required when running behind a reverse proxy.