Fix: Correct sidecar container termination order in pod lifecycle doc

[intojhanurag]

This PR corrects a documentation bug where the shutdown order of containers in a Pod was previously stated incorrectly.

Problem

The earlier version claimed that sidecar containers are terminated after the main container, which contradicts the actual behavior.

Fix

Updated the doc to reflect that sidecar containers are stopped before the main application container, as per Kubernetes implementation.

References

• Kubernetes code: https://github.com/kubernetes/kubernetes/blob/master/pkg%2Fkubelet%2Fkuberuntime%2Fkuberuntime_manager.go#L1110-L1120
• Original issue: Main container doesn't get stopped prior to sidecar containers #50859
• Slack thread : https://kubernetes.slack.com/archives/C0BP8PW9G/p1746008313521029?thread_ts=1746008313.521029&cid=C0BP8PW9G

/sig node

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign salaxander for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

• content/en/docs/OWNERS

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

[intojhanurag]

Hi @salaxander ! Kindly requesting a review for this small documentation fix.

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	d772a7d
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/6866bbee95cbfe00087f8182
😎 Deploy Preview	https://deploy-preview-51506--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[lmktfy]

/hold

I believe the docs are correct here. Can you provide evidence they are not?

[intojhanurag]

/hold

I believe the docs are correct here. Can you provide evidence they are not?

Thanks for the review!

You're right to ask for verification. This fix is based on a test shared by Alexandru Gheorghe in the #sig-node Slack channel, where the actual pod shutdown logs showed the sidecar was stopped before the main container:

Normal Created 96s kubelet Created container: myapp
Normal Started 96s kubelet Started container myapp
Normal Killing 29s kubelet Stopping container logshipper
Normal Killing 29s kubelet Stopping container myapp

He confirmed this behavior even when the main container had a 10-second delay on shutdown.

The full conversation is available here:
🔗 https://kubernetes.slack.com/archives/C0BP8PW9G/p1746008313521029?thread_ts=1746008313.521029&cid=C0BP8PW9G

You had suggested in that same thread that this might be a docs bug and encouraged filing a PR — so I’ve opened this PR as a follow-up to that suggestion.

[lmktfy]

@kubernetes/sig-node-pr-reviews please look at this.

I have concerns. I think sidecar containers should wait for the app container to stop before the sidecars start to terminate; I suspect that the current documentation accurately describes the current behavior.

Can you provide a technical review to confirm that the change is correct? Although I triaged the issue as accepted, I personally have not verified how Kubernetes actually works.

---

@intojhanurag would you be willing to provide a manifest for a Job that demonstrates that the commits in this PR are correct? If so please include any appropriate annotations etc.

[intojhanurag]

@kubernetes/sig-node-pr-reviews please look at this.

I have concerns. I think sidecar containers should wait for the app container to stop before the sidecars start to terminate; I suspect that the current documentation accurately describes the current behavior.

Can you provide a technical review to confirm that the change is correct? Although I triaged the issue as accepted, I personally have not verified how Kubernetes actually works.

@intojhanurag would you be willing to provide a manifest for a Job that demonstrates that the commits in this PR are correct? If so please include any appropriate annotations etc.

Sure, thanks for raising this!
I’ll prepare a test manifest to demonstrate the behavior and share the results shortly.
Looking forward to SIG Node’s feedback as well.

[k8s-ci-robot]

@intojhanurag: Reiterating the mentions to trigger a notification:
@kubernetes/sig-node-pr-reviews

In response to this:

@kubernetes/sig-node-pr-reviews please look at this.

I have concerns. I think sidecar containers should wait for the app container to stop before the sidecars start to terminate; I suspect that the current documentation accurately describes the current behavior.

Can you provide a technical review to confirm that the change is correct? Although I triaged the issue as accepted, I personally have not verified how Kubernetes actually works.

@intojhanurag would you be willing to provide a manifest for a Job that demonstrates that the commits in this PR are correct? If so please include any appropriate annotations etc.

Sure, thanks for raising this!
I’ll prepare a test manifest to demonstrate the behavior and share the results shortly.
Looking forward to SIG Node’s feedback as well.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[matthyx]

/cc

[intojhanurag]

Hi @lmktfy,

I've tried setting up a Job and Pod with signal traps in Minikube to capture container shutdown order, but couldn’t consistently observe termination logs — possibly due to how fast the pod exits or log collection behavior.

That said, I still believe the issue is valid based on the Slack thread. If someone from SIG Node could validate or reproduce the behavior from their side, that would really help.

Totally okay if the PR needs to be paused or closed for now — thank you for your time and review!

/cc @kubernetes/sig-node-pr-reviews

[k8s-ci-robot]

@intojhanurag: GitHub didn't allow me to request PR reviews from the following users: kubernetes/sig-node-pr-reviews.

Note that only kubernetes members and repo collaborators can review this PR, and authors cannot review their own PRs.

In response to this:

Hi @lmktfy,

I've tried setting up a Job and Pod with signal traps in Minikube to capture container shutdown order, but couldn’t consistently observe termination logs — possibly due to how fast the pod exits or log collection behavior.

That said, I still believe the issue is valid based on the Slack thread. If someone from SIG Node could validate or reproduce the behavior from their side, that would really help.

Totally okay if the PR needs to be paused or closed for now — thank you for your time and review!

/cc @kubernetes/sig-node-pr-reviews

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[k8s-ci-robot]

@intojhanurag: Reiterating the mentions to trigger a notification:
@kubernetes/sig-node-pr-reviews

In response to this:

Hi @lmktfy,

I've tried setting up a Job and Pod with signal traps in Minikube to capture container shutdown order, but couldn’t consistently observe termination logs — possibly due to how fast the pod exits or log collection behavior.

That said, I still believe the issue is valid based on the Slack thread. If someone from SIG Node could validate or reproduce the behavior from their side, that would really help.

Totally okay if the PR needs to be paused or closed for now — thank you for your time and review!

/cc @kubernetes/sig-node-pr-reviews

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.