How to Setup Kubernetes Dashboard on Docker Desktop – Complete Guide

Setting up the Kubernetes Dashboard on your local Docker Desktop can seem daunting, but it’s actually straightforward once you know the steps. In this guide, I’ll walk you through the entire process, from fixing common issues to accessing your dashboard.

Prerequisites

• Docker Desktop installed on your machine
• Kubernetes enabled in Docker Desktop settings
• kubectl command-line tool installed
• Basic familiarity with terminal/command line

Step 1: Verify Your Kubernetes Cluster Health

Before installing the dashboard, let’s make sure your Kubernetes cluster is healthy and running properly.

kubectl get nodes

You should see output showing your nodes in a “Ready” state. If you see nodes with “Unknown” or “NotReady” status, you’ll need to fix this first.

Troubleshooting: Node Issues

If your control plane node is unreachable or showing as “Unknown”, the quickest fix is to reset your Kubernetes cluster:

1. Open Docker Desktop
2. Click on Settings (gear icon)
3. Navigate to the Kubernetes section
4. Click “Reset Kubernetes Cluster”
5. Wait for the cluster to restart

After the reset, verify your nodes are healthy again with kubectl get nodes.

Step 2: Install the Kubernetes Dashboard

Now that your cluster is healthy, let’s install the dashboard. We’ll use version 2.7.0, which is stable and well-tested.

Create a file named dashboard-install.yaml with the complete dashboard manifest, or apply it directly using kubectl. For simplicity, I’ll show you the kubectl apply method:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

This command will create:

• A dedicated namespace called kubernetes-dashboard
• Service accounts and RBAC permissions
• The dashboard deployment and pods
• Required secrets and config maps
• The metrics scraper for gathering cluster metrics

Verify the Installation

Check that the dashboard pods are running:

kubectl get pods -n kubernetes-dashboard

You should see two pods in “Running” status:

• kubernetes-dashboard-xxxxxxxxx-xxxxx
• dashboard-metrics-scraper-xxxxxxxxx-xxxxx

Step 3: Create an Admin User

The dashboard requires authentication. Let’s create an admin service account with full cluster access.

Create a file named dashboard-admin.yaml:

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: admin-user
  namespace: kubernetes-dashboard
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-user
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: admin-user
  namespace: kubernetes-dashboard

Apply this configuration:

kubectl apply -f dashboard-admin.yaml

Step 4: Start the Kubernetes Proxy

The dashboard runs inside your cluster and isn’t directly accessible from your browser. We need to create a secure tunnel using kubectl proxy.

kubectl proxy

Keep this terminal window open. The proxy will run on port 8001 by default.

Troubleshooting: If you get an error saying “bind: Only one usage of each socket address is normally permitted”, it means the proxy is already running. That’s fine – just proceed to the next step!

Step 5: Generate Access Token

Now we need to generate a token to authenticate with the dashboard. Open a new terminal window (keep the proxy running) and run:

kubectl create token admin-user -n kubernetes-dashboard

This will output a long token string that looks like:

eyJhbGciOiJSUzI1NiIsImtpZCI6Ik5xZ...

Copy this entire token – you’ll need it in the next step.

Step 6: Access the Dashboard

With the proxy running and your token ready, open your browser and navigate to:

http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/

You’ll see the Kubernetes Dashboard login page. Select the “Token” option, paste your token into the text field, and click “Sign In”.

Common Issues and Solutions

Issue: “Internal error (500): Not enough data to create auth info structure”

This error occurs when trying to use the kubeconfig file option. Docker Desktop’s kubeconfig uses certificate-based authentication that isn’t compatible with the dashboard login.

Solution: Always use the Token method instead of the Kubeconfig option when logging into the dashboard.

Issue: Pods Not Starting

If the dashboard pods show as “Pending” or “ImagePullBackOff”:

1. Check your internet connection
2. Verify Docker Desktop has sufficient resources allocated
3. Check pod logs: kubectl logs -n kubernetes-dashboard <pod-name>

Issue: Token Expires

Tokens generated with kubectl create token expire after a certain period (usually 1 hour). When your token expires, simply generate a new one using the same command.

What You Can Do with the Dashboard

Once you’re logged in, the Kubernetes Dashboard provides a powerful web interface where you can:

• View and manage workloads (deployments, pods, services)
• Monitor resource usage and cluster health
• View logs from running containers
• Create and edit Kubernetes resources
• Manage namespaces and RBAC permissions
• Troubleshoot issues visually

Security Considerations

Since we created an admin user with cluster-admin privileges, this user has full access to your cluster. For local development, this is fine. However, for production environments, you should:

• Create service accounts with limited permissions
• Use namespace-specific roles instead of cluster-admin
• Implement proper network policies
• Use more secure authentication methods
• Never expose the dashboard directly to the internet

Conclusion

You now have a fully functional Kubernetes Dashboard running on your local Docker Desktop environment. This is an invaluable tool for learning Kubernetes, debugging issues, and managing your local cluster visually.

Remember to keep the kubectl proxy running whenever you want to access the dashboard, and generate a fresh token when your current one expires.

Happy Kubernetes exploring!