Accessing a Cluster Using Headlamp

Use Headlamp Desktop when you want to access one or more clusters from a workstation without deploying Headlamp in the clusters.

To use Headlamp Desktop to access a cluster:

1. If you haven't already done so, follow the steps to set up the cluster's kubeconfig configuration file and (if necessary) set the KUBECONFIG environment variable to point to the file. Note that you must set up your own kubeconfig file. You cannot access a cluster using a kubeconfig file that a different user set up. See Setting Up Cluster Access.

2. Verify that the kubeconfig file contains the Kubernetes context for the cluster you want to access by entering:

   kubectl config get-contexts

3. Install Headlamp Desktop by following the instructions for your operating system in the Headlamp Desktop documentation.

   For example, on macOS, you can install Headlamp Desktop using Homebrew by entering:

   brew install --cask headlamp

4. Start Headlamp Desktop.
5. Select the cluster or Kubernetes context you want to access.
6. Complete authentication if prompted.

Headlamp displays the Kubernetes resources that the identity in the kubeconfig file is authorized to access. The operations available in Headlamp depend on the Kubernetes RBAC permissions granted to that identity.

Because Headlamp Desktop runs on your workstation, it does not consume worker node resources and is not itself subject to virtual node workload restrictions.

Deploy Headlamp in a cluster when you want to provide a shared browser-based interface.

Before you install Headlamp, ensure that:

• You have set up access to the cluster. You can verify access by entering kubectl get nodes. See Setting Up Cluster Access.
• Helm is installed and available in your environment. You can verify the installation by entering helm version.
• Your Kubernetes identity has sufficient permissions to create the resources in the Headlamp Helm chart.

To install Headlamp using Helm:

1. Add the Headlamp Helm repository by entering:

   helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/

   helm repo update

2. Create a namespace for Headlamp by entering:

   kubectl create namespace headlamp

3. Install Headlamp by entering:

   helm install headlamp headlamp/headlamp --namespace headlamp

4. Verify the installation:

   kubectl get deployment,pods,service -n headlamp

   Wait until the Headlamp pod is running and ready.

Headlamp uses Kubernetes authentication and RBAC to determine which cluster resources users can access.

To authenticate to the Headlamp deployment installed using the Helm chart:

1. Verify the Headlamp service account by entering:

   kubectl get serviceaccount headlamp -n headlamp

2. Verify the ClusterRoleBinding by entering:

   kubectl get clusterrolebinding headlamp-admin -o yaml

   Important
   
   

   By default, the Headlamp Helm chart creates a headlamp-admin ClusterRoleBinding that grants the cluster-admin role to the headlamp service account. The cluster-admin role provides unrestricted access to the cluster. For production use, grant only the permissions required for your environment.

3. Create a temporary token for the Headlamp service account by entering:

   kubectl create token headlamp -n headlamp

4. Copy the token from the command output. You enter this token when you access Headlamp.

For shared deployments, consider configuring OpenID Connect (OIDC) authentication instead of distributing service account tokens. See the Headlamp in-cluster documentation.

For local administrative access, you can use kubectl port-forward to access the Headlamp service.

1. Forward local port 8080 to the Headlamp service by entering:

   kubectl port-forward -n headlamp service/headlamp 8080:80

2. Open a browser and go to:

   http://localhost:8080

3. When prompted, enter the authentication token you created earlier.

For shared production access, configure ingress, TLS, and an appropriate authentication mechanism rather than relying on port forwarding. See the Headlamp in-cluster documentation.

You can use Headlamp with clusters that contain virtual node pools.

• Headlamp Desktop runs outside the cluster and is not itself subject to virtual node workload restrictions. Workloads that you inspect or manage remain subject to the capabilities and limitations of the node type on which they run.
• An in-cluster Headlamp deployment runs as Kubernetes pods. If Headlamp pods are scheduled on virtual nodes, the pods are subject to the same Kubernetes feature, networking, storage, and resource constraints as other workloads running on virtual nodes.

In particular, kubectl port-forward is not supported for pods on virtual nodes. See Comparing Virtual Nodes with Managed Nodes and Resources Allocated to Pods Provisioned by Virtual Nodes.

After connecting to the cluster using Headlamp:

1. Select the cluster.
2. Select a namespace.
3. Open Workloads.
4. Select Deployments or Pods.
5. Select a resource to view its details, events, logs, and related resources.

The resources and operations that are shown depend on the Kubernetes RBAC permissions granted to the identity you used to access the cluster.

If the Kubernetes Metrics Server is installed in the cluster, Headlamp can also display resource usage information. For more information about the Kubernetes Metrics Server, see Deploying the Kubernetes Metrics Server on a Cluster.

To remove the Headlamp deployment created in this topic:

1. Uninstall the Headlamp Helm release by entering:

   helm uninstall headlamp -n headlamp

2. Delete the Headlamp namespace by entering:

   kubectl delete namespace headlamp

Removing Headlamp Desktop from your workstation does not modify the clusters that you accessed with it.