Chris Farhood
24033ca977
Remove all references to the incorrect `config.watchPlugins: false` requirement that was believed necessary for Headlamp v0.39.0+. Investigation revealed that plugins work correctly with the default `watchPlugins: true` setting. The earlier documentation was based on a misunderstanding of the plugin loading mechanism. Changes: - Remove watchPlugins: false from all YAML configuration examples - Remove warning sections about watchPlugins requirement - Update troubleshooting guides to focus on actual issues - Simplify installation instructions by removing unnecessary config Files updated: - README.md (main installation docs and troubleshooting table) - docs/DEPLOYMENT.md - docs/TROUBLESHOOTING.md - docs/getting-started/* (quick-start, installation, prerequisites) - docs/deployment/* (helm, production) - docs/troubleshooting/* (common-issues, README) - Multiple other doc files formatted by prettier This cleanup ensures ArtifactHub and GitHub documentation show correct, simplified installation instructions. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
225 lines
6.8 KiB
Markdown
225 lines
6.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](../user-guide/rbac-permissions.md)).
|
|
|
|
### Ingress (for external access)
|
|
|
|
If exposing Headlamp externally, configure an Ingress with TLS:
|
|
|
|
```yaml
|
|
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](installation.md)** - Choose installation method and deploy the plugin
|
|
2. **[Quick Start](quick-start.md)** - Get up and running in 5 minutes
|
|
3. **[RBAC Permissions](../user-guide/rbac-permissions.md)** - Detailed RBAC configuration
|
|
|
|
## Troubleshooting
|
|
|
|
If any prerequisite check fails, see:
|
|
|
|
- **[Troubleshooting Guide](../troubleshooting/README.md)** - Common issues and solutions
|
|
- **[RBAC Issues](../troubleshooting/rbac-issues.md)** - Permission debugging
|
|
- **[Network Problems](../troubleshooting/network-problems.md)** - Connectivity issues
|