Add migration guide from Kubernetes Dashboard to Headlamp

[Copilot]

Summary

This PR adds comprehensive migration documentation for users transitioning from Kubernetes Dashboard to Headlamp, with a focus on simplicity, ease of navigation, and actionable guidance.

Related Issue

(Issue linking handled by system)

Changes

• Added docs/installation/migration-from-kubernetes-dashboard.md (366 lines) with:
  • Table of contents for quick navigation to guide sections
  • Quick migration path with 4 structured steps using h4 headings for easy scanning:
    • Install Headlamp using Helm
    • Access Headlamp
    • Authenticate
    • Uninstall Kubernetes Dashboard (Optional)
  • Production deployment warning and parallel running recommendation
  • Streamlined installation comparison: Helm and YAML deployment options
  • Configuration mapping table for Helm values with simplified examples
  • Authentication guide with reorganized sections for better flow:
    • Available authentication guides listed first (Azure Entra ID, EKS, AKS Cluster OAuth, Keycloak, Dex)
    • OIDC authentication configuration (simplified without comparison labels)
    • Service account token authentication (Kubernetes 1.24+ only)
  • "Using Headlamp for Kubernetes Dashboard Users" section with intro and feature equivalency table
  • Advanced scenarios (OIDC reuse, RBAC, parallel running concept, OAuth2 Proxy and user impersonation)
  • OAuth2 Proxy integration section explaining Dashboard's impersonation approach and Headlamp's meUserInfoURL configuration
  • Enhanced plugins section with 5 popular examples:
    • Backstage - Service catalog integration
    • Prometheus - Enhanced metrics visualization
    • Helm App Catalog - Browse and install applications
    • Cert-Manager - Manage TLS certificates
    • Flux - GitOps continuous delivery
  • Resources and Support section with proper heading structure (h2, h3, h4)

Steps to Test

1. View rendered documentation at /docs/installation/migration-from-kubernetes-dashboard.md
2. Verify table of contents links navigate to correct sections
3. Verify all internal links resolve (authentication guides, plugin docs, OAuth2 Proxy tutorial, etc.)
4. Validate markdown renders correctly with code blocks and tables
5. Check that production deployment warning/tip box renders correctly
6. Check that it appears in documentation navigation with sidebar_position: 5
7. Verify proper heading hierarchy (h2 → h3 → h4) throughout the document, including h4 headings for migration steps
8. Confirm authentication section flows logically: guides overview → OIDC → service account token
9. Verify plugin list includes all 5 popular plugins with correct naming
10. Confirm parallel running section mentions concept without redundant install commands

Screenshots (if applicable)

N/A - Documentation only

Notes for the Reviewer

• Frontmatter follows existing conventions (title, sidebar_position)
• All referenced files verified to exist (12 new file references including AKS OAuth2 Proxy tutorial)
• Document uses proper markdown heading hierarchy (h2, h3, h4) throughout - no bold text used as headers
• Migration steps use h4 headings for better document structure and navigation
• 17 code examples covering essential Helm/kubectl commands and OAuth2 Proxy configurations
• Removed duplicate helm commands, prerequisites, and redundant feature comparison sections
• Removed legacy token generation instructions (pre-Kubernetes 1.24)
• Removed outdated bookmarks/URL migration section (Dashboard URL patterns are no longer accurate)
• Removed redundant helm install commands from parallel running section (covered in quickstart)
• Enhanced plugins section with Cert-Manager and Flux, renamed App Catalog to "Helm App Catalog"
• Authentication section simplified by removing redundant comparison labels
• OAuth2 Proxy section documents Dashboard's impersonation pattern and Headlamp's meUserInfoURL integration approach
• All subsections properly structured with semantic headings for better navigation and accessibility
• Section titles clarified throughout (e.g., "Running Kubernetes Dashboard and Headlamp in Parallel")
• Intro sentences added to key sections for better context
• Document streamlined to 366 lines with focused, actionable content

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add migration guide documentation from Kubernetes dashboard</issue_title>
<issue_description>## How to migration from Kubernetes dashboard to Headlamp?

First search for how people install Kubernetes dashboard.

https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/

There's installation section in the README of Kubernetes dashboard GitHub https://github.com/kubernetes/dashboard?tab=readme-ov-file#installation

Helm chart comparison

What is the equivalent helm commands to use Headlamp? Might be good in a migration guide to show a comparison. If they use option in Kubernetes dashboard, how to do that in Headlamp?

Here is information about the Kubernetes helm chart: https://artifacthub.io/packages/helm/k8s-dashboard/kubernetes-dashboard

Use links to the existing headlamp helm chart and docs.

differences between old way of installing kubernetes dashboard and the new way?

Was there an older way that people used to install dashboard? Maybe it's worth mentioning if there was

The simple way of migration - quickstart

For the simplest way of using Kubernetes dashboard, what is the simplest way to migrate?

This should be first. This should be a Quickstart migration.

Other things to consider should be mentioned below in different sections.

If you're doing X with dashboard, then this is how you do it with headlamp.

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add migration guide documentation from Kubernetes dashboard #4

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[illume]

@copilot Can we reduce the helm commands parts? It seems that there's some duplication and complication here.

[Copilot]

@copilot Can we reduce the helm commands parts? It seems that there's some duplication and complication here.

Reduced helm command duplication. Simplified the Installation Method Comparison section and removed redundant examples. The quickstart now has minimal commands, and the comparison section focuses on key differences. Commit: eccd41e

[illume]

@copilot Add a section about about oauth2proxy and impersonation how it was done in Kubernetes dashboard and how odic impersonation can be done with headlamp and oauth2proxy. If you can't find out how it is done(maybe also search GitHub issues) then leave a TODO note about how this section should be completed.

[Copilot]

@copilot Add a section about about oauth2proxy and impersonation how it was done in Kubernetes dashboard and how odic impersonation can be done with headlamp and oauth2proxy. If you can't find out how...

Added a comprehensive section on OAuth2 Proxy and user impersonation under "Advanced Migration Scenarios". The section explains:

• How Kubernetes Dashboard used OAuth2 Proxy with impersonation headers
• How to configure Headlamp with OAuth2 Proxy using the meUserInfoURL setting
• Helm deployment examples with OAuth2 Proxy configuration
• RBAC configuration details
• Key differences between Dashboard and Headlamp approaches
• Link to the complete AKS OAuth2 Proxy tutorial for a working example

Commit: 2b4c017

[illume]

@copilot

[illume]

Remove these install instructions

# Kubernetes Dashboard in its own namespace
helm install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard \
  --namespace kubernetes-dashboard

# Headlamp in kube-system
helm install headlamp headlamp/headlamp \
  --namespace kube-system

[Copilot]

Removed the helm install commands. Section now simply states that both dashboards can run simultaneously during migration. Commit: bf90e75

[illume]

Remove this "Migrating Bookmarks and URLs" section. The part about the Dashboard URLs being like that is no longer true.

[Copilot]

Removed the "Migrating Bookmarks and URLs" section entirely. Commit: bf90e75

[illume]

@copilot fix review comments

[Copilot]

@copilot fix review comments

Fixed all review comments. Removed redundant helm install commands and outdated bookmarks section. Commit: bf90e75