docs: implement Phase 1 - documentation reorganization

Reorganize and consolidate documentation into structured `/docs` directory for better navigation and maintainability. New documentation structure: - docs/README.md - Documentation hub with complete index - docs/getting-started/ - Installation and quick start guides - docs/development/ - Workflow and testing guides - docs/archive/ - Archived PHASE_*.md completion summaries Key changes: - Created docs/ directory with 9 subdirectories - Moved HEADLAMP_INSTALLATION.md → docs/getting-started/installation.md (streamlined) - Created docs/getting-started/quick-start.md (5-minute tutorial) - Moved DEVELOPMENT.md → docs/development/workflow.md - Moved TESTING_GUIDE.md → docs/development/testing.md - Archived 12 PHASE_*.md files to docs/archive/ - Updated CHANGELOG.md with v0.2.0 details - Created main README.md with badges and links to docs Benefits: - Clear documentation hierarchy by user journey - Easier navigation with centralized docs/README.md index - Reduced clutter in repository root - Improved cross-referencing between documents - Better onboarding for new users and contributors Phase 1 deliverables (1-2 days estimated, completed): ✅ Organized docs/ directory structure ✅ Consolidated installation guides ✅ Streamlined development documentation ✅ Updated CHANGELOG to v0.2.0 ✅ Archived phase completion files ✅ Created documentation hub ✅ Updated main README with navigation ✅ Fixed cross-references Next: Phase 2 - API documentation with TypeDoc 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:23:39 -05:00
parent 92cbea0add
commit bdf19cd3bf
19 changed files with 7497 additions and 0 deletions
@@ -0,0 +1,293 @@
+# Installation Guide
+
+Complete guide for installing the Headlamp Sealed Secrets plugin.
+
+## Prerequisites
+
+Before installing the plugin, ensure you have:
+
+1. **Headlamp v0.13.0 or later**
+   - Desktop app, server mode, or Kubernetes deployment
+
+2. **Sealed Secrets Controller** installed in your cluster:
+   ```bash
+   kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml
+   ```
+
+3. **kubectl access** to your Kubernetes cluster with permissions for:
+   - SealedSecret resources (list, get, create)
+   - Service resources (get)
+   - Namespace resources (list)
+
+## Quick Install
+
+### From GitHub Release (Recommended)
+
+Download and extract the latest release:
+
+**macOS:**
+```bash
+curl -LO https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/releases/download/v0.2.0/headlamp-sealed-secrets-0.2.0.tar.gz
+tar -xzf headlamp-sealed-secrets-0.2.0.tar.gz -C ~/Library/Application\ Support/Headlamp/plugins/
+```
+
+**Linux:**
+```bash
+curl -LO https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/releases/download/v0.2.0/headlamp-sealed-secrets-0.2.0.tar.gz
+tar -xzf headlamp-sealed-secrets-0.2.0.tar.gz -C ~/.config/Headlamp/plugins/
+```
+
+**Windows (PowerShell):**
+```powershell
+Invoke-WebRequest -Uri https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/releases/download/v0.2.0/headlamp-sealed-secrets-0.2.0.tar.gz -OutFile headlamp-sealed-secrets-0.2.0.tar.gz
+# Extract to %APPDATA%\Headlamp\plugins\
+```
+
+Then **restart Headlamp**.
+
+### Using Install Script (macOS/Linux)
+
+```bash
+git clone https://github.com/cpfarhood/headlamp-sealed-secrets-plugin
+cd headlamp-sealed-secrets-plugin
+./install-plugin.sh
+```
+
+The script will:
+- Install dependencies
+- Build the plugin
+- Copy files to the correct location
+- Provide next steps
+
+## Installation Methods
+
+### Method 1: Local Build (Development)
+
+For local development or testing:
+
+1. **Clone and build**:
+   ```bash
+   git clone https://github.com/cpfarhood/headlamp-sealed-secrets-plugin
+   cd headlamp-sealed-secrets-plugin/headlamp-sealed-secrets
+   npm install
+   npm run build
+   ```
+
+2. **Copy to plugins directory**:
+
+   **macOS:**
+   ```bash
+   mkdir -p ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets
+   cp dist/main.js package.json ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets/
+   ```
+
+   **Linux:**
+   ```bash
+   mkdir -p ~/.config/Headlamp/plugins/headlamp-sealed-secrets
+   cp dist/main.js package.json ~/.config/Headlamp/plugins/headlamp-sealed-secrets/
+   ```
+
+   **Windows:**
+   ```powershell
+   New-Item -ItemType Directory -Force -Path $env:APPDATA\Headlamp\plugins\headlamp-sealed-secrets
+   Copy-Item dist\main.js, package.json $env:APPDATA\Headlamp\plugins\headlamp-sealed-secrets\
+   ```
+
+3. **Restart Headlamp**
+
+### Method 2: Headlamp Server Mode
+
+For server deployments:
+
+1. **Start Headlamp with plugins directory**:
+   ```bash
+   headlamp-server -plugins-dir=/var/lib/headlamp/plugins
+   ```
+
+2. **Install plugin to server**:
+   ```bash
+   mkdir -p /var/lib/headlamp/plugins/headlamp-sealed-secrets
+   cp dist/main.js package.json /var/lib/headlamp/plugins/headlamp-sealed-secrets/
+   ```
+
+3. **Restart Headlamp server**
+
+### Method 3: Kubernetes Deployment
+
+For Headlamp running in Kubernetes:
+
+1. **Create ConfigMap** with plugin files:
+   ```bash
+   kubectl create configmap headlamp-sealed-secrets-plugin \
+     --from-file=main.js=dist/main.js \
+     --from-file=package.json=package.json \
+     -n headlamp
+   ```
+
+2. **Update 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: sealed-secrets-plugin
+             mountPath: /headlamp/plugins/headlamp-sealed-secrets
+         volumes:
+         - name: sealed-secrets-plugin
+           configMap:
+             name: headlamp-sealed-secrets-plugin
+   ```
+
+3. **Apply and restart**:
+   ```bash
+   kubectl apply -f headlamp-deployment.yaml
+   kubectl rollout restart deployment/headlamp -n headlamp
+   ```
+
+## Verification
+
+After installation, verify the plugin is working:
+
+1. **Open Headlamp** and connect to your cluster
+
+2. **Check sidebar** - Look for "Sealed Secrets" menu item
+
+3. **Navigate to Sealed Secrets**:
+   - You should see the SealedSecrets list view
+   - Controller health status should be visible
+   - "Create Sealed Secret" button should appear (if you have permissions)
+
+4. **Check browser console** (if issues occur):
+   - Open Developer Tools: View → Toggle Developer Tools
+   - Look for plugin loading messages or errors
+
+### Expected Features
+
+After successful installation:
+
+✅ **SealedSecrets List** - View all sealed secrets
+✅ **Create Sealed Secret** - Encrypt and create secrets
+✅ **Sealing Keys** - Download public certificates
+✅ **Controller Health** - Monitor controller status
+✅ **Settings** - Configure plugin behavior
+
+## Troubleshooting
+
+### Plugin Not Appearing
+
+**Check plugin directory**:
+```bash
+# macOS
+ls -la ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets/
+
+# Linux
+ls -la ~/.config/Headlamp/plugins/headlamp-sealed-secrets/
+
+# Should show: main.js and package.json
+```
+
+**Verify Headlamp version**:
+```bash
+headlamp --version  # Should be >= v0.13.0
+```
+
+**Check browser console**:
+1. Open Headlamp
+2. View → Toggle Developer Tools
+3. Look for errors in Console tab
+
+### Controller Not Found
+
+**Verify controller is running**:
+```bash
+kubectl get pods -n kube-system -l name=sealed-secrets-controller
+# Should show: Running pod
+```
+
+**Check controller service**:
+```bash
+kubectl get svc -n kube-system sealed-secrets-controller
+# Should exist with ClusterIP
+```
+
+**Reinstall if needed**:
+```bash
+kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml
+```
+
+### Permission Errors
+
+**Check RBAC permissions**:
+```bash
+# Can you list SealedSecrets?
+kubectl get sealedsecrets --all-namespaces
+
+# Can you get the service?
+kubectl get svc -n kube-system sealed-secrets-controller
+```
+
+**Verify CRD exists**:
+```bash
+kubectl get crd sealedsecrets.bitnami.com
+```
+
+See [Troubleshooting Guide](../troubleshooting/README.md) for more detailed solutions.
+
+## Updating the Plugin
+
+To update to a newer version:
+
+1. **Remove old version**:
+   ```bash
+   # macOS
+   rm -rf ~/Library/Application\ Support/Headlamp/plugins/headlamp-sealed-secrets
+
+   # Linux
+   rm -rf ~/.config/Headlamp/plugins/headlamp-sealed-secrets
+   ```
+
+2. **Install new version** (follow Quick Install above)
+
+3. **Restart Headlamp**
+
+## Uninstallation
+
+To completely 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 -Force $env:APPDATA\Headlamp\plugins\headlamp-sealed-secrets
+```
+
+Then restart Headlamp.
+
+## Next Steps
+
+- [Quick Start Guide](quick-start.md) - Create your first sealed secret
+- [User Guide](../user-guide/README.md) - Learn about all features
+- [Development Guide](../development/workflow.md) - Contribute to the plugin
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/discussions)
+- **Headlamp Docs**: [https://headlamp.dev/docs](https://headlamp.dev/docs)
+- **Sealed Secrets**: [https://github.com/bitnami-labs/sealed-secrets](https://github.com/bitnami-labs/sealed-secrets)
@@ -0,0 +1,230 @@
+# Quick Start Guide
+
+Get started with the Headlamp Sealed Secrets plugin in 5 minutes.
+
+## Prerequisites
+
+Before you begin, ensure:
+
+✅ Plugin is [installed](installation.md)
+✅ Headlamp is connected to your cluster
+✅ Sealed Secrets controller is running
+
+## Step 1: Verify Installation
+
+1. Open Headlamp
+2. Look for **"Sealed Secrets"** in the sidebar
+3. Click on it to open the plugin
+
+You should see:
+- Controller health status (green = healthy)
+- List of existing SealedSecrets (if any)
+- "Create Sealed Secret" button
+
+## Step 2: Create Your First Sealed Secret
+
+### Using the UI
+
+1. **Click "Create Sealed Secret"**
+
+2. **Fill in the form**:
+   - **Name**: `my-first-secret`
+   - **Namespace**: `default` (or your namespace)
+   - **Scope**: `strict` (recommended for production)
+
+3. **Add secret data**:
+   - Click "Add Key"
+   - **Key**: `password`
+   - **Value**: `mysecretvalue`
+
+4. **Click "Create"**
+
+The plugin will:
+- Fetch the public certificate from the controller
+- Encrypt your value client-side
+- Create the SealedSecret in your cluster
+
+### Understanding Scopes
+
+- **strict**: Secret can only be unsealed with same name+namespace (most secure)
+- **namespace-wide**: Can be renamed within the namespace
+- **cluster-wide**: Can be moved anywhere in the cluster
+
+## Step 3: Verify the Sealed Secret
+
+1. **Check the list** - Your new SealedSecret should appear
+
+2. **View details** - Click on `my-first-secret` to see:
+   - Metadata (name, namespace, creation time)
+   - Scope information
+   - Encrypted data (Base64-encoded, encrypted value)
+   - Owner references
+
+3. **Verify the plain Secret was created**:
+   ```bash
+   kubectl get secret my-first-secret -n default
+   ```
+
+The Sealed Secrets controller automatically creates a plain Kubernetes Secret from your SealedSecret.
+
+## Step 4: Use the Secret
+
+The unsealed Secret can be used like any Kubernetes secret:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: secret-test-pod
+spec:
+  containers:
+  - name: test-container
+    image: nginx
+    env:
+    - name: SECRET_PASSWORD
+      valueFrom:
+        secretKeyRef:
+          name: my-first-secret
+          key: password
+```
+
+Apply it:
+```bash
+kubectl apply -f pod.yaml
+```
+
+Verify:
+```bash
+kubectl exec secret-test-pod -- env | grep SECRET_PASSWORD
+# Output: SECRET_PASSWORD=mysecretvalue
+```
+
+## Step 5: Download Sealing Keys (Optional)
+
+For CI/CD or offline encryption:
+
+1. Navigate to **"Sealing Keys"** tab
+
+2. You'll see all active certificates with:
+   - Creation date
+   - Expiry date (with warnings if expiring soon)
+   - Fingerprint
+
+3. **Download certificate**:
+   - Click "Download" on the active key
+   - Save as `sealed-secrets-cert.pem`
+
+4. **Use with kubeseal CLI** (optional):
+   ```bash
+   echo -n mysecretvalue | kubeseal \
+     --cert sealed-secrets-cert.pem \
+     --scope strict \
+     --name my-secret \
+     --namespace default
+   ```
+
+## Common Tasks
+
+### Create a Secret with Multiple Keys
+
+1. Click "Create Sealed Secret"
+2. Add multiple key-value pairs:
+   - Key: `username`, Value: `admin`
+   - Key: `password`, Value: `secret123`
+   - Key: `api-key`, Value: `abc123xyz`
+3. Click "Create"
+
+### Update an Existing Secret
+
+**Note**: You cannot edit SealedSecrets directly. To update:
+
+1. Delete the old SealedSecret:
+   ```bash
+   kubectl delete sealedsecret my-first-secret -n default
+   ```
+
+2. Create a new one with updated values (using the UI)
+
+3. The controller will recreate the plain Secret
+
+### Delete a Sealed Secret
+
+1. Find the secret in the list
+2. Click on it to view details
+3. Click "Delete" button
+4. Confirm deletion
+
+**Warning**: This also deletes the unsealed Secret!
+
+## Troubleshooting
+
+### "Controller not found" Error
+
+**Check controller status**:
+```bash
+kubectl get pods -n kube-system -l name=sealed-secrets-controller
+```
+
+**If not running**, install it:
+```bash
+kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml
+```
+
+### "Permission denied" Error
+
+You need RBAC permissions for SealedSecret resources:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: sealed-secrets-user
+rules:
+- apiGroups: ["bitnami.com"]
+  resources: ["sealedsecrets"]
+  verbs: ["get", "list", "create", "delete"]
+- apiGroups: [""]
+  resources: ["services"]
+  verbs: ["get"]
+```
+
+### Encryption Fails
+
+1. **Check certificate is valid**:
+   - Go to "Sealing Keys" tab
+   - Verify certificate is not expired
+   - Check for expiry warnings
+
+2. **Verify controller connectivity**:
+   ```bash
+   kubectl get svc -n kube-system sealed-secrets-controller
+   ```
+
+3. **Check browser console**:
+   - View → Toggle Developer Tools
+   - Look for encryption errors
+
+## Next Steps
+
+Now that you've created your first sealed secret, explore more features:
+
+- **[User Guide](../user-guide/README.md)** - Learn about all features
+- **[Scopes Explained](../user-guide/scopes-explained.md)** - Deep dive into scope types
+- **[CI/CD Integration](../tutorials/ci-cd-integration.md)** - Automate secret creation
+- **[RBAC Permissions](../user-guide/rbac-permissions.md)** - Configure access control
+
+## Best Practices
+
+1. **Use strict scope** for production secrets
+2. **Store SealedSecrets in Git** (they're safe to commit!)
+3. **Don't store plain Secrets in Git**
+4. **Monitor certificate expiry** (plugin warns 30 days in advance)
+5. **Backup sealing keys** for disaster recovery
+6. **Rotate secrets regularly** (delete and recreate)
+
+## Need Help?
+
+- **Documentation**: [Full docs](../README.md)
+- **Troubleshooting**: [Common issues](../troubleshooting/README.md)
+- **GitHub Issues**: [Report bugs](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/issues)
+- **Discussions**: [Ask questions](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/discussions)