feat: add documentation for working with OCI 1.0 and OCI 1.1 containe…#411
feat: add documentation for working with OCI 1.0 and OCI 1.1 containe…#411knrc wants to merge 1 commit intosigstore:mainfrom
Conversation
✅ Deploy Preview for docssigstore ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
@Hayden-IO any idea who should review this? |
| |--------------|--------------|------------|--------------|-------| | ||
| | Old (`--new-bundle-format=false`) | Tag-based (OCI 1.0) | Yes | Yes | Legacy mode | | ||
| | Old (`--new-bundle-format=false`) | Referrers (OCI 1.1) | Yes | No | Signatures only, attestations always use tags | | ||
| | New (`--new-bundle-format=true`) | Tag-based (OCI 1.0) | No | No | Not supported, the new format requires referrers | |
There was a problem hiding this comment.
Not supported, the new format requires referrers
I thought the new bundle format works on both OCI 1.0 and 1.1. If the referrer's API isn't available, it goes ahead and creates a tag with format sha256-<digest> (no .sig) for the bundle.
There was a problem hiding this comment.
I did try this out, but perhaps I had an issue with my test. I will double check today
There was a problem hiding this comment.
@cmurphy I went back through the code and it looks like there is no fallback, if it's using the new format then it ends up in signDigestBundle and all paths lead to WriteReferrer
There was a problem hiding this comment.
Thinking a bit more about what you said with creating the manifest. Even if this did create the manifest in OCI 1.0, which I'm doubting because the type is wrong, it would create the artifact based on the sha of the manifest being written (it's not a tag) and there would be no way to discover it without reading all manifests and parsing them to locate the ones with the right subject.
There was a problem hiding this comment.
Looks like I may be wrong on that, I ran up a quick test to verify and does appear to work. Just digging into it some more.
There was a problem hiding this comment.
I've got it, as you said there's a fallback but it's handled in go-containerregistry and is transparent to cosign. I'll update the docs.
There was a problem hiding this comment.
For anyone else following, here's the link to the code in go-containerregistry
There was a problem hiding this comment.
and here's the OCI spec discussing the fallback, again for interested parties
There was a problem hiding this comment.
@cmurphy I've updated the docs, can you please take another look at the changes and review?
…r registries Signed-off-by: Kevin Conner <kev.conner@gmail.com>
| --- | ||
| type: docs | ||
| category: Container Registries | ||
| title: OCI and Referrers |
There was a problem hiding this comment.
Thanks for double checking the tag fallback option and updating the doc.
Taking a step back, I'm wondering who the audience for this page is meant to be? This is pretty in-depth for a user-facing document. In an ideal world (which I admit is not where we are yet), a cosign user shouldn't really have to know what the referrer's API is, it should "just work" (hence the tag fallback - the user may not even know what OCI version their registry supports, and that's fine). The changes you made in the signing and verification docs cover the user-facing issues of the referrer's API really well already.
Where I think a dedicated page like this could be useful is if it went into more depth on using oras or crane to discover and fetch bundles and attestations in ways that cosign doesn't do (or that we want to discourage and deprecate), so that folks using other tooling to examine their attestations have a resource for building their automation around referrers vs tags.
If you don't want to make any other changes, at a minimum I would suggest that the examples for the new bundle format come first and the legacy format come later. I think we want to be encouraging people to always use the new format - but to come here for workarounds if they have older images or older tooling that only support the old format.
2 participants
…r registries
Summary
This PR adds documentation regarding the support for storing signatures and attestations using OCI 1.0 and OCI 1.1 container registries.
Release Note
Add documentation for storage of signatures and attestations using OCI 1.0 and OCI 1.1 container registries.
Documentation