Skip to content

Native host access and verified return

View Markdown

Beta: this feature may change before general availability

This integration is an unqualified source candidate, disabled by default. Local tests do not establish customer access, physical erasure or successful return on hardware. An operator must qualify its fixed management image, provisioning authority, network and physical-host mapping before enabling a profile. Ordinary pool enrollment and the read-only local dashboard remain separate workflows.

The integration uses your existing access and reprovisioning authority. It does not create a new SSH service. Begin by completing the host package’s normal terminal Handback using its dedicated first connection credential. A local sticky hold or a Node deletion alone does not prove retirement.

An organization Owner or Admin uses the normal authenticated Node API. Status requires nodes:read; starting an operation requires an organization-level nodes:write credential. Existing project-restricted credentials cannot mutate org-scoped Nodes. Keep credentials out of JSON files and command histories.

  1. Read GET /apis/nodus.dev/v1/nodes/{node}/native-access. An unavailable response means no qualified fixed mapping exists for that Node. A configured first-use response says AwaitingFirstGrant, with generation 0 and nextGeneration: 1. approvedImages lists safe image aliases. Do not bypass a refusal with labels or direct database edits.
  2. Send POST to the same path with version: 1, action: "begin-grant", the expected generation, a new immutable UUID requestID, an operator-approved image alias and sshPublicKeys. Supply only public keys. Host identity, images, cleanup policy and credentials are server-owned.
  3. Read status until customerAccessReady is true. The normal controller queues the work; there is no manual advance command. The operator then uses the configured customer-image access path.
  4. To return the host, send action: "begin-return" with the same generation and a new requestID. Omit image and keys. Access eligibility is removed before cleanup begins.
  5. Wait for Returned. The trusted image’s physical probe and normal enrollment must both complete. The response’s returnedNode identifies the new management Node. Before another grant, retire that successor normally and use the returned nextGeneration; do not reuse an old Node or token.

Repeat an uncertain API request only with the same request UUID and identical fields. A changed duplicate refuses. Quarantined requires operator investigation; it is not permission to reissue an external mutation. Do not treat a timeout, an available host, or an active management image as cleanup proof.

The tested request shape is in examples/pools/native-return.json. It contains placeholder public data, not an enabled profile or credentials. Firmware that remains writable by a customer is outside this profile: disk erasure and GPU checks do not establish firmware integrity.