e2e: shared volume plugin deployment for CI tests (#59)

* e2e: shared volume plugin deployment replacing init container approach Replace the init container plugin installation with a shared PVC volume between the CI runner and Headlamp pod. The runner builds the plugin and copies it to the shared mount; Headlamp reads from the same volume. - Add deployment/headlamp-e2e-values.yaml (PVC-backed shared volume) - Add deployment/headlamp-plugins-pvc.yaml (PVC manifest) - Add scripts/deploy-plugin-via-volume.sh (build + copy + restart) - Remove deployment/headlamp-static-plugin-values.yaml (init container) This is CI-only test infrastructure — ArtifactHub remains the sole user-facing distribution channel. Co-Authored-By: Paperclip <noreply@paperclip.ing> * ci: update e2e workflow for shared volume plugin deployment Replace the old preflight-only approach with a build-and-deploy flow that uses a shared volume (hostPath) between the CI runner and the Headlamp pod. The workflow now builds the plugin from source, copies the artifact to a shared volume path, and optionally calls Gandalf's deploy script for Headlamp rollout coordination. Removes kubectl exec/cp references and version-match preflight in favor of deploying the PR's actual build artifact. Refs: PRI-216, PRI-195 Co-Authored-By: Paperclip <noreply@paperclip.ing> * ci: align e2e workflow with Gandalf's deploy script interface Simplify deploy step to call scripts/deploy-plugin-via-volume.sh directly instead of duplicating copy logic. Align env var names (PLUGIN_VOLUME_PATH, HEADLAMP_DEPLOY) with the deploy script's expected interface from PR #59. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: deploy plugin via temporary pod instead of assuming local PVC mount The deploy script assumed the PVC was mounted on the CI runner at /mnt/headlamp-plugins, but the runner pod doesn't have that mount. Fix by using a temporary pod (kubectl run) that mounts the PVC, receives the plugin tarball via stdin, and extracts it. Also adds missing workflow steps to create the PVC and upgrade Headlamp with the shared volume helm values before deploying. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: add kubectl, helm, and helm repo setup steps to e2e workflow The self-hosted runner doesn't have kubectl or helm pre-installed. Add setup steps using azure/setup-kubectl and azure/setup-helm actions, and add the Headlamp helm repo before the upgrade step. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: update Headlamp Helm repo URL from headlamp-k8s to kubernetes-sigs The Headlamp project moved to the kubernetes-sigs org. The old Helm chart repository URL (headlamp-k8s.github.io) returns 404, causing E2E workflow failure at the `helm repo add` step. Co-Authored-By: Paperclip <noreply@paperclip.ing> * chore: add RBAC manifest for E2E CI runner Documents the Role and RoleBinding applied to the cluster for the ARC runner service account. Grants permissions in kube-system needed for shared volume plugin deployment (PVCs, pods, Helm resources). Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: remove .github/workflows/e2e.yaml changes from PR The workflow changes should be handled separately by Hugh Hackman per PRI-215. This PR should only contain deployment manifests and scripts, not CI workflow modifications. Co-Authored-By: Paperclip <noreply@paperclip.ing> * ci: add shared volume plugin deployment to E2E workflow Adds the build, Helm, PVC, and plugin deploy steps needed for the shared volume E2E approach. Uses the correct kubernetes-sigs Helm repo URL and overrides config.sessionTTL=0 to avoid schema validation error. This is the workflow counterpart to the deployment manifests and scripts already in this PR (PVC, values overlay, deploy script). Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): set sessionTTL=1 to satisfy Helm schema minimum The Headlamp Helm chart schema enforces a minimum of 1 for config.sessionTTL. Setting it to 0 caused helm upgrade to fail with a schema validation error. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): add cluster-scoped RBAC for CI runner The Headlamp Helm chart manages ClusterRole and ClusterRoleBinding resources. The CI runner SA needs cluster-level permissions to get/update these during helm upgrade. Added ClusterRole and ClusterRoleBinding alongside the existing namespace-scoped Role. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): replace helm upgrade with kubectl patch to avoid cluster RBAC The CI runner SA cannot access cluster-scoped resources (ClusterRole, ClusterRoleBinding) needed by helm upgrade's 3-way merge. Replace the helm upgrade step with kubectl patch commands that add the shared volume mount directly to the Headlamp deployment. This eliminates the need for cluster-admin intervention: - kubectl patch adds PVC volume + volumeMount to the deployment - kubectl set env configures the plugins directory - kubectl rollout status waits for the update Also removes the now-unnecessary ClusterRole/ClusterRoleBinding from the RBAC manifest — only namespace-scoped Role/RoleBinding is needed. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): improve volume mount idempotency check Check for existing volume mount by mountPath and PVC claimName, not just by volume name. A prior helm upgrade may have created mounts with different names but the same path, causing kubectl patch to fail with "mountPath must be unique". Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): schedule deploy pod on same node as Headlamp The headlamp-plugins PVC is ReadWriteOnce, so the temporary deploy pod must run on the same node as the Headlamp pod to mount it. Look up the Headlamp pod's node and set nodeName in the pod spec. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): use Job with base64 tarball instead of kubectl run stdin The kubectl run --rm -i stdin pipe times out in the ARC runner environment. Replace with a Kubernetes Job that receives the plugin tarball as base64-encoded data in the container command. This avoids the unreliable attach/stdin mechanism entirely. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): use ConfigMap for tarball instead of inline base64 Embedding base64 data in the YAML spec broke parsing. Store the plugin tarball in a ConfigMap via --from-file and mount it in the deploy Job. This avoids both the stdin pipe issue and the YAML escaping issue. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): use temp file for Job YAML to avoid heredoc escaping Variable expansion inside heredocs breaks YAML parsing when values contain colons and quotes (like nodeName). Write the Job manifest to a temp file with literal YAML, then sed-substitute the dynamic values. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): use Pod instead of Job for plugin deploy The CI runner SA has permission to create Pods but not Jobs in kube-system. Switch from a Job to a plain Pod with restartPolicy:Never. Use ConfigMap mount for tarball data (no stdin piping needed). Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: align registerPluginSettings name with deployed plugin directory The plugin is deployed to the 'polaris' directory but was registered with 'headlamp-polaris', causing Headlamp to not match the settings component with the loaded plugin. This fixes all 5 failing E2E settings tests. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: use package name for registerPluginSettings, not directory name Headlamp identifies plugins by their package.json name (headlamp-polaris), not the deploy directory name (polaris). The previous commit incorrectly changed this to 'polaris', causing the settings component to never render in the plugin settings page — breaking all 5 E2E settings tests. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: align registerPluginSettings name with deploy directory 'polaris' The shared volume deploy script places the plugin at /headlamp/plugins/polaris/, so Headlamp matches settings by directory name 'polaris', not the package.json name 'headlamp-polaris'. This reverts commit b9d718b which incorrectly changed the registration name back to 'headlamp-polaris'. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: align plugin deploy dir with package.json name, clean stale dirs The PVC had a stale headlamp-polaris directory from a previous install. Headlamp loads plugins by scanning the plugins dir and reading package.json from each subdirectory — it was loading the old build from headlamp-polaris/ while the deploy script was writing to polaris/. The settings registration name needs to match the plugin name Headlamp identifies. Changes: - Deploy script now uses headlamp-polaris as the directory name (matching package.json name field) - Deploy pod cleans up both polaris/ and headlamp-polaris/ before deploying to ensure no stale copies remain - registerPluginSettings uses headlamp-polaris to match Headlamp's plugin identifier Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix: align registerPluginSettings and E2E test with package.json name Headlamp identifies plugins by reading package.json from the plugin directory. Since package.json name is 'headlamp-polaris', both the registerPluginSettings call and the E2E settings test must use 'headlamp-polaris', not 'polaris'. - registerPluginSettings('polaris') → registerPluginSettings('headlamp-polaris') - E2E test locator: text=polaris → text=headlamp-polaris Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): load main page before settings to ensure plugin list is populated Headlamp's PluginSettings component initializes its state from localStorage on mount and never syncs when props.plugins updates later. If the settings page loads before fetchAndExecutePlugins completes, the plugin list stays empty and the test can't find "headlamp-polaris". Fix: navigate to the main page first, wait for the Polaris sidebar entry to confirm the plugin is loaded (which populates localStorage), then navigate to the settings page. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): use client-side routing for settings navigation The PluginSettings component reads the plugin registry once on mount and never re-renders when new plugins register. Using page.goto() for the settings URL re-initializes the SPA, causing PluginSettings to mount before async plugin scripts finish calling registerPluginSettings(). Replace page.goto() with pushState + popstate to do client-side routing. This preserves the already-loaded plugin registrations from the main page, so PluginSettings sees the plugin immediately on mount. Co-Authored-By: Paperclip <noreply@paperclip.ing> * fix(e2e): use correct HOME-context URL for plugin settings page The settings page is at /settings/plugins (HOME sidebar context), not /c/main/settings/plugins (in-cluster context). The in-cluster URL doesn't match any route, so PluginSettings never mounted and the plugin entry was never visible. With the correct URL, no preloading or client-side routing hacks are needed — PluginSettings uses useTypedSelector on the Redux plugin store, so it re-renders automatically when registerPluginSettings() fires. Co-Authored-By: Paperclip <noreply@paperclip.ing> --------- Co-authored-by: Gandalf the Greybeard <gandalf@privilegedescalation.dev> Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Hugh Hackman <hugh@privilegedescalation.com> Co-authored-by: Hugh Hackman <hugh-hackman[bot]@users.noreply.github.com>
2026-03-18 02:42:42 +00:00
parent 76c7a5bc1f
commit 2a60029104
10 changed files with 326 additions and 111 deletions
@@ -7,6 +7,10 @@ on:
    branches: [main]
  workflow_dispatch:

+env:
+  HEADLAMP_NAMESPACE: kube-system
+  HEADLAMP_DEPLOY: headlamp
+
 jobs:
  e2e:
    runs-on: local-ubuntu-latest
@@ -25,46 +29,104 @@ jobs:
      - name: Install dependencies
        run: npm ci

-      - name: Preflight — verify Headlamp and plugin version
+      - name: Build plugin
+        run: npm run build
+
+      - name: Setup kubectl
+        uses: azure/setup-kubectl@v4
+
+      - name: Ensure PVC exists
+        run: kubectl apply -f deployment/headlamp-plugins-pvc.yaml
+
+      - name: Patch Headlamp deployment with shared volume mount
+        run: |
+          NS="$HEADLAMP_NAMESPACE"
+          DEPLOY="$HEADLAMP_DEPLOY"
+
+          # Check if the plugins volume and mount already exist (by name or mountPath)
+          DEPLOY_JSON=$(kubectl get deploy "$DEPLOY" -n "$NS" -o json)
+          HAS_VOL=$(echo "$DEPLOY_JSON" | \
+            python3 -c "import sys,json; d=json.load(sys.stdin); vols=d['spec']['template']['spec'].get('volumes',[]); print('yes' if any(v.get('persistentVolumeClaim',{}).get('claimName')=='headlamp-plugins' or v.get('name')=='plugins' for v in vols) else '')")
+          HAS_MOUNT=$(echo "$DEPLOY_JSON" | \
+            python3 -c "import sys,json; d=json.load(sys.stdin); mounts=d['spec']['template']['spec']['containers'][0].get('volumeMounts',[]); print('yes' if any(m.get('mountPath')=='/headlamp/plugins' or m.get('name')=='plugins' for m in mounts) else '')")
+
+          NEEDS_PATCH=false
+
+          if [ -z "$HAS_VOL" ]; then
+            echo "Adding plugins PVC volume..."
+            kubectl patch deploy "$DEPLOY" -n "$NS" --type=json -p '[
+              {"op":"add","path":"/spec/template/spec/volumes/-","value":{
+                "name":"plugins",
+                "persistentVolumeClaim":{"claimName":"headlamp-plugins"}
+              }}
+            ]'
+            NEEDS_PATCH=true
+          else
+            echo "Plugins volume already present, skipping."
+          fi
+
+          if [ -z "$HAS_MOUNT" ]; then
+            echo "Adding plugins volume mount..."
+            kubectl patch deploy "$DEPLOY" -n "$NS" --type=json -p '[
+              {"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-","value":{
+                "name":"plugins",
+                "mountPath":"/headlamp/plugins",
+                "readOnly":true
+              }}
+            ]'
+            NEEDS_PATCH=true
+          else
+            echo "Plugins volume mount already present, skipping."
+          fi
+
+          # Set the plugins directory via env var
+          kubectl set env deploy/"$DEPLOY" -n "$NS" \
+            HEADLAMP_CONFIG_PLUGIN_DIR=/headlamp/plugins
+
+          # Wait for rollout
+          kubectl rollout status deploy/"$DEPLOY" -n "$NS" --timeout=120s
+
+      - name: Deploy plugin via shared volume
+        run: scripts/deploy-plugin-via-volume.sh
+
+      - name: Preflight — verify Headlamp and plugin availability
        env:
          HEADLAMP_URL: ${{ secrets.HEADLAMP_URL || 'http://headlamp.kube-system.svc.cluster.local' }}
        run: |
