Dashboard Reference

The Kubetail Dashboard is a Go-based HTTP server that hosts the Dashboard web UI and provides the backend API that the web UI uses to interact with your Kubernetes clusters. The server executable is compiled from the source code located in the Kubetail repo at modules/dashboard and is typically deployed using the kubetail-dashboard docker image (see below). It’s possible to run kubetail-dashboard as a standalone container but we recommend deploying it with the official Kubetail helm chart.

Docker image

The kubetail-dashboard docker image is published to Docker Hub and the GitHub Container Registry on every release:

Registry	Image
Docker Hub	kubetail/kubetail-dashboard
GHCR	ghcr.io/kubetail-org/kubetail-dashboard

Two variants are available:

Tag suffix	Base image	Description
(none)	scratch	Minimal image, smallest footprint
-alpine	alpine	Includes a shell and standard utilities

Entrypoint

The default container entrypoint is /dashboard/dashboard:

dashboard [flags]

Flags

Flag	Short	Default	Description
--config	-c		Path to configuration file (e.g. /etc/kubetail/dashboard.yaml)
--addr	-a	:8080	Host address to bind to
--gin-mode		release	Gin framework mode (release, debug)

Configuration

The dashboard can be configured using a YAML, JSON, or TOML config file. Pass the path to the file with -c / --config. Environment variables can be referenced in the config file using ${VARIABLE_NAME} syntax.

dashboard --config /etc/kubetail/dashboard.yaml

YAML

## Kubetail Dashboard Configuration File
#
# This file defines the behavior for the kubetail dashboard server,
# which serves the web UI and provides the backend API for the dashboard.
#

## allowed-namespaces ##
#
# List of namespaces the dashboard is allowed to access.
# If empty, all namespaces are accessible.
#
# Default value: []
#
allowed-namespaces: []

## allowed-origins ##
#
# Additional origins (in addition to same-origin) accepted on WebSocket
# upgrade requests. Each entry must be a fully-qualified origin —
# scheme://host[:port] with no path. Comparison is case-insensitive on
# host and normalizes default ports (so https://example.com matches
# https://example.com:443).
#
# Use this when running the dashboard behind a reverse proxy that
# rewrites Host or terminates TLS without preserving scheme — direct
# same-origin matching against r.Host/r.TLS would otherwise reject
# legitimate browser requests. List the public-facing origin(s) the
# dashboard is served at.
#
# Examples:
#   - https://kubetail.example.com
#   - https://kubetail.example.com:8443
#
# Default value: []
#
allowed-origins: []

## kubeconfig ##
#
# Path to the kubeconfig file to use for Kubernetes API requests.
# If empty, the default path (~/.kube/config) or KUBECONFIG env var is used.
#
# Default value: ""
#
kubeconfig: ""

## addr ##
#
# The network address and port the HTTP server should bind to.
#
# Default value: :8080
#
addr: ":8080"

## auth-mode ##
#
# The authentication mode for the dashboard.
# Valid values: auto, token
#
# Default value: auto
#
auth-mode: auto

## base-path ##
#
# The base URL path for all dashboard endpoints.
#
# Default value: /
#
base-path: /

## cluster-api-endpoint ##
#
# The URL of the Cluster API server.
# If empty, the Cluster API integration is disabled.
#
# Default value: ""
#
cluster-api-endpoint: ""

## environment ##
#
# The environment the dashboard is running in.
# Valid values: desktop, cluster
#
# Default value: cluster
#
environment: cluster

## gin-mode ##
#
# The Gin framework mode.
# Valid values: debug, release
#
# Default value: release
#
gin-mode: release

## logging ##
#
# Configuration for the dashboard server's logging output
#
logging:

  ## enabled ##
  #
  # Whether logging is enabled for the server.
  #
  # Default value: true
  #
  enabled: true

  ## level ##
  #
  # The minimum log level to output.
  # Valid values: debug, info, warn, error, disabled
  #
  # Default value: info
  #
  level: info

  ## format ##
  #
  # The format of log output.
  # Valid values: json, pretty
  #
  # Default value: json
  #
  format: json

  ## access-log ##
  #
  # Configuration for HTTP access logging
  #
  access-log:

    ## enabled ##
    #
    # Whether access logging is enabled.
    #
    # Default value: true
    #
    enabled: true

    ## hide-health-checks ##
    #
    # Whether to omit health check requests (/healthz) from the access log.
    #
    # Default value: false
    #
    hide-health-checks: false

## session ##
#
# Session management settings
#
session:

  ## key-pairs ##
  #
  # One or more signing/encryption key pairs for session cookies. The first
  # pair is used for new cookies; additional pairs are accepted for reading
  # only, enabling zero-downtime key rotation.
  #
  # Each pair has:
  #   signing-key    (required) — hex-encoded HMAC signing key; 32 or 64 raw bytes recommended
  #   encryption-key (optional) — hex-encoded AES encryption key; 16, 24, or 32 raw bytes
  #
  # When empty and a local-storage-dir is configured, a random pair is
  # generated and persisted to disk on first startup.
  #
  key-pairs: []

  ## cookie ##
  #
  # Session cookie configuration
  #
  cookie:

    ## name ##
    #
    # The name of the session cookie.
    #
    # Default value: kubetail_dashboard_session
    #
    name: kubetail_dashboard_session

    ## path ##
    #
    # The URL path for which the cookie is valid.
    #
    # Default value: /
    #
    path: /

    ## domain ##
    #
    # The domain for which the cookie is valid.
    # If empty, the cookie is valid for the current domain only.
    #
    # Default value: ""
    #
    domain: ""

    ## max-age ##
    #
    # The maximum age of the cookie in seconds.
    #
    # Default value: 2592000 (30 days)
    #
    max-age: 2592000

    ## secure ##
    #
    # Whether the cookie should only be sent over HTTPS.
    #
    # Default value: false
    #
    secure: false

    ## http-only ##
    #
    # Whether the cookie is inaccessible to JavaScript.
    #
    # Default value: true
    #
    http-only: true

    ## same-site ##
    #
    # The SameSite attribute for the cookie.
    # Valid values: strict, lax, none
    #
    # Default value: lax
    #
    same-site: lax

## tls ##
#
# TLS configuration for the HTTP server
#
tls:

  ## enabled ##
  #
  # Whether TLS is enabled.
  #
  # Default value: false
  #
  enabled: false

  ## cert-file ##
  #
  # Path to the TLS certificate file.
  #
  # Default value: ""
  #
  cert-file: ""

  ## key-file ##
  #
  # Path to the TLS private key file.
  #
  # Default value: ""
  #
  key-file: ""

## ui ##
#
# UI-specific configuration options
#
ui:

  ## cluster-api-enabled ##
  #
  # Whether the Cluster API integration is enabled in the UI.
  #
  # Default value: true
  #
  cluster-api-enabled: true