Repository navigation
docs: Document pod runtime status and specific SSH not-ready reasons in the runpodctl reference - #758
Conversation
Add a Pod runtime status section to the runpodctl pod reference covering the new runtimeStatus/runtimeStatusReason/lastStatusChange fields on pod get and pod list, update the ssh reference with the specific not-ready causes and the --ports remedy warning, and cross-link from the SSH troubleshooting guide (runpodctl PR #315, CON-690).
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
|
|
||
| ## Pod runtime status | ||
|
|
||
| `runpodctl pod get` and `runpodctl pod list` now report a Pod's real runtime state in their JSON and YAML output, alongside the existing `desiredStatus`. `desiredStatus` is the state you asked for (for example, `RUNNING`), while `runtimeStatus` is what the Pod is actually doing. For example, a Pod still pulling a large image and a Pod that has been serving traffic for an hour both show `desiredStatus: RUNNING`, but their `runtimeStatus` values differ. |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-pod.mdx:279
desiredStatus vs runtimeStatus distinction (desiredStatus is what was requested, runtimeStatus is derived/actual) is documented verbatim in the podstate package comment, from open PR runpod/runpodctl#315 (CON-690, not yet merged).
Source: podstate.go:1–27 · ea017f6
|
|
||
| `runpodctl pod get` and `runpodctl pod list` now report a Pod's real runtime state in their JSON and YAML output, alongside the existing `desiredStatus`. `desiredStatus` is the state you asked for (for example, `RUNNING`), while `runtimeStatus` is what the Pod is actually doing. For example, a Pod still pulling a large image and a Pod that has been serving traffic for an hour both show `desiredStatus: RUNNING`, but their `runtimeStatus` values differ. | ||
|
|
||
| <ResponseField name="runtimeStatus" type="string"> |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-pod.mdx:281
Citation withdrawn.
podListOutput struct confirms runtimeStatus has no omitempty (always present); runtimeStatusReason and lastStatusChange both have omitempty. Same shape appears on pod get (cmd/pod/get.go response struct). From open PR runpodctl#315.
Source: list.go:34–53 · ea017f6
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
| Present when available. The backend's raw status text (for example, `Exited by user: <date>` or `Outbid: <date>`). | ||
| </ResponseField> | ||
|
|
||
| For example, `runpodctl pod list --output json` returns entries like this for a running Pod: |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-pod.mdx:293
JSON example field names (id, name, desiredStatus, runtimeStatus, imageName, gpuCount, costPerHr, createdAt, uptimeSeconds) all match real podListOutput fields populated in runList; no fabricated field names. --output flag consumed via cmd.Flag("output") (persistent flag, StringVarP "output"/"o", default "json"), so --output json is a valid invocation form.
Source: list.go:182–200 · ea017f6
|
|
||
| ### Runtime status values | ||
|
|
||
| | Value | Meaning | What to do | |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-pod.mdx:313
Citation withdrawn.
Runtime status values table (running/initializing/stopped/terminated/unknown) matches the Status constants and doc comments exactly, including "does not imply a port is reachable" and the terminated pod's narrow drop-out-of-list window (getMyPods filters terminatedAt: null, see lines 77-81 of same file).
Source: podstate.go:90–120 · ea017f6
|
|
||
| ### Runtime status reasons | ||
|
|
||
| | Token | Paired status | Meaning | |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-pod.mdx:323
Citation withdrawn.
Runtime status reasons table matches the eight Reason constants and their doc comments verbatim (awaiting_container, stopped/terminated_by_user, stopped/terminated_by_runpod, stopped/terminated_outbid, runtime_unavailable).
Source: podstate.go:127–165 · ea017f6
| </Tip> | ||
|
|
||
| <Note> | ||
| `runtimeStatus` and `desiredStatus` come from different sources, so a single command can briefly show them disagreeing (for example, `desiredStatus: RUNNING` next to `runtimeStatus: stopped`). When they disagree, trust `runtimeStatus`. |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-pod.mdx:345
Citation withdrawn.
Confirms runtimeStatus is derived from the GraphQL snapshot while desiredStatus is REST's, and that the two surfaces can momentarily disagree (matches PR README language "when they disagree, trust runtimeStatus").
Source: list.go:153–180 · ea017f6
| `runtimeStatus` and `desiredStatus` come from different sources, so a single command can briefly show them disagreeing (for example, `desiredStatus: RUNNING` next to `runtimeStatus: stopped`). When they disagree, trust `runtimeStatus`. | ||
| </Note> | ||
|
|
||
| The `uptimeSeconds` field now reports the container's actual uptime and is omitted entirely when no container is reporting, instead of always showing `0`. |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-pod.mdx:348
uptimeSeconds is set only when runtimeStatus is running and runtime telemetry exists; otherwise left nil, which the omitempty tag drops from output instead of always reporting 0.
Source: list.go:176–180 · ea017f6
| `runpodctl ssh info` explains which of the following cases applies. It also reports the Pod's `runtimeStatus`, so you can match a not-ready result to the runtime status vocabulary: | ||
|
|
||
| | Reason | Meaning | What to do | | ||
| | --- | --- | --- | |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-ssh.mdx:44
Not-ready reasons table (initializing/stopped/terminated via state.Explain; no port 22 published, no public IP, mapping not ready via sshPortDetail) matches NotReadyMessage/sshPortDetail exactly, including the three distinct running-pod SSH-unreachable causes.
Source: notready.go:10–50 · ea017f6
| | No public IP | Port 22 is mapped, but the machine has no publicly routable IP. This affects direct SSH over a public IP specifically; basic SSH (proxied through Runpod, no public IP required) may still work. | Use [Basic SSH](/pods/configuration/use-ssh#basic-ssh-with-key-authentication), which does not need a public IP. If you need direct SSH over a public IP, redeploy on a machine that provides one. | | ||
| | Mapping not ready yet | Port 22 is declared, but the host has not published the mapping yet. | Wait and try again. | | ||
|
|
||
| For the "No SSH port published" case, `runpodctl ssh info` gives you a ready-to-run command of the form `runpodctl pod update <pod-id> --ports <existing-ports>,22/tcp` that preserves your existing ports. |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-ssh.mdx:52
Confirms the exact remedy command form runpodctl pod update <pod-id> --ports <existing-ports>,22/tcp built by addSSHPortCommand, preserving existing declared ports before appending 22/tcp.
Source: notready.go:52–82 · ea017f6
|
|
||
| For the "No SSH port published" case, `runpodctl ssh info` gives you a ready-to-run command of the form `runpodctl pod update <pod-id> --ports <existing-ports>,22/tcp` that preserves your existing ports. | ||
|
|
||
| <Warning> |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-ssh.mdx:54
Confirms --ports is wholesale replacement (not additive like --env), sourced from cmd/pod/update.go setting req.Ports to exactly what was passed; changing ports bumps pod version (editJob increments version), which can trigger a container recreate/restart.
Source: notready.go:52–68 · ea017f6
|
|
||
| </Note> | ||
|
|
||
| `runpodctl ssh info` explains which of the following cases applies. It also reports the Pod's `runtimeStatus`, so you can match a not-ready result to the runtime status vocabulary: |
There was a problem hiding this comment.
Citation
runpodctl/reference/runpodctl-ssh.mdx:41
Confirms runSSHInfoWithArgs includes a "runtimeStatus" key in the not-ready JSON/YAML output map alongside the error/id/name/status fields.
Source: ssh.go:191–211 · ea017f6
There was a problem hiding this comment.
Citation
pods/configuration/use-ssh.mdx:77
Confirms Basic SSH is described elsewhere in this same file as proxied through Runpod's systems, supporting the runpodctl-ssh.mdx claim that basic SSH does not require a public IP.
Source: use-ssh.mdx:77 · eeff71f
The --status flag matches desiredStatus (RUNNING/EXITED) case-insensitively and does not accept runtimeStatus values like initializing, which now appear on the same page. Reflects the merged --status help-text clarification from runpodctl PR #315 (CON-690).
…pod-runtime-status
…e and stop reasons, add error
|
@Promptless apply these two style fixes only: Fix 1 — Em dashes in runpodctl/reference/runpodctl-pod.mdx In the terminated row of the “Runtime status values” table, replace the em dashes with parentheses: Current: a teardown script should treat “Pod not found”—not runtimeStatus: terminated—as the reliable signal that a Pod is gone. Fixed: a teardown script should treat “Pod not found” (not runtimeStatus: terminated) as the reliable signal that a Pod is gone. Fix 2 — “now” in runpodctl/reference/runpodctl-ssh.mdx In the Note under the ssh info command, remove the word “now” — docs describe current state, not changes from a previous version: Current: When a Pod is not reachable, runpodctl ssh info now reports the specific reason instead of a generic “pod not ready” message. Fixed: When a Pod is not reachable, runpodctl ssh info reports the specific reason instead of a generic message. |
|
In reply to this discussion I'm applying your two style fixes: parentheses in place of the em dashes in runpodctl-pod.mdx, and removing "now" from the Note in runpodctl-ssh.mdx. I won't make any other edits, and I'll reply here when the branch is updated. |
…w' in ssh info note
|
In reply to this discussion Both style fixes are on the branch. The |
This branch was successfully deployed
1 participant
Open in Promptless
runpodctl pod getandrunpodctl pod listnow report a derivedruntimeStatus(plus aruntimeStatusReasontoken when there is more to say) alongsidedesiredStatus, so users can tell a Pod that is still pulling its image apart from one that is actually running.runpodctl ssh infonow names the specific reason a Pod is unreachable instead of a generic "pod not ready" message.This adds a "Pod runtime status" section to the runpodctl pod reference documenting the six
runtimeStatusvalues and the reason tokens, a worked JSON example, and guidance on polling to readiness. It updates the ssh reference with a table of the specific not-ready causes and their remedies — including a warning thatrunpodctl pod update --portsreplaces the entire port list and can restart the container — and adds a discoverability cross-link from the Pods SSH troubleshooting guide. Thepod list --statusflag description now clarifies that it filtersdesiredStatus(RUNNING/EXITED, matched case-insensitively) and does not acceptruntimeStatusvalues likeinitializing, which return no results — a distinction that matters now that the same page teaches theruntimeStatusvocabulary.Files touched:
Revision for runpodctl PR #366 (REST v2 migration): runpodctl no longer reports
lastStatusChangeor thestopped_by_*/terminated_*/*_outbidreason tokens, because REST v2 doesn't return the status-change text they were derived from. This revision removes them, adds the newerrorruntime status (desiredStatusERROR, which won't recover on its own and still bills) to the pod and ssh tables, updatesstopped/terminatedto map directly fromEXITED/TERMINATED, and replaces the note aboutdesiredStatusandruntimeStatusdisagreeing, since both now come from one read. The branch is also merged up to currentmain.Sources: runpodctl PR #315 (Linear CON-690); runpodctl PR #366.
Revision for reviewer feedback: Both requested style fixes are applied verbatim. (1) In
runpodctl-pod.mdx, the em dashes in theterminatedrow of the runtime status table are now parentheses. (2) Inrunpodctl-ssh.mdx, "now" is removed from thessh infoNote, which now reads "...reports the specific reason instead of a generic message." No other edits were made.Trigger Events
Tip: Use labels in the Promptless dashboard to categorize suggestions by release or team 🏷️