doc: adds expectations with regards to pulling using OCI #5307
Conversation
this commit adds a new section to the adr on oci pulls where we lay down the expectations when it comes to pulling artifacts through oci. such expectations are written as an example workflow of what should be supported. Signed-off-by: Ricardo Maraschini <[email protected]>
add missing language specifiers to the markdown code section. Signed-off-by: Ricardo Maraschini <[email protected]>
ricardomaraschini
force-pushed
the
expected-oci-artifacts-workflow
branch
from
130970b to
48222f3
Compare
There was a problem hiding this comment.
Thanks, that's a good starting point. I was thinking about some sort of "specification" though. It's not clear how k0s will select the artifact to download, given only the OCI name and tag, nor how k0s will figure out the file name to use. If we specify these things explicitly, there's less room for ambiguity and "specification by implementation". It will also help when discussing certain design aspects:
For example, regarding artifact selection, I think it would make perfect sense to support platform filtering, so that you can distribute different artifacts for different platforms under the same name, just as you can with multi-arch images.
Regarding file name determination, ORAS chooses to set the org.opencontainers.image.title annotation to the file name specified on the command line. This is a pragmatic choice, but an implementation detail of ORAS, since this annotation is for the "human-readable title of the image", according to the OCI spec.
It wouldn't be too unreasonable to not use the file name from the OCI manifests, but just require it to be provided in the k0s config, depending on whether that file name is something that should be decided at "k0s config time" or at "artifact push time". This way, we could completely eliminate the annotation processing mentioned above. This extends to other file system properties as well, such as permissions, ownership, maybe even file times.
| #### Expected workflow | ||
|
|
||
| This feature supports pulling both the k0s binary and the k0s air-gap bundle. | ||
| Each repository tag should host only one artifact. To remotely host an artifact |
There was a problem hiding this comment.
What should happen if there are multiple artifacts?
| @@ -110,6 +110,39 @@ secretRef: | |||
| name: artifacts-token-based-auth | |||
| ``` | |||
|
|
|||
| #### Expected workflow | |||
|
|
|||
| This feature supports pulling both the k0s binary and the k0s air-gap bundle. | |||
There was a problem hiding this comment.
Downloading executables raises the question of how to manage the executable bit of the downloaded files.
|
|
||
| ```yaml | ||
| url: oci://registry.company.com/k0s/binary:v1.31.1 | ||
| sha256: <sha-for-the-binary> |
There was a problem hiding this comment.
Big question: Is this the digest of the image or the digest of the embedded binary?
When dealing with OCI artifacts, it would seem more natural to be the digest of the image (or image index) itself.
If it is the latter, this means that as long as the published artifact also uses SHA-256 as its digest algorithm (I have yet to see an image that doesn't), we would have an accurate way of figuring out which artifact to pick out of the image index. The downside would be that this would make multi-platform downloads with the same name impossible.
Description
this commit adds a new section to the adr on oci pulls where we lay down the expectations when it comes to pulling artifacts through oci.
such expectations are written as an example workflow of what should be supported.
Fixes #5143
Type of change