+          PLUGIN_NAME=$(node -p "require('./package.json').name")
          EXPECTED=$(node -p "require('./package.json').version")
-          PLUGIN_NAME=$(node -p "require('./package.json').artifacthub?.name || require('./package.json').name")
-          echo "Expected: $PLUGIN_NAME@$EXPECTED"
+          echo "Expecting: $PLUGIN_NAME@$EXPECTED"
+
+          # Wait for Headlamp to be reachable
+          for i in $(seq 1 30); do
+            HTTP_CODE=$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 5 "$HEADLAMP_URL" || true)
+            if [ "$HTTP_CODE" != "000" ]; then
+              echo "Headlamp responded HTTP $HTTP_CODE"
+              break
+            fi
+            echo "Waiting for Headlamp... ($i/30)"
+            sleep 2
+          done

-          # Check Headlamp connectivity
-          HTTP_CODE=$(curl -s -o /dev/null -w '%{http_code}' --connect-timeout 10 "$HEADLAMP_URL" || true)
          if [ "$HTTP_CODE" = "000" ]; then
-            echo "::error::Cannot reach Headlamp at $HEADLAMP_URL"
+            echo "::error::Cannot reach Headlamp at $HEADLAMP_URL after 60s"
            exit 1
          fi
-          echo "Headlamp responded HTTP $HTTP_CODE"

