doc: add TPM deployment walkthrough and reference architecture#6775
Open
Pittu-Sharma wants to merge 5 commits into
Open
doc: add TPM deployment walkthrough and reference architecture#6775Pittu-Sharma wants to merge 5 commits into
Pittu-Sharma wants to merge 5 commits into
Conversation
Signed-off-by: pittu sharma <pittusharma47@gmail.com>
Pittu-Sharma
requested review from
MarcosDY,
amartinezfayo,
evan2645,
rturner3 and
sorindumitru
as code owners
March 22, 2026 08:21
Author
|
Hi maintainers, I have added the TPM deployment walkthrough and reference architecture. Please review when convenient. Thanks! |
Member
|
Thanks @Pittu-Sharma for opening this PR. Some initial thoughts:
|
Signed-off-by: pittu sharma <pittusharma47@gmail.com>
|
|
||
| Before configuring SPIRE, each node's TPM must be provisioned with a Local Device Identifier (LDevID) out-of-band. This process typically involves: | ||
|
|
||
| 1. **Key Generation**: Using a tool like `tpm2-tools`, generate an asymmetric key pair securely within the TPM. The private portion of the key never leaves the hardware. |
Member
There was a problem hiding this comment.
You should have more detailed information here, exactly what commands should you run to generate the right key.
Member
There was a problem hiding this comment.
Hi @Pittu-Sharma, checking in to see if you are still planning on addressing this.
sorindumitru
enabled auto-merge
May 21, 2026 07:05
sorindumitru
disabled auto-merge
May 21, 2026 07:05
Signed-off-by: Marcos Yacob <marcosyacob@gmail.com>
There was a problem hiding this comment.
Pull request overview
Adds a new non-Kubernetes TPM 2.0 deployment guide and links it from existing SPIRE docs to improve discoverability and provide an end-to-end reference for TPM-based node attestation.
Changes:
- Added
doc/tpm_deployment_walkthrough.mddescribing a TPM-based redundant SPIRE deployment and provisioning flow. - Linked the walkthrough from
doc/using_spire.md. - Added “Prerequisites” sections in the agent/server
tpm_devidplugin docs linking to the walkthrough.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| doc/using_spire.md | Adds a “TPM” section linking to the new walkthrough for discoverability. |
| doc/tpm_deployment_walkthrough.md | New TPM deployment/provisioning walkthrough and reference architecture notes. |
| doc/plugin_server_nodeattestor_tpm_devid.md | Adds prerequisites and cross-link to the walkthrough from the server plugin doc. |
| doc/plugin_agent_nodeattestor_tpm_devid.md | Adds prerequisites and cross-link to the walkthrough from the agent plugin doc. |
Comment on lines
+13
to
+14
| - **Agent Nodes**: Physical or virtual infrastructure with `/dev/tpm0` | ||
| available. |
|
|
||
| ## Requirements | ||
|
|
||
| - **TPM 2.0 hardware**: Accessible via `/dev/tpm0`. |
Comment on lines
+20
to
+21
| - **Pre-provisioned DevID**: Key blobs and certificates must be on-node before | ||
| starting the agent. |
Comment on lines
+133
to
+136
| (in dev shell) # ./bin/spire-server entry create \ | ||
| -spiffeID spiffe://example.org/node/primary \ | ||
| -node \ | ||
| -selector tpm_devid:subject:cn:node-01.example.org |
Comment on lines
+139
to
+146
| ## Scaling and Recovery | ||
|
|
||
| **Horizontal Scaling**: Add server instances to the cluster by pointing them | ||
| to the same datastore. Scale agents by provisioning new TPM-backed nodes. | ||
|
|
||
| **Trust Recovery**: If an agent's certificate expires or the node is wiped, | ||
| re-provision the TPM and refresh the agent's identity. The agent will | ||
| re-attest using the new hardware-bound DevID on its next cycle. |
Comment on lines
+11
to
+13
| The server must be configured with the CA certificate(s) that signed the agents' | ||
| LDevID certificates (`devid_ca_path`). These are the same CA certificates used | ||
| during the out-of-band node provisioning process. See the |
Signed-off-by: Marcos Yacob <marcosyacob@gmail.com>
sorindumitru
left a comment
sorindumitru
left a comment
Member
There was a problem hiding this comment.
When I follow the guide I get:
unable to start a new TPM session: cannot load DevID key on TPM: tpm2.DecodePublic failed: decoding TPMT_PUBLIC: unexpected EOF
| -r /opt/spire/conf/agent/devid.priv.blob \ | ||
| -c /tmp/devid.ctx | ||
|
|
||
| tpm2_evictcontrol -C o -c /tmp/devid.ctx 0x81000001 |
Member
There was a problem hiding this comment.
Is there some way to figure out the right 0x81000001 value to use? I had to use a different once since this one was already in use:
WARNING:esys:src/tss2-esys/api/Esys_EvictControl.c:330:Esys_EvictControl_Finish() Received TPM Error
ERROR:esys:src/tss2-esys/api/Esys_EvictControl.c:114:Esys_EvictControl() Esys Finish ErrorCode (0x000001c4)
ERROR: Esys_EvictControl(0x1C4) - tpm:parameter(1):value is out of range or is not correct for the context
ERROR: Unable to run tpm2_evictcontrol
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.
Pull Request check list
Affected functionality
Documentation for TPM-based node attestation (non-Kubernetes).
Description of change
Created
doc/tpm_deployment_walkthrough.mdto provide a comprehensive reference architecture and redundant setup guide for SPIRE on TPM 2.0. Updateddoc/using_spire.mdwith a link to the new guide for easy discoverability.Which issue this PR fixes
fixes #5291