Installation

Detailed guide for installing Kubernetes Dashboard using Helm

Project Archived: This project is now archived and no longer maintained. Please consider using Headlamp for new deployments.

Overview

Kubernetes Dashboard supports only Helm-based installation as of version 7.0.0. Helm provides better control over dependencies and makes it easier to manage the multi-container setup required by Dashboard.

Prerequisites

Before installing Kubernetes Dashboard, ensure you have:

1. Kubernetes Cluster

   A running Kubernetes cluster with version 1.21.0 or higher.

   Verify your cluster version:

   kubectl version --short
   
2. Helm 3

   Helm 3 installed on your local machine.

   Check your Helm version:

   helm version
   

   Helm 2 is no longer supported. If you’re using Helm 2, follow the migration guide.

3. kubectl Access

   kubectl configured with access to your cluster and permissions to create namespaces and resources.

   Verify cluster access:

   kubectl cluster-info
   

Quick Installation

The fastest way to install Kubernetes Dashboard:

# Add kubernetes-dashboard repository
helm repo add kubernetes-dashboard https://kubernetes.github.io/dashboard/

# Deploy a Helm Release named "kubernetes-dashboard" using the kubernetes-dashboard chart
helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard --create-namespace --namespace kubernetes-dashboard

This command will:

• Create the kubernetes-dashboard namespace if it doesn’t exist
• Install or upgrade the Dashboard release
• Use default configuration values

Step-by-Step Installation

1. Add the Helm Repository

   Add the official Kubernetes Dashboard Helm repository:

   helm repo add kubernetes-dashboard https://kubernetes.github.io/dashboard/
   

   Update your local Helm chart repository cache:

   helm repo update
   
2. (Optional) Review Available Versions

   Check available chart versions:

   helm search repo kubernetes-dashboard --versions
   

   The latest stable version is 7.14.0.

3. (Optional) Customize Installation

   Download the default values file to customize your installation:

   helm show values kubernetes-dashboard/kubernetes-dashboard > values.yaml
   

   Edit values.yaml to customize settings like:

   • Resource limits and requests
   • Ingress configuration
   • Security settings
   • Optional dependencies (cert-manager, ingress-nginx, metrics-server)
4. Install the Chart

   Install Dashboard with default settings:

   helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
     --create-namespace \
     --namespace kubernetes-dashboard
   

   Or with custom values:

   helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
     --create-namespace \
     --namespace kubernetes-dashboard \
     -f values.yaml
   

Architecture Components

The Helm chart deploys the following components:

Core Dashboard Components

• Web UI (kubernetesui/dashboard-web:1.7.0): Frontend interface
• API Server (kubernetesui/dashboard-api:1.14.0): Backend API
• Auth Service (kubernetesui/dashboard-auth:1.4.0): Authentication handler
• Kong Gateway (v2.52.0): API gateway in DBless mode

Optional Components

• Metrics Scraper (kubernetesui/dashboard-metrics-scraper:1.2.2): Enabled by default
• Metrics Server (v3.13.0): Disabled by default, enable if not already in cluster
• Cert Manager (v1.19.1): Disabled by default, required for TLS certificates
• Ingress NGINX (v4.13.3): Disabled by default, for ingress support

Configuration Options

Enable Optional Dependencies

If you don’t have these components already installed in your cluster:

Enable Metrics Server

helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --create-namespace \
  --namespace kubernetes-dashboard \
  --set metrics-server.enabled=true

Configure Ingress

Enable and configure Ingress for external access:

helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --create-namespace \
  --namespace kubernetes-dashboard \
  --set app.ingress.enabled=true \
  --set app.ingress.hosts[0]=dashboard.example.com \
  --set app.ingress.ingressClassName=nginx

Resource Limits

Adjust resource limits for production deployments:

helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --create-namespace \
  --namespace kubernetes-dashboard \
  --set api.containers.resources.limits.cpu=500m \
  --set api.containers.resources.limits.memory=512Mi \
  --set web.containers.resources.limits.cpu=500m \
  --set web.containers.resources.limits.memory=512Mi

Verification

Verify the installation was successful:

1. Check Pod Status

   Ensure all pods are running:

   kubectl get pods -n kubernetes-dashboard
   

   Expected output (with default configuration):

   NAME                                                   READY   STATUS    RESTARTS   AGE
   kubernetes-dashboard-api-xxxxx                         1/1     Running   0          2m
   kubernetes-dashboard-auth-xxxxx                        1/1     Running   0          2m
   kubernetes-dashboard-kong-xxxxx                        1/1     Running   0          2m
   kubernetes-dashboard-metrics-scraper-xxxxx             1/1     Running   0          2m
   kubernetes-dashboard-web-xxxxx                         1/1     Running   0          2m
   
2. Check Services

   Verify services are created:

   kubectl get svc -n kubernetes-dashboard
   

   Look for the kubernetes-dashboard-kong-proxy service, which is the main entry point.

3. View Helm Release

   Check the Helm release status:

   helm list -n kubernetes-dashboard
   

Common Installation Issues

Pods stuck in Pending state

Cause: Insufficient cluster resources or persistent volume claims not bound.

Solution:

1. Check pod events: kubectl describe pod <pod-name> -n kubernetes-dashboard
2. Ensure your cluster has enough CPU and memory
3. For PVC issues, verify storage classes are available

CrashLoopBackOff errors

Cause: Configuration issues or incompatible Kubernetes version.

Solution:

1. Check pod logs: kubectl logs <pod-name> -n kubernetes-dashboard
2. Verify Kubernetes version is >= 1.21.0
3. Review custom values for configuration errors

ImagePullBackOff errors

Cause: Cannot pull container images from Docker Hub.

Solution:

1. Check network connectivity to Docker Hub
2. Verify image pull secrets if using a private registry
3. Check for rate limiting issues with Docker Hub

Dependency conflicts

Cause: cert-manager, nginx, or metrics-server already installed with different versions.

Solution: Disable the conflicting dependencies:

helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --create-namespace \
  --namespace kubernetes-dashboard \
  --set nginx.enabled=false \
  --set cert-manager.enabled=false \
  --set metrics-server.enabled=false

Uninstalling Dashboard

To completely remove Kubernetes Dashboard:

# Delete the Helm release
helm delete kubernetes-dashboard --namespace kubernetes-dashboard

# Delete the namespace (optional)
kubectl delete namespace kubernetes-dashboard

This will permanently delete all Dashboard data and configurations. Ensure you have backups if needed.

Upgrading

To upgrade to a newer version:

# Update repository
helm repo update

# Upgrade the release
helm upgrade kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --namespace kubernetes-dashboard

Major version upgrades (e.g., 6.x to 7.x) may require manual intervention. Always check the Helm chart README for upgrade notes.

Next Steps

Access Dashboard

Learn different methods to access your Dashboard installation

Configure Access Control

Set up authentication and authorization for your users

Additional Resources

• Helm Chart on ArtifactHub
• Chart Values Reference
• GitHub Repository