Headlamp

https://headlamp.dev/docs
Admin
Headlamp is an extensible, user-friendly Kubernetes web and desktop UI designed to manage and...
Tokens:73,504
Snippets:806
Trust Score:8.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install frontend dependencies

Source: https://headlamp.dev/docs/latest/development/frontend

Installs the required dependencies for the frontend. Run this before building or starting the frontend.

```bash
npm run frontend:install  
```

--------------------------------

### Install kubelogin with Homebrew

Source: https://headlamp.dev/docs/latest/development/oidc

Install kubelogin, a tool for testing Kubernetes authentication, using Homebrew. This is an example installation method.

```bash
# Here's how to do it with Homebrew as an example:  
brew install int128/kubelogin/kubelogin  

```

--------------------------------

### Install dependencies for frontend and app

Source: https://headlamp.dev/docs/latest/development/app

Run these commands to install the required dependencies for the frontend and the desktop app.

```bash
npm run frontend:install  
npm run app:install  
```

--------------------------------

### Start Dex with dex serve

Source: https://headlamp.dev/docs/latest/installation/in-cluster/dex

Command to start Dex using the configuration file created in the previous step.

```bash
dex serve dex-config.yaml  
```

--------------------------------

### Install Headlamp with Helm using values.yaml

Source: https://headlamp.dev/docs/latest/installation/in-cluster/azure-entra-id

Install Headlamp using Helm with the OIDC configuration from values.yaml. This installs Headlamp in the headlamp namespace.

```bash
helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/  
helm install headlamp-oidc headlamp/headlamp -f values.yaml --namespace=headlamp --create-namespace  
```

--------------------------------

### Start Minikube with OIDC configuration

Source: https://headlamp.dev/docs/latest/installation/in-cluster/dex

Command to start Minikube with the necessary OIDC configuration options. Replace <YOUR-DEX-URL> and <CLIENT-ID> with actual values.

```bash
minikube start -p=dex \  
--extra-config=apiserver.authorization-mode=Node,RBAC \  
--extra-config=apiserver.oidc-issuer-url=https://<YOUR-DEX-URL> \  
--extra-config=apiserver.oidc-username-claim=email \  
--extra-config=apiserver.oidc-client-id=<CLIENT-ID>  
```

--------------------------------

### Install OAuth2Proxy via Helm

Source: https://headlamp.dev/docs/latest/installation/in-cluster/aks-cluster-oauth

Installs OAuth2Proxy using the provided values.yaml file. The chart is from the oauth2-proxy repository.

```bash
helm install my-release oauth2-proxy/oauth2-proxy -f values.yaml  

```

--------------------------------

### Generate .msi installer with npm run app:package:win:msi

Source: https://headlamp.dev/docs/latest/development

Generates an .msi installer for Windows. Requires WiX Toolset installed and its binaries in the PATH.

```bash
npm run app:package:win:msi  
```

--------------------------------

### Start Minikube with Keycloak OIDC configuration

Source: https://headlamp.dev/docs/latest/installation/in-cluster/keycloak

Starts Minikube with the necessary OIDC configuration options for Keycloak authentication. Replace <YOUR-KEYCLOAK-URL>, <REALM-NAME>, and <CLIENT-ID> with your actual values.

```bash
minikube start -p=keycloak \  
--extra-config=apiserver.authorization-mode=Node,RBAC \  
--extra-config=apiserver.oidc-issuer-url=<YOUR-KEYCLOAK-URL>/realms/<REALM-NAME> \  
--extra-config=apiserver.oidc-username-claim=email \  
--extra-config=apiserver.oidc-client-id=<CLIENT-ID>  

```

--------------------------------

### Start Minikube Cluster for Gateway Testing

Source: https://headlamp.dev/docs/latest/development/gateway

Start a fresh Minikube cluster with a dedicated profile named gateway-checkup for local testing.

```bash
minikube start --profile=gateway-checkup  
```

--------------------------------

### Build the frontend

Source: https://headlamp.dev/docs/latest/development/frontend

Quickly builds the frontend after dependencies are installed.

```bash
npm run frontend:build  
```

--------------------------------

### Install all dependencies

Source: https://headlamp.dev/docs/latest/development

Installs the required frontend, app, and backend dependencies for Headlamp development. Requires Node.js >= 22.0.0, npm >= 11.0.0, and Go >= 1.25.9.

```bash
npm run install:all  
```

--------------------------------

### Install Headlamp with Glasskube

Source: https://headlamp.dev

Install Headlamp in your cluster using Glasskube.

```bash
glasskube install headlamp  
```

--------------------------------

### Install oidc-login plugin with krew

Source: https://headlamp.dev/docs/latest/installation/in-cluster/dex

Command to install the oidc-login plugin using krew.

