crane: mutate OCI image layout with annotations, layers etc.

[developer-guy]

Describe the bug

This is not a bug, and this is a feature.

Additional context

Recently, @sudo-bmitch talked about OCI image layout¹. He showed a demo of making file operations on the OCI image layout directory for adding new blobs, annotations, etc. crane already has the support of working with OCI image layout through a package pkg/v1/layout available in go-containerregistry but editing the OCI image layout for such operations adding new blobs, annotations, etc. is not possible, so, we talked with @imjasonh about this, and mutate cmd is the best place to implement this. Based on that, I've tested a sample code to make changes to OCI image layout, and it worked:

img2 := mutate.Annotations(img, annotations).(v1.Image)
err = p.ReplaceImage(img2, match.Digests(digest))
if err != nil {
	return fmt.Errorf("replacing image: %w", err)
}

PTAL @Dentrax

Footnotes

1. https://www.youtube.com/watch?v=TJVoFKTm9I0 ↩

[abitrolly]

Slides https://static.sched.com/hosted_files/ossna2022/9b/presentation.pdf

[developer-guy]

kindly ping @imjasonh @jonjohnsonjr

[imjasonh]

I think this is worth doing. What kind of changes would you like to see added to crane mutate? I can imagine an --oci-layout-path flag to write the mutated content to an OCI layout. Do you also see a need for an option to accept an OCI layout as an input image to mutate?

[developer-guy]

I can imagine an --oci-layout-path flag to write the mutated content to an OCI layout

This is exactly what I thought. We just need to add a flag for OCI Image Layout to tell crane this is an OCI Image Layout directory, not an image.

# this will append layer.tar.gz blob to oci-dir directory
$ crane mutate --append layer.tar.gz --oci-image-layout oci-dir

# current design
$ crane mutate --append layer.tar.gz ghcr.io/developer-guy/hello-world:latest

[developer-guy]

we can give a hand to address this issue with @Dentrax

[sudo-bmitch]

Anyone up for standardizing the reference syntax for a local Layout so that it's just a different way to reference an image rather than a flag?
opencontainers/tob#114

[abitrolly]

@sudo-bmitch I would try to simplify spec terminology. Local Layout forces me to go and find the page that describes what does it mean. Do you mean standardizing image references like:

• alpine
• alpine:latest
• docker.io/alpine/alpine:latest
• 04ec7965

and extending them to

• sha256:04ec7965
• podman://alpine:edge (used by dive https://github.com/wagoodman/dive#basic-features)
• ./savedimg.oci
• local+oci://./savedimg.oci

?

[sudo-bmitch]

Standardizing references to a layout refers to how we have lots of ways to reference the on disk format:
https://sudo-bmitch.github.io/presentations/oci-layout/presentation.html#28

Sometimes they mean a directory, sometimes a tar+gz of that directory, and rarely do they include the ability to specify a tag or digest within that directory.

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Keep fresh with the 'lifecycle/frozen' label.

[developer-guy]

Can you please re-open this issue @imjasonh? I'm going to add some test cases to prove it's working.

[thesayyn]

Friendly ping @imjasonh I am really interested in this for rules_oci. We have a pure overhead of running registries and making crane work on the said ephemeral registry. This doesn't scale well when there are hundreds of ephemeral registries working locally.

I'd be down for making series of PR's to make this work. @developer-guy i'd appreciate if you could lend me a hand