diff --git a/HEADLAMP_INSTALLATION.md b/HEADLAMP_INSTALLATION.md new file mode 100644 index 0000000..1da4b9d --- /dev/null +++ b/HEADLAMP_INSTALLATION.md @@ -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 diff --git a/SETUP_STATUS.md b/SETUP_STATUS.md new file mode 100644 index 0000000..435f88f --- /dev/null +++ b/SETUP_STATUS.md @@ -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 diff --git a/install-plugin.sh b/install-plugin.sh new file mode 100755 index 0000000..f1bf29a --- /dev/null +++ b/install-plugin.sh @@ -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