docs: add container cache sizing guide

[rjmurillo]

Summary

Adds docs/ContainerCacheSizing.md — a guide for engineers deploying .NET applications with IMemoryCache in containers.

What's Covered

• Why containers need explicit cache budgets — explains the System.Runtime.Caching cgroup mismatch problem
• Sizing strategy — step-by-step: determine container budget → translate to logical SizeLimit → keep shared cache unbounded
• Two SizeLimit strategies — count-based (1 unit = 1 entry) and weight-based (1 unit = 1 KiB), with code examples
• Time-based vs size-based expiry — when size limits are necessary vs when TTLs alone suffice
• Monitoring — which MeteredMemoryCache metrics to watch and container signals to correlate
• Kubernetes example — deployment YAML + matching cache configuration
• Common mistakes — SizeLimit on shared cache, assuming units are bytes, ignoring metrics, copying host-based limits

Context

Addresses the container cache sizing documentation gap identified in #32. The migration cookbook covers this topic at a high level; this guide provides the detailed, actionable guidance for container deployments that was missing from this repo's docs.

Checklist

• New documentation file
• Cross-references existing docs (BestPractices, OpenTelemetry, Performance)
• Formatted with pprettier
• No code changes — build/test not required

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request adds a comprehensive guide on effectively sizing IMemoryCache within .NET applications deployed in containers. It addresses the challenges of relying on host-wide memory pressure metrics in containerized environments and provides actionable strategies for configuring cache size limits, monitoring cache performance, and avoiding common pitfalls.

Highlights

• New Documentation: This PR introduces a new documentation file, docs/ContainerCacheSizing.md, providing guidance on sizing IMemoryCache in containerized .NET applications.
• Sizing Strategies: The guide covers determining container memory budgets, translating them to logical SizeLimit values, and choosing between count-based and weight-based sizing strategies.
• Monitoring and Best Practices: It emphasizes monitoring cache behavior using metrics and avoiding common mistakes like setting SizeLimit on the shared cache.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Copilot]

Pull request overview

I have re-read .github/copilot-instructions.md in full.

Adds a new documentation guide to help engineers size and operate IMemoryCache safely in containerized deployments, aligning guidance with this repo’s metered cache metrics and the .NET runtime’s approved metrics design.

Changes:

• Add docs/ContainerCacheSizing.md covering container-specific cache budgeting, SizeLimit strategies, and operational monitoring guidance.
• Provide concrete examples for count-based vs KiB-based sizing and a Kubernetes deployment snippet.
• Document key MeteredMemoryCache metrics to correlate with container memory/GC signals.

[gemini-code-assist]

Code Review

This pull request introduces a valuable new documentation file, docs/ContainerCacheSizing.md, which provides comprehensive guidance on sizing IMemoryCache in containerized .NET applications. The content is well-structured and highly informative, covering crucial aspects from budget determination to monitoring. My feedback focuses on a minor formatting inconsistency within the 'Common Mistakes' section to enhance readability and visual coherence.

[rjmurillo]

K8s QoS Fix (commit 07d12e7)

Fixed the Kubernetes YAML example per review feedback:

Before:
equests.memory: 256Mi\ / \limits.memory: 512Mi\ → Burstable QoS
After:
equests.memory: 512Mi\ / \limits.memory: 512Mi\ → Guaranteed QoS

Setting requests ≠ limits for memory is dangerous for cache workloads:

• Scheduler reserves only 256 MiB; pod OOMs the moment it exceeds that
• Burstable pods are evicted first under node pressure
• Cache sizing math assumed 512 MiB ceiling that may not be available

Added a callout explaining QoS classes and why
equests == limits\ for memory, citing K8s QoS docs and Robusta: memory limits.

This is why you should always set Kubernetes memory limits equal to memory requests. — Natan Yellin, Robusta.dev