Support manifest/blob/repository/tag commands in ORAS

[qweeah]

Repository / Tags

• Command to list repositories in a remote registry #470
• Command to show tags in a repository #469
• Command to create a tag for a manifest in the remote registry #471

Manifest

• Command to push a manifest to a remote registry #472
• ORAS get-manifest command #301
• Command to delete a manifest from a remote registry #473

Blob

• Command to push a blob to a remote registry #476
• Command to fetch a blob from a remote registry #475
• Command to delete a blob from a remote registry #474

[junczhu]

I am highly interested in following tasks and want to start working on them. Please assign them to me.

• oras repository list: List repository
• oras repository show-tags: List tags of a repository

[sajayantony]

These are awesome additions to ORAS and will make interacting with an OCI registry so much easier.

[lizMSFT]

Below is the UX design for ORAS manifest commands and ORAS blob commands from our discussion @shizhMSFT @qweeah @yuehaoliang-microsoft @lizMSFT

# Push
oras manifest push <name> - # read from stdin, return error if --password-stdin flag is used at the same time
oras manifest push <name> <path> # stdout human readable messages 
oras manifest push <name> <path> --media-type <mediaType>
oras manifest push <name> <path> --descriptor # stdout json descriptor

oras blob push <name> - # read from stdin, return error if --password-stdin flag is used at the same time
oras blob push <name> <path> # stdout human readable messages 
oras blob push <name> <path> --descriptor # stdout json descriptor


# Delete
oras manifest delete <name>
# warn users that other tags might also get deleted
# need add delete confirmation --yes or -y, ref: https://docs.microsoft.com/en-us/cli/azure/acr/manifest?view=azure-cli-latest#az-acr-manifest-delete
oras manifest delete <name> --yes --descriptor # stdout json descriptor

oras blob delete <name@digest>
# need add delete confirmation --yes or -y, ref: https://docs.microsoft.com/en-us/cli/azure/acr/manifest?view=azure-cli-latest#az-acr-manifest-delete
oras blob delete <name@digest> --yes --descriptor # stdout json descriptor 


# Fetch
# need pretty flag
oras manifest fetch <name> # default: stdout manifest content (output to stdout)
oras manifest fetch <name> --output <path>
# special case: oras manifest fetch <name> --output -
# fetch manifest to stdout
# --output - cannot be used with --descriptor at the same time
oras manifest fetch <name> --descriptor
oras manifest fetch <name> --output <path> --descriptor # stdout descriptor, save manifest content into file path

oras blob fetch <name@digest> # return error, either output or descriptor need to be provided, or provide both
oras blob fetch <name@digest> --output <path> # stdout progess status, save blob content into file path. should support pv to view progress of commands
# special case: oras blob fetch <name> --output -
# fetch blob to stdout, stdout NOT display progess status
# --output - cannot be used with --descriptor at the same time
oras blob fetch <name@digest> --descriptor # stdout descriptor (need pretty)
oras blob fetch <name@digest> --output <path> --descriptor # stdout descriptor, save blob content into file path

please let us know if you have any suggestions, thanks
cc @sajayantony @FeynmanZhou @yizha1

[qweeah]

For manifest fetch, what is the scope of --pretty? Should below commands store prettified manifest to file?

oras manifest fetch <name> --output <path> --pretty
oras manifest fetch <name> --output <path> --pretty --descriptor # the descriptor will be prettified

Storing prettified manifest to file makes more sense to me, e.g. below commands should saves indentical file content to <path>

oras manifest fetch <name> --pretty > <path> 
oras manifest fetch <name> --output <path> --pretty 
oras manifest fetch <name> --output - --pretty > <path> # shouldn't but could
oras manifest fetch <name> --output <path> --pretty --descriptor

@shizhMSFT @FeynmanZhou @yizha1 Can you help confirm. /cc @yuehaoliang-microsoft @lizMSFT

[yizha1]

If user can redirect the pretty output to a file using >, then we don't need a --output flag, right?

[qweeah]

If user can redirect the pretty output to a file using >, then we don't need a --output flag, right?

Yes, but the --output is designed for the scenario that 1) a user wants to save fetched manifest to a file somwhere and 2) gets the descriptor in stdout.

[shizhMSFT]

For manifest fetch, what is the scope of --pretty? Should below commands store prettified manifest to file?

oras manifest fetch <name> --output <path> --pretty
oras manifest fetch <name> --output <path> --pretty --descriptor # the descriptor will be prettified

Storing prettified manifest to file makes more sense to me, e.g. below commands should saves indentical file content to <path>

oras manifest fetch <name> --pretty > <path> 
oras manifest fetch <name> --output <path> --pretty 
oras manifest fetch <name> --output - --pretty > <path> # shouldn't but could
oras manifest fetch <name> --output <path> --pretty --descriptor

@shizhMSFT @FeynmanZhou @yizha1 Can you help confirm. /cc @yuehaoliang-microsoft @lizMSFT

Good point. I'd suggest that --pretty only applies to data output to stdout.

In other words,

oras manifest fetch <name> --pretty > <path>                     # manifest prettified
oras manifest fetch <name> --output <path> --pretty              # nothing prettified
oras manifest fetch <name> --output - --pretty > <path>          # manifest prettified
oras manifest fetch <name> --output <path> --pretty --descriptor # descriptor prettified

or we drop the --pretty option for all commands.

[FeynmanZhou]

The top-level ORAS manifest and ORAS blob commands look good. But the description copywriting of some commands needs to be polished and more straightforward. For example, @nima expressed his confusion about the meaning of the flag --descriptor.

We can use this doc to summarize the final CLI UX for all commands in v0.15.0.

[FeynmanZhou]

or we drop the --pretty option for all commands.

If we want to show prettified manifest for every oras manifest fetch command, why not set it as default and drop this flag?

[qweeah]

why not set it as default and drop this flag?

@FeynmanZhou prettifying a manifest will change the content(by adding space and newlines), thus changing the digest of the fetched manifest, so returning raw content is a must and should be set to default.

[shizhMSFT]

Closing as all sub tasks are finished.