DevContainer User
2.6 KiB
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
-
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.
-
kube-vip API server (if it existed) — Not available. kube-vip does not expose a dedicated API server or endpoint for querying its state.
-
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 |