Skip to content

feat: implement persistent Suspended conditions for Sandbox - #1150

Merged
kubernetes-prow[bot] merged 10 commits into
kubernetes-sigs:mainfrom
shrutiyam-glitch:sandbox-suspend-conditions
Jul 29, 2026
Merged

kubernetes-prow[bot] merged 10 commits into
kubernetes-sigs:mainfrom
shrutiyam-glitch:sandbox-suspend-conditions

Conversation

@shrutiyam-glitch

@shrutiyam-glitch shrutiyam-glitch commented Jul 14, 2026 •

Copy link
Copy Markdown
Contributor

What this PR does / why we need it:

This PR formally implements the Suspended persistent condition for Sandbox resources to accurately track the suspension state and lifecycle.

Note: These changes are based out of PR #893.

Current behavior:
computeSuspendedCondition returns nil whenever spec.operatingMode == Running, so the controller only sets/updates the Suspended condition while the Sandbox is suspended. As a result:

  • A newly created (running) Sandbox has no Suspended condition at all.
  • After a suspend → resume, the condition is left stale at True — it never transitions
    to False, so its lastTransitionTime never records when the Sandbox resumed.
  • Wait command kubectl wait --for=condition=Suspended=False can’t work, because the
    condition is not maintained as a proper False state.

This contradicts the Kubernetes convention that conditions are persistent once initialized and transition their status (rather than appearing/disappearing), and thatlastTransitionTime is preserved as history.

Applied behavior:

The Suspended condition is now persistent once initialized, properly transitioning its status (True or False) instead of appearing and disappearing. This preserves the lastTransitionTime history and enables standard kubectl wait commands.

States and their meaning:

  • Status False (Reason: NotSuspended): The Sandbox is active. This state is set immediately upon creation or when resumption is requested (Spec.OperatingMode = Running), even before the underlying Pod is actually provisioned.
  • Status False (Reason: PodTerminating): The Sandbox is in a transient suspension phase where the underlying Pod is currently terminating.
  • Status True (Reason: PodTerminated): The Sandbox is fully suspended, and the underlying Pod has been successfully terminated.

Key changes:

  • API Update (sandbox_types.go): Added SandboxConditionSuspended and specific suspension reasons (PodTerminated, PodTerminating, NotSuspended).
  • Controller Logic (sandbox_controller.go): Updated computeSuspendedCondition to properly construct and populate metav1.Condition objects for the Suspended type. The condition evaluates to True when fully suspended (Pod is terminated) and False when active or during a transient suspension phase (e.g., PodTerminating).
  • Documentation (keps/119-sandbox-suspended-state): Updated the condition hierarchy documentation to explicitly define the Suspended status values and reasons, reflecting the new standard Kubernetes condition mechanics.

Testing:

  • Updated the sandbox_controller_test.go and all E2E test suites (basic_test.go, shutdown_test.go, volumeclaimtemplate_test.go) to assert the presence and accuracy of the new Suspended condition under various scenarios.
  • Added new e2e tests in mode_test.go - TestSandboxSuspendResumeCycleWithOperatingMode, TestSandboxSuspensionWithTerminatingPod, TestSandboxPodDeletionKeepsSuspendedFalse
$ kubectl wait --for=condition=Suspended=False sandbox/sandbox-claim-8ed4a267 -n sandbox-test
sandbox.agents.x-k8s.io/sandbox-claim-8ed4a267 condition met

This enables kubectl wait --for=condition=Suspended=False and preserves the suspend/resume transition history via lastTransitionTime.

Note: When resume is requested (Spec.OperatingMode = Running), the Suspended condition status transitions to False (Running) immediately, even before the underlying Pod is actually provisioned or created (pod == nil).

Which issue(s) this PR is related to:

Fixes #873

Release Note

