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.