Add support for checkpoint image

This is an enhancement proposal for the checkpoint / restore feature of
Podman that enables container migration across multiple systems with
standard image distribution infrastructure.

A new option `--create-image <image>` has been added to the
`podman container checkpoint` command. This option tells Podman to
create a container image.  This is a standard image with a single layer,
tar archive, that that contains all checkpoint files. This is similar to
the current approach with checkpoint `--export`/`--import`.

This image can be pushed to a container registry and pulled on a
different system.  It can also be exported locally with `podman image
save` and inspected with `podman inspect`. Inspecting the image would
display additional information about the host and the versions of
Podman, criu, crun/runc, kernel, etc.

`podman container restore` has also been extended to support image
name or ID as input.

Suggested-by: Adrian Reber <areber@redhat.com>
Signed-off-by: Radostin Stoyanov <radostin@redhat.com>

2 files changed, 75 insertions, 4 deletions

diff --git a/docs/source/markdown/podman-container-checkpoint.1.md b/docs/source/markdown/podman-container-checkpoint.1.md
index 5c07cd975..a11897081 100644
--- a/docs/source/markdown/podman-container-checkpoint.1.md
+++ b/docs/source/markdown/podman-container-checkpoint.1.md
@@ -28,6 +28,60 @@ archives. Not compressing the checkpoint archive can result in faster checkpoint
 archive creation.\
 The default is **zstd**.
 
+#### **--create-image**=*image*
+
+Create a checkpoint image from a running container. This is a standard OCI image
+created in the local image store. It consists of a single layer that contains
+all of the checkpoint files. The content of this image layer is in the same format as a
+checkpoint created with **--export**. A checkpoint image can be pushed to a
+standard container registry and pulled on a different system to enable container
+migration. In addition, the image can be exported with **podman image save** and
+inspected with **podman inspect**. Inspecting a checkpoint image would display
+additional information, stored as annotations, about the host environment used
+to do the checkpoint:
+
+- **io.podman.annotations.checkpoint.name**: Human-readable name of the original
+  container.
+
+- **io.podman.annotations.checkpoint.rawImageName**: Unprocessed name of the
+  image used to create the original container (as specified by the user).
+
+- **io.podman.annotations.checkpoint.rootfsImageID**: ID of the image used to
+  create the original container.
+
+- **io.podman.annotations.checkpoint.rootfsImageName**: Image name used to
+  create the original container.
+
+- **io.podman.annotations.checkpoint.podman.version**: Version of Podman used to
+  create the checkpoint.
+
+- **io.podman.annotations.checkpoint.criu.version**: Version of CRIU used to
+  create the checkpoint.
+
+- **io.podman.annotations.checkpoint.runtime.name**: Container runtime (e.g.,
+  runc, crun) used to create the checkpoint.
+
+- **io.podman.annotations.checkpoint.runtime.version**: Version of the container
+  runtime used to create the checkpoint.
+
+- **io.podman.annotations.checkpoint.conmon.version**: Version of conmon used
+  with the original container.
+
+- **io.podman.annotations.checkpoint.host.arch**: CPU architecture of the host
+  on which the checkpoint was created.
+
+- **io.podman.annotations.checkpoint.host.kernel**: Version of Linux kernel
+  of the host where the checkpoint was created.
+
+- **io.podman.annotations.checkpoint.cgroups.version**: cgroup version used by
+  the host where the checkpoint was created.
+
+- **io.podman.annotations.checkpoint.distribution.version**: Version of host
+  distribution on which the checkpoint was created.
+
+- **io.podman.annotations.checkpoint.distribution.name**: Name of host
+  distribution on which the checkpoint was created.
+
 #### **--export**, **-e**=*archive*
 
 Export the checkpoint to a tar.gz file. The exported checkpoint can be used
@@ -145,6 +199,11 @@ Make a checkpoint for the container "mywebserver".
 # podman container checkpoint mywebserver
 ```
 
+Create a checkpoint image for the container "mywebserver".
+```
+# podman container checkpoint --create-image mywebserver-checkpoint-1 mywebserver
+```
+
 Dumps the container's memory information of the latest container into an archive.
 ```
 # podman container checkpoint -P -e pre-checkpoint.tar.gz -l
diff --git a/docs/source/markdown/podman-container-restore.1.md b/docs/source/markdown/podman-container-restore.1.md
index 5b1bf82c5..a70cc30d1 100644
--- a/docs/source/markdown/podman-container-restore.1.md
+++ b/docs/source/markdown/podman-container-restore.1.md
@@ -4,10 +4,11 @@
 podman\-container\-restore - Restores one or more containers from a checkpoint
 
 ## SYNOPSIS
-**podman container restore** [*options*] *container* [*container* ...]
+**podman container restore** [*options*] *name* [...]
 
 ## DESCRIPTION
-**podman container restore** restores a container from a checkpoint. The *container IDs* or *names* are used as input.
+**podman container restore** restores a container from a container checkpoint or
+checkpoint image. The *container IDs*, *image IDs* or *names* are used as input.
 
 ## OPTIONS
 #### **--all**, **-a**
@@ -106,14 +107,16 @@ If the **--name, -n** option is used, Podman will not attempt to assign the same
 address to the *container* it was using before checkpointing as each IP address can only
 be used once and the restored *container* will have another IP address. This also means
 that **--name, -n** cannot be used in combination with **--tcp-established**.\
-*IMPORTANT: This OPTION is only available in combination with __--import, -i__.*
+*IMPORTANT: This OPTION is only available for a checkpoint image or in combination
+with __--import, -i__.*
 
 #### **--pod**=*name*
 
 Restore a container into the pod *name*. The destination pod for this restore
 has to have the same namespaces shared as the pod this container was checkpointed
 from (see **[podman pod create --share](podman-pod-create.1.md#--share)**).\
-*IMPORTANT: This OPTION is only available in combination with __--import, -i__.*
+*IMPORTANT: This OPTION is only available for a checkpoint image or in combination
+with __--import, -i__.*
 
 This option requires at least CRIU 3.16.
 
@@ -175,6 +178,15 @@ $ podman run --rm -p 2345:80 -d webserver
 # podman container restore -p 5432:8080 --import=dump.tar
 ```
 
+Start a container with the name "foobar-1". Create a checkpoint image "foobar-checkpoint". Restore the container from the checkpoint image with a different name.
+```
+# podman run --name foobar-1 -d webserver
+# podman container checkpoint --create-image foobar-checkpoint foobar-1
+# podman inspect foobar-checkpoint
+# podman container restore --name foobar-2 foobar-checkpoint
+# podman container restore --name foobar-3 foobar-checkpoint
+```
+
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-container-checkpoint(1)](podman-container-checkpoint.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **criu(8)**