Output the descriptor of pushed artifact by `oras push`

[shizhMSFT]

The oras push command should have an option like --export-manifest-descriptor to write the descriptor of pushed artifact to a file so that the descriptor can be used for other processes like signing.

[shizhMSFT]

This can also be done by --export-manifest but more simplified.

@FeynmanZhou @yizha1 Any comments?

[sajayantony]

Could we consider aligning this with commands like manifest fetch ? Could you also describe what is the advantage of outputting these to a file instead of stdout and maybe just applying jq on top.

For e.g. docker manifest inspect has a --verbose option that outputs a different format with more fields -

$ docker manifest inspect --verbose docker.io/library/nginx@sha256:...
{
        "Ref": "docker.io/library/nginx@sha256:....",
        "Descriptor": {
                "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
                "digest": "sha256:5c134d3a19dc5fb01f4e7df9c36e3c054153e661b4bd3472858940894569d829",
                "size": 1570,
                "platform": {
                        "architecture": "mips64le",
                        "os": "linux"
                }
        },

this would just enable scripts to easily compose

docker manifest inspect --verbose {ref} | jq '.Descriptor' 

[shizhMSFT]

That's a different thing. The idea was to export the manifest or the manifest descriptor without fetching anything from the remote registry, which may not be trusted.

[shizhMSFT]

This also can be resolved by resolving #378 and then oras manfiest fetch --descriptor. However, doing --export-manifest or --export-manifest-descriptor is more efficient.

[shizhMSFT]

I was expecting to have something similar to --metadata-file.

[shizhMSFT]

By running the following commands, we will get a metadata.json file.

docker buildx create --use
docker buildx build --load --metadata-file metadata.json https://github.com/oras-project/oras.git#main

The content of metadata.json is

{
  "containerimage.buildinfo": {
    "frontend": "dockerfile.v0",
    "attrs": {
      "context": "https://github.com/oras-project/oras.git#main",
      "filename": "Dockerfile"
    },
    "sources": [
      {
        "type": "docker-image",
        "ref": "docker.io/library/alpine:3.15.4",
        "pin": "sha256:4edbd2beb5f78b1014028f4fbb99f3237d9561100b6881aabbf5acce2c4f9454"
      },
      {
        "type": "docker-image",
        "ref": "docker.io/library/golang:1.19.0-alpine",
        "pin": "sha256:0eb08c89ab1b0c638a9fe2780f7ae3ab18f6ecda2c76b908e09eb8073912045d"
      },
      {
        "type": "git",
        "ref": "https://github.com/oras-project/oras.git#main",
        "pin": "ee74ae205421c1183e7fb3fb90842a9cbf1ed625"
      }
    ]
  },
  "containerimage.config.digest": "sha256:e38d4a0954edda42d8d0a78c7e683385939384e8a2295103f79228b9a13704aa",
  "containerimage.descriptor": {
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "digest": "sha256:1fad23b0f5bc32605ccc952263c6ecfa6dbca0398347cda7c5b50beed7abeca8",
    "size": 1363,
    "annotations": {
      "org.opencontainers.image.created": "2022-08-16T08:41:47Z"
    }
  },
  "containerimage.digest": "sha256:1fad23b0f5bc32605ccc952263c6ecfa6dbca0398347cda7c5b50beed7abeca8"
}

[FeynmanZhou]

Hi @shizhMSFT @sajayantony ,

From my understanding, this feature is intended to export the descriptor of an artifact to a file instead of fetching something from a remote registry. ORAS has a flag of --export-manifest so using --export-manifest-descriptor looks more specific and intuitive to me.

Users can also use this feature to simplify the offline signing process for Notation since they can sign the descriptor from a local file instead of interacting with an OCI registry.

[shizhMSFT]

@jasminetMSFT Could you help follow up?

[jasminetMSFT]

@shizhMSFT No problem, I will look into this.

[shizhMSFT]

The user requirement needs to be verified by the local signing functionality of notation (Notary V2).

[shizhMSFT]

Closing this issue as the original requirement is achievable by the OCI-layout support. Precisely,

1. oras push --oci-layout to push artifacts to an OCI Layout folder.
2. oras manifest fetch --descriptor --oci-layout to inspect the manifest.
3. Make changes to the content of the OCI Layout folder if needed.
4. oras copy --from-oci-layout to copy the artifacts to the remote.