```bash
kubectl krew install oidc-login  
```

--------------------------------

### Expose Headlamp deployment and get minikube URL

Source: https://headlamp.dev/docs/latest/development

Exposes the Headlamp deployment as a NodePort service, gets the service details, and obtains the URL from minikube. Go to the printed URL in your browser and get your token to login.

```bash
$ kubectl expose deployment headlamp -n kube-system --type=NodePort --port=4466  
service/headlamp exposed  
  
$ kubectl get service headlamp -n kube-system  
NAME       TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE  
headlamp   NodePort   10.99.144.210   <none>        4466:30712/TCP   6m57s  
  
$ minikube service headlamp -n kube-system --url  
http://192.168.49.2:30342  

```

--------------------------------

### Build without installers for faster development

Source: https://headlamp.dev/docs/latest/development/app

Builds the app without creating installers, which is faster for development.

```bash
npm run app:build:dir  
```

--------------------------------

### Install Headlamp with Helm

Source: https://headlamp.dev/docs/latest/installation/in-cluster/dex

Add the Headlamp Helm repository and install Headlamp with the OIDC configuration from values.yaml in the headlamp namespace.

```bash
helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/  
helm install headlamp-oidc headlamp/headlamp -f values.yaml --namespace=headlamp --create-namespace  

```

--------------------------------

### Run full app with npm run start:app

Source: https://headlamp.dev/docs/latest/development

Runs everything including backend, frontend, and app in parallel.

```bash
npm run start:app  
```

--------------------------------

### Install translation tool dependencies

Source: https://headlamp.dev/docs/latest/development/i18n/contributing

Install the required tool dependencies before using the translation helper commands.

```bash
npm run tools:install  

```

--------------------------------

### Start backend with Cluster Inventory and frontend

Source: https://headlamp.dev/docs/latest/development/cluster-inventory

Start the Headlamp backend with Cluster Inventory enabled and the frontend in a separate terminal. The backend command requires a hub kubeconfig, a provider configuration file, and sets the dynamic clusters flag; the frontend command runs the development server.

```bash
npm run backend:build  
KUBECONFIG="$WORK/hub.kubeconfig" \
HEADLAMP_BACKEND_TOKEN=headlamp \
HEADLAMP_CONFIG_ENABLE_DYNAMIC_CLUSTERS=true \
./backend/headlamp-server -dev -listen-addr=localhost \
  --enable-cluster-inventory \
  --cluster-inventory-provider-file "$WORK/provider-config.json" \
  --cluster-inventory-label-selector='!headlamp.dev/ignore' \
  --cluster-inventory-root-reconcile-interval=10s \
  --cluster-inventory-no-crd-cache-ttl=30s
```

```bash
npm run frontend:start
```

--------------------------------

### Start development mode

Source: https://headlamp.dev/docs/latest/development/plugins/getting-started

Runs the plugin in development mode, making it available to Headlamp and watching for file changes to automatically rebuild.

```bash
npm run start  
```

--------------------------------

### Linux: Run Headlamp with --headless (AppImage)

Source: https://headlamp.dev/docs/latest/installation/desktop/headless

Starts Headlamp in headless mode using an AppImage binary.

```bash
./Headlamp.AppImage --headless # for AppImage  
```

--------------------------------

### Install Headlamp with kubectl apply

Source: https://headlamp.dev

Install Headlamp in your cluster using a configuration file. Review and modify the YAML before applying it.

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/headlamp/main/kubernetes-headlamp.yaml  
```

--------------------------------

### Install Headlamp with WinGet

Source: https://headlamp.dev

Install Headlamp on Windows using WinGet. A warning may appear because the app is unsigned.

```bash
winget install headlamp  
```

--------------------------------

### Install Ubuntu WSL packages for end-to-end tests

Source: https://headlamp.dev/docs/latest/development

Installs additional packages needed for end-to-end tests on Ubuntu WSL.

```bash
sudo apt-get install firefox libgstreamer-plugins-bad1.0-0 libegl1 libnotify4 libopengl0 libwoff1 libharfbuzz-icu0 libgstreamer-gl1.0-0 libwebpdemux2 libenchant1c2a libsecret-1-0 libhyphen0 libevdev2 libgles2 gstreamer1.0-libav  
```

--------------------------------

### Linux: Run Headlamp with --headless (Flatpak)

Source: https://headlamp.dev/docs/latest/installation/desktop/headless

Starts Headlamp in headless mode on Linux using Flatpak.

```bash
flatpak run io.kinvolk.Headlamp --headless  
```

--------------------------------

### Run Storybook

Source: https://headlamp.dev/docs/latest/development/frontend

Starts Storybook from within the Headlamp repo for discovering, developing, and testing components.

```bash
npm run frontend:storybook  
```

--------------------------------

### Package the app for specific platforms

Source: https://headlamp.dev/docs/latest/development/app

Platform-specific packaging commands for Windows, Linux, macOS, and Windows MSI installer.

```bash
npm run app:package:win      # Windows  
npm run app:package:linux    # Linux  
npm run app:package:mac      # macOS  
npm run app:package:win:msi  # Windows MSI installer  
```

--------------------------------

### Example output of packaging command

Source: https://headlamp.dev/docs/latest/development/plugins/getting-started

Shows the expected output from the packaging command, including the tarball path and its SHA256 checksum.

```bash
# Created tarball: "/tmp/my-first-plugin/my-first-plugin-0.1.0.tar.gz".  
# Tarball checksum (sha256): c45397ff5f8fac563c2b85a18c0dbbe732017bed71b24bf852b809911993be6f  

