SPIFFE Design Document

[torinvdb]

A follow-up to Issue #4560 in the spiffe/spire repository, the current links to the SPIFFE Reference Implementation Architecture & Design Document: SPIFFE Reference Implementation (SRI) documents within the official spiffe.io docs are deprecated and locked to public view. These links can be found within the 'Further Reading' sections of the SPIRE Agent Configuration Reference and the SPIRE Server Configuration Reference.

After deliberation on Issue #4560, this new issue was opened to guide discussion around creating a lightweight SPIFFE Reference Implementation (SRI) design document per the latest versions of the project. As it appears the previous documents were deprecated for some time and not entirely relevant to current versions, the concern of maintenance and overhead was rightfully brought up by @amartinezfayo. Regarding this, @edurra and I are willing to work on this, but I think some deliberation on what the structure and primary outcomes this doc would take on could be beneficial to undertake an iterative approach and better align with the project trajectory.

At the time of writing, I was considering a varied permutation of the original SRI document, which primarily focuses on the categories below. Mainly, the objective, as guided by @amartinezfayo, would be to focus on architectural and design decisions rather than direct implementation to keep the document maintainable. I welcome feedback in any regard to this issue and look forward to working on it!

Component Design

Break down SPIRE components like the server/agent and how they work (e.g., API design, etc) within the overall plugin architecture to provide secure workload attestation. To keep this lightweight, we can lean on the current SPIRE Architecture and Components section of the docs while focusing on how everything fits together from a design standpoint.

Reference Architecture

In this section, a reference architecture diagram of SPIRE will be provided to put all the pieces together in one place and provide technical run-throughs of key process flows (e.g., node/workload attestation and agent bootstrap). This diagram should expand on the high-level one provided in the SPIRE Architecture and Components section of the docs and seek to provide an in-depth explanation of how the various API calls flow through the reference architecture. Additionally, advanced deployment topologies like nested & federated could also have their own modified diagrams in future updates to the design document so readers can easily reference the overall data flow within the system for other use cases.

Putting it all together

Tie in the component design and architecture principles by referencing direct examples of deploying SPIRE, like those provided in the spire-tutorials repository. On top of this, touching on integrations with the broader ecosystem (e.g., using SPIRE with Envoy + OPA) can help showcase how SPIRE helps build Zero Trust Networks by acting as an IdP (not set on this, though, as it can change frequently).