Skip to content

docs(vaultmgr): expand architecture document#5933

Draft
eriknordmark wants to merge 1 commit into
lf-edge:masterfrom
eriknordmark:vaultmgr-architecture-doc
Draft

docs(vaultmgr): expand architecture document#5933
eriknordmark wants to merge 1 commit into
lf-edge:masterfrom
eriknordmark:vaultmgr-architecture-doc

Conversation

@eriknordmark
Copy link
Copy Markdown
Contributor

Description

Replaces the 30-line stub at pkg/pillar/docs/vaultmgr.md with a full
architecture document covering:

  • vaultmgr's responsibilities (data-at-rest encryption, vault key
    lifecycle, controller rescue, post-vault upgradeconverter).
  • pubsub I/O — VaultStatus, EncryptedVaultKeyFromDevice,
    EncryptedVaultKeyFromController, the persistent VaultConfig,
    plus the on-disk inputs (filesystem type, allow-vault-clean
    sentinel, policy-PCR file, TPM NV indices and handles).
  • internal components — single-file event loop in
    cmd/vaultmgr/vaultmgr.go, the filesystem-handler abstraction
    (pkg/pillar/vault/handler{_ext4,_zfs}.go), key derivation
    (pkg/pillar/vault/key.go), and the TPM glue used out of
    pkg/pillar/evetpm.
  • five control-flow paths — first-boot install, steady-state unlock,
    controller-rescue (PCR-mismatch after upgrade), empty-key wipe, and
    the post-vault upgradeconverter handshake that flips
    ConversionComplete.
  • a debugging section — pubsub records, files under /persist,
    the relevant fscrypt / zfs / vaultmgr / tpmmgr CLIs, log filtering
    under /persist/newlog/devUpload, useful grep patterns, and how
    to force each transition.

References from the original doc are carried forward in a "Further
reading" section: docs/SECURITY.md, the LF Edge "Encrypting
Sensitive Information at Rest at the Edge" and "Security APIs"
wiki pages, and a link to https://github.com/google/fscrypt.

The doc is structured to mirror nodeagent.md and baseosmgr.md
so the pillar docs remain consistent across microservices, as part
of the ongoing effort to give every pillar agent an architecture
doc and unit-test suite.

How to test and validate this PR

Docs-only change. Validation is a markdown review:

  • Render pkg/pillar/docs/vaultmgr.md (e.g. on github.com) and
    spot-check formatting (tables, fenced code blocks, links).
  • Cross-reference the "Components" section against
    pkg/pillar/cmd/vaultmgr/vaultmgr.go, pkg/pillar/vault/*.go, and
    pkg/pillar/evetpm/*.go for technical accuracy.
  • Confirm the well-known TPM handles and NV indices listed match
    pkg/pillar/evetpm/tpm.go.

No code changes; no automated test required.

Changelog notes

No user-facing changes.

PR Backports

Docs-only refactor, no need to backport.

  • 16.0-stable: No, docs-only refactor.
  • 14.5-stable: No, docs-only refactor.
  • 13.4-stable: No, docs-only refactor.

Checklist

  • I've provided a proper description
  • I've added the proper documentation
  • I've tested my PR on amd64 device — N/A, docs only
  • I've tested my PR on arm64 device — N/A, docs only
  • I've written the test verification instructions
  • I've set the proper labels to this PR
  • I've checked the boxes above, or I've provided a good reason why I didn't check them

Replace the 30-line stub with a full architecture doc covering
responsibilities, pubsub I/O, the filesystem-handler abstraction
(ext4 fscrypt, ZFS native encryption), key derivation, the TPM glue
in pkg/pillar/evetpm, and the five control-flow paths: first-boot
install, steady-state unlock, controller-rescue, empty-key wipe,
and the post-vault upgradeconverter. The debugging section covers
the canonical pubsub records, the on-disk files under /persist,
the relevant fscrypt / zfs / vaultmgr / tpmmgr CLIs, log filtering
under /persist/newlog/devUpload, useful grep patterns, and how to
force each transition for development.

Preserves the references the original doc carried (SECURITY.md,
the "Encrypting Sensitive Information at Rest at the Edge" wiki
page, https://github.com/google/fscrypt, the Security APIs wiki
page, and the /persist/newlog/devUpload log location).

Structured to mirror nodeagent.md and baseosmgr.md so the pillar
docs remain consistent across microservices.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: eriknordmark <erik@zededa.com>
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