-          # Check installed plugins and version match
+          # Verify plugin is visible
          PLUGIN_JSON=$(curl -sf --connect-timeout 10 "$HEADLAMP_URL/plugins" 2>/dev/null || echo "[]")
          node -e "
-            const expected = '$EXPECTED';
-            const pluginName = '$PLUGIN_NAME';
            const plugins = JSON.parse(process.argv[1]);
            console.log('Installed plugins:');
            for (const p of plugins) console.log('  ' + p.name + '@' + (p.version||'unknown'));
-            const ours = plugins.find(p => p.name === pluginName || p.name === 'polaris' || p.name.includes('polaris'));
+            const ours = plugins.find(p => p.name === '$PLUGIN_NAME' || p.name === 'polaris' || p.name.includes('polaris'));
            if (!ours) {
-              console.log('::warning::Plugin ' + pluginName + ' not found in Headlamp — data-dependent tests will fail');
+              console.log('::warning::Plugin $PLUGIN_NAME not yet visible — Headlamp may need a restart');
            } else {
              console.log('Found plugin: ' + ours.name + ' at path ' + ours.path);
            }
          " "$PLUGIN_JSON"

-          # Fetch deployed plugin version from package.json
-          DEPLOYED_VERSION=$(curl -sf --connect-timeout 10 "$HEADLAMP_URL/plugins/$PLUGIN_NAME/package.json" 2>/dev/null \
-            | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version" 2>/dev/null || echo "unknown")
-          echo "Deployed version: $DEPLOYED_VERSION"
-          if [ "$DEPLOYED_VERSION" != "$EXPECTED" ] && [ "$DEPLOYED_VERSION" != "unknown" ]; then
-            echo "::warning::Version mismatch — repo has $EXPECTED but Headlamp runs $DEPLOYED_VERSION. Tests may fail due to stale plugin."
-          fi
-
      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

@@ -0,0 +1,59 @@
+---
+# RBAC for the GitHub Actions CI runner to perform E2E test setup.
+# CI-only test fixture — NOT for production use.
+#
+# Grants the ARC runner service account namespace-scoped permissions in
+# kube-system to patch the Headlamp deployment (add shared volume mount),
+# manage PVCs, run temporary pods, and restart deployments.
+#
+# No cluster-scoped permissions needed — the E2E workflow uses kubectl patch
+# instead of helm upgrade, avoiding the need to read ClusterRole/ClusterRoleBinding.
+#
+# Apply with: kubectl apply -f deployment/e2e-ci-runner-rbac.yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: e2e-ci-runner
+  namespace: kube-system
+rules:
+  - apiGroups: [""]
+    resources: ["persistentvolumeclaims"]
+    verbs: ["get", "list", "create", "update", "patch", "delete"]
+  - apiGroups: [""]
+    resources: ["pods"]
+    verbs: ["get", "list", "create", "delete", "watch"]
+  - apiGroups: [""]
+    resources: ["pods/attach"]
+    verbs: ["create", "get"]
+  - apiGroups: ["apps"]
+    resources: ["deployments"]
+    verbs: ["get", "list", "patch", "watch"]
+  - apiGroups: ["apps"]
+    resources: ["deployments/scale"]
+    verbs: ["patch"]
+  - apiGroups: [""]
+    resources: ["secrets"]
+    verbs: ["get", "list", "create", "update", "patch", "delete"]
+  - apiGroups: [""]
+    resources: ["configmaps"]
+    verbs: ["get", "list", "create", "update", "patch", "delete"]
+  - apiGroups: [""]
+    resources: ["services"]
+    verbs: ["get", "list", "create", "update", "patch", "delete"]
+  - apiGroups: [""]
+    resources: ["serviceaccounts"]
+    verbs: ["get", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: e2e-ci-runner-binding
+  namespace: kube-system
+subjects:
+  - kind: ServiceAccount
+    name: local-ubuntu-latest-gha-rs-no-permission
+    namespace: arc-runners
+roleRef:
+  kind: Role
+  name: e2e-ci-runner
+  apiGroup: rbac.authorization.k8s.io
@@ -0,0 +1,22 @@
+---
+# Headlamp Helm values for E2E testing with shared volume plugin deployment.
+#
+# The CI runner and Headlamp pod share a PVC so that the runner can copy
+# built plugin artifacts directly into Headlamp's plugins directory.
+# This is a CI-only mechanism — production plugin distribution uses ArtifactHub.
+
+# Point Headlamp at the shared plugins mount
+config:
+  pluginsDir: /headlamp/plugins
+
+# PVC-backed volume shared with the CI runner
+volumes:
+  - name: plugins
+    persistentVolumeClaim:
+      claimName: headlamp-plugins
+
+# Mount into the Headlamp container
+volumeMounts:
+  - name: plugins
+    mountPath: /headlamp/plugins
+    readOnly: true
@@ -0,0 +1,14 @@
+---
+# PVC for sharing built plugin artifacts between the CI runner and Headlamp.
+# Used only in E2E test environments — not for production.
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: headlamp-plugins
+  namespace: kube-system
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 128Mi
@@ -1,83 +0,0 @@
---
-# 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
@@ -19,7 +19,7 @@ Helm provides the easiest way to deploy and manage the plugin in production. Thi

 ```bash
 # Add Headlamp Helm repository
-helm repo add headlamp https://headlamp-k8s.github.io/headlamp/
+helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
 helm repo update
 ```

@@ -210,7 +210,7 @@ metadata:
  namespace: flux-system
 spec:
  interval: 1h
-  url: https://headlamp-k8s.github.io/headlamp/
+  url: https://kubernetes-sigs.github.io/headlamp/
 ```

 ### HelmRelease
@@ -84,7 +84,7 @@ kubectl -n kube-system get deployment headlamp -o jsonpath='{.spec.template.spec

 ```bash
 # Add Headlamp Helm repository
-helm repo add headlamp https://headlamp-k8s.github.io/headlamp/
+helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
 helm repo update

 # Install Headlamp
@@ -2,11 +2,17 @@ import { test, expect, Page } from '@playwright/test';

 /** Navigate to the Polaris plugin settings page and wait for settings to render. */
 async function goToPolarisSettings(page: Page) {
-  await page.goto('/c/main/settings/plugins');
+  // Headlamp's plugin settings page is a HOME-context route at /settings/plugins,
+  // not an in-cluster route (/c/main/settings/plugins would 404). Headlamp loads
+  // plugin scripts asynchronously on SPA init. When registerPluginSettings() fires,
+  // it dispatches a Redux action — PluginSettings uses useTypedSelector so it
+  // re-renders automatically once the plugin registers. No preloading needed.
+  await page.goto('/settings/plugins');

-  // Find and click the Polaris plugin entry to open its settings
-  const pluginEntry = page.locator('text=polaris').first();
-  await expect(pluginEntry).toBeVisible({ timeout: 15_000 });
+  // Wait for the plugin to appear in the settings list. The timeout covers
+  // async plugin script loading + registration.
+  const pluginEntry = page.locator('text=headlamp-polaris').first();
+  await expect(pluginEntry).toBeVisible({ timeout: 30_000 });
  await pluginEntry.click();

  // Wait for the PolarisSettings component to render
@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# deploy-plugin-via-volume.sh
+#
+# Copies the built plugin into the shared PVC so Headlamp picks it up.
+# Uses a temporary Kubernetes Job to write to the PVC — the CI runner
+# does NOT need the PVC mounted locally.
+#
+# Usage:
+#   scripts/deploy-plugin-via-volume.sh
+#
+# Environment:
+#   HEADLAMP_NAMESPACE  — namespace where Headlamp runs (default: kube-system)
+#   HEADLAMP_DEPLOY     — Headlamp deployment name (default: headlamp)
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+HEADLAMP_NAMESPACE="${HEADLAMP_NAMESPACE:-kube-system}"
+HEADLAMP_DEPLOY="${HEADLAMP_DEPLOY:-headlamp}"
+
+# The deployed directory name must match the package.json name and
+# the registerPluginSettings name. Headlamp identifies plugins by
+# reading package.json from each subdirectory of the plugins dir.
+PLUGIN_DIR_NAME="headlamp-polaris"
+DIST_DIR="$REPO_ROOT/dist"
+
+if [ ! -d "$DIST_DIR" ]; then
+  echo "ERROR: dist/ not found. Run 'npm run build' first." >&2
+  exit 1
+fi
+
+echo "Deploying plugin to shared volume via temporary job..."
+echo "  Source:    $DIST_DIR"
+echo "  PVC:       headlamp-plugins"
+echo "  Plugin:    $PLUGIN_DIR_NAME"
+
+# Create tarball of plugin dist + package.json
+TAR_FILE=$(mktemp /tmp/plugin-XXXXXX.tar.gz)
+tar -czf "$TAR_FILE" -C "$DIST_DIR" . -C "$REPO_ROOT" package.json
+echo "  Tarball:   $TAR_FILE ($(du -h "$TAR_FILE" | cut -f1))"
+
+# Find the node where Headlamp is running — the PVC is ReadWriteOnce so
+# the deploy job must land on the same node to mount it.
+HEADLAMP_NODE=$(kubectl get pods -n "$HEADLAMP_NAMESPACE" \
+  -l "app.kubernetes.io/name=headlamp" \
+  -o jsonpath='{.items[0].spec.nodeName}' 2>/dev/null || true)
+if [ -z "$HEADLAMP_NODE" ]; then
+  HEADLAMP_NODE=$(kubectl get pods -n "$HEADLAMP_NAMESPACE" \
+    -l "app.kubernetes.io/instance=headlamp" \
+    -o jsonpath='{.items[0].spec.nodeName}' 2>/dev/null || true)
+fi
+if [ -n "$HEADLAMP_NODE" ]; then
+  echo "  Headlamp node: $HEADLAMP_NODE (scheduling deploy job there)"
+fi
+
+# Clean up any previous deploy resources
+kubectl delete pod plugin-deploy -n "$HEADLAMP_NAMESPACE" --ignore-not-found --wait=true 2>/dev/null || true
+kubectl delete configmap plugin-tarball -n "$HEADLAMP_NAMESPACE" --ignore-not-found 2>/dev/null || true
+sleep 2
+
+# Store the tarball in a ConfigMap (binary-safe via --from-file)
+echo "Creating ConfigMap with plugin tarball..."
+kubectl create configmap plugin-tarball \
+  -n "$HEADLAMP_NAMESPACE" \
+  --from-file=plugin.tar.gz="$TAR_FILE"
+
+# Build the Pod manifest as a temp file to avoid heredoc YAML escaping issues
+POD_FILE=$(mktemp /tmp/plugin-deploy-pod-XXXXXX.yaml)
+
+cat > "$POD_FILE" <<'YAMLDOC'
+apiVersion: v1
+kind: Pod
+metadata:
+  name: plugin-deploy
+spec:
+  restartPolicy: Never
+  containers:
+    - name: deploy
+      image: busybox:1.36
+      command: ["sh", "-c"]
+      args:
+        - |
+          echo "Cleaning up stale plugin directories..."
+          rm -rf /plugins/polaris /plugins/headlamp-polaris
+          echo "Extracting plugin to shared volume..."
+          mkdir -p /plugins/PLUGIN_DIR_PLACEHOLDER
+          tar -xzf /tarball/plugin.tar.gz -C /plugins/PLUGIN_DIR_PLACEHOLDER
+          echo "Files deployed:"
+          ls -la /plugins/PLUGIN_DIR_PLACEHOLDER/
+      volumeMounts:
+        - name: plugins
+          mountPath: /plugins
+        - name: tarball
+          mountPath: /tarball
+          readOnly: true
+  volumes:
+    - name: plugins
+      persistentVolumeClaim:
+        claimName: headlamp-plugins
+    - name: tarball
+      configMap:
+        name: plugin-tarball
+YAMLDOC
+
+# Substitute plugin dir name
+sed -i "s/PLUGIN_DIR_PLACEHOLDER/${PLUGIN_DIR_NAME}/g" "$POD_FILE"
+
+# Add nodeName if we know which node Headlamp is on
+if [ -n "$HEADLAMP_NODE" ]; then
+  sed -i "/restartPolicy: Never/i\\  nodeName: ${HEADLAMP_NODE}" "$POD_FILE"
+fi
+
+echo "Starting deploy pod..."
+kubectl apply -n "$HEADLAMP_NAMESPACE" -f "$POD_FILE"
+rm -f "$POD_FILE"
+
+# Wait for the pod to complete (Succeeded phase)
+echo "Waiting for deploy pod to complete..."
+kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/plugin-deploy \
+  -n "$HEADLAMP_NAMESPACE" --timeout=120s
+
+# Show logs
+kubectl logs plugin-deploy -n "$HEADLAMP_NAMESPACE" 2>/dev/null || true
+
+# Clean up
+kubectl delete pod plugin-deploy -n "$HEADLAMP_NAMESPACE" --ignore-not-found 2>/dev/null || true
+kubectl delete configmap plugin-tarball -n "$HEADLAMP_NAMESPACE" --ignore-not-found 2>/dev/null || true
+
+rm -f "$TAR_FILE"
+
+# Restart Headlamp to pick up the new plugin
+echo "Restarting Headlamp deployment to load plugin..."
+kubectl rollout restart "deployment/$HEADLAMP_DEPLOY" -n "$HEADLAMP_NAMESPACE"
+kubectl rollout status "deployment/$HEADLAMP_DEPLOY" -n "$HEADLAMP_NAMESPACE" --timeout=120s
+
+echo "Plugin deployed successfully."
@@ -99,7 +99,7 @@ registerRoute({
 });

 // Register plugin settings
-registerPluginSettings('polaris', PolarisSettings, true);
+registerPluginSettings('headlamp-polaris', PolarisSettings, true);

 // Register details view section for supported controller types
 registerDetailsViewSection(({ resource }) => {