```

--------------------------------

### Install Ubuntu WSL dependencies for Headlamp

Source: https://headlamp.dev/docs/latest/development

Installs required packages for running Headlamp on Ubuntu WSL. Note: libgconf-2-4 was removed starting with Ubuntu 24.04; install it separately if available.

```bash
sudo apt install libatk1.0-0 libatk-bridge2.0-0 libgdk-pixbuf2.0-0 libgtk-3-0 libgbm1 libnss3 libasound2  
```

--------------------------------

### Verify Gateway and Routes Setup

Source: https://headlamp.dev/docs/latest/development/gateway

Commands to verify that the Gateway and Routes are accepted and functioning after applying the manifests. Includes checking gateway, gatewayclass, routes, and backend policies.

```bash
kubectl get gateway  
kubectl get gatewayclass  
kubectl get httproute  
kubectl get grpcroute  
kubectl describe gateway envoy-gateway  
kubectl get backendtlspolicies.gateway.networking.k8s.io  
kubectl get xbackendtrafficpolicies.gateway.networking.x-k8s.io  
```

--------------------------------

### macOS: Run Headlamp with --headless (Homebrew)

Source: https://headlamp.dev/docs/latest/installation/desktop/headless

Starts Headlamp in headless mode on macOS when installed via brew.

```bash
/Applications/Headlamp.app/Contents/MacOS/Headlamp --headless  
```

--------------------------------

### Install Headlamp with Helm

Source: https://headlamp.dev

Install Headlamp in your cluster using Helm. Adds the Headlamp Helm repository and installs the chart in the kube-system namespace.

```bash
helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/  
helm install my-headlamp headlamp/headlamp --namespace kube-system  
```

--------------------------------

### Build and package a plugin

Source: https://headlamp.dev/docs/latest/development/plugins/building

Build and package a plugin in its folder before manual installation. Run these commands in the plugin directory to produce the plugin archive.

```bash
cd my-plugin/  
npm install  
npm run build  
npm run package  

```

--------------------------------

### Run everything together

Source: https://headlamp.dev/docs/latest/development/app

Runs the backend, frontend, and app together.

```bash
npm run start:with-app  
```

--------------------------------

### Install required tool dependencies

Source: https://headlamp.dev/docs/latest/development/plugins/i18n

Run these commands to install the dependencies needed for i18n extraction.

```bash
npm run frontend:install  
npm run app:install  

```

--------------------------------

### Install Headlamp with Flatpak

Source: https://headlamp.dev

Install Headlamp on Linux using Flatpak. Requires the Flathub repository to be set up.

```bash
flatpak install flathub io.kinvolk.Headlamp  
```

--------------------------------

### Build the desktop app

Source: https://headlamp.dev/docs/latest/development/app

Builds the frontend, sets up plugins, and compiles the Electron app into a distributable package.

```bash
npm run app:build  
```

--------------------------------

### Install plugin archive on Linux/macOS

Source: https://headlamp.dev/docs/latest/development/plugins/building

Install a plugin archive into the default plugins directory on Linux/macOS. The directory is $HOME/.config/Headlamp/plugins.

```bash
mkdir -p ~/.config/Headlamp/plugins/  
tar xvf my-first-plugin-0.1.0.tar.gz -C ~/.config/Headlamp/plugins/  

