spin registry push container image metadata

[rgl]

At https://github.com/rgl/spin-http-ts-example/tree/test-release I'm building an example container image. When I build a container image with docker build, I can set container image metadata with:

...
LABEL org.opencontainers.image.source="$HELLO_SOURCE_URL"
LABEL org.opencontainers.image.revision="$HELLO_REVISION"
LABEL org.opencontainers.image.description="Example Spin HTTP Application written in TypeScript"
LABEL org.opencontainers.image.licenses="ISC"

And build/push it with:

docker build \
    --build-arg "HELLO_SOURCE_URL=$HELLO_SOURCE_URL" \
    --build-arg "HELLO_VERSION=$HELLO_VERSION" \
    --build-arg "HELLO_REVISION=$HELLO_REVISION" \
    -t "$IMAGE" \
    .
docker push "$IMAGE"

And the image endsup with the expected metadata, like in https://github.com/rgl/spin-http-ts-example/pkgs/container/spin-http-ts-example/169177958?tag=0.1.0-rc3.

But when using spin registry push no metadata is sent, like in https://github.com/rgl/spin-http-ts-example/pkgs/container/spin-http-ts-example/169178514?tag=0.1.0-rc5.

So, can we please have a way to set metadata?

[itowlson]

Let me see if I can elicit a scope / functional spec here, because I am not sure how closely this needs to follow Docker.

To literally follow Docker we would need:

• A persistent way to define metadata slots with fixed or parameterised values (the equivalent of the LABEL statements), e.g. in spin.toml
• A way to set the parameterised values at push time, e.g. arguments to spin registry push

But another approach would be:

• A way to define metadata at push time (no persistent slots), e.g. spin registry push --metadata org.opencontainers.image.license=mylicence

The latter would be considerably easier; admittedly the UI would be less convenient but maybe this is mostly done from CI where it doesn't matter?

cc @radu-matei @vdice

[vdice]

The first approach (new section in spin.toml, support for overriding at time of publish) brings a host of design/UX questions as this would be the first instance of capturing registry/publishing-related data in a Spin app's build document. I can imagine some other values that may be handy to store there (or near) like a default registry reference, etc... but all of this is to say that it probably warrants a wider discussion (and perhaps a SIP?)

I'd also be curious if the latter approach (publish-time metadata injection) might suffice for the needs here? Would the metadata be used in any other registry commands besides spin registry push (eg inspection somehow on spin registry pull?) Or would the metadata mostly just be informational?

[rgl]

For my particular case, the metadata is informational only, and a push time only way is enough. I do not have enough experience to comment about other use cases.

PS I'm also not sure how to name the argument. Whether it should be metadata, annotation, label, or something else. Maybe its name should be aligned with the oci image artifact specification?

[rgl]

FWIW, In the context of the OCI image spec, the correct name seems to the annotations instead of metadata. So probably, should be implemented as, e.g.:

spin registry push \
  --annotation org.opencontainers.image.description="Example Spin HTTP Application written in TypeScript" \
  --annotation org.opencontainers.image.licenses="ISC"

An example of the image can be seen at https://github.com/opencontainers/image-spec/blob/main/manifest.md#example-image-manifest, which boils down to:

{
  "annotations": {
    "com.example.key1": "value1",
    "com.example.key2": "value2"
  }
}

[rgl]

BTW, if you point me in the right direction, I would like to try to implement this :-)

[vdice]

@rgl the --annotation approach sounds good to me. Thanks for volunteering to take a look at implementing!

• The spin registry push command logic starts here: https://github.com/fermyon/spin/blob/main/src/commands/registry.rs#L30

• Check out the oci crate for all oci/registry-related logic. Specifically, here's where we currently build the OCI image manifest during push -- and right now are supplying None for the optional annotations HashMap: https://github.com/fermyon/spin/blob/main/crates/oci/src/client.rs#L190

Let us know if we can be of further help.

[rgl]

Thank You! Got it working at #2254! :-)

[radu-matei]

Shared a suggestion in #2259 for this.

Thank you for your work, @rgl!