Outdated SPIFFE Reference Implementation Architecture

[torinvdb]

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. I spoke briefly with @dfeldman in the SPIFFE Community Day chat, and it appears the contents of the documents are outdated and likely no longer relevant to the current version of SPIRE.

As the linked Google Docs are locked, I don't know what the original implementation architecture looked like, but I believe there is significant value in updating it to match the latest version of SPIRE. By doing so, the SPIRE Agent & Server configuration reference can be supplemented with a reference implementation architecture for those getting interested & involved with using the project. I'd be happy to assist in modeling this updated architecture with the right clarification on the original documentation.

[amartinezfayo]

Thank you @torinvandenbulk for filing this issue.
I think that the main motivation to keep the links to those old documents was to have a historical reference about the origin of some of the first architectural decisions in SPIRE. Those documents were probably held under the Scytale organization (which was then acquired by HPE), in the early days of SPIRE development.
Maybe @drrt has some idea of how to get access to those docs, or who owns them now?

but I believe there is significant value in updating it to match the latest version of SPIRE

I think that it would be great to have something like that, although I'm worried about its maintenance over time, which I think would be challenging.

[edwbuck]

One document, the SPIFFE Reference Implementation Architectur, is readable without embedded images, courtesy of the Internet Archive Project (aka the Wayback Machine) . If there is enough interest, it should be transcribed into a more accessible location. Note that the early forms of Google Docs seems to have damaged the capture of this document, leading to a capture with embedded issues that lead to requests to reload the document.

The other document, the Design Document: SPIFFE Reference Implementation (SRI), is also readable without embedded images, courtesy of the Internet Archive Project (aka the Wayback Machine) . Again, if there is enough interest, it too should be transcribed into a more accessible location. Again, the javascript and other elements inherit to Google Docs seems seems to have damaged the capture of this document, leading to a capture with embedded issues leading to reqeusts to reload the document.

This comment is informational, and doesn't imply that we would use these copies for any resolution; but, if no other copies are available, we now have links to the documents, in their respective image-free forms.

I like the idea of a reference architecture, as it prevents drift from the architectural principles by documenting the architectural principles. That said, I share Agustin's concerns that the documentation is likely already quite out of date, and would require a good review to ensure it is relevant to today's source code.

[evan2645]

Hey @torinvandenbulk , thank you for opening this, and thank you to @amartinezfayo and @edwbuck for digging in

I have a question for you - is the content you're looking for adequately covered in the SPIFFE book? If so, does it make sense to replace these old design doc links with a reference to it?

[torinvdb]

Thank you, @amartinezfayo and @edwbuck, for shedding some light on the reference architecture sources. After having read through the previous documentation (via the Wayback Machine), I think that the high-level design decisions and configuration items of SPIRE are adequately covered in the SPIFFE book. Supplementing the current SPIRE Server & Agent configuration reference docs with links to the book is a good call for visibility @evan2645 .

That said, I believe there is a gap between the book's coverage and reference implementation documentation. The book covers deployment topologies well, and there are already exists some excellent low-level examples of getting started with SPIRE. A in-depth reference architecture could be beneficial to bridge the gap and provide a comprehensive guideline for practitioners looking at running SPIRE. My mind immediately thinks of the Secure Software Factory and FRSCA, as they provide both a reference architecture and an operational tech stack for building a secure software supply chain. This is just an example for illustrative purposes, as the scope of these two projects is widely different than in our case, but it shows the general idea.

The SPIFFE Reference Implementation Architecture looks like it was aiming to do something similar to this with K8s and AWS. Given the complexity of maintaining these reference architectures with vendor-specific services, I'm hesitant to suggest CSP-specific implementation diagrams, but K8s would be a good open source example. You bring up a good point @amartinezfayo , maybe agreeing on a more lightweight approach than a full revamp of the original could ease some complexity? Not suggesting we abandon their content though, but use them as source for a new reference implementation architecture based on the latest docs and existing examples to help support the effort.

[amartinezfayo]

maybe agreeing on a more lightweight approach than a full revamp of the original could ease some complexity? Not suggesting we abandon their content though, but use them as source for a new reference implementation architecture based on the latest docs and existing examples to help support the effort.

@torinvandenbulk That seems reasonable and would be useful to have IMO. My main concern continues to be the resources needed to work on this effort. From your initial comment, it seems that you would be willing to help with this?
If that's the case, maybe a good first step would be to create a separate issue (I believe that it should be in https://github.com/spiffe/spiffe.io) for this and briefly explain what content would be added. It could be structured in a way that 1) the content is added in incremental pieces, so it doesn't need to have all covered at once and 2) is focused on the architecture and design principles and not on the implementation details so it's less prone to become outdated over time.
Although I don't think that we can commit to help on writing the content, we can definitely help reviewing it.
What do you think?

[torinvdb]

From your initial comment, it seems that you would be willing to help with this?
If that's the case, maybe a good first step would be to create a separate issue (I believe that it should be in https://github.com/spiffe/spiffe.io) for this and briefly explain what content would be added. It could be structured in a way that 1) the content is added in incremental pieces, so it doesn't need to have all covered at once and 2) is focused on the architecture and design principles and not on the implementation details so it's less prone to become outdated over time.
Although I don't think that we can commit to help on writing the content, we can definitely help reviewing it.
What do you think?

Absolutely, I'd be more than willing to work on this, and your suggestion seems like a sensible approach to me - I'll open an issue in the SPIFFE repo to track this. Thanks for all your help guiding this initiative in the right place.

[amartinezfayo]

That's great, thank you @torinvandenbulk! I'll go ahead and close the issue here.