docs: design for sidecar container GPU resource accounting

[maishivamhoo123]

What type of PR is this?
this is a design docs for HAMi supporting the sidecar Container.

What this PR does / why we need it:
This PR adds a file docs/develop/sidecarContainer-design.md, which contains design for supporting sidecar containers (init containers with restartPolicy: Always) in vGPU accounting.

Right now HAMi treats a sidecar like a normal init container that runs andexits. But a sidecar keeps running next to the app containers for the whole pod lifetime. Because of this, its usage is counted with max instead of being added to the app containers, so the pod's real GPU usage is higher than what HAMi records. Also, the shrink after init never happens for pods
that have a sidecar, so their init container memory is never released.
Which issue(s) this PR fixes:
Part of : #2563

AI disclosure: I used Claude to help find relevant upstream Kubernetes documentation, to improve the formatting of this design document, and to fix spelling and grammar mistakes. The design itself and the analysis of HAMi's current behavior are my own work

Summary by CodeRabbit

Documentation

• Added design guidance for supporting native sidecar containers.
• Documented how sidecars are identified and handled during admission, scheduling, scoring, and resource accounting.
• Clarified resource calculation, shrink behavior, usage tracking, and annotation requirements.
• Added examples covering sidecar-aware resource management and Kubernetes ResourceQuota interactions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 48670023-b67f-45c9-82d1-db8b0d5e20db

📥 Commits

Reviewing files that changed from the base of the PR and between 4436c75 and cb5bb81.

📒 Files selected for processing (1)

• docs/develop/sidecarsContainer-design.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/develop/sidecarsContainer-design.md

---

📝 Walkthrough

Walkthrough

The PR adds a design document for HAMi support of Kubernetes native sidecar containers. It defines sidecar classification, resource accounting, admission, scheduling, usage recording, shrink behavior, and ResourceQuota interaction.

Changes

Native sidecar support

Layer / File(s)	Summary
Native sidecar classification and accounting docs/develop/sidecarsContainer-design.md	Defines sidecar detection with RestartPolicy: Always, effective resource accounting, and sidecar-aware admission, scheduling, scoring, and annotation handling.
Native sidecar lifecycle and usage docs/develop/sidecarsContainer-design.md	Documents usage recording, shrink rules, lifecycle examples, crash-loop handling, and all-sidecar pod behavior.
ResourceQuota interaction docs/develop/sidecarsContainer-design.md	Describes HAMi and Kubernetes ResourceQuota comparison behavior, including ordering-dependent rejection cases.

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

Mergeability Score: ⚪ Minimal · up to cb5bb

This change adds design documentation for sidecar-container GPU accounting and does not alter product behavior or runtime configuration; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related issues

• [Feature] Support Kubernetes native sidecar containers (initContainers with restartPolicy: Always). #2563 — The issue addresses native sidecar support and GPU resource accounting described by this design document.

Possibly related PRs

• Project-HAMi/HAMi#2064 — Both PRs document init-container resource accounting, including effective resources, shrinking, admission, scheduling, and usage recording.
• Project-HAMi/HAMi#2535 — Both PRs document ResourceQuota interaction with HAMi resource accounting and shrink behavior.

Suggested reviewers: archlitchi

Poem

A rabbit maps each sidecar’s place,
And counts its resources with care.
Init peaks shrink when states align,
While quotas follow the design.
HAMi’s rules are clear and bright.

🚥 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 and concisely describes the added design document for sidecar container GPU resource accounting.
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.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/develop/sidecarsContainer-design.md`:
- Around line 52-54: Update the definition of init_peak in the sidecarsContainer
design to explicitly set init_peak[uuid] to 0 when a pod has only sidecar init
containers, and treat missing resource entries as zero before applying max() or
addition.
- Around line 39-40: Add language identifiers to every fenced code block in the
sidecar design documentation, including the blocks near the effective
calculation and the other referenced sections. Use text or another appropriate
identifier after each opening fence while preserving the documented content.
- Around line 37-54: Update the ResourceQuota section to explicitly document
that HAMi’s conservative sidecar simplification can over-reserve compared with
Kubernetes admission when sidecars start after the peak non-sidecar init.
Include the example values showing Kubernetes at 20Gi versus HAMi at 22Gi, and
remove any claim that both systems always agree at admission.
- Around line 79-81: Define and document a positional container resolver before
sidecar classification: map each annotation position to pod.Spec.InitContainers
or pod.Spec.Containers after subtracting the init-container count, then inspect
the resolved container’s RestartPolicy. Update CollapseInitContainerUsage, the
device plugin Allocate flow, and WebUI classification to use this resolver
rather than position alone, and document how WebUI obtains pod.Spec because
annotations do not identify sidecars.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c7f21ae3-8050-46ab-9830-7e80699a5043

📥 Commits

Reviewing files that changed from the base of the PR and between 634bf2b and 719cb26.

📒 Files selected for processing (1)

• docs/develop/sidecarsContainer-design.md

[mesutoezdil]

This is being closed because it does not comply with the contribution guidelines.

[maishivamhoo123]

@mesutoezdil i edited my pr description according to the contribution guidelines , i added the AI disclosure .
i am currently working on this PR, can you please open this PR,
i will make sure that i will not repeat this mistake from my next PR.
Thank you!

[maishivamhoo123]

@archlitchi @Shouren @DSFans2014 can you please review this PR?

[mesutoezdil]

left 2 questions inline

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unittests	62.46% <ø> (+0.10%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mesutoezdil]

/lgtm

[archlitchi]

/lgtm

[hami-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: archlitchi, maishivamhoo123

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [archlitchi]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment