privilegedescalation/headlamp-polaris-plugin
Archived
12
0
Fork 0
Code Issues 4 Pull Requests 3 Actions Packages Projects Releases 50 Wiki Activity

docs: enhance README with badges, documentation links, and updated features

Browse Source 
Major improvements to README.md:

1. Added badges:
   - CI and E2E test status badges
   - License badge
   - Quick navigation links to docs sections

2. Updated features:
   - Added dark mode support (v0.3.5)
   - Highlighted critical Headlamp v0.39.0+ watchPlugins requirement
   - Updated installation instructions with current best practices

3. Added comprehensive documentation section:
   - Links to all docs/ files (ARCHITECTURE, DEPLOYMENT, SECURITY, TROUBLESHOOTING, TESTING)
   - Table of contents with descriptions
   - Quick reference troubleshooting table

4. Streamlined development section:
   - Quick start commands
   - Testing instructions with examples
   - Links to detailed guides in CONTRIBUTING.md and TESTING.md

5. Updated release process:
   - Reflects GitHub Actions (not Gitea)
   - Documents ArtifactHub 30-minute sync
   - Links to detailed release process in CONTRIBUTING.md

6. Added Contributing section:
   - Links to CONTRIBUTING.md
   - Highlights key development practices

7. General improvements:
   - Removed outdated Gitea references
   - Updated version references to v0.3.5
   - Better organization and navigation
   - Professional footer

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
Chris Farhood
2026-02-11 23:36:07 -05:00
parent d4fe2c9ea9
commit 2c2f04ff5d
1 changed files with 155 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+155 -84
View File
@@ -1,9 +1,14 @@
# headlamp-polaris-plugin # Headlamp Polaris Plugin
[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/polaris)](https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin) [![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/polaris)](https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin)
[![CI](https://github.com/cpfarhood/headlamp-polaris-plugin/actions/workflows/ci.yaml/badge.svg)](https://github.com/cpfarhood/headlamp-polaris-plugin/actions/workflows/ci.yaml)
[![E2E Tests](https://github.com/cpfarhood/headlamp-polaris-plugin/actions/workflows/e2e.yaml/badge.svg)](https://github.com/cpfarhood/headlamp-polaris-plugin/actions/workflows/e2e.yaml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
A [Headlamp](https://headlamp.dev/) plugin that surfaces [Fairwinds Polaris](https://polaris.docs.fairwinds.com/) audit results directly in the Headlamp UI. A [Headlamp](https://headlamp.dev/) plugin that surfaces [Fairwinds Polaris](https://polaris.docs.fairwinds.com/) audit results directly in the Headlamp UI.
**📚 [Documentation](#documentation) | 🚀 [Installation](#installing) | 🔒 [Security](#rbac--security-setup) | 🛠️ [Development](#development)**
## What It Does ## What It Does
Adds a **Polaris** top-level sidebar section to Headlamp with comprehensive security, reliability, and efficiency audit integration: Adds a **Polaris** top-level sidebar section to Headlamp with comprehensive security, reliability, and efficiency audit integration:
@@ -21,6 +26,7 @@ Adds a **Polaris** top-level sidebar section to Headlamp with comprehensive secu
- **Exemption Management** -- add or remove Polaris exemptions via annotation patches directly from the UI; supports per-check exemptions or exempt-all - **Exemption Management** -- add or remove Polaris exemptions via annotation patches directly from the UI; supports per-check exemptions or exempt-all
- **Configurable Dashboard URL** -- supports both Kubernetes service proxy URLs and full HTTP/HTTPS URLs for external Polaris deployments - **Configurable Dashboard URL** -- supports both Kubernetes service proxy URLs and full HTTP/HTTPS URLs for external Polaris deployments
- **Connection Testing** -- test button in settings to verify Polaris dashboard connectivity and show version info - **Connection Testing** -- test button in settings to verify Polaris dashboard connectivity and show version info
- **Dark Mode Support** -- full theme adaptation using MUI CSS variables; drawer, settings, and all UI elements respect system/Headlamp theme
### Data & Refresh ### Data & Refresh
@@ -32,78 +38,89 @@ Error states are handled explicitly with context-specific messages: RBAC denied
## Prerequisites ## Prerequisites
| Requirement | Minimum version | | Requirement | Minimum version |
|-------------|----------------| | -------------------------------- | ------------------ |
| Headlamp | v0.26+ | | Headlamp | v0.26+ |
| Polaris (with dashboard enabled) | Any recent release | | Polaris (with dashboard enabled) | Any recent release |
| Kubernetes | v1.24+ | | Kubernetes | v1.24+ |
Polaris must be deployed in the `polaris` namespace with the dashboard component enabled (`dashboard.enabled: true` in the Helm chart, which is the default). The plugin reads from the `polaris-dashboard` ClusterIP service on port 80. Polaris must be deployed in the `polaris` namespace with the dashboard component enabled (`dashboard.enabled: true` in the Helm chart, which is the default). The plugin reads from the `polaris-dashboard` ClusterIP service on port 80.
## Installing ## Installing
### Option 1: Artifact Hub + Headlamp plugin manager (recommended) ### Option 1: Headlamp Plugin Manager (Recommended)
The plugin is published on [Artifact Hub](https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin). Configure Headlamp's `pluginsManager` in your Helm values to install it automatically: **⚠️ CRITICAL for Headlamp v0.39.0+:** You **must** set `config.watchPlugins: false` or the plugin will not load. See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md#critical-headlamp-v0390-configuration) for details.
The plugin is published on [Artifact Hub](https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin). Configure Headlamp via Helm:
```yaml ```yaml
config:
pluginsDir: /headlamp/plugins
watchPlugins: false # CRITICAL for v0.39.0+
pluginsManager: pluginsManager:
sources: sources:
- url: https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin - name: headlamp-polaris-plugin
url: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/download/v0.3.5/headlamp-polaris-plugin-0.3.5.tar.gz
``` ```
Headlamp will fetch and install the plugin on startup. Or install via the Headlamp UI:
### Option 2: Docker init container 1. Go to **Settings → Plugins**
2. Click **Catalog** tab
3. Search for "Polaris"
4. Click **Install**
The plugin ships as a container image at `git.farh.net/farhoodliquor/headlamp-polaris-plugin`. ### Option 2: Sidecar Container (Alternative)
Add it as an init container in your Headlamp Helm values: For detailed sidecar installation instructions, see [docs/DEPLOYMENT.md#installation-method-2-sidecar-container](docs/DEPLOYMENT.md#installation-method-2-sidecar-container).
```yaml ```yaml
initContainers: sidecars:
- name: polaris-plugin - name: headlamp-plugin
image: git.farh.net/farhoodliquor/headlamp-polaris-plugin:latest image: node:lts-alpine
command: ["sh", "-c", "cp -r /plugins/* /headlamp/plugins/"] command: ['/bin/sh']
args:
- -c
- |
npm install -g @kinvolk/headlamp-plugin
headlamp-plugin install --config /config/plugin.yml
tail -f /dev/null
volumeMounts: volumeMounts:
- name: plugins - name: plugins
mountPath: /headlamp/plugins mountPath: /headlamp/plugins
- name: plugin-config
volumes: mountPath: /config
- name: plugins
emptyDir: {}
volumeMounts:
- name: plugins
mountPath: /headlamp/plugins
``` ```
### Option 3: Manual tarball install ### Option 3: Manual Tarball Install
Download the `.tar.gz` from the [GitHub releases page](https://github.com/cpfarhood/headlamp-polaris-plugin/releases) or the [Gitea releases page](https://git.farh.net/farhoodliquor/headlamp-polaris-plugin/releases), then extract into Headlamp's plugin directory: Download the `.tar.gz` from the [GitHub releases page](https://github.com/cpfarhood/headlamp-polaris-plugin/releases), then extract into Headlamp's plugin directory:
```bash ```bash
tar xzf headlamp-polaris-plugin-<version>.tar.gz -C /headlamp/plugins/ wget https://github.com/cpfarhood/headlamp-polaris-plugin/releases/download/v0.3.5/headlamp-polaris-plugin-0.3.5.tar.gz
tar xzf headlamp-polaris-plugin-0.3.5.tar.gz -C /headlamp/plugins/
``` ```
### Option 4: Build from source ### Option 4: Build from Source
```bash ```bash
git clone https://github.com/cpfarhood/headlamp-polaris-plugin.git
cd headlamp-polaris-plugin
npm install npm install
npm run build npm run build
npx @kinvolk/headlamp-plugin extract . /headlamp/plugins npx @kinvolk/headlamp-plugin extract . /headlamp/plugins
``` ```
## Installing Dev/Preview Versions For complete installation instructions including Helm integration, FluxCD examples, and production deployment checklist, see **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)**.
Dev preview versions are **not currently available** through the Headlamp plugin manager. Stable versions can be installed from ArtifactHub via the plugin manager UI.
## RBAC / Security Setup ## RBAC / Security Setup
The plugin fetches audit data through the Kubernetes API server's **service proxy** sub-resource. The identity making the request (Headlamp's service account, or the user's own token in token-auth mode) must be granted: The plugin fetches audit data through the Kubernetes API server's **service proxy** sub-resource. The identity making the request (Headlamp's service account, or the user's own token in token-auth mode) must be granted:
| Verb | API Group | Resource | Resource Name | Namespace | | Verb | API Group | Resource | Resource Name | Namespace |
|------|-----------|----------|---------------|-----------| | ----- | ----------- | ---------------- | ------------------- | --------- |
| `get` | `""` (core) | `services/proxy` | `polaris-dashboard` | `polaris` | | `get` | `""` (core) | `services/proxy` | `polaris-dashboard` | `polaris` |
### Minimal RBAC manifests ### Minimal RBAC manifests
@@ -115,10 +132,10 @@ metadata:
name: polaris-proxy-reader name: polaris-proxy-reader
namespace: polaris namespace: polaris
rules: rules:
- apiGroups: [""] - apiGroups: ['']
resources: ["services/proxy"] resources: ['services/proxy']
resourceNames: ["polaris-dashboard"] resourceNames: ['polaris-dashboard']
verbs: ["get"] verbs: ['get']
--- ---
apiVersion: rbac.authorization.k8s.io/v1 apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding kind: RoleBinding
@@ -127,8 +144,8 @@ metadata:
namespace: polaris namespace: polaris
subjects: subjects:
- kind: ServiceAccount - kind: ServiceAccount
name: headlamp # adjust to match your Headlamp service account name: headlamp # adjust to match your Headlamp service account
namespace: kube-system # adjust to match the namespace Headlamp runs in namespace: kube-system # adjust to match the namespace Headlamp runs in
roleRef: roleRef:
kind: Role kind: Role
name: polaris-proxy-reader name: polaris-proxy-reader
@@ -153,49 +170,81 @@ The plugin only performs `GET` requests through the service proxy. No `create`,
Every proxied request is recorded in Kubernetes API audit logs as a `get` on `services/proxy` in the `polaris` namespace. If the auto-refresh interval generates more audit volume than desired, increase the refresh interval in the plugin settings or adjust your audit policy. Every proxied request is recorded in Kubernetes API audit logs as a `get` on `services/proxy` in the `polaris` namespace. If the auto-refresh interval generates more audit volume than desired, increase the refresh interval in the plugin settings or adjust your audit policy.
## Documentation
Comprehensive documentation is available in the `docs/` directory:
| Document | Description |
| ------------------------------------------------- | --------------------------------------------------------------------- |
| **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** | System architecture, data flow, component hierarchy, design decisions |
| **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** | Complete deployment guide with Helm, FluxCD, RBAC, network policies |
| **[SECURITY.md](SECURITY.md)** | Security model, RBAC requirements, vulnerability reporting |
| **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** | Common issues, debugging, RBAC testing, network debugging |
| **[TESTING.md](docs/TESTING.md)** | Unit tests, E2E tests, CI/CD, best practices |
| **[CONTRIBUTING.md](CONTRIBUTING.md)** | Development workflow, branching strategy, PR process |
| **[CHANGELOG.md](CHANGELOG.md)** | Complete release history (v0.0.1 to current) |
## Troubleshooting ## Troubleshooting
| Symptom | Likely cause | Fix | **For comprehensive troubleshooting, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).**
|---------|-------------|-----|
| **403 Access Denied** | Missing RBAC binding for `services/proxy` | Apply the Role + RoleBinding from the RBAC section above | Quick reference:
| **404 or 503** | Polaris not installed, or dashboard disabled | Install Polaris with `dashboard.enabled: true` in the `polaris` namespace |
| **No data** | Polaris running but no workloads scanned yet | Wait for the next Polaris audit cycle or restart the Polaris pod | | Symptom | Likely Cause | Quick Fix |
| **Stale data** | Refresh interval too long | Lower the interval in **Settings > Plugins > Polaris** | | ------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
| **Plugin not in sidebar** | Headlamp v0.39.0+ plugin loading issue | Set `config.watchPlugins: false` and hard refresh (Cmd+Shift+R) |
| **403 Access Denied** | Missing RBAC binding for `services/proxy` | Apply Role + RoleBinding from RBAC section |
| **404 or 503** | Polaris not installed, or dashboard disabled | Install Polaris with `dashboard.enabled: true` in `polaris` namespace |
| **Dark mode white backgrounds** | Old plugin version | Upgrade to v0.3.5+ and hard refresh browser |
| **Settings page empty** | Old plugin version | Upgrade to v0.3.3+ |
| **No data / infinite spinner** | Network policy or Polaris pod down | Check network policies and `kubectl get pods -n polaris` |
## Development ## Development
### Setup **For detailed development guide, see [CONTRIBUTING.md](CONTRIBUTING.md).**
### Quick Start
```bash ```bash
# Clone repository
git clone https://github.com/cpfarhood/headlamp-polaris-plugin.git git clone https://github.com/cpfarhood/headlamp-polaris-plugin.git
cd headlamp-polaris-plugin cd headlamp-polaris-plugin
# Install dependencies
npm install npm install
```
### Run locally (hot reload) # Run with hot reload
npm start # Opens Headlamp at http://localhost:4466
```bash # Build for production
npm start
```
This starts the Headlamp plugin dev server. Point a running Headlamp instance at the dev server to see changes live.
### Build for production
```bash
npm run build # outputs dist/main.js npm run build # outputs dist/main.js
npm run package # creates headlamp-polaris-plugin-<version>.tar.gz npm run package # creates headlamp-polaris-plugin-<version>.tar.gz
# Run tests
npm test # unit tests
npm run e2e # E2E tests (requires Headlamp instance)
# Code quality
npm run lint # eslint
npm run tsc # type-check
npm run format # prettier format
``` ```
### Type-check, lint, format, and test ### Running Tests
```bash ```bash
npm run tsc # type-check without emitting # Unit tests (Vitest)
npm run lint # eslint npm test
npm run format:check # prettier check npm run test:watch
npm test # vitest unit tests
# E2E tests (Playwright)
export HEADLAMP_TOKEN=$(kubectl create token headlamp -n kube-system --duration=24h)
npm run e2e
npm run e2e:headed # see browser
``` ```
For complete testing guide including CI/CD integration, see **[docs/TESTING.md](docs/TESTING.md)**.
## Project Structure ## Project Structure
``` ```
@@ -244,11 +293,13 @@ Each check in a `ResultSet` has `Success` (bool) and `Severity` (`"warning"`, `"
The **Skipped** count shown in the plugin only reflects checks with `Severity: "ignore"` in the Polaris API response. It does **not** include annotation-based exemptions (e.g., `polaris.fairwinds.com/privilegeEscalationAllowed-exempt: "true"`). The **Skipped** count shown in the plugin only reflects checks with `Severity: "ignore"` in the Polaris API response. It does **not** include annotation-based exemptions (e.g., `polaris.fairwinds.com/privilegeEscalationAllowed-exempt: "true"`).
**Why?** Polaris completely omits exempted checks from the `results.json` endpoint. The native Polaris dashboard UI computes the "skipped" count client-side by: **Why?** Polaris completely omits exempted checks from the `results.json` endpoint. The native Polaris dashboard UI computes the "skipped" count client-side by:
1. Querying Kubernetes resources (Deployments, DaemonSets, StatefulSets, Pods) directly 1. Querying Kubernetes resources (Deployments, DaemonSets, StatefulSets, Pods) directly
2. Parsing their annotations for `polaris.fairwinds.com/*-exempt` keys 2. Parsing their annotations for `polaris.fairwinds.com/*-exempt` keys
3. Counting how many checks were exempted 3. Counting how many checks were exempted
This plugin only has access to the processed audit results via the service proxy and does not query raw Kubernetes resources. To show accurate exemption counts, the plugin would need to: This plugin only has access to the processed audit results via the service proxy and does not query raw Kubernetes resources. To show accurate exemption counts, the plugin would need to:
- Request cluster-wide read access to all workload types (requires additional RBAC grants beyond `services/proxy`) - Request cluster-wide read access to all workload types (requires additional RBAC grants beyond `services/proxy`)
- Parse annotations on every workload in every namespace - Parse annotations on every workload in every namespace
- Cross-reference with the Polaris check catalog to count exemptions - Cross-reference with the Polaris check catalog to count exemptions
@@ -259,43 +310,63 @@ This is a significant architectural change and is not currently implemented. Hov
## Releasing ## Releasing
Releases are automated via CI. To cut a release: Releases are automated via **GitHub Actions**. To cut a release:
```bash ```bash
# Bump version in package.json and artifacthub-pkg.yml (version + archive-url), then: # 1. Update CHANGELOG.md with new version
git add package.json artifacthub-pkg.yml # 2. Bump version in package.json and artifacthub-pkg.yml:
git add package.json artifacthub-pkg.yml CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z" git commit -m "chore: bump version to X.Y.Z"
git push origin main
# 3. Create and push tag:
git tag vX.Y.Z git tag vX.Y.Z
git push origin main vX.Y.Z git push origin vX.Y.Z
``` ```
This triggers the **Gitea Actions** release workflow (`.gitea/workflows/release.yaml`): This triggers the **GitHub Actions** release workflow (`.github/workflows/release.yaml`):
1. Build the plugin in a `node:20` container 1. Build the plugin in a `node:20` container
2. Package a `.tar.gz` tarball 2. Package a `.tar.gz` tarball
3. Build and push a Docker image to `git.farh.net/farhoodliquor/headlamp-polaris-plugin:{tag}` and `:latest` 3. Create a GitHub release with the tarball attached
4. Create a Gitea release with the tarball attached 4. Calculate SHA256 checksum
5. Create a GitHub release with the same tarball (for Artifact Hub) 5. Update `artifacthub-pkg.yml` checksum on main branch
6. Update `artifacthub-pkg.yml` checksum on main and force-move the tag to match 6. Force-move the tag to include checksum update
A guard step prevents infinite loops: if the release tarball checksum already matches the metadata, the build is skipped. A guard step prevents infinite loops: if the release tarball checksum already matches the metadata, the workflow is skipped.
### CI secrets ### ArtifactHub Sync
| Secret | Where | Purpose | ArtifactHub pulls plugin metadata from GitHub every **30 minutes**. After creating a release:
|---|---|---|
| `REGISTRY_TOKEN` | Gitea | Personal access token with `package:write` scope for Docker image push |
| `GH_PAT` | Gitea | GitHub personal access token for creating GitHub releases |
The Gitea release uses the built-in `github.token`. The `archive-checksum` in `artifacthub-pkg.yml` is updated automatically by the release workflow. - Wait 30 minutes for sync
- Check [ArtifactHub package page](https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin)
- New version should appear in Headlamp plugin catalog
For complete release process and version numbering guidelines, see **[CONTRIBUTING.md#release-process](CONTRIBUTING.md#release-process)**.
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development workflow
- Branching strategy (feature branches required for code changes)
- Commit message conventions (Conventional Commits)
- PR process and review checklist
- Code style guidelines
- Testing requirements
## Links ## Links
- [Artifact Hub](https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin) - **[GitHub Repository](https://github.com/cpfarhood/headlamp-polaris-plugin)** - Source code, issues, releases
- [GitHub (mirror)](https://github.com/cpfarhood/headlamp-polaris-plugin) - **[Artifact Hub](https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin)** - Plugin catalog listing
- [Gitea (source of truth)](https://git.farh.net/farhoodliquor/headlamp-polaris-plugin) - **[Headlamp](https://headlamp.dev/)** - Kubernetes web UI
- [Headlamp](https://headlamp.dev/) - **[Fairwinds Polaris](https://polaris.docs.fairwinds.com/)** - Kubernetes best practices audit tool
- [Fairwinds Polaris](https://polaris.docs.fairwinds.com/)
## License ## License
MIT [MIT License](LICENSE) - see LICENSE file for details.
---
**Made with ❤️ for the Kubernetes community**