Chris Farhood
1f2287489c
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>
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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**:
|
|
|
|
1. **Headlamp hooks** (`K8s.ResourceClasses.*.useList()`) — for Services and Nodes.
|
|
2. **`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:
|
|
```typescript
|
|
vi.mock('@kinvolk/headlamp-plugin/lib', () => ({
|
|
ApiProxy: { request: vi.fn().mockResolvedValue({ items: [] }) },
|
|
K8s: {
|
|
ResourceClasses: {
|
|
Service: { useList: vi.fn(() => [[], null]) },
|
|
Node: { useList: vi.fn(() => [[], null]) },
|
|
},
|
|
},
|
|
}));
|
|
```
|