Support manifest commands in ORAS CLI

[sajayantony]

Currently the ORAS CLI does not support manifest commands.
Docker has an inspect command and so does crane. These cannot be used to view all types of manifests or ORAS manifest. I would be beneficial if the oras CLI could support retrieving manifest of types it is aware of or even types that can be specified on the CLI.

Here is a candidate specification for the ORAS CLI. This however has be translated into the underlying library so that frameworks like notary and ratify can use this capability to fetch the manifest.

Fetch a Manifest

Command returns a docker manifest, manifestlist , OCI manifest, index or ORAS Artifact which are the common types of manifest already available.

oras manifest  docker.io/library/ubuntu:20.04
{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {...}
    ]
}

Fetch by digest

• This MAY return a manifest that is a known type and support pretty formatting.
• The manifest may also be an unknown type and in that case should support returning raw type. For e.g. the manifest may be an XML document.

oras manifest myregistry.io/image@sha256:123

Fetch raw manifest

This enables digest computation

oras manifest  --raw docker.io/library/ubuntu:20.04

Fetch platform manifest

This enables the client to request a manifest for a given platform by os/arch/variant

oras manifest  --platform arm/linux/v7 docker.io/library/ubuntu:20.04

Fetch with headers

Output the raw headers to stderr so that debugging the request is easier. I think we can mask out the authorization to avoid exposing credentials and if there is an ask to show the auth header then include a like --expose-credentials. But would keep that out of scope for now.

oras manifest  --verbose docker.io/library/ubuntu:20.04
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Docker-Content-Digest, WWW-Authenticate, Link, X-Ms-Correlation-Request-Id
Connection: keep-alive
Content-Length: 1164
Content-Type: application/vnd.docker.distribution.manifest.v2+json
Date: Tue, 16 Nov 2021 05:35:57 GMT
Docker-Content-Digest: sha256:cb46ec7e025e48edd4bc47e3478f98d4ee758035cf7877160671935104f2452f
Docker-Distribution-Api-Version: registry/2.0
Etag: "sha256:cb46ec7e025e48edd4bc47e3478f98d4ee758035cf7877160671935104f2452f"
Server: openresty
Strict-Transport-Security: max-age=31536000; includeSubDomains, max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Ms-Client-Request-Id:
X-Ms-Correlation-Request-Id: 9a23700f-eab1-4b06-8d60-0ccdff2ffba5
X-Ms-Request-Id: cf771f1c-56ed-41b2-b6b9-48d78bfd8f8c

{
    "config": {
        "digest": "sha256:77e0a129aa5d1dffe246a647be72ad11c1de2d1df090fe3336c249912697f0e2",
        "mediaType": "application/vnd.docker.container

Usage

oras manifest 
     [--media-type {comma separated values}] 
     [--platform {os/arch/variant}] 
     [--raw|--pretty {default is pretty}]] 
     [--verbose]      
     REFERENCE

[shizhMSFT]

Here are my shower thoughts. /cc @qweeah @sajayantony @FeynmanZhou @yizha1

Overview

The proposed command is

Usage:
  oras fetch-manifest [flags] <name:tag|name@digest>

Flags:
  -d, --debug                    debug mode
  -h, --help                     help for fetch-manifest
      --insecure                 allow connections to SSL registry without certs
      --media-type string        accepted media types
  -p, --password string          registry password or identity token
      --password-stdin           read password or identity token from stdin
      --plain-http               allow insecure connections to registry without SSL check
      --platform string          set platform if target is multi-platform capable
  -r, --raw                      output raw manifest without formatting
  -u, --username string          registry username
  -v, --verbose                  verbose output

The fetch- prefix makes the command consistent with oras pull, oras push, oras <verb>...
Additionally, the fetch keyword is consistent with the APIs in oras-go.

Similarly, we can have oras fetch-blob later.

Scenarios

Fetch a manifest by tag:

oras fetch-manifest docker.io/library/hello-world:latest

Fetch a manifest by digest:

oras fetch-manifest docker.io/library/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4

Fetch a raw manifest:

oras fetch-manifest -r docker.io/library/hello-world:latest

Fetch a manifest by platform:

oras fetch-manifest --platform arm/linux/v7 docker.io/library/hello-world:latest

Fetch a manifest in debug, showing all headers with auth sanitized:

oras fetch-manifest -d docker.io/library/hello-world:latest

Fetch a manifest in verbose mode, showing the descriptor of the manifest:

oras fetch-manifest --platform amd64/linux -v docker.io/library/hello-world:latest

Output (basically the OCI descriptor in the main branch):

{
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "digest": "sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4",
    "size": 525,
    "data": "ewogICJzY2hlbWFWZXJzaW9uIjogMiwKICAibWVkaWFUeXBlIjogImFwcGxpY2F0aW9uL3ZuZC5kb2NrZXIuZGlzdHJpYnV0aW9uLm1hbmlmZXN0LnYyK2pzb24iLAogICJjb25maWciOiB7CiAgICAibWVkaWFUeXBlIjogImFwcGxpY2F0aW9uL3ZuZC5kb2NrZXIuY29udGFpbmVyLmltYWdlLnYxK2pzb24iLAogICAgInNpemUiOiAxNDY5LAogICAgImRpZ2VzdCI6ICJzaGEyNTY6ZmViNWQ5ZmVhNmE1ZTk2MDZhYTk5NWU4NzlkODYyYjgyNTk2NWJhNDhkZTA1NGNhYWI1ZWYzNTZkYzZiMzQxMiIKICB9LAogICJsYXllcnMiOiBbCiAgICB7CiAgICAgICJtZWRpYVR5cGUiOiAiYXBwbGljYXRpb24vdm5kLmRvY2tlci5pbWFnZS5yb290ZnMuZGlmZi50YXIuZ3ppcCIsCiAgICAgICJzaXplIjogMjQ3OSwKICAgICAgImRpZ2VzdCI6ICJzaGEyNTY6MmRiMjk3MTAxMjNlM2U1M2E3OTRmMjY5NDA5NGI5YjQzMzhhYTllZTVjNDBiOTMwY2I4MDYzYTFiZTM5MmM1NCIKICAgIH0KICBdCn0K"
}

Note: verbose mode can be combined with the raw mode. In that scenario, the output JSON has no indents.

[nima]

Curious why pretty-printing is even something that the client needs to deal with? Is it unreasonable to leave that to the user (to use jq for instance)?

[qweeah]

I think pretty-printing should be disabled by default, so other utilities like notation manifest can be chained with less flags provided.

Also we should add --indent(-n) to allow user changing the indent.

[FeynmanZhou]

I agree with Shiwei that we can combine verbose and raw into one mode for a simplified UX. As for the command naming, either noun verb or verb noun ordering works, but noun verb seems to be more common, see CLI Guide. So I prefer oras manifest fetch in this scenario.

[SteveLasker]

Adding manifest commands is great.
Curious why we're proposing fetch over pull
+1 on not changing the output by default, leaving the user to use jq or other tools. Not that we don't want to help, but this can alter the contents.