Skip to content

docs: add node infrastructure concept page (Batch 2)#210

Merged
marc0olo merged 9 commits intoinfra/learn-hub-migration-prepfrom
docs/concepts-node-infrastructure
May 8, 2026
Merged

docs: add node infrastructure concept page (Batch 2)#210
marc0olo merged 9 commits intoinfra/learn-hub-migration-prepfrom
docs/concepts-node-infrastructure

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented May 6, 2026

Summary

  • Creates docs/concepts/node-infrastructure.md with full migration of two Learn Hub articles: IC-OS overview (SetupOS, HostOS, GuestOS) and Trusted Execution Environments
  • TEE section covers: SEV-SNP memory encryption, VM launch measurements, attestation reports (including node-to-node and external attestation paths), sealing keys, disk partition layout table (A/B sets, which partitions are encrypted and why), traditional-vs-sealing-key encryption history, HKDF/LUKS key derivation, full 7-step GuestOS upgrade process with Upgrade VM and mutual attestation, and full emergency recovery section (manual rollback with NNS proposal steps + Recovery-GuestOS mechanism with upgrade-vs-recovery comparison table)
  • Adds 3 images from Learn Hub: TEE architecture overview (tee-overview.jpg), SEV-SNP attestation report diagram (tee-attestation-report.svg), SEV-SNP key derivation diagram (tee-key-derivation.svg)
  • Adds concepts/node-infrastructure to the explicit Concepts sidebar after app-architecture
  • Updates docs/concepts/https-outcalls.md: replaces the Learn Hub TEE link with the new internal path; removes a stale Learn Hub further-reading link for the skipped HTTPS Outcalls article

Staging files deleted

  • .migration/learn-hub/how-does-icp-work/node-infrastructure/overview.mddocs/concepts/node-infrastructure.md
  • .migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.mddocs/concepts/node-infrastructure.md#trusted-execution-environments

Sync recommendation

hand-written

@marc0olo marc0olo requested a review from a team as a code owner May 6, 2026 14:57
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Review notes

Content and links look good. One soft dependency to note:

Dependency on #209: The "Further reading" section links to protocol/index.md, which only exists once PR #209 merges. Not a hard build failure, but the link will be dead until then. Consider merging after #209 or temporarily removing the link and adding it back post-merge.

No other issues: no banned patterns, frontmatter complete, Learn Hub TEE link correctly replaced with the internal node-infrastructure.md#trusted-execution-environments path, <!-- Upstream: --> comment present.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Two items to address before merging:

1. Em-dash on line 89 (banned project-wide)

The "Further reading" bullet uses an em-dash, which is banned per project style rules:

- [Protocol Stack](protocol/index.md) — the replica software that runs inside GuestOS

Fix:

- [Protocol Stack](protocol/index.md): the replica software that runs inside GuestOS

2. Soft dependency on PR #209

The link to protocol/index.md will be a dead link until PR #209 merges and that page exists. Recommend merging this PR after #209 to avoid a temporarily broken link.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Feedback addressed:

  • Replaced em-dash with colon in node-infrastructure.md line 89 Further reading bullet

Note on the soft dependency: the link to protocol/index.md will still be dead until PR #209 merges. Since #209 is now ready, recommend merging #209 first then this one.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 7, 2026

Brand voice audit applied. The following fixes were committed in 7fe7c79:

Fixed automatically:

  • node-infrastructure.md: expanded NNS on first occurrence ("pushed by the NNS" → "pushed by the Network Nervous System (NNS)")
  • node-infrastructure.md: replaced banned term "workload" ("untrusted workload running in a virtual machine" → "untrusted process running in a virtual machine")

No other brand issues found: no blockchain comparisons, no em-dashes, no "reverse gas model", no DAO, no "on-chain"/"cross-chain"/"full-stack" with hyphens, no "token" used as a primary descriptor.

@marc0olo marc0olo force-pushed the infra/learn-hub-migration-prep branch from dabad66 to d191270 Compare May 8, 2026 09:02
@marc0olo marc0olo force-pushed the docs/concepts-node-infrastructure branch from 30ded57 to 20c2520 Compare May 8, 2026 09:18
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 8, 2026

After PR #209 merges:

  1. Add { slug: "concepts/node-infrastructure" } to sidebar.mjs after { slug: "concepts/app-architecture" } in the explicit Concepts items list
  2. Update Further reading to restore: - [Protocol Stack](protocol/index.md): the replica software that runs inside GuestOS

marc0olo added 8 commits May 8, 2026 14:31
Migrates two Learn Hub articles from the "Node Infrastructure" section into
a single docs/concepts/node-infrastructure.md page covering the IC-OS stack
(SetupOS, HostOS, GuestOS) and TEE fundamentals (SEV-SNP memory encryption,
VM launch measurements, attestation, and sealing keys).

Updates docs/concepts/https-outcalls.md: replaces Learn Hub TEE link with
the new internal path and removes a stale Learn Hub further-reading entry.
- Expand NNS to "Network Nervous System (NNS)" on first occurrence
- Replace "untrusted workload" with "untrusted process" (workload is banned vocabulary)
…m Learn Hub

Adds three missing images (TEE overview, attestation report, key
derivation diagrams). Restores content dropped during initial migration:
node-to-node and external attestation paths, encrypted partition names
(var/store vs boot/root/config), HKDF/LUKS key derivation, detailed
GuestOS upgrade process with Upgrade VM and mutual attestation, and the
full emergency recovery section covering manual rollback and the
governance-gated Recovery-GuestOS mechanism.
… encryption history, and full recovery steps

Adds the disk partition layout table (showing which partitions are
encrypted and why), the upgrade-vs-recovery-image comparison table, the
traditional-vs-sealing-key disk encryption context, the full 7-step
manual rollback and Recovery-GuestOS numbered processes, and the
four-feature overview list. Completes the full Learn Hub TEE article
migration.
@marc0olo marc0olo force-pushed the docs/concepts-node-infrastructure branch from f5c8839 to bcbf7f3 Compare May 8, 2026 12:33
…urther reading link

Adds node-infrastructure after app-architecture in the explicit Concepts
sidebar (now that PR #209 has merged). Restores the Protocol Stack
further reading link that was blocked during cross-branch validation.
@marc0olo marc0olo merged commit 072e068 into infra/learn-hub-migration-prep May 8, 2026
3 checks passed
@marc0olo marc0olo deleted the docs/concepts-node-infrastructure branch May 8, 2026 13:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant