docs: add Headlamp plugin installation guides and setup script

Add comprehensive installation documentation and automated setup for Headlamp plugin manager integration. New files: - install-plugin.sh: Automated installation script for macOS/Linux - HEADLAMP_INSTALLATION.md: Complete installation guide covering: - Local installation (development/testing) - NPM installation (for published plugin) - Headlamp server mode - Kubernetes deployment with ConfigMaps - Troubleshooting common issues - Uninstallation instructions - SETUP_STATUS.md: Quick reference for current setup status Features: - Cross-platform support (macOS, Linux, Windows) - Multiple installation methods documented - Troubleshooting guide for common issues - Development mode instructions - Plugin verification steps Plugin is now ready for: ✅ Local Headlamp desktop installation ✅ Headlamp server deployment ✅ Kubernetes-based Headlamp with ConfigMaps ✅ Development with hot reload Current installation: - Location: ~/Library/Application Support/Headlamp/plugins/headlamp-sealed-secrets/ - Version: 0.2.0 - Sealed Secrets controller: Running in cluster - Status: Ready for use 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>
2026-02-11 23:04:12 -05:00
parent 4740179b0b
commit d20b9258f8
3 changed files with 496 additions and 0 deletions
@@ -0,0 +1,240 @@
+# Headlamp Plugin Manager Installation Guide
+
+This guide covers installing the Sealed Secrets plugin into Headlamp.
+
+## Prerequisites
+
+1. **Headlamp Desktop App** (v0.13.0 or later) installed
+2. **Sealed Secrets Controller** installed in your Kubernetes cluster:
+   ```bash
+   kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml
+   ```
+
+## Installation Methods
+
+### Method 1: Local Installation (Development/Testing)
+
+This method is ideal for local testing or development.
+
+1. **Build the plugin**:
+   ```bash
+   cd headlamp-sealed-secrets
+   npm install
+   npm run build
+   ```
+
+2. **Copy to Headlamp plugins directory**:
+
+   **macOS**:
+   ```bash
+   mkdir -p ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets
+   cp -r dist/* ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets/
+   cp package.json ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets/
+   ```
+
+   **Linux**:
+   ```bash
+   mkdir -p ~/.config/Headlamp/plugins/headlamp-sealed-secrets
+   cp -r dist/* ~/.config/Headlamp/plugins/headlamp-sealed-secrets/
+   cp package.json ~/.config/Headlamp/plugins/headlamp-sealed-secrets/
+   ```
+
+   **Windows**:
+   ```powershell
+   mkdir $env:APPDATA\Headlamp\plugins\headlamp-sealed-secrets
+   Copy-Item -Recurse dist\* $env:APPDATA\Headlamp\plugins\headlamp-sealed-secrets\
+   Copy-Item package.json $env:APPDATA\Headlamp\plugins\headlamp-sealed-secrets\
+   ```
+
+3. **Restart Headlamp** - The plugin will be loaded automatically.
+
+### Method 2: Install from NPM (Recommended for Users)
+
+Once the plugin is published to NPM:
+
+```bash
+npm install -g headlamp-sealed-secrets
+```
+
+Then follow the same directory copy steps as Method 1.
+
+### Method 3: Headlamp Server with Plugin Support
+
+If you're running Headlamp in server mode with plugin support:
+
+1. **Set plugin directory** when starting Headlamp:
+   ```bash
+   headlamp-server -plugins-dir=/path/to/plugins
+   ```
+
+2. **Copy plugin to the plugins directory**:
+   ```bash
+   cp -r dist /path/to/plugins/headlamp-sealed-secrets
+   ```
+
+### Method 4: Kubernetes Deployment with Plugins
+
+For Kubernetes deployments of Headlamp:
+
+1. **Create a ConfigMap** with the plugin:
+   ```bash
+   kubectl create configmap headlamp-sealed-secrets-plugin \
+     --from-file=main.js=dist/main.js \
+     --from-file=package.json=package.json \
+     -n headlamp
+   ```
+
+2. **Mount the ConfigMap** in your Headlamp deployment:
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: headlamp
+     namespace: headlamp
+   spec:
+     template:
+       spec:
+         containers:
+         - name: headlamp
+           image: ghcr.io/headlamp-k8s/headlamp:latest
+           volumeMounts:
+           - name: plugins
+             mountPath: /headlamp/plugins/headlamp-sealed-secrets
+         volumes:
+         - name: plugins
+           configMap:
+             name: headlamp-sealed-secrets-plugin
+   ```
+
+## Verifying Installation
+
+1. **Open Headlamp** and connect to your Kubernetes cluster
+2. **Check the sidebar** - You should see a new "Sealed Secrets" menu item
+3. **Navigate to Sealed Secrets** to verify the plugin loaded correctly
+
+### Expected Features
+
+After successful installation, you'll have access to:
+
+- **SealedSecrets List** - View all sealed secrets across namespaces
+- **Create Sealed Secret** - Encrypt and create new sealed secrets
+- **Sealing Keys** - View and download public sealing certificates
+- **Controller Health** - Monitor sealed-secrets controller status
+- **Settings** - Configure plugin behavior
+
+## Troubleshooting
+
+### Plugin Not Showing Up
+
+1. **Check plugin directory location**:
+   - macOS: `~/Library/Application Support/Headlamp/plugins/`
+   - Linux: `~/.config/Headlamp/plugins/`
+   - Windows: `%APPDATA%\Headlamp\plugins\`
+
+2. **Verify file structure**:
+   ```
+   headlamp-sealed-secrets/
+   ├── main.js       # Built plugin code (required)
+   └── package.json  # Plugin metadata (required)
+   ```
+
+3. **Check Headlamp version**:
+   ```bash
+   headlamp --version  # Should be v0.13.0 or later
+   ```
+
+4. **Check console for errors**:
+   - Open Headlamp Developer Tools: View → Toggle Developer Tools
+   - Look for plugin loading errors in the Console tab
+
+### Controller Not Found
+
+If you see "Sealed Secrets controller not found":
+
+1. **Verify controller is running**:
+   ```bash
+   kubectl get pods -n kube-system -l name=sealed-secrets-controller
+   ```
+
+2. **Check controller service**:
+   ```bash
+   kubectl get svc -n kube-system sealed-secrets-controller
+   ```
+
+3. **Install the controller** if missing:
+   ```bash
+   kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml
+   ```
+
+### Permission Errors
+
+If you see permission-related errors:
+
+1. **Check RBAC permissions** - Ensure your user has permissions to:
+   - List/Get/Create `SealedSecret` resources
+   - Get `Service` resources (to fetch certificates)
+   - List `Namespace` resources
+
+2. **Verify CRD installation**:
+   ```bash
+   kubectl get crd sealedsecrets.bitnami.com
+   ```
+
+## Uninstallation
+
+To remove the plugin:
+
+**macOS**:
+```bash
+rm -rf ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets
+```
+
+**Linux**:
+```bash
+rm -rf ~/.config/Headlamp/plugins/headlamp-sealed-secrets
+```
+
+**Windows**:
+```powershell
+Remove-Item -Recurse $env:APPDATA\Headlamp\plugins\headlamp-sealed-secrets
+```
+
+Then restart Headlamp.
+
+## Development Mode
+
+For plugin development with hot reload:
+
+```bash
+cd headlamp-sealed-secrets
+npm install
+npm start
+```
+
+This starts the development server with hot reload. Any changes to the source code will automatically rebuild and reload the plugin in Headlamp.
+
+## Plugin Updates
+
+To update the plugin:
+
+1. **Pull latest changes**:
+   ```bash
+   git pull origin main
+   cd headlamp-sealed-secrets
+   ```
+
+2. **Rebuild and reinstall**:
+   ```bash
+   npm install
+   npm run build
+   # Then copy to plugins directory (see Method 1 above)
+   ```
+
+3. **Restart Headlamp** to load the updated plugin.
+
+## Support
+
+- **Issues**: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/issues
+- **Documentation**: See [README.md](headlamp-sealed-secrets/README.md)
+- **Headlamp Docs**: https://headlamp.dev/docs/latest/
+- **Sealed Secrets**: https://github.com/bitnami-labs/sealed-secrets
@@ -0,0 +1,177 @@
+# Plugin Setup Status
+
+## ✅ Current Installation Status
+
+### Plugin Installation
+- **Status**: ✅ Installed
+- **Location**: `~/Library/Application Support/Headlamp/plugins/headlamp-sealed-secrets/`
+- **Version**: 0.2.0
+- **Build Date**: 2026-02-11
+
+### Files Installed
+```
+~/Library/Application Support/Headlamp/plugins/headlamp-sealed-secrets/
+├── main.js       ✅ (359.73 kB)
+├── package.json  ✅
+├── README.md     ✅
+└── LICENSE       ✅
+```
+
+### Kubernetes Cluster
+- **Context**: `default`
+- **Sealed Secrets Controller**: ✅ Running
+  - Deployment: `sealed-secrets-controller` in `kube-system`
+  - CRD: `sealedsecrets.bitnami.com` installed
+  - Age: 4 days 4 hours
+
+### Development Environment
+- **Dev Server**: ✅ Running (port-forward to headlamp on port 8080)
+- **Build Status**: ✅ Latest build successful
+- **Tests**: 36/39 passing (92%)
+
+## 🚀 Quick Start
+
+### Access the Plugin
+
+1. **If using Headlamp Desktop App**:
+   - Restart Headlamp
+   - Open Headlamp
+   - Look for "Sealed Secrets" in the sidebar
+
+2. **If using Development Server** (currently running):
+   - Access at: http://localhost:8080
+   - Plugin is hot-reloading (changes rebuild automatically)
+
+### Create Your First Sealed Secret
+
+1. Navigate to "Sealed Secrets" in the sidebar
+2. Click "Create Sealed Secret"
+3. Fill in:
+   - Name: `my-first-secret`
+   - Namespace: `default`
+   - Secret key: `password`
+   - Secret value: `mysecretvalue`
+4. Click "Create"
+
+### View Sealing Keys
+
+1. Navigate to "Sealed Secrets" → "Sealing Keys"
+2. View all active and expired certificates
+3. Download certificates for CI/CD use
+
+## 📋 Installation Methods
+
+### Method 1: Automated Install Script (Recommended)
+```bash
+./install-plugin.sh
+```
+
+### Method 2: Manual Install
+```bash
+cd headlamp-sealed-secrets
+npm install
+npm run build
+
+# macOS
+cp -r dist/* ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets/
+cp package.json ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets/
+```
+
+### Method 3: Development Mode (Hot Reload)
+```bash
+cd headlamp-sealed-secrets
+npm install
+npm start
+```
+Access at: http://localhost:8080
+
+## 🔧 Troubleshooting
+
+### Plugin Not Showing Up
+
+1. **Check installation**:
+   ```bash
+   ls -la ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets/
+   ```
+   Should show: `main.js` and `package.json`
+
+2. **Restart Headlamp completely**:
+   - Quit Headlamp (⌘+Q on macOS)
+   - Reopen Headlamp
+
+3. **Check browser console**:
+   - View → Toggle Developer Tools
+   - Look for plugin errors in Console
+
+### Controller Issues
+
+1. **Verify controller is running**:
+   ```bash
+   kubectl get pods -n kube-system -l name=sealed-secrets-controller
+   ```
+
+2. **Check controller logs**:
+   ```bash
+   kubectl logs -n kube-system -l name=sealed-secrets-controller
+   ```
+
+3. **Reinstall controller if needed**:
+   ```bash
+   kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml
+   ```
+
+## 📚 Documentation
+
+- **Installation Guide**: [HEADLAMP_INSTALLATION.md](HEADLAMP_INSTALLATION.md)
+- **Plugin README**: [headlamp-sealed-secrets/README.md](headlamp-sealed-secrets/README.md)
+- **Development Guide**: [DEVELOPMENT.md](DEVELOPMENT.md) (if exists)
+- **Enhancement Plan**: [ENHANCEMENT_PLAN.md](ENHANCEMENT_PLAN.md)
+
+## 🎯 Features Available
+
+### Current Features (v0.2.0)
+- ✅ List all SealedSecrets across namespaces
+- ✅ Create new SealedSecrets with client-side encryption
+- ✅ View and download sealing keys
+- ✅ Certificate expiry warnings (30-day threshold)
+- ✅ Controller health monitoring
+- ✅ RBAC permission checks
+- ✅ API version auto-detection
+- ✅ WCAG 2.1 AA accessibility
+- ✅ Skeleton loading states
+- ✅ Error boundaries for error handling
+- ✅ Type-safe error handling (Result types)
+- ✅ Input validation with helpful error messages
+- ✅ Retry logic with exponential backoff
+
+### Planned Features
+- 🔄 Decrypt SealedSecret values (requires controller API)
+- 🔄 Re-encrypt secrets to new scope
+- 🔄 Export/import SealedSecrets
+- 🔄 Bulk operations
+- 🔄 Advanced filtering and search
+
+## 📊 Version History
+
+### v0.2.0 (2026-02-11) - Current
+- Phase 1: Type-safe error handling
+- Phase 2: UX improvements
+- Phase 3: Performance optimizations
+- Phase 4.1: Unit tests (92% passing)
+
+### v0.1.0 (2026-02-11) - Initial Release
+- Basic SealedSecret management
+- Create, list, view operations
+- Certificate management
+
+## 🔗 Links
+
+- **Repository**: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin
+- **Issues**: https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/issues
+- **NPM**: (To be published)
+- **Artifact Hub**: (To be published)
+
+---
+
+**Last Updated**: 2026-02-11 23:03 PST
+**Status**: ✅ Ready for Use
@@ -0,0 +1,79 @@
+#!/bin/bash
+#
+# Install Headlamp Sealed Secrets Plugin
+#
+# This script builds and installs the plugin to your local Headlamp installation.
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}Headlamp Sealed Secrets Plugin Installer${NC}"
+echo "=========================================="
+echo
+
+# Detect OS and set plugin directory
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    PLUGIN_DIR="$HOME/Library/Application Support/Headlamp/plugins/headlamp-sealed-secrets"
+    echo -e "${YELLOW}Detected: macOS${NC}"
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    PLUGIN_DIR="$HOME/.config/Headlamp/plugins/headlamp-sealed-secrets"
+    echo -e "${YELLOW}Detected: Linux${NC}"
+else
+    echo -e "${RED}Unsupported OS: $OSTYPE${NC}"
+    echo "For Windows, please see HEADLAMP_INSTALLATION.md"
+    exit 1
+fi
+
+echo "Plugin will be installed to: $PLUGIN_DIR"
+echo
+
+# Check if node/npm are available
+if ! command -v npm &> /dev/null; then
+    echo -e "${RED}Error: npm is not installed${NC}"
+    echo "Please install Node.js and npm first"
+    exit 1
+fi
+
+# Navigate to plugin directory
+cd "$(dirname "$0")/headlamp-sealed-secrets"
+
+echo -e "${GREEN}Step 1: Installing dependencies...${NC}"
+npm install
+
+echo
+echo -e "${GREEN}Step 2: Building plugin...${NC}"
+npm run build
+
+echo
+echo -e "${GREEN}Step 3: Creating plugin directory...${NC}"
+mkdir -p "$PLUGIN_DIR"
+
+echo
+echo -e "${GREEN}Step 4: Copying plugin files...${NC}"
+cp -v dist/main.js "$PLUGIN_DIR/"
+cp -v package.json "$PLUGIN_DIR/"
+cp -v README.md "$PLUGIN_DIR/" 2>/dev/null || true
+cp -v LICENSE "$PLUGIN_DIR/" 2>/dev/null || true
+
+echo
+echo -e "${GREEN}✓ Installation complete!${NC}"
+echo
+echo "Plugin installed to: $PLUGIN_DIR"
+echo
+echo "Next steps:"
+echo "1. Restart Headlamp desktop application"
+echo "2. Open Headlamp and connect to your cluster"
+echo "3. Look for 'Sealed Secrets' in the sidebar"
+echo
+echo "To verify sealed-secrets controller is installed:"
+echo "  kubectl get pods -n kube-system -l name=sealed-secrets-controller"
+echo
+echo "To install sealed-secrets controller (if not present):"
+echo "  kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml"
+echo