Add new commands to support uploading and downloading images

[qweeah]

What is the version of your ORAS CLI

oras v1.1.0

What would you like to be added?

Had an offline discussion with @shizhMSFT and he suggests to add two commands:

• oras backup (alias: snapshot, pull-image) to support saving an image from remote registry to an OCI image layout tar archive.

Usage:
  oras backup --output <oci_layout_path> <reg>/<repo>[{:<tag>|@digest]}] [...]

• oras restore (alias: push-image) to support pushing an image from an OCI image layout tar archive to remote registry.

Usage:
  oras restore --output <reg>/<repo> <oci_layout_path>[{:<tag>|@digest]}]

Why is this needed for ORAS?

oras cp is not intuitive to use, e.g. user might use oras push to push images from an OCI layout and succeed with false positive (see #1353). Adding those two wrapper commands of oras cp can help avoid that.

Are you willing to submit PRs to contribute to this feature?

• Yes, I am willing to implement it.

[TerryHowe]

Why not backup and restore?

…

On Tue, Apr 23, 2024, 12:31 AM Billy Zha ***@***.***> wrote: What is the version of your ORAS CLI oras v1.2.0 What would you like to be added? Had an offline discussion with @shizhMSFT <https://github.com/shizhMSFT> and he suggests to add two commands: - oras snapshot (alias: dump, backup, pull-image) to support saving an image from remote registry to an OCI image layout. Usage: oras snapshot [flags] ***@***.***} <oci_layout_path>[:<tag>] - oras restore (alias: push-image) to support pushing an image from an OCI image layout to remote registry. Usage: oras restore [flags] ***@***.***} <reg>/<repo>[:<tag>] Why is this needed for ORAS? oras cp are not intuitive to uses, e.g. user might use oras push to push images from an OCI layout and succeed with false positive (see #1353 <#1353>). Adding those two wrapper commands of oras cp can help avoid that. Are you willing to submit PRs to contribute to this feature? - Yes, I am willing to implement it. — Reply to this email directly, view it on GitHub <#1366>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAZNMMXDTQXO6V6M5ZEACLY6X52ZAVCNFSM6AAAAABGUFNS5WVHI2DSMVQWIX3LMV43ASLTON2WKOZSGI2TQMBVG44TCMI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[shizhMSFT]

Why not backup and restore?

Nice input. I've revised the proposal accordingly to oras backup and marked snapshot as an alias.

[sajayantony]

Could you also include reasoning why pull doesn't work here.

oras pull --to-oci-layout <oci_layout_path> <reg>/<repo>[{:<tag>|@digest]}] [...]

[sajayantony]

As per the call I'm ok if we limit to tar archive only dealing.

[shizhMSFT]

As per the call, here is an alternative without introducing new commands.

• oras backup --> oras pull --archive <tar_path> <name>{:<tag>|@<digest>}
• oras restore --> oras push --archive <tar_path> <name>[:<tag>[,<tag>][...]] <file>[:<type>] [...]

The major difference between oras backup/restore and oras pull/push is that oras backup/restore can take multiple images across registries and repositories.

Example usages are

# working with remote registry
oras pull localhost:5000/hello:v1 --archive hello.tar # backup hello:v1 to hello.tar
oras push localhost:5000/hello:v1 --archive hello.tar # restore hello:v1 from hello.tar

# working with entire repository
oras pull localhost:5000/hello --archive hello.tar # backup all images in hello to hello.tar
oras push localhost:5000/hello --archive hello.tar # restore all images in hello.tar

# working with multiple images
oras pull localhost:5000/hello:v1,foo,bar --archive hello.tar # backup v1, foo, and bar
oras push localhost:5000/hello:v1,foo --archive hello.tar     # restore v1 and foo, and ignore bar

# working with referrers
oras pull --include-referrers localhost:5000/hello:v1 --archive hello.tar
oras push --include-referrers localhost:5000/hello:v1 --archive hello.tar

# working with OCI layout. UX would be better if using `oras cp`.
oras pull --oci-layout layout.tar:v1 --archive hello.tar
oras pull --oci-layout layout-dir:v1 --archive hello.tar
oras push --oci-layout layout-dir:v1 --archive hello.tar

[qweeah]

oras restore --> oras push --archive <tar_path> [:[,][...]] [:] [...]

I think the usage is change to oras push <name>[:<tag>[,<tag>][...]] {<file>[:<type>] [...]|--archive <tar_path>}.

[TerryHowe]

Currently, pull skips successors though, right?

[qweeah]

Currently, pull skips successors though, right?

Depends on the type. subject are skipped unless --include-subject is specified. manifests in an index will be pulled.