Implemented the `Suspended` condition for `Sandbox` objects to track suspension lifecycle states (NotSuspended, PodTerminating, PodTerminated). Note that the legacy `PodNotTerminated` reason is deprecated in favor of `PodTerminating`. Additionally, the `Suspended` condition is now always present on the resource after initial reconciliation; clients should evaluate its boolean `status` value rather than checking for its presence.

Summary by CodeRabbit

Summary

  • New Features
    • Expanded sandbox suspension reasons, including explicit “not suspended” and a dedicated “pod terminating” suspension flow (with an older reason marked deprecated).
  • Bug Fixes
    • Sandbox status now consistently reports the Suspended condition (including running state), with improved messaging and preserved in-progress pod deletion behavior.
  • Documentation
    • Updated the suspended-state KEP condition hierarchy and dependency matrix to match revised semantics.
  • Tests
    • Updated unit and e2e coverage for suspend/resume cycles, terminating-pod handling, shutdown assertions, and added a new e2e check to ensure direct pod deletion doesn’t incorrectly flip suspension state.

@netlify

netlify Bot commented Jul 14, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for agent-sandbox canceled.

Name Link
🔨 Latest commit f3a156f
🔍 Latest deploy log https://app.netlify.com/projects/agent-sandbox/deploys/6a6a811c9462290008b5e4f9

@kubernetes-prow
kubernetes-prow Bot requested review from barney-s and janetkuo July 14, 2026 00:29
@kubernetes-prow kubernetes-prow Bot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jul 14, 2026
@coderabbitai

coderabbitai Bot commented Jul 14, 2026 •

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Changes

Suspended condition lifecycle

Layer / File(s) Summary
Condition contract and controller behavior
api/v1beta1/sandbox_types.go, controllers/sandbox_controller.go, docs/keps/119-sandbox-suspended-state/README.md
Suspended-condition reasons and documentation are updated, and the controller now always reports running, terminating, or terminated states.
Controller condition regression coverage
controllers/sandbox_controller_test.go
Unit tests cover persistent Suspended conditions, terminating Pods, returned Pods, and condition non-accumulation.
Suspend and resume end-to-end flow
test/e2e/basic_test.go, test/e2e/mode_test.go, test/e2e/shutdown_test.go, test/e2e/volumeclaimtemplate_test.go
E2E tests cover running, suspension, Pod deletion, resumption, Pod recreation, shutdown, and volume-claim scenarios.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Sandbox
  participant Controller
  participant Pod
  Sandbox->>Controller: update operating mode
  Controller->>Pod: inspect or delete Pod
  Pod-->>Controller: Pod present, terminating, or absent
  Controller-->>Sandbox: update Suspended and Ready conditions
  Sandbox->>Controller: resume operating mode
  Controller->>Pod: recreate Pod
  Controller-->>Sandbox: report Suspended=False and Ready=True
Loading

Possibly related PRs

Suggested reviewers: janetkuo, barney-s

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The code implements persistent Suspended conditions, matching #873's persistence and kubectl wait requirements.
Out of Scope Changes check ✅ Passed All changes align with the suspended-condition feature; no unrelated code changes are evident.
Title check ✅ Passed The title is concise and accurately summarizes the main change: making Sandbox Suspended conditions persistent.
Description check ✅ Passed The PR description matches the template and clearly covers purpose, issue link, and release note.
✨ 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

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

@shrutiyam-glitch

Copy link
Copy Markdown
Contributor Author

/assign @SHRUTI6991

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
controllers/sandbox_controller_test.go (1)

334-340: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Standardize test assertions to use API constants instead of string literals.

This test case (and several others throughout this file) hardcodes string literals for the condition Type, Status, and Reason. For consistency with the rest of the codebase and to protect against future refactoring typos, consider standardizing on the exported API constants (sandboxv1beta1.SandboxConditionSuspended, metav1.ConditionFalse, sandboxv1beta1.SandboxReasonSuspendedRunning, etc.) as utilized in the E2E tests.

