privilegedescalation/headlamp-kube-vip-plugin
12
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 8 Wiki Activity

docs: add architecture decision records

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
DevContainer User
2026-03-05 13:50:01 +00:00
parent 5676ffd876
commit 6940acc780
5 changed files with 298 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/adr/001-react-context-state.md
+66
View File
@@ -0,0 +1,66 @@
# ADR 001: React Context for Centralized State
**Status**: Accepted
**Date**: 2026-03-05
**Deciders**: Development Team
---
## Context
The kube-vip plugin shares data across 4 page views (Overview, Services, Nodes, Config) and 1 detail view section (Service). Data comes from standard Kubernetes resources:
- **Services** (via `useList()`)
- **Nodes** (via `useList()`)
- **DaemonSet** (via `ApiProxy.request()`)
- **Pods** (with fallback, via `ApiProxy.request()`)
- **Leases** (`coordination.k8s.io/v1`, via `ApiProxy.request()`)
- **ConfigMap** (via `ApiProxy.request()`)
The context exposes 12 fields: `kubeVipInstalled`, `daemonSetStatus`, `kubeVipPods`, `cloudProviderPods`, `loadBalancerServices`, `nodes`, `leases`, `ipPools`, `configMapData`, `kubeVipConfig`, `loading`, `error`, and `refresh`.
The plugin uses dual-track fetching: Headlamp `useList()` for Services and Nodes, `ApiProxy.request()` for everything else.
---
## Decision
Use a single `KubeVipDataProvider` React Context wrapping all routes and the Service detail section registration. All kube-vip state is computed in the provider and made available to consumers via the `useKubeVipData()` hook.
---
## Consequences
### Positive
- ✅ Single fetch location eliminates duplicate API calls across views
- ✅ Consistent data across all views at any point in time
- ✅ Derived state (e.g., `ipPools` from ConfigMap) computed once in the provider
- ✅ `refresh()` function updates everything in a single call
### Negative
- ⚠️ All consumers re-render on any change to any of the 12 fields
- ⚠️ Complex provider component managing 12 fields and multiple fetch strategies
These negatives are mitigated by the fact that kube-vip state changes infrequently (VIP assignments and pool configurations are relatively stable), so unnecessary re-renders are rare in practice.
---
## Alternatives Considered
1. **Per-page fetching** — Rejected. Would duplicate DaemonSet, ConfigMap, and Lease fetching across multiple pages, leading to redundant API calls and potential data inconsistency between views.
2. **Multiple contexts** (e.g., separate contexts for pods, services, config) — Rejected. Data is heavily cross-referenced: `kubeVipInstalled` depends on the DaemonSet, pod discovery depends on labels from the DaemonSet, and IP pool utilization requires both ConfigMap data and Service annotations. Splitting contexts would require complex inter-context dependencies.
3. **External state library** (e.g., Redux, Zustand) — Rejected. External state management libraries are not available in the Headlamp plugin runtime environment.
---
## Changelog
| Date | Change |
| ---- | ------ |
| 2026-03-05 | Initial decision recorded |
docs/architecture/adr/002-annotation-based-state.md
+63
View File
@@ -0,0 +1,63 @@
# ADR 002: Annotation-Based State Without CRDs
**Status**: Accepted
**Date**: 2026-03-05
**Deciders**: Development Team
---
## Context
kube-vip does not define any Custom Resource Definitions. All kube-vip state is inferred from standard Kubernetes resources:
- **DaemonSet status** indicates whether kube-vip is installed
- **`kube-vip.io/*` annotations on Services** indicate VIP configuration (requested IP, interface, load balancer class)
- **Lease holder identity** indicates leader election status
- **ConfigMap data** contains IP pool configuration
The plugin must extract kube-vip-specific state from these standard resources without relying on any custom APIs or CRDs.
---
## Decision
Parse kube-vip state entirely from annotations on standard Kubernetes resources and ConfigMap data. No CRDs are queried. Annotation parsing functions in `k8s.ts` extract VIP configuration from Service annotations (e.g., `kube-vip.io/vipAddress`, `kube-vip.io/loadbalancerIPs`). IP pool configuration is parsed from the `kubevip` ConfigMap via `parseIPPools()`. Leader election status is read from Lease `.spec.holderIdentity`.
---
## Consequences
### Positive
- ✅ No CRD dependency — works with any kube-vip installation regardless of version or configuration
- ✅ Uses only standard Kubernetes resources accessible via the standard API
- ✅ Annotation parsing is implemented as pure functions, making it straightforward to test
- ✅ Works across all kube-vip versions that follow the annotation conventions
### Negative
- ⚠️ Annotation schema is implicit — there is no API validation or schema enforcement for annotation values
- ⚠️ Annotations may change across kube-vip versions without notice, since they are not part of a formal API contract
- ⚠️ Parsing logic must handle missing or malformed annotations gracefully
These negatives are mitigated by defensive parsing with fallbacks for missing annotations and sensible defaults when annotation values are absent or unparseable.
---
## Alternatives Considered
1. **kube-vip CRDs** (if they existed) — Not available. kube-vip does not define any Custom Resource Definitions, so there are no custom resources to query.
2. **kube-vip API server** (if it existed) — Not available. kube-vip does not expose a dedicated API server or endpoint for querying its state.
3. **Parse kube-vip pod logs** — Rejected. Log parsing is inherently fragile, depends on log format stability, and requires log access RBAC permissions that may not be available in all environments.
---
## Changelog
| Date | Change |
| ---- | ------ |
| 2026-03-05 | Initial decision recorded |
docs/architecture/adr/003-static-pod-discovery.md
+66
View File
@@ -0,0 +1,66 @@
# ADR 003: Static Pod Discovery with Label Selector Fallback
**Status**: Accepted
**Date**: 2026-03-05
**Deciders**: Development Team
---
## Context
kube-vip can be deployed in two ways:
1. **DaemonSet deployment**: Pods are managed by a DaemonSet and have standard labels (e.g., `app: kube-vip`) that can be used for label-selector based discovery.
2. **Static pod deployment**: Pod manifests are placed in `/etc/kubernetes/manifests/` on each node. Static pods do not have the same labels as DaemonSet-managed pods and follow the naming convention `kube-vip-<node-name>`.
The plugin needs to discover kube-vip pods regardless of the deployment method. The pod fetch uses a two-level fallback strategy: first try label-selector based discovery, then fall back to listing all pods in `kube-system` and filtering by name prefix.
---
## Decision
Implement a two-level pod discovery fallback:
1. **Primary**: Fetch pods using label selector (matches DaemonSet-deployed kube-vip).
2. **Fallback**: If the label-selector fetch fails or returns empty, list all pods in the `kube-system` namespace and filter by `name.startsWith('kube-vip')` (matches static pod naming convention).
This covers both deployment methods without requiring user configuration.
---
## Consequences
### Positive
- ✅ Works with both DaemonSet and static pod deployments out of the box
- ✅ No user configuration needed — deployment method is auto-detected
- ✅ Automatic fallback is transparent to the user and other plugin components
### Negative
- ⚠️ Fallback fetches all `kube-system` pods, which is a broader query than necessary
- ⚠️ Name-prefix matching (`kube-vip`) is convention-dependent and could produce false positives if other pods share the prefix
These negatives are mitigated by the fact that `kube-system` typically has a manageable number of pods, and the name prefix `kube-vip` is the standard convention used by the kube-vip project.
---
## Alternatives Considered
1. **Label selector only** — Rejected. Would miss static pod deployments entirely, leaving users who deploy kube-vip as static pods without visibility.
2. **Name prefix only** — Rejected. Less efficient than label selector for DaemonSet deployments, as it requires listing all pods in the namespace rather than using server-side filtering.
3. **User-configured discovery method** — Rejected. Adds unnecessary configuration burden for something that can be reliably auto-detected through the fallback strategy.
4. **Node filesystem check for static pod manifests** — Rejected. Requires node-level filesystem access, which is not available to Headlamp plugins running in the browser.
---
## Changelog
| Date | Change |
| ---- | ------ |
| 2026-03-05 | Initial decision recorded |
docs/architecture/adr/004-component-testing-strategy.md
+64
View File
@@ -0,0 +1,64 @@
# ADR 004: Comprehensive Component-Level Testing with Shared Helpers
**Status**: Accepted
**Date**: 2026-03-05
**Deciders**: Development Team
---
## Context
The plugin has extensive test coverage including both unit tests (`k8s.ts`, `KubeVipDataContext`) and component render tests (`ConfigPage`, `NodesPage`, `OverviewPage`, `ServiceDetailSection`, `ServicesPage`). Component tests need to mock both Headlamp's API and CommonComponents.
A shared `test-helpers.tsx` file provides fixture factories, and a `__mocks__/commonComponents.ts` file provides stub implementations of Headlamp's CommonComponents for render testing.
---
## Decision
Implement comprehensive component-level testing with two shared test infrastructure files:
1. **`test-helpers.tsx`**: Shared fixture factories for creating test data (mock Services, Nodes, Pods, DaemonSets, ConfigMaps, Leases). Provides consistent test data across all test files.
2. **`__mocks__/commonComponents.ts`**: Stub implementations of Headlamp CommonComponents (`SectionBox`, `SimpleTable`, `StatusLabel`, `NameValueTable`) that render as simple HTML elements for testing.
All component tests render with a `KubeVipDataProvider` wrapper using mocked context values, verifying the component renders correct data from context.
---
## Consequences
### Positive
- ✅ Consistent test fixtures across all test files eliminate divergent test data
- ✅ CommonComponents mocks enable render testing without the full Headlamp runtime
- ✅ Comprehensive coverage of component rendering logic and context integration
- ✅ Easy to add new component tests by reusing existing fixtures and mocks
### Negative
- ⚠️ Mock maintenance burden when Headlamp's CommonComponents API changes
- ⚠️ Test helpers may diverge from actual API shapes over time if not kept in sync
These negatives are mitigated by type-checking test helpers against the actual interfaces, ensuring compile-time detection of API shape mismatches.
---
## Alternatives Considered
1. **Unit tests only** (no component rendering) — Rejected. Misses rendering bugs and context integration issues that only surface when components are mounted with real context values.
2. **E2E tests only** — Rejected. Too slow for rapid development feedback and requires a running Headlamp instance with a connected cluster.
3. **Inline mocks per test file** — Rejected. Leads to inconsistent and duplicated test setup across files, making it harder to maintain and update when APIs change.
4. **Storybook for component testing** — Rejected. Additional tooling overhead is not justified for the scope of this plugin, and Storybook does not easily integrate with Headlamp's plugin component model.
---
## Changelog
| Date | Change |
| ---- | ------ |
| 2026-03-05 | Initial decision recorded |
docs/architecture/adr/README.md
+39
View File
@@ -0,0 +1,39 @@
# Architecture Decision Records
## What is an ADR?
An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. ADRs are used to record the motivation behind decisions so that future team members can understand why certain choices were made.
## Format
This project uses the Nygard-style ADR format:
- **Title**: Short noun phrase describing the decision
- **Status**: Proposed, Accepted, Deprecated, or Superseded
- **Context**: The forces at play, including technical, political, social, and project-specific
- **Decision**: The change that is being proposed or has been agreed upon
- **Consequences**: What becomes easier or harder as a result of this decision
- **Alternatives Considered**: Other options that were evaluated
## Index
| ADR | Title | Status | Date |
| --- | ----- | ------ | ---- |
| [001](001-react-context-state.md) | React Context for Centralized State | Accepted | 2026-03-05 |
| [002](002-annotation-based-state.md) | Annotation-Based State Without CRDs | Accepted | 2026-03-05 |
| [003](003-static-pod-discovery.md) | Static Pod Discovery with Label Selector Fallback | Accepted | 2026-03-05 |
| [004](004-component-testing-strategy.md) | Comprehensive Component-Level Testing with Shared Helpers | Accepted | 2026-03-05 |
## Creating New ADRs
1. Copy an existing ADR as a template
2. Assign the next sequential number (e.g., `005-your-decision.md`)
3. Fill in all sections following the Nygard-style format
4. Set the status to `Proposed` until the team has reviewed and accepted
5. Update the index table in this README
6. Add a changelog entry at the bottom of the ADR
## References
- [Michael Nygard's article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [ADR GitHub organization](https://adr.github.io/)