From 3328d1753cd917a66fe1617ce4e700d5ddbedbaf Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Wed, 22 Jan 2025 09:13:37 -0700 Subject: [PATCH 01/15] docs: backup and restore specification Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 107 +++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/proposals/backup-restore.md diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md new file mode 100644 index 000000000..e5347eeac --- /dev/null +++ b/docs/proposals/backup-restore.md @@ -0,0 +1,107 @@ +# Backup and Restore Commands + +This document describes how the backup and restore commands will work and how the feature will be rolled out. +The proposal is to create the feature as a minimum viable product and follow that up with non breaking features to the commands. +The initial implementation will be the easiest implementation that is useful. + +## Minium Viable Product + +The backup command will initially just support writing to a directory and the restore command will only support reading from a directory. + +### oras backup + +The backup command will initially only support reading a list of files from the command line and writing to a directory: + +```bash +oras backup --output ./mirror registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 +``` + +The generated directory structure is `/`. +The command above puts the OCI layout for the Kubernetes API server in `mirror/kube-api-server-arm64`. +The directory structure with intermediate blobs removed: + +```bash +$ find mirror +mirror +mirror/kube-apiserver-arm64 +mirror/kube-apiserver-arm64 +mirror/kube-apiserver-arm64/ingest +mirror/kube-apiserver-arm64/oci-layout +mirror/kube-apiserver-arm64/blobs +mirror/kube-apiserver-arm64/blobs/sha256 +mirror/kube-apiserver-arm64/blobs/sha256/3f4e2c5863480125882d92060440a5250766bce764fee10acdbac18c872e4dc7 +... +mirror/kube-apiserver-arm64/blobs/sha256/4f80fb2b9442dbecd41e68b598533dcaaf58f9d45cce2e03a715499aa9f6b676 +mirror/kube-apiserver-arm64/index.json +mirror/kube-controller-manager-arm64 +mirror/kube-controller-manager-arm64 +mirror/kube-controller-manager-arm64/ingest +mirror/kube-controller-manager-arm64/oci-layout +mirror/kube-controller-manager-arm64/blobs +mirror/kube-controller-manager-arm64/blobs/sha256 +mirror/kube-controller-manager-arm64/blobs/sha256/3f4e2c5863480125882d92060440a5250766bce764fee10acdbac18c872e4dc7 +... +mirror/kube-controller-manager-arm64/blobs/sha256/4f80fb2b9442dbecd41e68b598533dcaaf58f9d45cce2e03a715499aa9f6b676 +mirror/kube-controller-manager-arm64/index.json +$ +``` + +The directory `mirror` must exist for the initial feature. +Each image will be stored in a subdirectory which matches the repository name. + +### oras restore + +Initially, the restore command will only support reading a directory and writing to a registry: + +```bash +oras restore --input ./mirror localhost:15000/my-mirror +``` + +The above backup example would result in: +```bash +localhost:15000/my-mirror/kube-apiserver-arm64:v1.31.0 +localhost:15000/my-mirror/kube-controller-manager-arm64:v1.31.0 +``` + +A namespace in the registry will be optional. +The registry in the above example could be specified as `localhost:15000`. + + +Any directory in the input that does not contain an `index.json` shall be silently ignored. + +## Compressed Tar File Support + +After the command supports directory write and read, support will be added for write and read to a compressed tar file. +The directory structure in the tar file would be the same as in the directory output. + +```bash +oras backup --output ./mirror.tgz registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 +``` + +There will be no validation on file name. +The file name does not need to end in `tgz`, but the format will be compressed tar file. +If the file exists, it will be overwritten. + +```bash +oras restore --input ./mirror.tgz localhost:15000/my-mirror +``` +If the specified source is a file, the format is assumed to be a compressed tar file. + +## Backup file input from a file + +The backup command will support an `--input filename` argument which will be a file. +The format of the contents of the file is a list of images names separated by newlines. +If the `--input` argument is specified, no images may be specified on the command line. + +## Backup file input from standard input + +The backup command will support the `--input -` argument to read a list of images from standard input. +The format of the input is a list of images names separated by newlines. + +## Restore file input from standard input + +The restore command will support the `--input -` argument to read a compressed tar input from standard input. + +## Optimize blobs + +Add the feature to create blobs that are duplicated between images as hard links in the directory output and compressed tar files. From 65b908aac313dde597ce3bdf5c3285eb1ff4ab88 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Thu, 6 Feb 2025 10:37:01 -0700 Subject: [PATCH 02/15] Update docs/proposals/backup-restore.md Co-authored-by: Andrew Block Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index e5347eeac..5d7f0031e 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -4,7 +4,7 @@ This document describes how the backup and restore commands will work and how th The proposal is to create the feature as a minimum viable product and follow that up with non breaking features to the commands. The initial implementation will be the easiest implementation that is useful. -## Minium Viable Product +## Minimum Viable Product The backup command will initially just support writing to a directory and the restore command will only support reading from a directory. From c1b9bfa8f351920897e2c469a838cb8b6286a20d Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Thu, 6 Feb 2025 10:38:33 -0700 Subject: [PATCH 03/15] Update docs/proposals/backup-restore.md Co-authored-by: Andrew Block Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 5d7f0031e..9ee7f6985 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -104,4 +104,4 @@ The restore command will support the `--input -` argument to read a compressed t ## Optimize blobs -Add the feature to create blobs that are duplicated between images as hard links in the directory output and compressed tar files. +A further enhancement is to create blobs that are duplicated between images as hard links in the directory output and compressed tar files. From f362a6981b1d0fbd145d6bdb91f4bf44edf0d721 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Thu, 6 Feb 2025 12:43:42 -0700 Subject: [PATCH 04/15] Update docs/proposals/backup-restore.md Co-authored-by: Andrew Block Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 9ee7f6985..9e6cf0ed2 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -51,7 +51,7 @@ Each image will be stored in a subdirectory which matches the repository name. ### oras restore -Initially, the restore command will only support reading a directory and writing to a registry: +Initially, the restore command will support reading a directory and writing the content to a remote registry: ```bash oras restore --input ./mirror localhost:15000/my-mirror From dbd4049880c27aee0b43f16eccfe92a4a1a7bfd5 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Thu, 6 Feb 2025 12:50:44 -0700 Subject: [PATCH 05/15] Update docs/proposals/backup-restore.md Co-authored-by: Andrew Block Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 9e6cf0ed2..03433c19b 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -89,7 +89,7 @@ If the specified source is a file, the format is assumed to be a compressed tar ## Backup file input from a file -The backup command will support an `--input filename` argument which will be a file. +The backup command will support an `--input filename` argument which will be a file containing the remove resources to retrieve. The format of the contents of the file is a list of images names separated by newlines. If the `--input` argument is specified, no images may be specified on the command line. From 230e5500b80b37f358b5471a9e2828470b2a5ed1 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Thu, 6 Feb 2025 12:55:03 -0700 Subject: [PATCH 06/15] address document comments Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 03433c19b..63ce1f704 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -1,16 +1,20 @@ # Backup and Restore Commands +The backup and restore commands will add the capability to backup a list of artifacts from a registry and restore them to another registry. +The artifacts that ill be supported are any OCI compatible artifact such as container images, helm charts and other artifacts. +This feature will have many use cases, but the use case that will benefit the most is air gapped registries. +These commands will allow copying artifacts to and from air gapped registries over the sneakernet or other limited communication channel. This document describes how the backup and restore commands will work and how the feature will be rolled out. The proposal is to create the feature as a minimum viable product and follow that up with non breaking features to the commands. -The initial implementation will be the easiest implementation that is useful. ## Minimum Viable Product The backup command will initially just support writing to a directory and the restore command will only support reading from a directory. +As well as the flags described here, the commands will support the normal set of flags to support TLS and authentication. ### oras backup -The backup command will initially only support reading a list of files from the command line and writing to a directory: +The backup command will initially only support reading a list of atifacts from the command line and writing to a directory: ```bash oras backup --output ./mirror registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 @@ -89,7 +93,7 @@ If the specified source is a file, the format is assumed to be a compressed tar ## Backup file input from a file -The backup command will support an `--input filename` argument which will be a file containing the remove resources to retrieve. +The backup command will support an `--input filename` argument which will be a file containing the remote resources to retrieve. The format of the contents of the file is a list of images names separated by newlines. If the `--input` argument is specified, no images may be specified on the command line. From 0b4d525c43b5564c759850ee818ef08800f7d27d Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Wed, 2 Apr 2025 07:51:55 -0600 Subject: [PATCH 07/15] docs: update document for template Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 121 +++++++++++++++++++++---------- 1 file changed, 82 insertions(+), 39 deletions(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 63ce1f704..771fd991c 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -1,20 +1,56 @@ -# Backup and Restore Commands +# ORAS Backup and Restore Commands + The backup and restore commands will add the capability to backup a list of artifacts from a registry and restore them to another registry. -The artifacts that ill be supported are any OCI compatible artifact such as container images, helm charts and other artifacts. -This feature will have many use cases, but the use case that will benefit the most is air gapped registries. -These commands will allow copying artifacts to and from air gapped registries over the sneakernet or other limited communication channel. +Backup and restore will be support for any OCI compatible artifact (e.g. container images, helm charts, configuration files,...). + + +## Overview + +This document outlines the different ways that the ORAS backup and restore commands can be used. + + +## Problem Statement & Motivation + +Currently, ORAS commands function on one artifact at a time, so copying a large numbers of artifacts will require scripting. +There is also no ability to copy multiple artifacts to a compressed tar file. + +* https://github.com/oras-project/oras/issues/1366 +* https://github.com/oras-project/oras/issues/730 + + +## Scenarios + +This feature will be useful for mirroring, air gapped registries, and disaster recovery. + +Users often need to mirror registries for performance and reliability reasons. +Pulling images over the Internet can be significantly slower than pulling images from a local registry. +If network connections are unreliable, a local registry will potentially be a lot more reliable. + +Air gapped environments normally require users to copy many artifiacts to a portable storage medium and sneaker net that storage into the environment. +The backup and restore commands will make writing that portable storage medium easy. + +The backup and restore commands will also help users wanting to copy artifiacts from a registry for disaster recovery. +It may be significantly easier to restore a registy from a backup rather than recreate the artifacts. + + +## Existing Solutions or Expectations + +This functionality is similar, but more flexible than `docker save` and `docker load`. +The Docker commands only allow the use of a tar file. -This document describes how the backup and restore commands will work and how the feature will be rolled out. -The proposal is to create the feature as a minimum viable product and follow that up with non breaking features to the commands. -## Minimum Viable Product +## Proposal -The backup command will initially just support writing to a directory and the restore command will only support reading from a directory. +The backup and restore commands will support reading and writing multiple files to and from a registry. As well as the flags described here, the commands will support the normal set of flags to support TLS and authentication. + ### oras backup -The backup command will initially only support reading a list of atifacts from the command line and writing to a directory: +The backup command will read a list of atifacts from the command line or from standard input. +It will support writing to a directory or compressed tar file. + +For example, backing up artifacts specified on the command line to a directory: ```bash oras backup --output ./mirror registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 @@ -50,12 +86,41 @@ mirror/kube-controller-manager-arm64/index.json $ ``` -The directory `mirror` must exist for the initial feature. Each image will be stored in a subdirectory which matches the repository name. +The backup command will also have the ability to write output to a compressed tar file. For example: + +```bash +oras backup --output ./mirror.tgz registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 +``` + +There will be no validation on file name. +The file name does not need to end in `tgz`, but the format will be compressed tar file. +If the file exists, it will be overwritten. + +#### Backup file input from a file + +The backup command will support an `--input filename` argument which will be a file containing the remote resources to retrieve. +The format of the contents of the file is a list of images names separated by newlines. +If the `--input` argument is specified, no images may be specified on the command line. + +#### Backup file input from standard input + +The backup command will support the `--input -` argument to read a list of images from standard input. +The format of the input is a list of images names separated by newlines. + +#### Optimize blobs + +A further enhancement is to create blobs that are duplicated between images as hard links in the directory output and compressed tar files. + + ### oras restore -Initially, the restore command will support reading a directory and writing the content to a remote registry: +The restore command will support reading a directory or a compressed tar file and writing the content to a remote registry. + +#### Restore from a directory + +An example of restoring from a directory: ```bash oras restore --input ./mirror localhost:15000/my-mirror @@ -70,42 +135,20 @@ localhost:15000/my-mirror/kube-controller-manager-arm64:v1.31.0 A namespace in the registry will be optional. The registry in the above example could be specified as `localhost:15000`. - Any directory in the input that does not contain an `index.json` shall be silently ignored. -## Compressed Tar File Support - -After the command supports directory write and read, support will be added for write and read to a compressed tar file. -The directory structure in the tar file would be the same as in the directory output. - -```bash -oras backup --output ./mirror.tgz registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 -``` +#### Restore from a compressed tar file -There will be no validation on file name. -The file name does not need to end in `tgz`, but the format will be compressed tar file. -If the file exists, it will be overwritten. +The directory structure in the tar file will be the same as in the directory output. +An example of reading from a compressed tar file: ```bash oras restore --input ./mirror.tgz localhost:15000/my-mirror ``` -If the specified source is a file, the format is assumed to be a compressed tar file. - -## Backup file input from a file - -The backup command will support an `--input filename` argument which will be a file containing the remote resources to retrieve. -The format of the contents of the file is a list of images names separated by newlines. -If the `--input` argument is specified, no images may be specified on the command line. - -## Backup file input from standard input -The backup command will support the `--input -` argument to read a list of images from standard input. -The format of the input is a list of images names separated by newlines. +If the specified source is a file, the format is assumed to be a compressed tar file. +There will be no validation of file name format. -## Restore file input from standard input +#### Restore file input from standard input The restore command will support the `--input -` argument to read a compressed tar input from standard input. - -## Optimize blobs - -A further enhancement is to create blobs that are duplicated between images as hard links in the directory output and compressed tar files. From e1ba0c9d81bb22ea0141f5d15c134483aa99f628 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Thu, 12 Jun 2025 07:47:51 -0600 Subject: [PATCH 08/15] Clarify compressed tar file format and handling Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 771fd991c..082ab8fad 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -88,7 +88,8 @@ $ Each image will be stored in a subdirectory which matches the repository name. -The backup command will also have the ability to write output to a compressed tar file. For example: +The backup command will also have the ability to write output to a new compressed tar file where the contents are in oci-layout +format. For example: ```bash oras backup --output ./mirror.tgz registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 From ebba3623a493d13eb7b438a2d4d28417356c71da Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Sat, 28 Jun 2025 05:28:42 -0600 Subject: [PATCH 09/15] Update docs/proposals/backup-restore.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 082ab8fad..5017db7c5 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -11,7 +11,7 @@ This document outlines the different ways that the ORAS backup and restore comma ## Problem Statement & Motivation -Currently, ORAS commands function on one artifact at a time, so copying a large numbers of artifacts will require scripting. +Currently, ORAS commands function on one artifact at a time, so copying a large number of artifacts will require scripting. There is also no ability to copy multiple artifacts to a compressed tar file. * https://github.com/oras-project/oras/issues/1366 From 2823ac8f745005343794645851b6ed160ee067cd Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Sat, 28 Jun 2025 05:29:10 -0600 Subject: [PATCH 10/15] Update docs/proposals/backup-restore.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 5017db7c5..1117e3856 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -26,10 +26,10 @@ Users often need to mirror registries for performance and reliability reasons. Pulling images over the Internet can be significantly slower than pulling images from a local registry. If network connections are unreliable, a local registry will potentially be a lot more reliable. -Air gapped environments normally require users to copy many artifiacts to a portable storage medium and sneaker net that storage into the environment. +Air gapped environments normally require users to copy many artifacts to a portable storage medium and sneaker net that storage into the environment. The backup and restore commands will make writing that portable storage medium easy. -The backup and restore commands will also help users wanting to copy artifiacts from a registry for disaster recovery. +The backup and restore commands will also help users wanting to copy artifacts from a registry for disaster recovery. It may be significantly easier to restore a registy from a backup rather than recreate the artifacts. From 92a978fcdf6c54a4e2e0ba25285202ad2b3692f3 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Sat, 28 Jun 2025 05:29:25 -0600 Subject: [PATCH 11/15] Update docs/proposals/backup-restore.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 1117e3856..ea54bd897 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -30,7 +30,7 @@ Air gapped environments normally require users to copy many artifacts to a porta The backup and restore commands will make writing that portable storage medium easy. The backup and restore commands will also help users wanting to copy artifacts from a registry for disaster recovery. -It may be significantly easier to restore a registy from a backup rather than recreate the artifacts. +It may be significantly easier to restore a registry from a backup rather than recreate the artifacts. ## Existing Solutions or Expectations From f92b30c1f3a79b3e02e1a82766b4ae62994c795f Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Sat, 28 Jun 2025 05:33:49 -0600 Subject: [PATCH 12/15] Update docs/proposals/backup-restore.md Co-authored-by: Feynman Zhou Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index ea54bd897..0c55b1134 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -6,7 +6,7 @@ Backup and restore will be support for any OCI compatible artifact (e.g. contain ## Overview -This document outlines the different ways that the ORAS backup and restore commands can be used. +This document outlines various scenarios related to backing up and restoring OCI images from registries and local files. It covers a common workflow for downloading and uploading one or more image resources to and from disk, identifies limitations and challenges in existing solutions, and presents proposals for improvements to enhance usability and portability of managing OCI images. ## Problem Statement & Motivation From d1a1507542318931bf2bdbcc421bb1b7de699e33 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Sat, 28 Jun 2025 06:33:53 -0600 Subject: [PATCH 13/15] Update document based on feedback Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 0c55b1134..496433462 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -56,6 +56,10 @@ For example, backing up artifacts specified on the command line to a directory: oras backup --output ./mirror registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 ``` +It is mandatory to specify `--output` argument with the destination. +The source artifacts may be read from different registries although the example reads artifacts from one registry. +If no reference tag or digest is specified, the entire repository will be copied. + The generated directory structure is `/`. The command above puts the OCI layout for the Kubernetes API server in `mirror/kube-api-server-arm64`. The directory structure with intermediate blobs removed: @@ -99,17 +103,6 @@ There will be no validation on file name. The file name does not need to end in `tgz`, but the format will be compressed tar file. If the file exists, it will be overwritten. -#### Backup file input from a file - -The backup command will support an `--input filename` argument which will be a file containing the remote resources to retrieve. -The format of the contents of the file is a list of images names separated by newlines. -If the `--input` argument is specified, no images may be specified on the command line. - -#### Backup file input from standard input - -The backup command will support the `--input -` argument to read a list of images from standard input. -The format of the input is a list of images names separated by newlines. - #### Optimize blobs A further enhancement is to create blobs that are duplicated between images as hard links in the directory output and compressed tar files. From be370afbe3b719e7533d3fcab807d2582a70ddbf Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Sat, 28 Jun 2025 08:56:58 -0600 Subject: [PATCH 14/15] Address comments on restore Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 496433462..0003ba95b 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -99,9 +99,10 @@ format. For example: oras backup --output ./mirror.tgz registry.k8s.io/kube-apiserver-arm64:v1.31.0 registry.k8s.io/kube-controller-manager-arm64:v1.31.0 ``` -There will be no validation on file name. -The file name does not need to end in `tgz`, but the format will be compressed tar file. -If the file exists, it will be overwritten. +If the output specified is an existing directory, the output will be written in that directory in OCI layout format. +If the output specified is an existing file, it will be overwritten. +If the output specified is neither a file or a directory, file output is assumed. +The file name does NOT need to end in `tgz`, but file output will be compressed tar file. #### Optimize blobs @@ -120,7 +121,9 @@ An example of restoring from a directory: oras restore --input ./mirror localhost:15000/my-mirror ``` -The above backup example would result in: +It is mandatory to specify `--input` argument with the source directory or file. + +The above restore example would result in: ```bash localhost:15000/my-mirror/kube-apiserver-arm64:v1.31.0 localhost:15000/my-mirror/kube-controller-manager-arm64:v1.31.0 From 7b472687fa4a81ec54899b15e9cfe0ad7e8dd7a8 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Sat, 28 Jun 2025 09:08:31 -0600 Subject: [PATCH 15/15] Address feedback around registry and repositories in restore Signed-off-by: Terry Howe --- docs/proposals/backup-restore.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/proposals/backup-restore.md b/docs/proposals/backup-restore.md index 0003ba95b..7f3efa71c 100644 --- a/docs/proposals/backup-restore.md +++ b/docs/proposals/backup-restore.md @@ -122,6 +122,9 @@ oras restore --input ./mirror localhost:15000/my-mirror ``` It is mandatory to specify `--input` argument with the source directory or file. +The destination registry that is being restored to may be different from the source registry. +An option will be provided to map repositories from the backup to different repositories on the destination registry. +For example, a backup of `foo.registry.example/test` can be restored to `bar.registry.example/another-test` where `test` is mapped to `another-test`. The above restore example would result in: ```bash