🧹 Proposed refactor (example for this occurrence)
 					{
-						Type:               "Suspended",
-						Status:             "False",
+						Type:               string(sandboxv1beta1.SandboxConditionSuspended),
+						Status:             metav1.ConditionFalse,
 						ObservedGeneration: 1,
-						Reason:             "Running",
+						Reason:             sandboxv1beta1.SandboxReasonSuspendedRunning,
 						Message:            "Sandbox is running.",
 					},
🤖 Prompt for 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.

In `@controllers/sandbox_controller_test.go` around lines 334 - 340, Standardize
the condition assertions throughout the test cases in
controllers/sandbox_controller_test.go to use exported API constants instead of
hardcoded strings. Update Type, Status, and Reason fields in the relevant
condition fixtures, including the condition shown, to use the corresponding
sandboxv1beta1 and metav1 constants while preserving the existing expected
values.
🤖 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 `@api/v1beta1/sandbox_types.go`:
- Around line 31-37: Restore the exported SandboxReasonSuspendedPodNotTerminated
constant in the v1beta1 API, defining it as a deprecated alias of the
replacement suspended-pod reason constant and documenting the deprecation.
Preserve the existing SandboxReasonSuspendedPodTerminated,
SandboxReasonSuspendedPodTerminating, and SandboxReasonSuspendedRunning values.

---

Nitpick comments:
In `@controllers/sandbox_controller_test.go`:
- Around line 334-340: Standardize the condition assertions throughout the test
cases in controllers/sandbox_controller_test.go to use exported API constants
instead of hardcoded strings. Update Type, Status, and Reason fields in the
relevant condition fixtures, including the condition shown, to use the
corresponding sandboxv1beta1 and metav1 constants while preserving the existing
expected values.
🪄 Autofix (Beta)

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 38f3f2ea-8dfc-409a-ab45-c47279ebcf7a

📥 Commits

Reviewing files that changed from the base of the PR and between 8c6b5fc and 7e828b5.

📒 Files selected for processing (8)
  • api/v1beta1/sandbox_types.go
  • controllers/sandbox_controller.go
  • controllers/sandbox_controller_test.go
  • docs/keps/119-sandbox-suspended-state/README.md
  • test/e2e/basic_test.go
  • test/e2e/mode_test.go
  • test/e2e/shutdown_test.go
  • test/e2e/volumeclaimtemplate_test.go

Comment thread api/v1beta1/sandbox_types.go Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the Sandbox controller/API to maintain a persistent Suspended condition (instead of creating/removing it), so suspension state transitions can be observed reliably (e.g., kubectl wait --for=condition=Suspended=False) and lastTransitionTime reflects suspend/resume changes.

Changes:

  • Adds/updates Suspended condition reason constants (e.g., Running, PodTerminating, PodTerminated) and updates computeSuspendedCondition to always return a condition (defaulting to False/Running).
  • Updates controller unit tests and multiple e2e tests to assert Suspended=False is present for running sandboxes, and correct transitions during suspend/resume.
  • Updates KEP-119 documentation to describe the new persistent condition semantics and reason mapping.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
api/v1beta1/sandbox_types.go Adds/adjusts Suspended condition reason constants for clearer suspension state reporting.
controllers/sandbox_controller.go Makes Suspended condition persistent and populates it with Status/Reason/Message.
controllers/sandbox_controller_test.go Updates unit tests to expect the persistent Suspended condition in all modes.
test/e2e/basic_test.go Asserts Suspended=False/Running exists for a default running sandbox.
test/e2e/mode_test.go Expands operating-mode test into a suspend → resume lifecycle assertion including Suspended transitions.
test/e2e/shutdown_test.go Adds Suspended=False/Running expectations to shutdown-related e2e assertions.
test/e2e/volumeclaimtemplate_test.go Adds Suspended=False/Running expectations to VCT e2e assertions.
docs/keps/119-sandbox-suspended-state/README.md Updates the documented condition hierarchy and scenario table for the persistent Suspended condition.

