Skip to content

Node Bootstrap Trust Delivery v1

As of: March 9, 2026

Purpose

Define the platform baseline for delivering and updating control-plane HTTPS trust to node agents without manual operator file copy.

This document covers: 1. bootstrap trust bundle shape, 2. first-delivery path, 3. update and rotation direction, 4. audit and rollback expectations.

Scope

In scope: 1. trust material for control-plane HTTPS/API verification, 2. onboarding and bootstrap delivery path, 3. trust-bundle update model, 4. CA rotation handling direction.

Out of scope: 1. node certificate issuance internals, 2. direct Vault implementation details, 3. provider-specific bare-metal bootstrap mechanics.

Problem Statement

Recent real-node onboarding on platform_control required manual copy of the public CA bundle to establish HTTPS trust for: 1. enrollment, 2. renewal, 3. task polling, 4. terminal stream initiation.

That is acceptable for one bootstrap test, but not for a reusable platform baseline.

Trust Separation

Two trust domains must remain distinct:

1. Control-plane HTTPS trust

Used by the node agent to verify: 1. GPUAAS_API_URL 2. other platform-controlled HTTPS endpoints the node agent talks to

Stored at: 1. GPUAAS_CA_BUNDLE_PATH

2. Node-cert lifecycle trust

Used for node certificate issuance/renewal artifacts returned by enrollment and renewal flows.

Stored at: 1. GPUAAS_NODE_CERT_CA_BUNDLE_PATH

These paths must never be collapsed into one file.

Bootstrap Trust Bundle

The platform must treat bootstrap trust as a versioned bundle, not a loose file.

Minimum fields: 1. trust_bundle_version 2. environment_name 3. environment_domain 4. bundle_pem 5. sha256_fingerprint 6. published_at 7. optional replaces_version

This bundle is the control-plane HTTPS trust root for node bootstrap.

Initial Delivery Model

Rule

Nodes still talk only to platform-controlled endpoints. They do not fetch trust material from Vault directly.

Preferred first-delivery path

The node bootstrap bundle should include: 1. GPUAAS_API_URL 2. GPUAAS_CA_FINGERPRINT 3. either: - embedded trust bundle material, or - a platform-owned trust-bundle URL reachable through the same control-plane authority

Bootstrap/onboarding should deliver: 1. a rendered trust bundle file, 2. plus the expected fingerprint/version metadata, 3. through the same onboarding package or cloud-init payload that delivers node identity/bootstrap metadata.

That keeps first trust under platform control and removes the scp step.

Update Model

Trust updates must be explicit and auditable.

Recommended direction: 1. control plane publishes a new bootstrap trust bundle version, 2. onboarding paths use the latest version for new nodes, 3. enrolled nodes receive trust-bundle update instructions through a typed platform-controlled path, 4. node agent writes the new control-plane trust bundle to GPUAAS_CA_BUNDLE_PATH, 5. node agent records currently trusted bundle version.

Normal updates must not require: 1. binary rebuild, 2. manual shell edits, 3. direct human file copy to every node.

Rotation Model

New node bootstrap

  1. new node receives current trust bundle version at bootstrap time,
  2. node verifies the platform endpoint using that bundle and/or fingerprint,
  3. node enrolls normally.

Existing nodes during CA rotation

  1. platform stages new trust bundle version,
  2. control plane distributes updated trust bundle to enrolled nodes through a platform-owned path,
  3. nodes accept the new trust root before the old one is retired,
  4. explicit grace window is documented and auditable.

Rollback

If the new trust bundle is faulty: 1. platform may revert nodes to the previous trust bundle version during grace, 2. rollback must be auditable, 3. rollback must not silently merge public HTTPS trust with node-cert lifecycle trust.

Delivery Options

Option A: Embedded bundle in onboarding/bootstrap payload

Good for: 1. cloud-init, 2. MaaS-delivered bootstrap, 3. operator-downloaded bootstrap package.

Pros: 1. simplest first trust path, 2. no second fetch before enrollment.

Option B: Platform-owned trust-bundle endpoint

Good for: 1. environments where bootstrap payload should stay small, 2. controlled trust refresh flows.

Constraints: 1. first fetch still requires a bootstrap fingerprint anchor, 2. endpoint must be platform-controlled and environment-stable, 3. node must not need generic internet CA trust to start.

Use embedded bundle delivery first. Add endpoint-based refresh later if it simplifies rotation.

Audit Requirements

Every trust-bundle lifecycle mutation must be auditable: 1. bootstrap_trust.publish 2. bootstrap_trust.activate 3. bootstrap_trust.rollback 4. bootstrap_trust.retire

Recorded fields: 1. actor 2. trust bundle version 3. replaces version when applicable 4. environment 5. fingerprint 6. correlation id 7. result

Node-side reporting should include: 1. current control-plane trust bundle version, 2. current fingerprint, 3. last successful trust-bundle update time.

Transitional Reality

Today some real nodes still require manual CA copy.

That is acceptable only as a temporary operator bootstrap path if: 1. the canonical lifecycle is this document, 2. new environment design work does not assume manual scp forever, 3. bootstrap trust and node-cert trust stay separate.

Non-Negotiable Invariants

  1. node agents still talk only to platform-controlled endpoints,
  2. public HTTPS trust and node-cert lifecycle trust remain distinct,
  3. trust updates must be auditable and reversible,
  4. node bootstrap must not depend on direct Vault access,
  5. the stable environment endpoint model from Platform_DNS_Cert_Endpoint_Model_v1.md remains the anchor.
  1. doc/architecture/PKI_Spec.md
  2. doc/architecture/Node_Agent_Spec.md
  3. doc/architecture/Platform_Signing_and_Bootstrap_Trust_v1.md
  4. doc/architecture/Platform_DNS_Cert_Endpoint_Model_v1.md
  5. doc/architecture/Platform_Vault_Secrets_Baseline_v1.md