Accessing Dashboard

How to access Kubernetes Dashboard after installation

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

Overview

Once Kubernetes Dashboard is installed in your cluster, there are several methods to access it. This guide covers the most common approaches, from simple port forwarding to production-ready ingress configurations.

The methods described here assume you used the default Helm-based installation. If you modified the default configuration, you may need to adjust the service names and namespaces accordingly.

Access Methods

kubectl port-forward (Recommended for Development)

The simplest and most secure method for accessing Dashboard locally is using kubectl port-forward. This method works without any ingress configuration and is ideal for development and testing.

1. Start Port Forwarding

   Forward the Kong proxy service to your local machine:

   kubectl -n kubernetes-dashboard port-forward svc/kubernetes-dashboard-kong-proxy 8443:443
   

   The command will block your terminal. Keep it running while you access Dashboard.

2. Access Dashboard

   Open your browser and navigate to:

   https://localhost:8443
   

   Your browser will show a certificate warning because Dashboard uses a self-signed certificate by default. This is expected for local development. Click “Advanced” and proceed to the site.

3. Login

   You’ll be presented with the Dashboard login screen. You’ll need a bearer token to authenticate.

   See the Creating Sample User section below for instructions on generating a token.

Advantages:

• No additional configuration required
• Secure (traffic stays within kubectl tunnel)
• Works on any platform

Disadvantages:

• Only accessible from the machine running the command
• Requires keeping terminal open
• Not suitable for production

kubectl proxy

Another local access method using the Kubernetes API proxy:

1. Start kubectl proxy

   kubectl proxy --port=8001
   
2. Access Dashboard

   Navigate to the following URL:

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

   Note the trailing slash at the end of the URL - it’s required!

Important Limitation: When using kubectl proxy, the Authorization header will not work properly because the API server drops additional headers. Use bearer token authentication on the login screen instead.

Ingress (Recommended for Production)

For production deployments, use an Ingress resource to expose Dashboard with proper TLS and authentication.

1. Prerequisites

   Ensure you have:

   • An Ingress controller installed (e.g., nginx-ingress, Traefik)
   • cert-manager for TLS certificate management (optional but recommended)
   • A domain name pointing to your cluster
2. Enable Ingress in Helm

   Update your Dashboard installation with Ingress enabled:

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

   Replace dashboard.example.com with your actual domain.

3. Configure TLS with cert-manager

   If using cert-manager, configure the issuer:

   helm upgrade kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
     --namespace kubernetes-dashboard \
     --set app.ingress.enabled=true \
     --set app.ingress.hosts[0]=dashboard.example.com \
     --set app.ingress.ingressClassName=nginx \
     --set app.ingress.issuer.name=letsencrypt-prod \
     --set app.ingress.issuer.scope=cluster
   
4. Verify Ingress

   Check that the Ingress resource was created:

   kubectl get ingress -n kubernetes-dashboard
   
5. Access Dashboard

   Navigate to your configured domain:

   https://dashboard.example.com
   

Default Ingress Annotations:

When using the default configuration, Dashboard applies these annotations:

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/ssl-passthrough: "true"
nginx.ingress.kubernetes.io/ssl-redirect: "true"

These annotations ensure proper HTTPS communication between the ingress controller and Dashboard’s Kong gateway.

NodePort Service

Expose Dashboard directly on a node port (not recommended for production):

1. Update Service Type

   Modify the Kong proxy service to use NodePort:

   kubectl patch svc kubernetes-dashboard-kong-proxy -n kubernetes-dashboard \
     -p '{"spec":{"type":"NodePort"}}'
   
2. Get NodePort

   Find the assigned port:

   kubectl get svc kubernetes-dashboard-kong-proxy -n kubernetes-dashboard
   

   Look for the port mapping in the output (e.g., 443:30001/TCP).

3. Access Dashboard

   Access Dashboard using any node’s IP address:

   https://<node-ip>:<node-port>
   

NodePort exposes Dashboard directly on your cluster nodes. This is generally not recommended for production due to security concerns. Use Ingress instead.

LoadBalancer Service

For cloud environments, use a LoadBalancer service:

1. Update Service Type

   kubectl patch svc kubernetes-dashboard-kong-proxy -n kubernetes-dashboard \
     -p '{"spec":{"type":"LoadBalancer"}}'
   
2. Get External IP

   Wait for the external IP to be assigned:

   kubectl get svc kubernetes-dashboard-kong-proxy -n kubernetes-dashboard --watch
   

   This may take several minutes depending on your cloud provider.

3. Access Dashboard

   Once the EXTERNAL-IP is assigned:

   https://<external-ip>
   

LoadBalancer services typically incur additional costs from your cloud provider and expose Dashboard to the internet. Ensure you have proper authentication and network policies in place.

Authentication

Creating a Sample User

To access Dashboard, you need a bearer token. Here’s how to create a sample admin user:

