Setting up the Headlamp add-on

Understanding the Headlamp add-on

The Headlamp add-on is the recommended replacement for the archived kubernetes-dashboard project. Headlamp provides a modern, user-friendly interface for viewing and managing Kubernetes resources in your cluster.

Key features of the Headlamp add-on include:

• IAM OIDC authentication: Seamlessly authenticate with your IBM Cloud account using IAM OIDC.
• Independent lifecycle management: The add-on version is decoupled from cluster master BOM versions, allowing for independent updates.
• Ready to Access: The add-on is automatically exposed through an Ingress resource on your cluster's default public ingress hostname with a headlamp subdomain.
• Secure access: Each cluster receives a unique OIDC client ID to prevent authentication spoofing attacks.

Prerequisites

Before you install the Headlamp add-on, ensure that your cluster meets the following requirements:

• You must have the Writer or Manager IBM Cloud IAM service access role for IBM Cloud Kubernetes Service.
• Your cluster must be running a supported Kubernetes version.
• For Classic clusters, you must enable VRF and service endpoints.
• Your browser must have access to:
  • The cluster's default ingress hostname.
  • The IBM Cloud IAM authorization endpoint at https://iam.cloud.ibm.com.

Installing the Headlamp add-on

The Headlamp add-on is currently only available through the CLI. You cannot install or manage the add-on from the IBM Cloud console.

Accessing the Headlamp dashboard

After you install the Headlamp add-on, you can access the dashboard through your cluster's default ingress hostname.

1. Get your cluster's default ingress hostname.

   ibmcloud ks cluster get --cluster <cluster_name_or_ID> | grep "Ingress Subdomain"
   

2. Open your browser and navigate to https://headlamp.<ingress_subdomain>, where <ingress_subdomain> is your cluster's default ingress hostname.

   Example: https://headlamp.mycluster-abc123-0000.us-south.containers.appdomain.cloud

3. Click Sign In to authenticate with IBM Cloud IAM.

4. If you're not already logged in to IBM Cloud, you'll be redirected to the IAM login page. After authentication, you'll be redirected back to the Headlamp dashboard.

5. Once authenticated, you can view and manage your cluster resources through the Headlamp interface.

Migrating from kubernetes-dashboard

The Kubernetes community has archived the kubernetes-dashboard project. After you install the Headlamp add-on, you can scale down the kubernetes-dashboard deployment if it's running in your cluster.

To scale down the kubernetes-dashboard deployment after installing Headlamp:

kubectl scale deployment -n kube-system kubernetes-dashboard --replicas=0
kubectl scale deployment -n kube-system dashboard-metrics-scraper --replicas=0

Understanding Headlamp authentication

The Headlamp add-on uses IBM Cloud IAM OIDC authentication to secure access to your cluster resources.

When you enable the Headlamp add-on, the following authentication components are automatically configured:

• Unique client ID: A unique OIDC client ID is created for your cluster and stored in a Kubernetes secret in the ibm-system namespace.
• Hybrid private-public OIDC: Headlamp uses private IAM endpoints for backchannel requests, while frontchannel - login in the browser - happens over public IAM endpoints.
• Token management: Authentication tokens are stored in browser cookies and automatically included in requests to the Kubernetes API server.

The authentication flow works as follows:

1. When you access the Headlamp dashboard, you're presented with a login page.
2. Clicking Sign In redirects you to the public IBM Cloud IAM authorization endpoint.
3. After successful authentication, IAM redirects you back to Headlamp with an authorization code.
4. Headlamp exchanges the authorization code for an access token over private network.
5. The access token is used to authenticate requests to the Kubernetes API server.

Your access to cluster resources is determined by your IBM Cloud IAM roles and Kubernetes RBAC permissions enforced by the Kubernetes API server.

Updating the Headlamp add-on

The Headlamp add-on is automatically updated when new versions are released. You can check the current version and health status of the add-on at any time.

To check the add-on version:

ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>

Disabling the Headlamp add-on

If you no longer need the Headlamp dashboard, you can disable the add-on.

When you disable the Headlamp add-on, the following resources are removed:

• Headlamp deployment and pods
• Headlamp service and ingress resources
• OIDC client ID and associated secrets

Accessing Headlamp over private ingress on VPC clusters

Configure your VPC cluster to access Headlamp through private ingress instead of public ingress for enhanced security.

When you choose to access Headlamp from private networks, like over a VPC VPN, you can reconfigure your cluster with the following steps:

1. Disable your cluster's public ALB.

   ibmcloud ks ingress alb disable --cluster <cluster_name_or_ID> --alb <public_ALB_ID>
   

2. Enable private ingress.

   ibmcloud ks ingress alb enable vpc-gen2 --cluster <cluster_name_or_ID> --alb <private_ALB_ID>
   

3. Register a domain to the private ALB.

   ibmcloud ks ingress domain create --cluster <cluster_name_or_ID> --hostname $<private_ALB_ID_hostname>
   

4. Set the new domain as the default.

   ibmcloud ks ingress domain default replace --cluster <cluster_name_or_ID> --domain <new_domain>
   

The IBM Cloud backend updates headlamp in approximately 5 minutes. When the update completes, the dashboard is available on the new default ingress hostname, with headlamp. subdomain.

Kubernetes resources created by the addon

The Headlamp addon creates several Kubernetes resources in your cluster that require proper network configuration.

If you have a custom firewall or network settings, you need to configure that to allow communication between the following resources:

• 4 Ingress resources
  • private with private-iks-k8s-nginx ingressClass
  • public with public-iks-k8s-nginx ingressClass
  • private with private-iks-traefik ingressClass
  • public with public-iks-traefik ingressClass
• 1 Service (ClusterIP on port 80 → 4466)
• 1 Deployment
  • headlamp container (port 4466)
  • nginx sidecar container

Enable OIDC for Headlamp add-on over public endpoints

If your cluster cannot connect to private IAM endpoints, override the OIDC endpoint settings to use public endpoints.

These steps assume that the cluster can access the IAM public endpoints.

Before you begin, ensure that kubectl is configured for the cluster.

1. Open the headlamp-values ConfigMap for editing:

   kubectl edit cm -n ibm-system headlamp-values
   

   In the editor, add the following to the data section. Replace <account_id> with the ID of the account where the cluster is deployed.

   data:
     values.yaml: |-
       oidc:
         overrides:
           tokenEndpointUrl: "https://iam.cloud.ibm.com/identity/token?account=<account_id>"
           jwksUri: "https://iam.cloud.ibm.com/identity/keys"
   

2. Wait up to 5 minutes for the updated values to propagate to the cluster.

3. Restart the Headlamp deployment:

   kubectl rollout restart deployment/headlamp -n ibm-system
   

Troubleshooting the Headlamp add-on

Use the following information to troubleshoot common issues with the Headlamp add-on.