Create SSH-key-management.mdx - #748
lavanya-gunreddi wants to merge 31 commits into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
| ``` | ||
| </Step> | ||
| <Step title="Add the public key to your account"> | ||
| Paste your public key into the **SSH Public Keys** field in your [Runpod account settings](https://www.console.runpod.io/user/settings). This is the same field for team and organization members. There is no organization-specific keys page. For the full procedure, including the CLI method, see [Generate an SSH key and add it to your Runpod account](/pods/configuration/use-ssh#generate-an-ssh-key-and-add-it-to-your-runpod-account). |
There was a problem hiding this comment.
Citation
Citation withdrawn.
Confirms SSH public keys are personal/per-member, pasted into the "SSH Public Keys" field in account settings (https://www.console.runpod.io/user/settings) -- same field regardless of team vs. org membership; there is no separate org-level SSH key store.
Source: use-ssh.mdx:43 · e13c3f7
|
|
||
| ## Key scope and membership | ||
|
|
||
| Runpod injects the union of current members' public keys into a Pod when the organization creates it, and that key set is frozen at creation. A key added after a Pod is created reaches only Pods deployed afterward. Restarting a Pod reuses its original key set, so to put an updated key set on a Pod, redeploy it by creating a new Pod. |
There was a problem hiding this comment.
Citation
Citation withdrawn.
Corroborates create-time key injection: Runpod injects account public keys into a Pod via the PUBLIC_KEY mechanism, overridable per-Pod with SSH_PUBLIC_KEY at deploy time. This documents the create-time injection behavior generally; it does not independently confirm the org-specific "union of current members' keys, frozen at creation, unaffected by restart" semantics, which rest on evidence outside this docs repo (reviewer-cited monorepo source) and are only consistent with, not proven by, this citation.
Source: use-ssh.mdx:71–73 · e13c3f7
| - Dev. | ||
| - Basic. | ||
|
|
||
| The Billing role is limited to billing tasks: it does not manage SSH keys or connect to compute. |
There was a problem hiding this comment.
Citation
Citation withdrawn.
Confirms real org/team roles are Basic, Billing, Dev, Admin (not Owner/Member/Read-only) and that the Billing role cannot connect to existing Pods (permissions matrix row "Connect to existing Pods": Basic true, Billing false, Dev true, Admin true).
|
|
||
| **Connected to the wrong Pod** | ||
|
|
||
| Copy the IP and port fresh from the **Connect** tab. They may change when you stop and resume the Pod. |
There was a problem hiding this comment.
Citation
Citation withdrawn.
Corroborates "the IP and port may change when you stop and resume the Pod" -- matches connect-to-ide.mdx wording ("If you stop and then resume your Pod, the port numbers may change"), correcting the inaccurate "each time restarted" framing.
Source: connect-to-ide.mdx:168 · e13c3f7
|
Yes — we've addressed rambo-runpod's review comments and pushed updates to this branch. The main fix: the page described an organization-level SSH key store, but that doesn't exist in the product. We reframed it around the real model — each member adds their own SSH public key in their account settings, and when the organization deploys a Pod, Runpod injects the union of all current members' keys, frozen at Pod creation. We corrected the follow-on consequences to match: deleting a key or removing a member only affects future deploys, so existing Pods must be redeployed (not restarted) to pick up the change. We also fixed the roles list and the inverted connection commands, added a data-loss warning wherever the page tells readers to terminate and redeploy, and removed all eight We scoped this pass to
One thing worth a human check before merge: the specific "union of current members' keys, frozen at Pod creation" semantics come from the reviewer's operator-verified notes. We corroborated the core model against existing docs, but please confirm against the product. |
rambo-runpod
left a comment
rambo-runpod
left a comment
There was a problem hiding this comment.
COMMENT: 1 critical, 3 high, 4 medium, 3 low
SEVERITY - medium
IMPACT - The page states injection unconditionally, but the deploy path only appends PUBLIC_KEY when startSsh is set and no PUBLIC_KEY is already in the env, so a template or deploy-time override silently suppresses the member union.
SOLUTION - Note that a PUBLIC_KEY or SSH_PUBLIC_KEY value supplied at deploy time replaces the union, and add that as a cause under "Key not injected into a Pod".
SEVERITY - medium
IMPACT - Five passages tell readers that terminating and redeploying is the only way to change a Pod's key set, so operators destroy container data they could have kept.
SOLUTION - Offer Edit Pod with a new PUBLIC_KEY value first (resets the Pod but preserves /workspace and network volumes), and keep terminate as the fallback.
SEVERITY - medium
IMPACT - SSH keys are named rows with runpodctl ssh add-key and remove-key --name, but "Manage your keys" documents only the blob textarea, right after telling readers to verify with runpodctl ssh list-keys.
SOLUTION - Add the CLI add and remove path alongside the console field, matching the Web/CLI tab pattern in pods/configuration/use-ssh.mdx.
SEVERITY - medium
IMPACT - Line 32 sends readers to "the full role matrix" for SSH key permissions, but roles-and-permissions.mdx is Teams content with no SSH key row, so the link answers nothing.
SOLUTION - Add an SSH key management row to that matrix, or drop the link until an Organizations role matrix exists.
Unaddressed (12)
Three of the four 404 links carried from review 1 are still broken; npx mintlify broken-links on this head reports the same 6 in 2 files.
- high -
overview.mdxlinks to/organizations/roles-and-permissions,/organizations/ssh-key-management,/organizations/resource-tagging; all three still 404: #748 (comment) - high -
manage-accounts.mdxstill points at/accounts-billing/roles-and-permissionsin three places (lines 36, 45, 51): #748 (comment) - medium -
SSH-key-management.mdxis still the only hand-written page in the repo with capitals in its filename: #748 (review) - medium - PR #682 still adds a parallel root-level
organizations/tree that conflicts with this one: #748 (review) - medium -
roles-and-permissions.mdxis still Teams content sitting in the Organizations nav group: #748 (review) - medium -
pods/configuration/use-ssh.mdxis still untouched, so DOCS-480's cross-link from the main SSH page is missing: #748 (review) - medium -
resource-tagging.mdxstill does not state that tagging is available to Organizations only, which the follow-up asked for: #748 (comment) - medium - one
[CONFIRM: ...]author note remains atoverview.mdx:21: #748 (review) - low - the new Organizations
pagesarray indocs.jsonis still indented two levels shallower than its siblings: #748 (review) - low -
overview.mdxstill lowercases pods and capitalizes Endpoints, Network Volumes, Clusters: #748 (review) - low -
resource-tagging.mdxstill has nosidebarTitleand its title still reads "Resource tags": #748 (review) - low -
overview.mdx:21still uses the{ /* ... */ }comment form: #748 (review)
Resolved on SSH-key-management.mdx: the org-key-store critical, and the roles, rename, deletion, restart, connection-recipe and offboarding highs. Also resolved: the eight [CONFIRM] notes on that page, the horizontal rules, the DSA wording, and the stop-and-resume port wording from the follow-up.
Non-blocking (3)
SEVERITY - low
IMPACT - resource-tagging.mdx:9 still calls the tag value "optional" even though CreateTagInput.value is String!, so an omitted value is a schema error rather than a blank.
SOLUTION - Drop "optional" and keep only "can be left blank", per the follow-up correction.
SEVERITY - low
IMPACT - Three of the four new pages carry tag: "NEW" and overview.mdx does not, so the nav group shows an inconsistent badge set.
SOLUTION - Add tag: "NEW" to overview.mdx or drop it from all four.
SEVERITY - low
IMPACT - "There is no separate organization SSH keys page" appears three times (lines 10, 74, 84), padding the page with a restated negative.
SOLUTION - Keep it once in the intro and cut the repeats at lines 74 and 84.
Review metadata
review 2 · opus · b83240dc
RAN - jq . docs.json FAIL (parse error line 295) | npx mintlify broken-links 6 broken in 2 files, but nav unresolved because docs.json will not parse, so new-page links went unchecked | node scripts/validate-tooltips.js pass | source verification against RunPod monorepo 6b778e621 (2026-09-16): model/src/sshKey/orgKeyUnion.ts, model/src/authz/roleGrid.ts, model/src/authz/roleGrid.unit.test.ts, model/src/utils/index.ts, model/src/sshKey/manageSshPublicKeys.ts, node/graphql/schema/userSettings.ts
NOT RUN - vale (not installed) | mintlify dev render check (nav unbuildable until docs.json parses)
RELIED ON - pods/manage-pods.mdx for Edit Pod env semantics; I did not verify end-to-end that a Pod reset re-reads PUBLIC_KEY
| "accounts-billing/organizations/resource-tagging" | ||
| ] | ||
| } | ||
| "accounts-billing/sales-tax", |
There was a problem hiding this comment.
SEVERITY - critical
IMPACT - docs.json is invalid JSON, so the whole site nav fails to build and every page in it, not just the four new ones, is unreachable.
SOLUTION - Add the missing comma after the } closing the Organizations group on line 294, then confirm with jq . docs.json.
jq fails with Expected separator between values at line 295, column 42, and npx mintlify broken-links warns Failed to read or resolve docs.json on every pass, which also means its link check never resolved the nav and never validated the new pages. Introduced by the main merge e13c3f7f: docs.json parses cleanly at both origin/main and at 7f9324b6, and fails only at this head.
|
|
||
| - Admin. | ||
| - Dev. | ||
| - Basic. |
There was a problem hiding this comment.
SEVERITY - high
IMPACT - A team member with the Basic role follows this page, is told they may add their own key, and the mutation denies them; the page's Teams/Orgs parity claim makes the error unavoidable.
SOLUTION - Scope the Admin/Dev/Basic list to organization roles and state that under a team account only Admin and Dev can add or delete keys.
TEAM_ROLE_CAPABILITIES in model/src/authz/roleGrid.ts grants SSH_KEY_MANAGE to admin and dev only; owner, member, billing and basic all deny, pinned by roleGrid.unit.test.ts ("team basic x SSH_KEY_MANAGE -> false", both in teamCan and in the team-scope principal suite). ORG_ROLE_CAPABILITIES does grant it to basic, so the list is right for organizations and wrong for teams, while lines 10 and 74 assert the two are the same and line 32 links to a Teams roles page.
| - Dev. | ||
| - Basic. | ||
|
|
||
| The Billing role is limited to billing tasks: it does not manage SSH keys or connect to compute. |
There was a problem hiding this comment.
SEVERITY - high
IMPACT - A Billing member who already had a key on file gets OS-level SSH into every org Pod deployed after they join, while this line tells admins that role cannot connect to compute.
SOLUTION - Say the injected union covers every current member including Billing, and that excluding someone from Pod access requires removing them from the organization before the deploy.
getOrgMemberPubKeyUnion in model/src/sshKey/orgKeyUnion.ts selects organizationMembership by organizationId with no role filter, then unions those users' sshPublicKey rows. The Billing role's lack of POD.USE in ORG_ROLE_CAPABILITIES gates the console and API connect paths only; it does not remove the key from PUBLIC_KEY, and a personal account joined to an org brings its existing keys along.
|
|
||
| **Roles and permissions** — assign roles to org members to control access to pods, endpoints, billing, and org settings. See [Roles and permissions](/organizations/roles-and-permissions). | ||
|
|
||
| **SSH key management** — store SSH public keys at the org level so all members can securely connect to Pods without individual key setup. See [SSH key management](/organizations/ssh-key-management). |
There was a problem hiding this comment.
SEVERITY - high
IMPACT - The Organizations landing page still sells the org-level key store that review 1 flagged as nonexistent, so readers hit the wrong model before they ever reach the corrected page.
SOLUTION - Reword to match SSH-key-management.mdx: each member adds their own key in account settings, and org Pod deploys inject the union of members' keys at creation.
The corrective push scoped itself to SSH-key-management.mdx and left this line intact. orgKeyUnion.ts states "there is no org-owned key store", and SshPublicKey is keyed on userId only. "without individual key setup" is also backwards: individual key setup is exactly what the real model requires.
|
@Promptless Apply rules from promptless.md and runpod style guide to all the files in this branch |
|
In reply to this discussion On it — I'll apply the rules from promptless.md and the Runpod style guide across the files changed in this branch, and follow up here with the results. |
|
In reply to this discussion Review done — this branch changes six files, and I'm applying the style-guide and promptless.md fixes to each. A couple of notable items I'm addressing: |
- Rename SSH-key-management.mdx to kebab-case ssh-key-management.mdx and update docs.json nav + the overview link to the lowercase path - Fix docs.json Organizations pages-array indentation to match siblings - Replace em-dash label separators with colons in overview.mdx - Correct term casing in overview.mdx (Pods; endpoints/network volumes lowercase; Instant Clusters); spell out 'org' as 'organization' - Expand overview and resource-tagging meta descriptions to 110-160 chars
|
In reply to this discussion Done — the style-guide and promptless.md fixes have been applied and pushed to this branch (PR #748). That includes the kebab-case rename of the SSH key page with its nav and link updates, em-dash separators replaced with colons, term casing corrected (Pods, endpoints, network volumes, Instant Clusters), "org" spelled out to "organization", and two meta descriptions expanded to the required length. |
|
In reply to this discussion Done — I applied the Runpod style guide and promptless.md rules across all six files changed in this branch and pushed the result to PR #748. That included renaming the SSH page to lowercase kebab-case ( A few of rambo-runpod's review comments are factual/content items rather than style — for example the overview page still describing the old org-level key store, the Review: https://app.gopromptless.ai/suggestions/5c3954b9-ec0d-4b08-9f30-6441a7e95bfc |
2 participants
Style-guide + promptless.md pass (per @lavanya-gunreddi request)
Applied the Runpod style guide and promptless.md rules across the files changed in this branch. Disposition per reviewer item:
docs.jsoninvalid JSON (critical, review 2): applied verbatim — the missing comma was already fixed on the branch; this pass additionally re-indented the Organizationspagesarray to match its siblings and pointed the nav entry at the lowercase file.SSH-key-management.mdx→ssh-key-management.mdx; updateddocs.jsonand the overview link to the lowercase path.overview.mdxcasing (low): "Use Pods, endpoints, network volumes, and Instant Clusters": applied verbatim —pods→Pods,Endpoints→endpoints,Network Volumes→network volumes,Clusters→Instant Clusters.overview.mdxwith colons.overview.mdx(68→145) andresource-tagging.mdx(89→156) to the required 110–160 range.org→organizationin prose (style guide): applied inoverview.mdx.Not addressed in this style pass (out of scope — flagged for a human/factual follow-up)
This pass covered style and formatting only. The following review items are factual/content changes and were left for a separate pass:
[CONFIRM: ...]author note atoverview.mdx:21(Settings → Organization path) — an unverified UI-path claim.overview.mdx"SSH key management" bullet still says keys are stored "at the organization level"/"without individual key setup"; the SSH page was corrected to the per-member model, but the landing-page summary wording is a factual edit, not a style one.resource-tagging.mdxavailability wording (Organizations-only), the "tag value optional" vs "can be left blank" correction,sidebarTitle/title alignment, and thetag: "NEW"badge consistency.roles-and-permissions.mdxbeing Teams content in the Organizations nav group; team vs org role differences on the SSH page; the DOCS-480 cross-link frompods/configuration/use-ssh.mdx.