privilegedescalation/headlamp-kube-vip-plugin

Files

T

Chris Farhood 50338ad7c4 docs: redirect install namespace references from kube-system to headlamp

Update documentation to reference the Headlamp plugin namespace (headlamp)
instead of kube-system where kube-vip itself is deployed.

Files changed (all docs only):
- README.md: requirements, troubleshooting table
- CLAUDE.md: data sources, key constants namespace
- SECURITY.md: plugin scope permissions list

Out of scope — left untouched per PRI-340 plan:
- Source files (k8s.ts, KubeVipDataContext.tsx, OverviewPage.tsx)
- Test helpers (test-helpers.tsx) — kube-system is the watched workload namespace
- ADR 003 — describes kube-vip static pod fallback behavior, not install namespace

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-05-04 07:49:25 +00:00

3.8 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Headlamp plugin for kube-vip virtual IP and load balancer visibility. Read-only — monitors kube-vip DaemonSet/pods, LoadBalancer services, nodes, IP pools, and leader election. No cluster write operations.

Plugin name: kube-vip
Target: Headlamp >= v0.26
Data sources: kube-vip DaemonSet/pods in headlamp, Services (type:LoadBalancer), Nodes, Leases, kubevip ConfigMap
Reference plugin: ../headlamp-polaris-plugin

Commands

npm start          # dev server with hot reload
npm run build      # production build
npm run package    # package for headlamp
npm run tsc        # TypeScript type check (no emit)
npm run lint       # ESLint
npm run lint:fix   # ESLint with auto-fix
npm run format     # Prettier write
npm run format:check # Prettier check
npm test           # vitest run
npm run test:watch # vitest watch mode

All tests and tsc must pass before committing.

Architecture

src/
├── index.tsx                         # Plugin entry: registerRoute, registerSidebarEntry, registerDetailsViewSection
├── test-helpers.tsx                  # Shared test utilities and fixtures
├── api/
│   ├── k8s.ts                        # Types + helpers (Services, Nodes, Pods, DaemonSets, Leases, ConfigMaps)
│   └── KubeVipDataContext.tsx        # Shared React context provider
└── components/
    ├── OverviewPage.tsx               # Dashboard: deployment status, cluster summary, VIP overview
    ├── ServicesPage.tsx               # LoadBalancer services with VIP assignments and detail panel
    ├── NodesPage.tsx                  # Nodes with kube-vip pod status and leader election
    ├── ConfigPage.tsx                 # DaemonSet config, IP pools, leases, pod details
    ├── ServiceDetailSection.tsx       # Injected into Headlamp Service detail view
    └── __mocks__/
        └── commonComponents.ts       # Test mocks for headlamp CommonComponents

Data flow

KubeVipDataContext.tsx uses two fetching strategies:

Headlamp hooks (K8s.ResourceClasses.*.useList()) — for Services and Nodes.
ApiProxy.request() — for kube-vip DaemonSet, pods (with label selector fallback for static pods), cloud-provider pods, Leases, and the kubevip ConfigMap.

kube-vip uses no CRDs. All state comes from standard Kubernetes resources and kube-vip.io/* annotations on Services.

Key constants (src/api/k8s.ts)

Namespace: headlamp
DaemonSet name: kube-vip-ds
Cloud provider name: kube-vip-cloud-provider
ConfigMap name: kubevip
Annotation prefix: kube-vip.io/
Pod selector: app.kubernetes.io/name=kube-vip-ds
Cloud provider selector: app=kube-vip-cloud-provider
Metrics port: 2112

Code conventions

Functional React components only — no class components
All imports from @kinvolk/headlamp-plugin/lib and @kinvolk/headlamp-plugin/lib/CommonComponents
No additional UI libraries (no MUI direct imports, no Ant Design, etc.)
TypeScript strict mode — no any, use unknown + type guards at API boundaries
Context provider (KubeVipDataProvider) wraps each route component in index.tsx
Tests: vitest + @testing-library/react, mock with vi.mock('@kinvolk/headlamp-plugin/lib', ...)
vitest.setup.ts provides a spec-compliant localStorage shim for Node 22+ compatibility

Testing

Mock pattern for headlamp APIs:

vi.mock('@kinvolk/headlamp-plugin/lib', () => ({
  ApiProxy: { request: vi.fn().mockResolvedValue({ items: [] }) },
  K8s: {
    ResourceClasses: {
      Service: { useList: vi.fn(() => [[], null]) },
      Node: { useList: vi.fn(() => [[], null]) },
    },
  },
}));

3.8 KiB Raw Permalink Blame History