Skip to content

Commit a48f258

Browse files
ameijerameijer
authored
Merge pull request #441 from spa-raj/main
Introducing Kubemodel blog post
2 parents 0554244 + 0086649 commit a48f258

File tree

3 files changed

+193
-0
lines changed

3 files changed

+193
-0
lines changed

‎blog/2025-12-09-introducing-kubemodel/img/uid_tracking_metrics.jpg‎

175 KB
Loading

‎blog/2025-12-09-introducing-kubemodel/index.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
slug: introducing-kubemodel
3+
title: "Introducing KubeModel: OpenCost's Next-Generation Data Model"
4+
authors: [sparshraj]
5+
tags: [kubemodel, Data Model 2.0, Kubernetes, UID, LFX mentorship, OpenCost]
6+
---
7+
8+
*This project was initiated as part of the LFX Fall 2025 mentorship program at OpenCost and development is ongoing.*
9+
10+
OpenCost is evolving. As Kubernetes environments grow in complexity with pods being recreated, names being reused, and resources constantly shifting, the need for a more robust, scalable data model has become clear. Today, we're excited to introduce **KubeModel**, the foundation of OpenCost's Data Model 2.0, designed to bring precision, efficiency, and reliability to Kubernetes cost tracking.
11+
12+
<!--truncate-->
13+
14+
## The Challenge: Tracking Resources in a Dynamic Environment
15+
16+
Kubernetes is inherently dynamic. Pods come and go, deployments scale up and down, and resource names can be reused across recreation cycles. Traditional metric tracking that relies solely on resource names struggles in this environment for a number of reasons including:
17+
18+
- **Name reuse**: When a pod is recreated with the same name, historical cost data can become ambiguous. This is particularly problematic in stateful set pods.
19+
- **Resource correlation**: Linking metrics across different time windows becomes unreliable.
20+
- **Debugging complexity**: Without stable identifiers, tracing cost anomalies back to specific resource instances is challenging.
21+
22+
KubeModel addresses these challenges head-on with a comprehensive approach to resource identification and tracking.
23+
24+
## What is KubeModel?
25+
26+
KubeModel is a new data model for Kubernetes resource tracking in OpenCost. It introduces a **flat architecture** with core resource types that mirror Kubernetes primitives:
27+
28+
- **Cluster** - The top-level container
29+
- **Namespace** - Logical resource groupings
30+
- **Node** - Compute instances with CPU, RAM, and GPU details
31+
- **Pod** - The fundamental deployment unit
32+
- **Container** - Individual workload containers
33+
- **Owner/Controller** - Deployments, StatefulSets, ReplicaSets, DaemonSets, Jobs
34+
- **Service** - Network service abstractions
35+
- **Volume & PVC** - Persistent storage resources
36+
- **ResourceQuota** - Namespace resource limits and requests
37+
- **KubeModelSet** - A collection of KubeModel resources for a specific time window
38+
- **GPU** - GPU resource tracking *(Coming soon)*
39+
40+
### Flat Architecture for Performance
41+
42+
Unlike nested hierarchies, KubeModel maintains a **flat map-based structure** enabling O(1) lookups while preserving resource relationships through UIDs and references. This design choice prioritizes:
43+
44+
- **Fast access**: Constant-time lookups regardless of cluster size.
45+
- **Clean relationships**: Resources reference each other via stable identifiers.
46+
- **Efficient serialization**: The flat structure translates well to binary formats.
47+
- **Use case agnostic**: Flexible design supports diverse consumption patterns and applications.
48+
49+
Here's the core KubeModelSet structure that holds all resources for a time window:
50+
51+
`core/pkg/model/kubemodel/kubemodel.go`
52+
```go
53+
type KubeModelSet struct {
54+
Metadata *Metadata `json:"meta"`
55+
Window Window `json:"window"`
56+
Cluster *Cluster `json:"cluster"`
57+
Namespaces map[string]*Namespace `json:"namespaces"`
58+
Containers map[string]*Container `json:"containers,omitempty"`
59+
Owners map[string]*Owner `json:"owners,omitempty"`
60+
Nodes map[string]*Node `json:"nodes,omitempty"`
61+
Pods map[string]*Pod `json:"pods,omitempty"`
62+
Services map[string]*Service `json:"services,omitempty"`
63+
}
64+
```
65+
66+
Each resource type is stored in a flat map keyed by UID, enabling O(1) lookups while maintaining relationships through UID references between resources.
67+
68+
## UID Support: The Heart of Data Model 2.0
69+
70+
The cornerstone of KubeModel is comprehensive **UID (Unique Identifier) support** across all Kubernetes resources. Every resource in Kubernetes has a UID - a stable, unique identifier that persists for the lifetime of that specific resource instance.
71+
72+
![UID Tracking Metrics](./img/uid_tracking_metrics.jpg)
73+
*Figure 1: Prometheus metrics showing UID labels for precise resource identification across queries.*
74+
75+
### Enhanced Metric Tracking
76+
77+
With UID support integrated into OpenCost's metrics, we now have:
78+
79+
- **Stable resource identification** across queries, even when names are reused.
80+
- **Improved cost attribution** to specific resource instances rather than just names.
81+
- **Better multi-cluster support** by preventing resource name conflicts.
82+
- **Enhanced debugging** through stable identifiers throughout the resource lifecycle.
83+
84+
Here's an example of how we track node CPU capacity with UID support:
85+
86+
`pkg/metrics/nodemetrics.go`
87+
```go
88+
type KubeNodeStatusCapacityCPUCoresMetric struct {
89+
fqName string
90+
help string
91+
cores float64
92+
node string
93+
uid string // <-- UID field for unique resource identification
94+
}
95+
96+
func newKubeNodeStatusCapacityCPUCoresMetric(fqname string, node string, uid string, cores float64) KubeNodeStatusCapacityCPUCoresMetric {
97+
return KubeNodeStatusCapacityCPUCoresMetric{
98+
fqName: fqname,
99+
help: "kube_node_status_capacity_cpu_cores Node Capacity CPU Cores",
100+
cores: cores,
101+
node: node,
102+
uid: uid,
103+
}
104+
}
105+
106+
func (nam KubeNodeStatusCapacityCPUCoresMetric) Write(m *dto.Metric) error {
107+
m.Gauge = &dto.Gauge{
108+
Value: &nam.cores,
109+
}
110+
m.Label = []*dto.LabelPair{
111+
{
112+
Name: toStringPtr("node"),
113+
Value: &nam.node,
114+
},
115+
{
116+
Name: toStringPtr("uid"),
117+
Value: &nam.uid,
118+
},
119+
}
120+
return nil
121+
}
122+
```
123+
124+
The `uid` field is now a first-class citizen in every metric struct. The `Write` method serializes it as a Prometheus label, ensuring every emitted metric carries its resource's unique identifier for precise tracking.
125+
126+
### Implementation Scope
127+
128+
The UID implementation spans the entire OpenCost stack:
129+
130+
- **61+ metric result types** enhanced with UID fields
131+
- **30+ Prometheus queries** updated to include UID in aggregation
132+
- **9 resource types** with comprehensive UID validation
133+
- **31 metrics** covered by integration tests
134+
135+
Resources enhanced include Pods, Deployments, StatefulSets, Services, Namespaces, Nodes, PersistentVolumes, PersistentVolumeClaims, Jobs, and ReplicaSets.
136+
137+
## Binary Serialization with Bingen
138+
139+
KubeModel introduces **bingen-annotated Go structs** enabling efficient binary serialization. Bingen is OpenCost specific tooling for generating binary serialization code from annotated Go structs. This provides:
140+
141+
- **Compact storage**: Binary formats are significantly smaller than JSON/YAML
142+
- **Fast serialization/deserialization**: Critical for high-frequency metric collection
143+
- **FinOps-agent integration**: Compatible with date-based storage hierarchies (YYYY/MM/DD)
144+
145+
## Metric Hydration: Bridging Data Sources
146+
147+
The **metric hydration** system populates KubeModelSet instances with data from various sources:
148+
149+
- Prometheus metrics from the costmodel datasource
150+
- Cluster cache transformations for real-time resource state
151+
- Computed values like PublicIPSeconds per node for cloud cost attribution
152+
153+
This creates a unified view of resource metrics that can be serialized, stored, and analyzed efficiently.
154+
155+
## Implemented So Far
156+
157+
KubeModel represents a significant step forward for OpenCost. The foundation has been laid through several contributions:
158+
159+
1. **Core resource types and KubeModelSet** - The fundamental data structures
160+
2. **UID support across all metrics** - Stable resource identification
161+
3. **Binary serialization pipeline** - Efficient storage and transmission
162+
163+
## The Road Ahead
164+
165+
This work is part of a broader effort to modernize OpenCost's architecture, making it more capable of handling the demands of enterprise Kubernetes environments. Upcoming features include:
166+
167+
1. **ResourceQuota integration** - Tracking namespace-level resource constraints
168+
2. **Comprehensive integration tests** - Ensuring reliability at scale
169+
3. **S3 storage support** - Storing compressed KubeModel entries in S3 for scalable, durable, and cost-effective long-term data retention
170+
171+
## Get Involved
172+
173+
KubeModel is being developed in the open, and we welcome contributions. Check out the ongoing work:
174+
175+
- [Core KubeModel Introduction](https://github.com/opencost/opencost/pull/3472)
176+
- [Flat Architecture with Binary Serialization](https://github.com/opencost/opencost/pull/3443)
177+
- [UID Support for K8s Resource Metrics](https://github.com/opencost/opencost/pull/3366)
178+
- [ResourceQuotas Support](https://github.com/opencost/opencost/pull/3435)
179+
- [Initial KubeModel Proposal](https://github.com/opencost/opencost/pull/3485)
180+
181+
## Acknowledgments
182+
183+
A special thanks to my mentors for their guidance and support throughout this project: [Alex Meijer](https://github.com/ameijer), [Sean Holcomb](https://github.com/Sean-Holcomb), and [Niko Kovacevic](https://github.com/nikovacevic).
184+
185+
---
186+
187+
*KubeModel is the next evolution of OpenCost's data infrastructure. As we continue building out Data Model 2.0, we're excited to deliver more accurate, efficient, and reliable Kubernetes cost tracking for the community.*

‎blog/authors.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,9 @@ mewzherder:
4545
title: Kubecost Team
4646
url: https://github.com/mewzherder
4747
image_url: https://avatars.githubusercontent.com/u/7811869?v=4
48+
49+
sparshraj:
50+
name: Sparsh Raj
51+
title: LFX Fall 2025 Mentee @ OpenCost
52+
url: https://github.com/spa-raj
53+
image_url: https://avatars.githubusercontent.com/u/49100336?v=4

0 commit comments

Comments
 (0)