1. Create Service Account

   Create a file named dashboard-adminuser.yaml:

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: admin-user
     namespace: kubernetes-dashboard
   

   Apply it:

   kubectl apply -f dashboard-adminuser.yaml
   
2. Create ClusterRoleBinding

   Create a file named dashboard-clusterrolebinding.yaml:

   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 it:

   kubectl apply -f dashboard-clusterrolebinding.yaml
   

   This grants full cluster-admin privileges. For production, create more restrictive roles with only the necessary permissions.

3. Generate Token

   Create a temporary token:

   kubectl -n kubernetes-dashboard create token admin-user
   

   This will output a JWT token. Copy it for use in the Dashboard login screen.

   For a long-lived token, create a Secret:

   apiVersion: v1
   kind: Secret
   metadata:
     name: admin-user
     namespace: kubernetes-dashboard
     annotations:
       kubernetes.io/service-account.name: "admin-user"
   type: kubernetes.io/service-account-token
   

   Then retrieve it:

   kubectl get secret admin-user -n kubernetes-dashboard -o jsonpath="{.data.token}" | base64 -d
   
4. Login to Dashboard

   1. Navigate to Dashboard using one of the access methods above
   2. Select “Token” authentication method
   3. Paste the token you generated
   4. Click “Sign in”

Clean Up Sample User

When you’re done testing, remove the admin user:

kubectl -n kubernetes-dashboard delete serviceaccount admin-user
kubectl -n kubernetes-dashboard delete clusterrolebinding admin-user
kubectl -n kubernetes-dashboard delete secret admin-user  # if you created the long-lived token

Security Considerations

Always use HTTPS

Dashboard should only be accessed over HTTPS. The Kong gateway uses HTTPS by default. Never disable TLS in production.

Network Policies

Consider enabling network policies to restrict access:

helm upgrade kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --namespace kubernetes-dashboard \
  --set app.security.networkPolicy.enabled=true

Token Security

• Token login only works over HTTPS
• Never commit tokens to version control
• Use short-lived tokens when possible
• Rotate tokens regularly
• Grant minimal required permissions

Pod Security

Dashboard runs with restrictive security contexts by default:

• Non-root user (UID 1001, GID 2001)
• Read-only root filesystem
• No privilege escalation
• Dropped all capabilities

Troubleshooting

Certificate warnings in browser

Cause: Dashboard uses self-signed certificates by default.

Solutions:

• For development: Accept the certificate warning
• For production: Use cert-manager with a trusted CA like Let’s Encrypt

Cannot connect - connection refused

Troubleshooting steps:

1. Verify pods are running:

   kubectl get pods -n kubernetes-dashboard
   

2. Check service exists:

   kubectl get svc kubernetes-dashboard-kong-proxy -n kubernetes-dashboard
   

3. Check port-forward command is correct:

   kubectl -n kubernetes-dashboard port-forward svc/kubernetes-dashboard-kong-proxy 8443:443
   

Login fails with 'Invalid token'

Possible causes:

• Token has expired (if using temporary token)
• Accessing over HTTP instead of HTTPS
• Token was not copied correctly
• Service account was deleted

Solution: Generate a new token and ensure you’re accessing over HTTPS.

403 Forbidden errors after login

Cause: The service account doesn’t have sufficient permissions.

Solution: Review and update the RBAC permissions for your service account. See Kubernetes RBAC documentation for details.

404 errors loading Dashboard resources

Possible causes:

• Incorrect proxy URL (missing trailing slash)
• Cluster configuration issues
• Known issue with Kubernetes 1.7.x

Solutions:

• Ensure URL ends with / when using kubectl proxy
• Try accessing via port-forward instead
• Check Dashboard logs: kubectl logs -n kubernetes-dashboard -l app.kubernetes.io/name=web

Advanced Configuration

Custom TLS Certificates

Provide your own TLS certificates:

kubectl create secret tls kubernetes-dashboard-certs \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key \
  -n kubernetes-dashboard

helm upgrade kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --namespace kubernetes-dashboard \
  --set app.ingress.tls.secretName=kubernetes-dashboard-certs

Reverse Proxy with Authentication

For advanced setups, you can use a reverse proxy (e.g., OAuth2 Proxy) in front of Dashboard to handle authentication:

1. Deploy OAuth2 Proxy or similar
2. Configure it to pass Authorization: Bearer <token> header
3. Ensure the Kubernetes API server is configured to accept these tokens
4. Point users to the proxy URL instead of directly to Dashboard

Authorization headers do NOT work when accessing Dashboard through kubectl proxy because the API server drops additional headers.

Next Steps

Access Control

Learn about Kubernetes RBAC and how to configure granular permissions for Dashboard users

View Metrics

Enable metrics-server to view resource usage graphs in Dashboard

Additional Resources

• Kubernetes Authentication Documentation
• Kubernetes Authorization Documentation
• Dashboard FAQ
• Ingress NGINX Documentation