Comment thread controllers/sandbox_controller.go Resolved
@shrutiyam-glitch
shrutiyam-glitch force-pushed the sandbox-suspend-conditions branch from c182f57 to 51469e6 Compare July 14, 2026 20:07

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 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 `@api/v1beta1/sandbox_types.go`:
- Around line 38-40: Restore the exported constant SandboxReasonSuspendedRunning
in the v1beta1 API alongside SandboxReasonNotSuspended as a deprecated alias,
preserving the existing value and downstream compilation compatibility. Add the
deprecation documentation to direct users to SandboxReasonNotSuspended.
🪄 Autofix (Beta)

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ea400124-6144-433c-8880-a9b2f51e7685

📥 Commits

Reviewing files that changed from the base of the PR and between 7e828b5 and c182f57.

📒 Files selected for processing (7)
  • api/v1beta1/sandbox_types.go
  • controllers/sandbox_controller.go
  • controllers/sandbox_controller_test.go
  • test/e2e/basic_test.go
  • test/e2e/mode_test.go
  • test/e2e/shutdown_test.go
  • test/e2e/volumeclaimtemplate_test.go
🚧 Files skipped from review as they are similar to previous changes (1)
  • test/e2e/basic_test.go

Comment thread api/v1beta1/sandbox_types.go Resolved
Comment thread api/v1beta1/sandbox_types.go Resolved
@kubernetes-prow kubernetes-prow Bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jul 14, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 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 `@test/e2e/mode_test.go`:
- Around line 183-186: After adding the test finalizer in the Pod update block,
register t.Cleanup to fetch the Pod with a background context, remove the
"agents.x-k8s.io/test-hold" finalizer when present, and persist the update.
Ignore NotFound errors so cleanup remains safe when the Pod is already deleted.
🪄 Autofix (Beta)

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3e713a61-d42f-4e01-a4c2-3f5b7b769c56

📥 Commits

Reviewing files that changed from the base of the PR and between 51469e6 and 6975290.

📒 Files selected for processing (1)
  • test/e2e/mode_test.go

Comment thread test/e2e/mode_test.go Resolved
@shrutiyam-glitch
shrutiyam-glitch force-pushed the sandbox-suspend-conditions branch from 6975290 to 5f8e037 Compare July 14, 2026 23:58

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 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 `@test/e2e/mode_test.go`:
- Around line 297-355: Enhance TestSandboxPodDeletionKeepsSuspendedFalse to
observe Sandbox status continuously from Pod deletion through recreation, rather
than only checking runningReady afterward. Poll or watch the Suspended condition
during this interval and fail immediately if it becomes True, while retaining
the final recovery and Ready assertion.
- Around line 50-95: Extend the end-to-end suspend/resume assertions around
runningStatus and suspendedStatus to capture the Suspended condition after every
phase. Verify each captured condition has a nonzero lastTransitionTime and that
the timestamp advances for every True↔False transition, including the additional
phase covered by the later status assertions; keep the checks across the
controller/API-server boundary.
🪄 Autofix (Beta)

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f3aee166-2f38-4049-b504-40a80ffafae4

📥 Commits

Reviewing files that changed from the base of the PR and between 6975290 and 5f8e037.

📒 Files selected for processing (2)
  • api/v1beta1/sandbox_types.go
  • test/e2e/mode_test.go
🚧 Files skipped from review as they are similar to previous changes (1)
  • api/v1beta1/sandbox_types.go

Comment thread test/e2e/mode_test.go Resolved
Comment thread test/e2e/mode_test.go Resolved
@kubernetes-prow

kubernetes-prow Bot commented Jul 21, 2026 •

Copy link
Copy Markdown

@shrutiyam-glitch: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name Commit Details Required Rerun command
presubmit-agent-sandbox-benchmarks-kops-gcp 1817c97 link false /test presubmit-agent-sandbox-benchmarks-kops-gcp

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Details

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. I understand the commands that are listed here.

yuzhiquan added a commit to yuzhiquan/agent-sandbox that referenced this pull request Jul 27, 2026
…ernetes-sigs#1150

