feat: Add kubeReserved calculation visibility for troubleshooting

[moko-poi]

Summary

This PR addresses issue #8497 by adding comprehensive visibility into how Karpenter calculates kubeReserved and allocatable resources for instance types. This helps users, especially those using Custom AMI families, understand and troubleshoot capacity-related issues.

Changes

Code Changes

• Added detailed V(1) logging in NewInstanceType() to track resource calculations
  • Logs instance type, AMI family, and pod configuration
  • Shows effective pods count used for kubeReserved calculation
  • Displays capacity, reserved, and allocatable values for CPU and memory
• Refactored calculation logic for better readability and debuggability
  • Extracted effectivePods and kubeReservedResources as variables
  • Makes the calculation process more transparent

Documentation Changes

• Added "Debugging kubeReserved Calculations" section to troubleshooting docs
  • Step-by-step guide for enabling and viewing verbose logs
  • Detailed explanation of each log field
  • Documentation of default kubeReserved calculation formulas
  • Practical example for Custom AMI users
• Fixed metric name in existing documentation

Problem Solved

Issue #8497 - Problem 3: Lack of visibility

"Some way to know what Karpenter thinks the allocable an instance type has."

Users previously had no way to understand:

• How Karpenter calculates kubeReserved for different instance types
• Why their configured maxPods might not match the effective pod count
• How Custom AMI configurations affect resource calculations

Impact

• ✅ Non-breaking change: No behavior modifications, only adds observability
• ✅ Zero performance impact: Logs are at V(1) level (disabled by default)
• ✅ Immediate value: Users can now troubleshoot capacity issues effectively
• ✅ Foundation for future work: Enables debugging for upcoming PRs (Add minimal docs on how to build and some minor build improvements #2: MaxPods floor, Added a node group abstraction that implements the scale subresource #3: Custom AMI optimization)

Testing

• Code compiles successfully
• Existing tests pass
• Log output verified with verbose mode

Example Log Output

{
  "level": "info",
  "ts": "2025-12-23T19:30:52Z",
  "msg": "calculated instance type resources",
  "instance-type": "m5.large",
  "ami-family": "Custom",
  "max-pods-configured": 110,
  "effective-pods": 737,
  "uses-eni-limited-overhead": true,
  "capacity-memory": "8192Mi",
  "capacity-cpu": "2",
  "kube-reserved-memory": "8362Mi",
  "kube-reserved-cpu": "80m",
  "system-reserved-memory": "0",
  "system-reserved-cpu": "0",
  "allocatable-memory": "6.5Gi",
  "allocatable-cpu": "1920m"
}

Related Issues

• Relates to Karpenter incorrectly calculates Node's memory allocable due kubeReserve assumptions #8497 (Problem 3: Visibility)
• Prepares groundwork for future PRs addressing Problems 1 & 2

Checklist

• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works (N/A - observability only)
• New and existing unit tests pass locally with my changes

Screenshots/Recordings

N/A - This is a logging and documentation enhancement

[DerekFrank]

This doesn't really address #8497, and I am not sure that the amount of logs is worth it.

[DerekFrank]

Won't this log a line for every single instance on startup? I'm not sure that kind of spam is useful

[moko-poi]

Good catch! I've updated the code to only log for Custom AMI families where this troubleshooting info is most valuable. This avoids the log spam from hundreds of instance types at startup.

[DerekFrank]

For the non-custom AMIs, we could instead put this information into the website. After we figure out the override behavior for #8497, we can log the result for custom amis only I think

[moko-poi]

@DerekFrank Thank you for the valuable feedback! You're absolutely right about the log volume concern and the relationship with #8497.

After reviewing the situation, I understand that:

1. PR fix(kubereserved): allow custom AMI bypass and floor kubeReserved to … #8705 addresses Problems 1 & 2 (calculation logic fixes)
2. This PR should focus on Problem 3 (visibility) as a complementary solution

I'll update this PR to:

• Limit logging to Custom AMI families only (where troubleshooting is most needed)
• Enhance documentation with static calculation formulas for EKS-optimized AMIs
• Add a clear dependency note on fix(kubereserved): allow custom AMI bypass and floor kubeReserved to … #8705

Rationale:

• For EKS-optimized AMIs (AL2, AL2023, Bottlerocket): Static formulas → documentation is sufficient
• For Custom AMIs: Dynamic calculations based on user config → runtime logging is valuable for troubleshooting

[moko-poi]

Fixed in 27e46d3! Now only logs for Custom AMI families to avoid the spam:

if amiFamilyType == v1.AMIFamilyCustom {
    log.FromContext(ctx).V(1).Info("calculated instance type resources for Custom AMI", ...)
}

For EKS-optimized AMIs, I've added detailed documentation with formulas and examples instead.

[jigisha620]

@moko-poi,
Even if this is specific for custom AMIs, I think on startup this will print log for every instance type. Can we move this to trace level verbosity?

[moko-poi]

@jigisha620 Good point! I've updated the log level to V(2) in 4a49e45.

This ensures the logs are only visible when users explicitly need detailed troubleshooting with --v=2, avoiding log spam during normal operations even with Custom AMI.