docs: Document pod runtime status and specific SSH not-ready reasons in the runpodctl reference - #758
docs: Document pod runtime status and specific SSH not-ready reasons in the runpodctl reference#758promptless[bot] wants to merge 2 commits into
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.
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).
|
|
||
| `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.
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.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
| 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.
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.
|
|
||
| ### Runtime status values | ||
|
|
||
| | Value | Meaning | What to do | |
There was a problem hiding this comment.
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).
|
|
||
| ### Runtime status reasons | ||
|
|
||
| | Token | Paired status | Meaning | |
There was a problem hiding this comment.
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).
| </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.
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").
| `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.
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.
| `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.
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.
| | 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.
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.
|
|
||
| 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.
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.
|
|
||
| </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.
Confirms runSSHInfoWithArgs includes a "runtimeStatus" key in the not-ready JSON/YAML output map alongside the error/id/name/status fields.
There was a problem hiding this comment.
(Line 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:
docs/pods/configuration/use-ssh.mdx
Line 77 in 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).
Open in Promptless
runpodctl pod getandrunpodctl pod listnow report a derivedruntimeStatus(plus aruntimeStatusReasontoken and the rawlastStatusChangetext) 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 five
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:
Source: runpodctl PR #315 (Linear CON-690).
Trigger Events
Tip: Use labels in the Promptless dashboard to categorize suggestions by release or team 🏷️