Per review: removing the stale Suspended=True condition on resume is a
behavior change beyond this PR's scope, and PR kubernetes-sigs#1150 fixes the same
staleness in the opposite (K8s-conventional) direction — making
Suspended persistent and transitioning it to False instead of removing
it. Reverting the removal keeps main's behavior unchanged here and
leaves the fix to kubernetes-sigs#1150; a comment now pins that decision so the
removal set and kubernetes-sigs#1150 land coherently.

Ref kubernetes-sigs#1281
yuzhiquan added a commit to yuzhiquan/agent-sandbox that referenced this pull request Jul 28, 2026
Proposes idle-based automatic suspension and resume-on-traffic:
- spec.lifecycle.idlePolicy (idleTimeoutSeconds, action Suspend|Delete,
  suspendedTTLSeconds, resumeOn, workloadActivity), propagated via
  SandboxTemplate/SandboxClaim with an override policy
- per-sandbox coordination.k8s.io Lease as the activity channel
  (router, SDKs, and opt-in workload renewals)
- opt-in sandbox-router resume path: singleflight operatingMode patch,
  request held until the backing Pod is ready
- source-aware expiry (ExpiryDecision) so idle reclaim and ordinary
  shutdownTime/TTL expiry keep distinct events and terminal condition
  messages

