Cilium Multi-Pool IPAM - RemainingIps metrics implementation

## Inspiration

As someone passionate about contributing to meaningful open source projects, I found my inspiration in a real-world operational pain point with Cilium's Multi-Pool IPAM (found when i search for ssue on github) . while node-level IP capacity metrics existed, there was no per-pool visibility into remaining IP capacity. This meant clusters could experience silent IP exhaustion in one pool while others had capacity, leading to pod scheduling failures without early warning.

I realized this was a huge observability gap affecting the entire Cilium community. The chance to solve a real problem that impacts platform reliability for countless users worldwide. while contributing to a major CNCF project I deeply respect, became my driving motivation.

## What it does

The cilium_ipam_remaining_ips metric provides real-time per-pool IP availability monitoring for Cilium's multi-pool IPAM deployments. It exposes remaining IPs per pool with support for both IPv4 and IPv6, enabling operators to: 1) Detect IP pool exhaustion before it causes failures 2) Implement proactive alerting 3) Plan long-term capacity for multi-pool IPAM infrastructure 4) Monitor dual-stack deployments with per-family visibility

## How I built it

I architected this as a comprehensive extension to Cilium's IPAM subsystem:

Core Algorithm Foundation

CIDR Range Mathematics -Developed precise algorithms to calculate available addresses across multiple CIDR blocks

Efficient IP Counting - Implemented iterative allocator scanning handling both IPv4 and IPv6 address spaces

Big Integer Arithmetic - Built robust handling for IPv6's massive address space using Go's big.Int

System Architecture

Multi-Allocator Coordination - Designed logic that works across all allocators in a pool

Metrics Interface Abstraction - Created a clean API integrating with Cilium's Prometheus instrumentation

Pool Lifecycle Integration- Ensured dynamic updates as pools are modified.

## Challenges I ran into

CIDR Index Calculation - Computing accurate index ranges for IPv4/IPv6 CIDR blocks required careful bit manipulation

Initial Design Misjudgment - Early in the implementation, I incorrectly used trigger-based metrics instead of standard gauge metrics, which only updated during specific events rather than providing continuous visibility. This taught me the importance of selecting the right Prometheus metric type for the use case.

Testing Environment Issues - Repeatedly faced deployment challenges where the cluster would pull the default Cilium image instead of my custom-built version, causing the pods to run without my new metrics and making it impossible to verify the functionality. This required meticulous attention to image tagging and deployment configurations.

Large Address Spaces -Using big.Int for IPv6 support to handle astronomical address space calculations

Negative Remaining IPs- Encountered a critical issue where remaining IP calculations showed negative numbers due to:

Race conditions between allocation and metric collection

Overlapping CIDR ranges causing double-counting of allocations Per-Pool Complexity- Ensuring metrics correctly separated multiple pools and IP families without cross-contamination

Integration - Coordinating with existing IPAM allocators without breaking backward compatibility

## Accomplishments that I'm proud of

Closed the observability gap - First true per-pool IP visibility in Cilium's multi-pool IPAM

Complete Mathematical Implementation - Successfully translated CIDR mathematics into production-ready code

Dual-Stack Precision - Accurate handling of both IPv4 examples (e.g., 10.0.1.0/30 with 4 addresses) and IPv6 (e.g., 2001:db8:100::/126 with 4 addresses)

Comprehensive Testing Strategy - Implemented end-to-end unit tests for every function - from CIDR calculations and IP counting algorithms to metric registration and edge case handling

** Edge Case Handling** -Solved the negative IPs problem with intelligent clamping logic and tested boundary conditions

## What I learned

Cilium architecture and internals -

CIDR arithmetic - Deep understanding of IP addressing, CIDR notation, and bit manipulation

Prometheus best practices - Proper metric design with meaningful labels for operational visibility

Go's big.Int - Necessity of arbitrary-precision arithmetic for large IPv6 address spaces

Kubernetes networking - How IPAM subsystem work under the hood in cloud-native environments

Open-source contribution - The importance of comprehensive testing, and community collaboration.

Current status

The feature is fully implemented and functionally complete - all CIDR calculations work correctly, mathematical logics are properly implemented, and the metric exports accurate remaining IP counts. The negative IPs issue has been resolved with robust clamping logic. However, as with any significant contribution to a major project, it's currently under maintainer review in the Cilium repository

Documentation and Learning in public

I believe in thorough documentation and knowledge sharing. Alongside this implementation, I've created: A comprehensive resources to help the community understand and benefit from this work:

** Medium Article: Implementing Per-Pool IP Availability Metrics in Cilium's Multi-Pool IPAM**

** Reference Logic: Per-Pool IP Metrics CIDR Calculations & Logic Reference**