chore: bump version to 0.3.1

- Update package.json version - Update artifacthub-pkg.yml version and archive URL - Add PROJECT_ASSESSMENT.md for tracking improvements - Add deployment/ directory with plugin loading fix documentation 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 21:48:04 -05:00
parent c1156e5cf5
commit 20e8063cbb
5 changed files with 434 additions and 3 deletions
@@ -0,0 +1,58 @@
+# Headlamp Plugin Loading Issue - Root Cause and Fix
+
+## Problem
+Headlamp v0.39.0 was not loading plugins installed via the plugin manager. Plugins appeared in Settings → Plugins but:
+- No sidebar entries appeared
+- No plugin settings were available
+- Plugin JavaScript was not being executed in the browser
+
+## Root Cause
+When `config.watchPlugins: true` (the default), Headlamp treats catalog-managed plugins in `/headlamp/plugins/` as "development directory" plugins. This causes:
+- Backend serves plugin metadata correctly
+- Backend logs show "Treating catalog-installed plugin in development directory as user plugin"
+- **Frontend does NOT execute the plugin JavaScript**
+- Plugin registrations (`registerSidebarEntry`, `registerRoute`, etc.) never happen
+
+## Solution
+Set `config.watchPlugins: false` in the Headlamp HelmRelease values:
+
+```yaml
+spec:
+  values:
+    config:
+      watchPlugins: false
+    pluginsManager:
+      enabled: true
+      configContent: |
+        plugins:
+          - name: polaris
+            source: https://artifacthub.io/packages/headlamp/polaris/headlamp-polaris-plugin
+          # ... other plugins
+```
+
+## Why This Works
+With `watchPlugins: false`:
+- Headlamp no longer treats catalog-managed plugins as "development" plugins
+- Frontend properly loads and executes plugin JavaScript on startup
+- Plugin registrations happen correctly
+- All plugin features (sidebar, routes, settings, etc.) work as expected
+
+## Testing
+After applying this fix:
+1. Verify plugins are installed: `kubectl logs -n kube-system <headlamp-pod> -c headlamp-plugin`
+2. Verify watchPlugins is false: `kubectl logs -n kube-system <headlamp-pod> -c headlamp | grep "Watch Plugins"`
+3. Hard refresh browser (Cmd+Shift+R / Ctrl+Shift+F5) to clear cached JavaScript
+4. Verify plugin sidebar entries appear
+5. Verify plugin functionality works
+
+## Additional Notes
+- This appears to be a bug/limitation in Headlamp v0.39.0
+- The `watchPlugins` feature is intended for development scenarios where plugins are being actively modified
+- For production deployments with catalog-managed plugins, `watchPlugins: false` is the correct configuration
+- Once plugins are loaded, subsequent restarts or updates work correctly as long as `watchPlugins` remains false
+
+## References
+- Headlamp Helm Chart: https://github.com/headlamp-k8s/headlamp/tree/main/charts/headlamp
+- Plugin Manager: https://github.com/headlamp-k8s/headlamp/tree/main/plugins/headlamp-plugin
+- Issue discovered: 2026-02-11
+- Fix applied: 2026-02-12
@@ -0,0 +1,83 @@
+---
+# Custom Headlamp values for static plugin installation
+# This disables the plugin manager and uses an init container instead
+
+# Disable the plugin manager sidecar
+pluginsManager:
+  enabled: false
+
+# Use an init container to install plugins to /headlamp/static-plugins
+initContainers:
+  - name: install-plugins
+    image: node:lts-alpine
+    command:
+      - /bin/sh
+      - -c
+      - |
+        set -e
+        echo "Installing plugins to /headlamp/static-plugins..."
+
+        # Create plugins directory
+        mkdir -p /headlamp/static-plugins
+
+        # Set up npm cache
+        export NPM_CONFIG_CACHE=/tmp/npm-cache
+        export NPM_CONFIG_USERCONFIG=/tmp/npm-userconfig
+        mkdir -p /tmp/npm-cache /tmp/npm-userconfig
+
+        # Install polaris plugin
+        echo "Installing polaris plugin..."
+        cd /headlamp/static-plugins
+        npm pack headlamp-polaris-plugin@0.3.0
+        tar -xzf headlamp-polaris-plugin-0.3.0.tgz
+        mv package headlamp-polaris-plugin
+        rm headlamp-polaris-plugin-0.3.0.tgz
+
+        # Install other plugins
+        npx --yes @headlamp-k8s/plugin@latest install \
+          --source https://artifacthub.io/packages/headlamp/headlamp-plugins/headlamp_flux \
+          --folderName /headlamp/static-plugins
+
+        npx --yes @headlamp-k8s/plugin@latest install \
+          --source https://artifacthub.io/packages/headlamp/headlamp-trivy/headlamp_trivy \
+          --folderName /headlamp/static-plugins
+
+        npx --yes @headlamp-k8s/plugin@latest install \
+          --source https://artifacthub.io/packages/headlamp/headlamp-plugins/headlamp_cert-manager \
+          --folderName /headlamp/static-plugins
+
+        npx --yes @headlamp-k8s/plugin@latest install \
+          --source https://artifacthub.io/packages/headlamp/headlamp-plugins/headlamp_ai_assistant \
+          --folderName /headlamp/static-plugins
+
+        echo "All plugins installed successfully"
+        ls -la /headlamp/static-plugins
+    securityContext:
+      runAsUser: 100
+      runAsGroup: 101
+      runAsNonRoot: true
+      privileged: false
+    resources:
+      requests:
+        cpu: 100m
+        memory: 256Mi
+      limits:
+        memory: 512Mi
+    volumeMounts:
+      - name: static-plugins
+        mountPath: /headlamp/static-plugins
+
+# Configure headlamp to use static plugins
+config:
+  pluginsDir: /headlamp/static-plugins
+
+# Add volume for static plugins
+volumes:
+  - name: static-plugins
+    emptyDir: {}
+
+# Add volume mount to main container
+volumeMounts:
+  - name: static-plugins
+    mountPath: /headlamp/static-plugins
+    readOnly: true