---
title: "Headlamp for Kubernetes | Hostman Docs"
description: "Learn how to install and use Headlamp interface for managing Kubernetes clusters. Check our step-by-step guides for working with Hostman cloud infrastructure and services."
---

> For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt).

Headlamp is a web-based interface for managing a cluster. It allows you to view cluster resources, manage them, and monitor application status without using [kubectl](https://hostman.com/docs/kubernetes/connect-to-clusters/kubectl/).

## Installation

> [!NOTE]
> Before installing the add-on, make sure that [Nginx Ingress](https://hostman.com/docs/kubernetes/addons/nginx-ingress/) is installed in your cluster.

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** tab and select **Headlamp**.
3.  Enable **Advanced setup** and adjust the configuration for your needs. For example, you can set up:
    -   the domain where the interface will be available;
    -   ingress settings;
    -   OIDC configuration.
4.  Click **Install**.

To verify that the add-on is installed correctly, run:

```shell
kubectl get pod -n headlamp
```

If the installation was successful, you will see a pod with the `Running` status.

## Authentication

After installation, the Headlamp icon will appear in the cluster dashboard.

![D2492951 3acf 406b 9ac5 04a276e82d10](https://content.hostman.com/assets/05e1c356-6b2c-4304-86ed-6036cd34b5df.png?width=1558&height=866)

Click it to open the interface. If you are not authenticated, you will need to provide a token.

You can obtain the token from the **Dashboard** tab by clicking **Copy** next to **Dashboard token**:

![Dd656c47 9ad0 4ca1 A263 6f7a7f96a915](https://content.hostman.com/assets/76eff32b-5356-4715-8873-12ca992edb71.png?width=1558&height=866)

After authentication, the Headlamp interface will be displayed.

![6454a333 1712 4216 Ad93 808ab30dced1.png](https://content.hostman.com/assets/ab310c7c-d68e-4595-991d-26e5bf0f9fb8.png?width=2926&height=1658)

_[Headlamp](https://headlamp.dev/) interface_

Main sections are:

-   **Cluster**: cluster information and status
-   **Map**: visualization of resources and their relationships
-   **Workloads**: management of workloads (Pods, Deployments, StatefulSets)
-   **Storage**: PVCs, PVs, and storage classes
-   **Network**: services, ingress, and network policies
-   **Gateway**: Gateway API resources
-   **Security**: roles, service accounts, and access policies
-   **Configuration**: ConfigMaps, Secrets, and other settings
-   **Custom Resources**: custom resources (CRDs)
-   **Create**: create resources via the interface

## Configuring Authentication

If the Headlamp interface is exposed externally, it is recommended to configure additional basic authentication.

Headlamp does not support username and password authentication directly. Instead, basic authentication is configured at the `ingress` level.

Create a file with a username and password:

```shell
htpasswd -c auth admin
```

Here, `admin` is the username. You will be prompted to enter the desired password twice.

This command creates a file named `auth`.

If the `htpasswd` utility is not available, install the `apache2-utils` package.

Next, create a secret in the `headlamp` namespace using the generated file:

```shell
kubectl create secret generic headlamp-basic-auth \
  --from-file=auth \
  -n headlamp
```

Go to the **Addons** section in the cluster dashboard and open the installed **Headlamp** add-on.

Enable advanced setup and locate the following block:

```shell
ingress:
 enabled: true
 annotations: {}
```

Remove `{}` next to `annotations` and add the required annotations:

```shell
ingress:
  enabled: true
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: headlamp-basic-auth
    nginx.ingress.kubernetes.io/auth-realm: "Authentication Required"
```

Click **Save** and wait for the add-on to be updated.

After that, when accessing Headlamp, you will first be prompted for a username and password, and then for a token.

To change the password, create a new `auth` file and update the secret in the cluster.