filter_kubernetes: Document metadata cache and freshness

[Abdessamade03]

What

Adds a "Metadata cache and freshness" section to the Kubernetes filter documentation, explaining:

• How pod metadata is cached (an in-memory table keyed by namespace + pod_name).
• Why the default kube_meta_cache_ttl=0 means entries have no time-based expiry (random eviction only at capacity), so long-lived pods with a stable name (for example, StatefulSet members) keep serving the labels and annotations captured when the entry was first cached, until the pod restarts or the entry is evicted.
• How to tune freshness with kube_meta_cache_ttl, kube_meta_namespace_cache_ttl, and cache_use_docker_id, including the request-load tradeoffs.

Also cross-links the "You can't see new objects getting metadata" troubleshooting note to the new section.

Why

Documentation half of the improvement discussed in fluent/fluent-bit#11961, where the current (by-design) caching behavior surprised a user running StatefulSets. @patrick-stephens suggested documenting the behavior and caveats as an immediately-useful first step; an opt-in implementation improvement will follow separately.

Notes

• Docs-only change to pipeline/filters/kubernetes.md.
• Checked against the repository's .markdownlint.json (MD013 disabled, atx headings, _ emphasis).

Summary by CodeRabbit

• Documentation
  • Added a new section explaining Kubernetes pod metadata caching, including default freshness behavior and how cache capacity impacts eviction.
  • Clarified when updates to pod labels/annotations (especially in-place changes) may appear stale, and how to tune freshness using available cache-related settings.
  • Expanded troubleshooting guidance for partially missing pod metadata, including Pod-specific refresh behavior and a pointer to the new cache details.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c469b338-dc21-492c-b5da-d3f0e940a20b

📥 Commits

Reviewing files that changed from the base of the PR and between 1b44248 and 997430c.

📒 Files selected for processing (1)

• pipeline/filters/kubernetes.md

✅ Files skipped from review due to trivial changes (1)

• pipeline/filters/kubernetes.md

---

📝 Walkthrough

Walkthrough

Documentation update to the Kubernetes filter page adding a new "Metadata cache and freshness" section describing pod metadata caching behavior, TTL configuration options, and staleness scenarios, plus an extension to the troubleshooting section referencing this new content.

Changes

Metadata Cache Documentation

Layer / File(s)

Summary

Metadata cache and freshness section and troubleshooting update pipeline/filters/kubernetes.md

Adds a new documentation section explaining the in-memory metadata cache keyed by namespace/pod_name, default eviction behavior when kube_meta_cache_ttl is 0, staleness scenarios, and configuration options (kube_meta_cache_ttl, kube_meta_namespace_cache_ttl, cache_use_docker_id) to tune freshness, then extends troubleshooting with Pod-specific skipped-refresh guidance and a reference to the new section.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: documenting Kubernetes filter metadata cache behavior and freshness.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[eschabell]

@Abdessamade03 verified this against the current code base, merging!