docs(vaultmgr): expand architecture document#5933
Draft
eriknordmark wants to merge 1 commit into
Draft
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Replaces the 30-line stub at
pkg/pillar/docs/vaultmgr.mdwith a fullarchitecture document covering:
vaultmgr's responsibilities (data-at-rest encryption, vault keylifecycle, controller rescue, post-vault
upgradeconverter).VaultStatus,EncryptedVaultKeyFromDevice,EncryptedVaultKeyFromController, the persistentVaultConfig,plus the on-disk inputs (filesystem type, allow-vault-clean
sentinel, policy-PCR file, TPM NV indices and handles).
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 ofpkg/pillar/evetpm.controller-rescue (PCR-mismatch after upgrade), empty-key wipe, and
the post-vault upgradeconverter handshake that flips
ConversionComplete./persist,the relevant fscrypt / zfs / vaultmgr / tpmmgr CLIs, log filtering
under
/persist/newlog/devUpload, useful grep patterns, and howto force each transition.
References from the original doc are carried forward in a "Further
reading" section:
docs/SECURITY.md, the LF Edge "EncryptingSensitive 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.mdandbaseosmgr.mdso 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:
pkg/pillar/docs/vaultmgr.md(e.g. on github.com) andspot-check formatting (tables, fenced code blocks, links).
pkg/pillar/cmd/vaultmgr/vaultmgr.go,pkg/pillar/vault/*.go, andpkg/pillar/evetpm/*.gofor technical accuracy.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.
Checklist