Depends on KEP-119 persistent Suspended conditions (kubernetes-sigs#1150).
Converges with the idle lifecycle policy discussion in kubernetes-sigs#849.

Ref kubernetes-sigs#968
yuzhiquan added a commit to yuzhiquan/agent-sandbox that referenced this pull request Jul 28, 2026
Proposes idle-based automatic suspension and resume-on-traffic:
- spec.lifecycle.idlePolicy (idleTimeoutSeconds, action Suspend|Delete,
  suspendedTTLSeconds, resumeOn, workloadActivity), propagated via
  SandboxTemplate/SandboxClaim with an override policy
- per-sandbox coordination.k8s.io Lease as the activity channel
  (router, SDKs, and opt-in workload renewals)
- opt-in sandbox-router resume path: singleflight operatingMode patch,
  request held until the backing Pod is ready
- source-aware expiry (ExpiryDecision) so idle reclaim and ordinary
  shutdownTime/TTL expiry keep distinct events and terminal condition
  messages

Depends on KEP-119 persistent Suspended conditions (kubernetes-sigs#1150).
Converges with the idle lifecycle policy discussion in kubernetes-sigs#849.

Ref kubernetes-sigs#968
Comment thread controllers/sandbox_controller.go Resolved
Comment thread controllers/sandbox_controller.go Resolved
Comment thread controllers/sandbox_controller.go Resolved
@kubernetes-prow kubernetes-prow Bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jul 29, 2026

@janetkuo janetkuo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/lgtm

@kubernetes-prow kubernetes-prow Bot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 29, 2026
@kubernetes-prow

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: janetkuo, shrutiyam-glitch

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:

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

@kubernetes-prow kubernetes-prow Bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jul 29, 2026
@kubernetes-prow
kubernetes-prow Bot merged commit b9d2a10 into kubernetes-sigs:main Jul 29, 2026
18 checks passed
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Agent Sandbox Jul 29, 2026
drogovozDP pushed a commit to volatilemolotov/agent-sandbox that referenced this pull request Aug 18, 2026
…es-sigs#1150)

* base changes

* Update the sandbox coditions

* Address comment and unit tests

* Add more e2e tests

* Update KEP document and align API conventions

* Replace "Running" reason with "NotSuspended" in KEP matrix and prose to match the implementation.
* Deprecate SandboxReasonSuspendedPodNotTerminated in sandbox_types.go.

```release-note
Deprecated the `PodNotTerminated` reason string in favor of `PodTerminating`.
The Sandbox `Suspended` status condition is now always present after initial reconciliation (clients should inspect its boolean `status` value rather than checking for its presence).
```

* Add reason when pod is not owned

* Add Unknown reason status

* Update doc and address regression
jensfr added a commit to jensfr/agent-sandbox that referenced this pull request Aug 20, 2026
Port the fix from upstream PR kubernetes-sigs#1150 (commit b9d2a10).

computeSuspendedCondition now always returns a condition value (not a
pointer). When operatingMode is Running, it returns Suspended: False
with reason NotSuspended, clearing the stale Suspended: True left
behind after a stop. This prevents the OpenShell gateway from
reporting the sandbox as Stopped when it is actually Ready.

New Suspended condition reasons: NotSuspended, PodTerminating,
PodNotOwned, PodStateUnknown. Deprecated: PodNotTerminated.

Fixes: RHBAS-19

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
russellb added a commit to russellb/OpenShell that referenced this pull request Aug 25, 2026
On Agent Sandbox v1beta1, a `sandbox stop` then `sandbox start` left the
sandbox stuck at `Starting` and `start` timed out after 300s, even though
the workload pod was `Running 1/1` and the CR reported `Ready=True`.

The v1beta1 controller (v0.5.0) sets `Suspended=True (PodTerminated)` on
stop and does not clear it on resume, so a resumed CR carries both
`Ready=True (DependenciesReady)` and a stale `Suspended=True`. The gateway's
`derive_phase` treated any `Suspended=True` condition as `Stopped` before it
consulted `Ready`, so a resumed-but-Ready sandbox was read as not-running and
the `Starting` phase never advanced to `Ready`.

`Ready=True` means the sandbox is usable through this gateway and must win
over a `Suspended=True` condition. Only resolve `Stopped` from `Suspended`
when `Ready` is not `True`; a genuine stop leaves `Ready` unset or `False`,
so it still resolves to `Stopped`. v1alpha1 (which encodes desired state as
`spec.replicas` and emits no lingering `Suspended`) is unaffected.

The underlying stale condition is an upstream bug in the agent-sandbox
controller, fixed by kubernetes-sigs/agent-sandbox#1150 (in v0.5.6). This
gateway change keeps OpenShell resilient regardless of controller version.

Fixes NVIDIA#2932

Signed-off-by: Russell Bryant <[email protected]>
pull Bot pushed a commit to Stars1233/OpenShell that referenced this pull request Aug 25, 2026
…DIA#2933)

On Agent Sandbox v1beta1, a `sandbox stop` then `sandbox start` left the
sandbox stuck at `Starting` and `start` timed out after 300s, even though
the workload pod was `Running 1/1` and the CR reported `Ready=True`.

The v1beta1 controller (v0.5.0) sets `Suspended=True (PodTerminated)` on
stop and does not clear it on resume, so a resumed CR carries both
`Ready=True (DependenciesReady)` and a stale `Suspended=True`. The gateway's
`derive_phase` treated any `Suspended=True` condition as `Stopped` before it
consulted `Ready`, so a resumed-but-Ready sandbox was read as not-running and
the `Starting` phase never advanced to `Ready`.

`Ready=True` means the sandbox is usable through this gateway and must win
over a `Suspended=True` condition. Only resolve `Stopped` from `Suspended`
when `Ready` is not `True`; a genuine stop leaves `Ready` unset or `False`,
so it still resolves to `Stopped`. v1alpha1 (which encodes desired state as
`spec.replicas` and emits no lingering `Suspended`) is unaffected.

The underlying stale condition is an upstream bug in the agent-sandbox
controller, fixed by kubernetes-sigs/agent-sandbox#1150 (in v0.5.6). This
gateway change keeps OpenShell resilient regardless of controller version.

Fixes NVIDIA#2932

Signed-off-by: Russell Bryant <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. lgtm "Looks good to me", indicates that a PR is ready to be merged. ready-for-review release-note-action-required Denotes a PR that introduces potentially breaking changes that require user action. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Fix suspended condition persistence

6 participants