Add a describe command to get descriptors of things

[sajayantony]

Currently a client must fetch the manifest and compute the hash to actually show the descriptor. These would be just HEAD requests.
I would like to purpose a describe command that resolves the entity and outputs the descriptor of the given entity.
This may be a manifest or a tag.

For e.g.

$ oras manifest describe localhost:5000/hello-world:latest
Digest: sha256:38fa349577729651ac1fc3ec785f908719a8100da5f5ba9bd3f549411061f583
MediaType: application/vnd.docker.distribution.manifest.v2+json
Size: 524
Ref: localhost:5000/hello-world:latest

This can also be applied to the blobs also to check for existance without actually fetching the blob as well.

[northtyphoon]

how about oras manifest inspect ...?

[sajayantony]

The reason I didn’t suggest inspect is because docker has manifest inspect that shows the manifest and also a verbose option that changes the output including the descriptor. It does GET on the manifest and ORAS has fetch already.

I was hoping that describe only shows the descriptor for manifest and blobs. Basically a check if exists HEAD without pulling content.

[shizhMSFT]

@sajayantony It is already supported using --descriptor. Try

$ oras manifest fetch --descriptor ghcr.io/oras-project/oras:v0.15.1 --pretty
{
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "digest": "sha256:c963603f576c9a21270ac60e5f180806f92e1de011e301fdbcf9141ae3be6662",
  "size": 1079
}

[shizhMSFT]

It only sends a HEAD request.

$ oras manifest fetch --descriptor ghcr.io/oras-project/oras:v0.15.1 --pretty --debug
DEBU[0000]  Request URL: "https://ghcr.io/v2/oras-project/oras/manifests/v0.15.1"
DEBU[0000]  Request method: "HEAD"
DEBU[0000]  Request headers:
DEBU[0000]    "Accept": "application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.cncf.oras.artifact.manifest.v1+json"
DEBU[0000]    "User-Agent": "oras/0.14.0+unreleased"
DEBU[0000]  Response Status: "401 Unauthorized"
DEBU[0000]  Response headers:
DEBU[0000]    "Content-Type": "application/json"
DEBU[0000]    "Www-Authenticate": "Bearer realm=\"https://ghcr.io/token\",service=\"ghcr.io\",scope=\"repository:oras-project/oras:pull\""
DEBU[0000]    "Date": "Thu, 20 Oct 2022 15:24:13 GMT"
DEBU[0000]    "Content-Length": "73"
DEBU[0000]    "X-Github-Request-Id": "5887:609B:207CE:409F5:6351681C"
DEBU[0000]  Request URL: "https://ghcr.io/token?scope=repository%3Aoras-project%2Foras%3Apull&service=ghcr.io"
DEBU[0000]  Request method: "GET"
DEBU[0000]  Request headers:
DEBU[0000]    "User-Agent": "oras/0.14.0+unreleased"
DEBU[0001]  Response Status: "200 OK"
DEBU[0001]  Response headers:
DEBU[0001]    "Content-Type": "application/json"
DEBU[0001]    "Docker-Distribution-Api-Version": "registry/2.0"
DEBU[0001]    "Date": "Thu, 20 Oct 2022 15:24:13 GMT"
DEBU[0001]    "Content-Length": "69"
DEBU[0001]    "X-Github-Request-Id": "5887:609B:207D0:409F6:6351681C"
DEBU[0001]  Request URL: "https://ghcr.io/v2/oras-project/oras/manifests/v0.15.1"
DEBU[0001]  Request method: "HEAD"
DEBU[0001]  Request headers:
DEBU[0001]    "Accept": "application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.cncf.oras.artifact.manifest.v1+json"
DEBU[0001]    "Authorization": "*****"
DEBU[0001]    "User-Agent": "oras/0.14.0+unreleased"
DEBU[0001]  Response Status: "200 OK"
DEBU[0001]  Response headers:
DEBU[0001]    "Docker-Distribution-Api-Version": "registry/2.0"
DEBU[0001]    "Etag": "\"sha256:c963603f576c9a21270ac60e5f180806f92e1de011e301fdbcf9141ae3be6662\""
DEBU[0001]    "Date": "Thu, 20 Oct 2022 15:24:13 GMT"
DEBU[0001]    "X-Github-Request-Id": "5887:609B:207D1:409F8:6351681D"
DEBU[0001]    "Content-Length": "1079"
DEBU[0001]    "Content-Type": "application/vnd.docker.distribution.manifest.list.v2+json"
DEBU[0001]    "Docker-Content-Digest": "sha256:c963603f576c9a21270ac60e5f180806f92e1de011e301fdbcf9141ae3be6662"
{
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "digest": "sha256:c963603f576c9a21270ac60e5f180806f92e1de011e301fdbcf9141ae3be6662",
  "size": 1079
}

[sajayantony]

Hm. Didn’t know. Btw Why do we need pretty option? Also is it supported in the blob commands as well?

[shizhMSFT]

--pretty is to format the JSON with indentation.

[shizhMSFT]

Yes, oras blob fetch also supports the --descriptor option.

[sajayantony]

I would expect the output to be text by default and have -o json for
the json output. Also was asking about pretty option since, this is constructed by the CLI it might be worth considering the pretty option by default. Again this is a discussion so I guess I’m asking so that I can understand the thinking behind this.

[shizhMSFT]

Let's start with the command oras manifest fetch. It fetches the manifest as it is. The resulted manifest might be compact or formatted. However, we cannot format it by default since it will change the digest of the manifest. Moreover, most developers use jq to format the manifest (e.g. oras manifest fetch ghcr.io/oras-project/oras:v0.15.1 | jq) to get colored output, which is more human friendly. On the other hand, raw output by default is script-friendly and it is also easier for humans to identify the abnormality (e.g. manifest is not a valid JSON or even it is an XML). Similarly, crane manifest also prints the raw output. Considering that not all environments have jq installed (e.g. on Windows / Mac, or in containers), it is better for oras to have an option to format the JSON output, which is --pretty.

Based on this logic, oras manifest fetch --descriptor fetches the manifest descriptor and outputs in the raw compact form according to the image-spec. The raw output is script-friendly and can be used to create compact index manifest or for other purposes (e.g. pass to notation for offline signing / verification).

If needed, users can pipe the output to jq.

Again, if jq is not installed, --pretty option can be added for minimal user experience.