DevContainer User
64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
# 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 |
|