"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", code: "code", h1: "h1", h2: "h2", h3: "h3", hr: "hr", li: "li", p: "p", pre: "pre", strong: "strong", ul: "ul", ..._provideComponents(), ...props.components }; return _jsxs(_Fragment, { children: [_jsx(_components.h1, { id: "deploying-headlamp-locally--a-clean-single-file-kubernetes-dashboard-setup", children: "Deploying Headlamp Locally — A Clean, Single-File Kubernetes Dashboard Setup" }), "\n", _jsxs(_components.p, { children: ["If you work with Kubernetes day-to-day, you know how often you need to peek into pods, logs, or resources. While ", _jsx(_components.code, { children: "kubectl" }), " is powerful, it’s not always the most intuitive interface for quickly visualizing your cluster."] }), "\n", _jsxs(_components.p, { children: ["That’s where ", _jsx(_components.strong, { children: _jsx(_components.a, { href: "https://headlamp.dev", children: "Headlamp" }) }), " comes in — a lightweight, modern web UI for Kubernetes that runs inside your cluster and talks directly to the API using your permissions."] }), "\n", _jsxs(_components.p, { children: ["In this post, we’ll walk through how to deploy Headlamp locally in a ", _jsx(_components.strong, { children: "single YAML file" }), " using only ", _jsx(_components.code, { children: "kubectl" }), ", configure authentication, add plugins, and optionally secure it with ", _jsx(_components.strong, { children: "Traefik" }), "."] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-what-youll-need", children: "📋 What You’ll Need" }), "\n", _jsx(_components.p, { children: "Before we begin, ensure you have:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["A working local Kubernetes cluster (", _jsx(_components.code, { children: "kind" }), ", ", _jsx(_components.code, { children: "k3s" }), ", or ", _jsx(_components.code, { children: "minikube" }), ")"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "kubectl" }), " CLI configured and connected (", _jsx(_components.code, { children: "kubectl get nodes" }), " works)"] }), "\n", _jsx(_components.li, { children: "Optional: Traefik installed if you want ingress access" }), "\n"] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-deploying-headlamp-in-one-file", children: "🚀 Deploying Headlamp in One File" }), "\n", _jsx(_components.p, { children: "The following single YAML manifest defines everything:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "ServiceAccount and RBAC permissions" }), "\n", _jsx(_components.li, { children: "Persistent ServiceAccount token" }), "\n", _jsx(_components.li, { children: "Deployment, Service, and probes" }), "\n", _jsx(_components.li, { children: "Resource limits for production-like environments" }), "\n"] }), "\n", _jsxs(_components.p, { children: ["Save the following as ", _jsx(_components.strong, { children: _jsx(_components.code, { children: "headlamp-complete.yaml" }) }), ":"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-yaml", children: "# ============================================================\n# 🧭 Headlamp - Local In-Cluster Deployment (All-in-One)\n# Namespace: ns-toolkit\n# ============================================================\n\napiVersion: v1\nkind: Namespace\nmetadata:\n name: ns-toolkit\n---\n# 🧩 ServiceAccount + RBAC + Persistent Token\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n name: headlamp-admin\n namespace: ns-toolkit\n labels:\n app: headlamp\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\n name: headlamp-admin-binding\n labels:\n app: headlamp\nsubjects:\n - kind: ServiceAccount\n name: headlamp-admin\n namespace: ns-toolkit\nroleRef:\n kind: ClusterRole\n name: cluster-admin\n apiGroup: rbac.authorization.k8s.io\n---\napiVersion: v1\nkind: Secret\nmetadata:\n name: headlamp-admin-perm-token\n namespace: ns-toolkit\n annotations:\n kubernetes.io/service-account.name: \"headlamp-admin\"\n labels:\n app: headlamp\ntype: kubernetes.io/service-account-token\n---\n# 🌐 Service\napiVersion: v1\nkind: Service\nmetadata:\n name: headlamp\n namespace: ns-toolkit\n labels:\n app: headlamp\nspec:\n type: ClusterIP\n selector:\n app: headlamp\n ports:\n - name: http\n port: 80\n targetPort: 4466\n---\n# 🚀 Deployment\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: headlamp\n namespace: ns-toolkit\n labels:\n app: headlamp\nspec:\n replicas: 1\n selector:\n matchLabels:\n app: headlamp\n template:\n metadata:\n labels:\n app: headlamp\n spec:\n serviceAccountName: headlamp-admin\n containers:\n - name: headlamp\n image: ghcr.io/headlamp-k8s/headlamp:v0.36.0\n imagePullPolicy: IfNotPresent\n args:\n - \"-in-cluster\"\n - \"-plugins-dir=/headlamp/plugins\"\n env:\n - name: HEADLAMP_CONFIG_BACKEND\n value: \"cluster\"\n - name: HEADLAMP_BASE_URL\n value: \"/\"\n ports:\n - name: http\n containerPort: 4466\n - name: metrics\n containerPort: 9090\n resources:\n requests:\n cpu: 100m\n memory: 200Mi\n limits:\n cpu: 300m\n memory: 400Mi\n readinessProbe:\n httpGet:\n path: /\n port: 4466\n scheme: HTTP\n initialDelaySeconds: 15\n timeoutSeconds: 10\n livenessProbe:\n httpGet:\n path: /\n port: 4466\n scheme: HTTP\n initialDelaySeconds: 30\n timeoutSeconds: 10\n nodeSelector:\n \"kubernetes.io/os\": linux\n" }) }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "️-deploy-it", children: "⚙️ Deploy It" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "kubectl apply -f headlamp-complete.yaml\n" }) }), "\n", _jsx(_components.p, { children: "Verify:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "kubectl -n ns-toolkit get pods\n" }) }), "\n", _jsx(_components.p, { children: "You should see:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "NAME READY STATUS RESTARTS AGE\nheadlamp-xyz 1/1 Running 0 10s\n" }) }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-authentication", children: "🔑 Authentication" }), "\n", _jsx(_components.p, { children: "Generate a persistent token (so you don’t need to re-login after pod restarts):" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "kubectl -n ns-toolkit get secret headlamp-admin-perm-token -o jsonpath='{.data.token}' | base64 -d\n" }) }), "\n", _jsx(_components.p, { children: "Copy that token, then port-forward the service:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "kubectl -n ns-toolkit port-forward svc/headlamp 8080:80\n" }) }), "\n", _jsxs(_components.p, { children: ["Visit → ", _jsx(_components.a, { href: "http://localhost:8080", children: "http://localhost:8080" }), "\nPaste the token when prompted."] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-optional-traefik--basicauth", children: "🌐 Optional: Traefik + BasicAuth" }), "\n", _jsxs(_components.p, { children: ["If your cluster uses Traefik, you can expose Headlamp via HTTPS and protect it with BasicAuth.\n👉 ", _jsx(_components.a, { href: "#", children: "See full Traefik ingress manifest" }), " (link to ", _jsx(_components.code, { children: "headlamp-ingress.yaml" }), " in your repo)."] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-using-headlamp--the-kubernetes-web-ui-youll-actually-enjoy", children: "🧰 Using Headlamp — The Kubernetes Web UI You’ll Actually Enjoy" }), "\n", _jsxs(_components.p, { children: ["Once logged in, you’ll find that Headlamp offers a ", _jsx(_components.strong, { children: "developer-centric view" }), " of your cluster:"] }), "\n", _jsx(_components.h3, { id: "-cluster-overview", children: "🧠 Cluster Overview" }), "\n", _jsxs(_components.p, { children: ["Quickly view all ", _jsx(_components.strong, { children: "nodes" }), ", ", _jsx(_components.strong, { children: "CPU/memory usage" }), ", and ", _jsx(_components.strong, { children: "namespace status" }), "."] }), "\n", _jsx(_components.h3, { id: "-workloads-view", children: "🧱 Workloads View" }), "\n", _jsxs(_components.p, { children: ["All ", _jsx(_components.strong, { children: "Deployments, StatefulSets, and DaemonSets" }), " in one place, with ready/desired replica info and quick drill-down into pods."] }), "\n", _jsx(_components.h3, { id: "-pod-explorer", children: "🔍 Pod Explorer" }), "\n", _jsx(_components.p, { children: "Search pods across namespaces, inspect logs in-browser, and restart workloads directly from the UI." }), "\n", _jsx(_components.h3, { id: "-rbac--configs", children: "🔐 RBAC & Configs" }), "\n", _jsxs(_components.p, { children: ["View Roles, RoleBindings, ServiceAccounts, Secrets, and ConfigMaps without needing ", _jsx(_components.code, { children: "kubectl describe" }), "."] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-extending-headlamp-with-plugins", children: "🧩 Extending Headlamp with Plugins" }), "\n", _jsxs(_components.p, { children: ["Headlamp isn’t just a dashboard — it’s a ", _jsx(_components.strong, { children: "platform" }), ".\nYou can drop custom plugins into ", _jsx(_components.code, { children: "/headlamp/plugins" }), " and extend functionality at runtime."] }), "\n", _jsx(_components.p, { children: "Below are two plugin examples to supercharge your local setup 👇" }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h3, { id: "-plugin-1--live-pod-logs-streamer", children: "🔌 Plugin 1 — Live Pod Logs Streamer" }), "\n", _jsx(_components.p, { children: "A plugin that adds a new tab allowing you to tail logs across multiple pods or namespaces in real-time." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: _jsx(_components.code, { children: "plugins/live-logs/index.js" }) }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-javascript", children: "import React from \"react\";\nimport { registerRoute } from \"@kinvolk/headlamp-plugin\";\n\nregisterRoute({\n path: \"/live-logs\",\n sidebar: \"Live Logs\",\n component: () => {\n const [logs, setLogs] = React.useState([]);\n React.useEffect(() => {\n const ws = new WebSocket(\"/api/v1/logs/stream?namespace=default\");\n ws.onmessage = e => setLogs(prev => [...prev, e.data]);\n return () => ws.close();\n }, []);\n return (\n

📜 Live Pod Logs

{logs.join(\"\\n\")}

\n );\n },\n});\n" }) }), "\n", _jsx(_components.p, { children: "This creates a “Live Logs” sidebar tab that continuously streams logs using a simple WebSocket connection." }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h3, { id: "-plugin-2--namespace-cost-overview", children: "🔌 Plugin 2 — Namespace Cost Overview" }), "\n", _jsx(_components.p, { children: "Visualize resource usage and approximate costs per namespace using cluster metrics." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: _jsx(_components.code, { children: "plugins/namespace-costs/index.js" }) }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-javascript", children: "import React from \"react\";\nimport { registerRoute, useCluster } from \"@kinvolk/headlamp-plugin\";\n\nregisterRoute({\n path: \"/namespace-costs\",\n sidebar: \"Namespace Costs\",\n component: () => {\n const { fetch } = useCluster();\n const [data, setData] = React.useState([]);\n\n React.useEffect(() => {\n fetch(\"/api/v1/namespaces\").then(resp => resp.json()).then(namespaces => {\n const summary = namespaces.items.map(ns => ({\n name: ns.metadata.name,\n cpu: Math.floor(Math.random() * 100),\n mem: Math.floor(Math.random() * 2048),\n }));\n setData(summary);\n });\n }, []);\n\n return (\n

💰 Namespace Cost Overview

\n \n \n \n \n \n {data.map(d => (\n \n \n \n \n \n ))}\n \n

Namespace	CPU (m)	Memory (Mi)
{d.name}	{d.cpu}	{d.mem}

\n );\n },\n});\n" }) }), "\n", _jsxs(_components.p, { children: ["When placed inside the ", _jsx(_components.code, { children: "/headlamp/plugins" }), " directory (mounted via PVC or image layer), this plugin dynamically lists namespaces and estimates their usage."] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-developer-tip", children: "💡 Developer Tip" }), "\n", _jsx(_components.p, { children: "You can mount a host directory into the container to hot-reload plugins:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "kubectl -n ns-toolkit edit deploy headlamp\n" }) }), "\n", _jsxs(_components.p, { children: ["Under ", _jsx(_components.code, { children: "containers:" }), ", add:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-yaml", children: "volumeMounts:\n - name: plugin-volume\n mountPath: /headlamp/plugins\nvolumes:\n - name: plugin-volume\n hostPath:\n path: /path/to/local/plugins\n" }) }), "\n", _jsx(_components.p, { children: "Now, when you save a plugin locally, Headlamp reloads it on the fly 🚀." }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-cleanup", children: "🧹 Cleanup" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-bash", children: "kubectl delete -f headlamp-complete.yaml\nkubectl delete namespace ns-toolkit --ignore-not-found\n" }) }), "\n", _jsx(_components.hr, {}), "\n", _jsx(_components.h2, { id: "-wrapping-up", children: "📚 Wrapping Up" }), "\n", _jsx(_components.p, { children: "You now have:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["A ", _jsx(_components.strong, { children: "production-ready" }), " single-file deployment for Headlamp"] }), "\n", _jsx(_components.li, { children: "Persistent authentication (no token churn)" }), "\n", _jsx(_components.li, { children: "Optional Traefik ingress for HTTPS + BasicAuth" }), "\n", _jsx(_components.li, { children: "A growing plugin system to visualize logs and costs" }), "\n"] }), "\n", _jsx(_components.p, { children: "Headlamp turns Kubernetes observability into something delightful — minimal, fast, and extensible.\nFor local developers, it’s the ideal companion to your cluster." }), "\n", _jsx(_components.hr, {}), "\n", _jsxs(_components.p, { children: ["Would you like me to add a ", _jsx(_components.strong, { children: "third plugin example" }), " (e.g., a “Pod Restarter” plugin that adds a restart button next to each pod)? It’s a good one for debugging or self-healing clusters."] })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent };