headlamp-polaris-plugin/docs/getting-started/prerequisites.md

Prerequisites

Before installing the Headlamp Polaris Plugin, ensure your environment meets the following requirements.

Required Components

Requirement	Minimum Version	Recommended Version
Kubernetes	v1.24+	v1.28+
Headlamp	v0.26+	v0.39+
Polaris (dashboard enabled)	Any recent release	Latest stable
Browser	Modern (ES2020+)	Latest Chrome/Firefox/Safari/Edge

Polaris Requirements

The plugin requires Polaris to be deployed with the dashboard component enabled:

• Namespace: polaris (default expected namespace)
• Dashboard enabled: dashboard.enabled: true in Helm chart (default)
• Service: polaris-dashboard ClusterIP service on port 80

Verify Polaris Installation

# Check Polaris pods are running
kubectl -n polaris get pods

# Expected output:
# NAME                                 READY   STATUS    RESTARTS   AGE
# polaris-dashboard-xxxxxxxxx-xxxxx    1/1     Running   0          1h
# polaris-webhook-xxxxxxxxx-xxxxx      1/1     Running   0          1h

# Check Polaris dashboard service exists
kubectl -n polaris get svc polaris-dashboard

# Expected output:
# NAME                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
# polaris-dashboard   ClusterIP   10.96.xxx.xxx   <none>        80/TCP    1h

# Test Polaris dashboard API
kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json | jq .PolarisOutputVersion

# Expected output:
# "1.0"

Install Polaris (if not present)

# Add Fairwinds Helm repository
helm repo add fairwinds-stable https://charts.fairwinds.com/stable
helm repo update

# Install Polaris with dashboard enabled
helm install polaris fairwinds-stable/polaris \
  --namespace polaris \
  --create-namespace \
  --set dashboard.enabled=true

# Wait for pods to be ready
kubectl -n polaris wait --for=condition=ready pod -l app.kubernetes.io/name=polaris --timeout=300s

Headlamp Requirements

Verify Headlamp Installation

# Check Headlamp is deployed
kubectl -n kube-system get pods -l app.kubernetes.io/name=headlamp

# Expected output:
# NAME                        READY   STATUS    RESTARTS   AGE
# headlamp-xxxxxxxxxx-xxxxx   1/1     Running   0          1h

# Check Headlamp version (must be v0.26+)
kubectl -n kube-system get deployment headlamp -o jsonpath='{.spec.template.spec.containers[0].image}'

# Expected output:
# ghcr.io/headlamp-k8s/headlamp:v0.39.0  (or similar)

Install Headlamp (if not present)

# Add Headlamp Helm repository
helm repo add headlamp https://headlamp-k8s.github.io/headlamp/
helm repo update

# Install Headlamp
helm install headlamp headlamp/headlamp \
  --namespace kube-system \
  --set config.pluginsDir="/headlamp/plugins" \
  --set config.watchPlugins=false \
  --set pluginsManager.enabled=true

# Wait for pod to be ready
kubectl -n kube-system wait --for=condition=ready pod -l app.kubernetes.io/name=headlamp --timeout=300s

RBAC Requirements

The plugin requires permissions to access the Polaris dashboard via Kubernetes service proxy.

Required Permission

Verb	API Group	Resource	Resource Name	Namespace
get	"" (core)	services/proxy	polaris-dashboard	polaris

Verify RBAC Permissions

# Test if Headlamp service account has permission
kubectl auth can-i get services/proxy \
  --as=system:serviceaccount:kube-system:headlamp \
  -n polaris \
  --resource-name=polaris-dashboard

# Expected output: yes

# If "no", you need to create RBAC (see installation guide)

Network Requirements

Service Proxy Access

The plugin accesses Polaris through the Kubernetes API server's service proxy:

Headlamp Pod → Kubernetes API Server → Polaris Dashboard Service

Required network paths:

• Headlamp pod → Kubernetes API server (443)
• Kubernetes API server → Polaris dashboard service (80)

NetworkPolicy Considerations

If the polaris namespace has NetworkPolicies enabled, ensure the Kubernetes API server can reach the polaris-dashboard service on port 80.

Test Network Connectivity

# Test service proxy endpoint from API server
kubectl get --raw /api/v1/namespaces/polaris/services/polaris-dashboard:80/proxy/results.json | jq . > /dev/null

# If successful, no output
# If failed, check NetworkPolicies and service status

Browser Requirements

The plugin uses modern JavaScript features and requires:

• ES2020+ support
• localStorage enabled
• JavaScript enabled
• Cookies enabled (for Headlamp session)

Tested Browsers

Browser	Minimum Version
Chrome/Chromium	80+
Firefox	75+
Safari	13.1+
Edge	80+

Optional Components

OIDC Authentication (for multi-user deployments)

If using Headlamp with OIDC authentication, each user must have RBAC permissions for service proxy access (see RBAC Permissions).

Ingress (for external access)

If exposing Headlamp externally, configure an Ingress with TLS:

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: headlamp.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: headlamp-tls
      hosts:
        - headlamp.example.com

Pre-Installation Checklist

Before proceeding to installation, verify:

• Kubernetes cluster v1.24+ running
• Polaris deployed in polaris namespace with dashboard enabled
• Polaris dashboard service accessible via service proxy
• Headlamp v0.26+ deployed
• RBAC permissions configured (or ready to configure)
• Network connectivity between API server and Polaris dashboard
• Modern browser available

Next Steps

Once all prerequisites are met:

1. Installation Guide - Choose installation method and deploy the plugin
2. Quick Start - Get up and running in 5 minutes
3. RBAC Permissions - Detailed RBAC configuration

Troubleshooting

If any prerequisite check fails, see:

• Troubleshooting Guide - Common issues and solutions
• RBAC Issues - Permission debugging
• Network Problems - Connectivity issues