```

--------------------------------

### Test the configuration

Source: https://headlamp.dev/docs/latest/installation/in-cluster/dex

Command to list namespaces to verify OIDC authentication works. A browser window will open for login.

```bash
kubectl get ns  
```

--------------------------------

### Install Headlamp with Chocolatey

Source: https://headlamp.dev

Install Headlamp on Windows using Chocolatey. A warning may appear because the app is unsigned.

```bash
choco install headlamp  
```

--------------------------------

### Set up oidc-login

Source: https://headlamp.dev/docs/latest/installation/in-cluster/dex

Command to configure oidc-login with the necessary parameters. Replace placeholders with actual values.

```bash
kubectl oidc-login setup --oidc-issuer-url=https://<YOUR-DEX-URL> \ --oidc-client-id=<CLIENT-ID> \  
--oidc-client-secret=<CLIENT-SECRET>  
```

--------------------------------

### Install Headlamp with Homebrew

Source: https://headlamp.dev

Install Headlamp on macOS using Homebrew. A warning may appear because the app is unsigned.

```bash
brew install --cask headlamp  
```

--------------------------------

### Run Headlamp in static build mode with -base-url /headlamp

Source: https://headlamp.dev/docs/latest/installation/base-url

Build the frontend and serve it with the backend using a base-url. The -html-static-dir flag points to the built frontend. Access the app at http://localhost:4466/headlamp/.

```bash
npm run frontend:build  
./backend/headlamp-server -dev -base-url /headlamp -html-static-dir frontend/build  

```

--------------------------------

### Run npm scripts for backend, frontend, and app

Source: https://headlamp.dev/docs/latest/development/architecture

Use these npm scripts from the headlamp/ repo root to build, lint, test, and start the backend, frontend, and desktop app components. The scripts are defined in the root package.json and cover the main development workflows.

```bash
npm run backend:build  
npm run backend:lint  
npm run backend:test  
npm run backend:start  
npm run frontend:build  
npm run frontend:lint  
npm run frontend:test  
npm run frontend:start  
npm run app:test  
npm run start:app  

```

--------------------------------

### Download and customize Headlamp ingress YAML

Source: https://headlamp.dev/docs/latest/installation/in-cluster

Downloads the sample ingress YAML and replaces the __URL__ placeholder with the desired URL (here headlamp.mydeployment.io). The sample assumes Contour and cert-manager are set up; otherwise TLS will not be enabled.

```bash
curl -s https://raw.githubusercontent.com/kubernetes-sigs/headlamp/main/kubernetes-headlamp-ingress-sample.yaml | sed -e s/__URL__/headlamp.mydeployment.io/ > headlamp-ingress.yaml  
```

--------------------------------

### Build backend and frontend

Source: https://headlamp.dev/docs/latest/development

Builds both the backend and frontend components of Headlamp.

```bash
npm run build  
```

--------------------------------

### Build Headlamp backend with npm run backend:build

Source: https://headlamp.dev/docs/latest/development/backend

Builds the Headlamp backend server. Run this before starting the server in development mode.

```bash
npm run backend:build  
```

--------------------------------

### Install Headlamp with Cluster Inventory values

Source: https://headlamp.dev/docs/latest/installation/in-cluster

Installs Headlamp with the cluster-inventory-values.yaml file to enable Cluster Inventory. The chart sets config.clusterInventory.labelSelector to !headlamp.dev/ignore by default.

```bash
helm install my-headlamp headlamp/headlamp --namespace kube-system --values cluster-inventory-values.yaml  
```

--------------------------------

### Run the desktop app in development mode

Source: https://headlamp.dev/docs/latest/development/app

Runs the built app in development mode.

```bash
npm run app:start  
```

--------------------------------

### Scaffold a new plugin with headlamp-plugin

Source: https://headlamp.dev/docs/latest/development/plugins/getting-started

Run this command in a dedicated projects directory (not in Headlamp's plugin installation directory) to create a new plugin, navigate into it, and install dependencies.

```bash
# Create a new plugin  
npx --yes @kinvolk/headlamp-plugin create my-first-plugin  
  
# Navigate to the plugin directory  
cd my-first-plugin  
  
# Install dependencies  
npm install  
```

--------------------------------

### Start backend with log level warn

Source: https://headlamp.dev/docs/latest/development

Starts the backend with the log level set to 'warn'. Supported values: debug, info, warn, error (default: info). The log level can also be set via the HEADLAMP_CONFIG_LOG_LEVEL environment variable.

```bash
npm run backend:start -- --log-level warn  
```

--------------------------------

### Package the app for all platforms

Source: https://headlamp.dev/docs/latest/development/app

Packages the app for all platforms.

```bash
npm run app:package  
```

--------------------------------

### getClusterDefaultNamespace

Source: https://headlamp.dev/docs/latest/development/api/lib/k8s/api/v1/clusterApi/API

Gets the default namespace for a given cluster.

```APIDOC
## getClusterDefaultNamespace

### Description
Returns the default namespace for the given cluster.

### Method
GET

### Endpoint
/api/v1/cluster/{cluster}/defaultNamespace

### Parameters
#### Path Parameters
- **cluster** (string) - Required - The name of the cluster.

### Response
#### Success Response (200)
- **namespace** (string) - The default namespace.

#### Response Example
{
  "namespace": "default"
}
```
Tokens:
Raw