RFC: crane mutate to modify image metadata

[imjasonh]

@squee1945 mentioned it might be useful to have a tool that can change the entrypoint in an image in a registry in one command. Remotely adding/removing envs and labels seems useful too, and would be done nearly exactly the same way.

Strawman usage

$ crane mutate gcr.io/my-project/my-image:my-tag \
    --entrypoint=foo \
    --env=FOO=bar \
    --env=BAR=baz \
    --env=BAZ= \ # unset
    --label=some.label.key=some.label.value \
    --label=another.key=another.value \
    --label=unset.this.key
<digest of newly modified image>

This would fetch the config for the image, update entrypoint/env/labels, and push a new manifest with the original image's layers and the modified config. No layers would be copied, and the new image would be pushed to the original image's repository.

From there, you can tag the resulting digest with crane cp <digest> <tag-you-want> (sidenote: maybe crane tag would be a useful alias?)

Alternatives considered

We could have separate commands that would each do one operation, e.g.:

$ crane mutate env gcr.io/my-project/my-image:my-tag FOO bar
<digest>
$ crane mutate env <prev-digest> BAR baz
<another-digest>
$ crane mutate env <prev-digest> BAR # unset
<yet-another-digest>

You get the idea. Since the output is the new digest, you could theoretically chain them:

$ crane mutate env $(crane mutate env original FOO bar) BAR baz

But that's gross, and also ends up sending multiple updates needlessly. So let's not do that.

[jonjohnsonjr]

I want it still.

[imjasonh]

How's this for a fairly minimal first stab:

crane mutate gcr.io/my/image
  [--label foo=bar] \
  [--annotate foo=bar] \
  [--entrypoint blah] \
  [--tag gcr.io/my/image:mutated]

• if --tag is omitted, it tags over the original image
• --label and --annotation must include a =, the key is strings.SplitN(lbl, "=", 2)[0], the value is the rest
• error if no modifications are requested

For --label and --entrypoint, if gcr.io/my/image is a manifest list, the mutation is applied for all images in the manifest list (don't support nested manifest lists for now).

wdyt?

[jonjohnsonjr]

For --label and --entrypoint, if gcr.io/my/image is a manifest list, the mutation is applied for all images in the manifest list (don't support nested manifest lists for now).

Agree for --label. I don't agree with doing this for --annotate, I think, because it precludes a way to annotate the manifest list. I'd rather punt on that for now, unless you have a use case in mind. If you do, I'd rather come up with a better solution.

don't support nested manifest lists for now

Ok with it for now, but leave a TODO. We should support this.

Let's land at least --entrypoint ASAP. @ahmetb ran into this recently.

[imjasonh]

Yeah, I want --entrypoint to go with crane append to get a poor facsimile of ko 😈

I want --label and --annotation for shipwright-io/build#731. Would it be okay for --annotation on a manifest list to annotate all images, and the containing manifest list? 🤔

[jonjohnsonjr]

Would it be okay for --annotation on a manifest list to annotate all images, and the containing manifest list?

This would surprise me as default behavior. How would you feel about a -r flag to induce this?

[imjasonh]

This would surprise me as default behavior. How would you feel about a -r flag to induce this?

I'd be okay with that.