RFC: crane amend

[jonjohnsonjr]

See also:

• Improve append command - ease the process to push manifests to remote registries from a set of images #891
• How do we set the manifest platform."os.version" property? #1137
• crane: how to copy a sub-set of a image platforms? #1143

There is a pretty obvious need for a command to create/manipulate manifest lists, analogous to crane append. Originally I was hoping to extend crane append to do this, but I think having separate commands for images vs indexes could simplify the UX quite a bit. Also, I just really like the name crane amend.

I would love input from the community around use cases and ideas around the API surface. It's possible that we might need more than one command to cover everything, but the use cases I have in mind seem very related.

Use cases

1. Constructing a new manifest list

This would mirror crane append with no base. I am unsure exactly how to express something like overriding the platform of an image. We discussed this quite a bit in #891 so that might be a reasonable path forward.

2. Appending to an existing manifest list

This seems like i could just be a variant of the first use case where you supply an existing index ​to amend.

3. Merging existing manifest lists

This feels different enough that it might make sense as a separate command or possibly the composition of two commands?

@imjasonh has implemented this as https://github.com/imjasonh/combine

4. Reducing an existing manifest list to a subset of platforms

Not sure exactly how we would want to express this -- a flag of which platforms/positions to keep or which platforms/positions to remove? For most folks, it's probably most natural to say "I want only these platforms' because it's more declarative and context-independent, but I'm not sure if we want something more expressive/general than this.

Open Questions

1. Should it be possible to create an index that references arbitrary mediaTypes, e.g. a layer

[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.

[thesayyn]

I believe many of these ideas eventually boil down to merging layouts on disk and avoiding tricks like argument positions.
I get the feeling that the maintainers don't want to introduce yet another and are obliged to maintain that forever.

Thinking out loud.

4. i'd see this as being supported in pull either with

newly introduced options for platform selection

• --platform-only to get exact set of platforms
• a softer version would be a combination of --platform-exclude and --platform-include. possibly fetching images that not listed via these two.

but then you left wondering how about other properties such as annotations os.features os.version (recently added). this feature won't be complete ever

a brand new option --select

this option can express everything from platforms to features with power of CEL
the user provided expression gets evaluated against every manifest in the reference.
it would look like below

# get only linux/amd64 or linux/arm64
crane pull --format oci --select "platform.os == 'linux' && platform.architecture.endsWith('64')" 

# get only windows images with a specific feature
crane pull --format oci --select "platform.os == 'windows' && platform.features.exists_one(f, f == 'win32k.sys')" 

# get only linux image with variant and arch
crane pull --format oci --select "platform.variant == 'v6' && platform.architecture == 'arm'" 

2. Appending to an existing manifest list

Expressing with options is also painful as a layout could have either a manifest or manifest list or an even worse combination of them.
so this boils down to two options --refname to pick a manifest from the index.json by looking into annotations and --platform to pick an image if the descriptor --refname points to is an index.
then you encounter the same issue how about selecting by os.features or annotations?

I'd like to propose that we introduce the --select option here to pick images.

[thesayyn]

just created a PoC implementing --select https://github.com/thesayyn/ocil it works like a charm.