Document Trusted Builders

[dfreilich]

Summary

We now have a concept of a trusted builder, and we should document it.

What questions should this documentation answer?

• What is a trusted builder? What is an untrusted builder?
• What practical difference is there between them?
• What commands can I use with trusted or untrusted builders?

Who is the target audience for this documentation?

• App Developer
• Operator

Additional Information

Relevant RFCs:

• https://github.com/buildpacks/rfcs/blob/main/text/0025-dont-trust-builders.md
  Relevant Pack PRs:
• Execute the lifecycle in a single container pack#595
• run analyze, restore, and export in an ephemeral image pack#631
• Trust builder command pack#634
• Fail when using an untrusted builder and no lifecycle image available pack#644
• Add Trusted (Yes/No) output to inspect-builder pack#697
• Add list-trusted-builders command pack#693
• Add untrust-builder command pack#699
  Relevant articles:
• https://medium.com/buildpacks/faster-more-secure-builds-with-pack-0-11-0-4d0c633ca619

[yaelharel]

I would add to "What questions should this documentation answer?":

• How can I trust/untrust builders?
• How can I see what builders are trusted?

[jromero]

One thing to keep in mind is that this feature is specific to pack and NOT the buildpacks project as a whole. I would suggest that we have a section of the site dedicated to pack.

[dfreilich]

Hmm. But it did go through the RFC/spec process, and it is formally added to the spec, so it's a bit more broad than only pack, though in implementation it is only used by pack.

[dfreilich]

With #161, we should have a section for pack!

[jromero]

Hmm. But it did go through the RFC/spec process, and it is formally added to the spec, so it's a bit more broad than only pack, though in implementation it is only used by pack.

I see the RFC (buildpacks/rfcs#46) that you might be referencing but it's more about creator with some example cases on how pack would use it. I can't see how the implementation in how/why we use creator vs phases in pack is something that is CNB project wide. Could you elaborate a little more and maybe provide some reference?

[dfreilich]

Ah never mind, with the spec, I was thinking about the project descriptor (#165 ).

[dfreilich]

But I do think it is important, particularly given the presence of trusted builders in our commands and logs, to have some good and clear documentation around it

[dfreilich]

The split between pack/buildpacks/lifecycle in the docs is an interesting/difficult one, because in practice most of the docs site is for pack (for instance, all of the guides are leading through pack commands).