From 36c940b093af58d02eb6e7fd186f14cce84a8dd9 Mon Sep 17 00:00:00 2001 From: Nicolas Lacasse Date: Fri, 10 Aug 2018 15:56:31 -0700 Subject: Move checkpoint/restore readme to g3doc directory. PiperOrigin-RevId: 208282383 Change-Id: Ifa4aaf5d925b17d9a0672ea951a4570d35855300 --- README.md | 3 +- g3doc/checkpoint_restore.md | 108 ++++++++++++++++++++++++++++++++++++++++++++ runsc/checkpoint_restore.md | 108 -------------------------------------------- 3 files changed, 110 insertions(+), 109 deletions(-) create mode 100644 g3doc/checkpoint_restore.md delete mode 100644 runsc/checkpoint_restore.md diff --git a/README.md b/README.md index 01c898086..709da37a0 100644 --- a/README.md +++ b/README.md @@ -365,7 +365,7 @@ Then restart the Docker daemon. gVisor has the ability to checkpoint a process, save its current state in a state file, and restore into a new container using the state file. For more information about the checkpoint and restore commands, see the -[checkpoint/restore readme](https://gvisor.googlesource.com/gvisor/+/master/runsc/checkpoint_restore.md). +[checkpoint-restore][checkpoint/restore readme] ## FAQ & Known Issues @@ -442,6 +442,7 @@ See [Contributing.md](CONTRIBUTING.md). [apparmor]: https://wiki.ubuntu.com/AppArmor [bazel]: https://bazel.build [bug]: https://github.com/google/gvisor/issues +[checkpoint-restore]: https://gvisor.googlesource.com/gvisor/+/master/g3doc/checkpoint_restore.md [cri-o-k8s]: https://github.com/kubernetes-incubator/cri-o/blob/master/kubernetes.md [cri-o]: https://github.com/kubernetes-incubator/cri-o [docker-storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver diff --git a/g3doc/checkpoint_restore.md b/g3doc/checkpoint_restore.md new file mode 100644 index 000000000..5fa3280a8 --- /dev/null +++ b/g3doc/checkpoint_restore.md @@ -0,0 +1,108 @@ +# runsc checkpoint/restore + +gVisor supports checkpointing and restoring containers. A container’s state can +be checkpointed and later restored into one or more containers. This can be used +to save work and time in cases of failure and allow for container migration. A +single container can perform slower setup tasks and then be checkpointed so that +many containers with the same task can be “restored” and started more quickly. + +### How to checkpoint/restore + +To use the runsc checkpoint command, first run a container. + +```sh +runsc run +``` + +To checkpoint the container, the --image-path flag must be provided. This is the +directory path within which the checkpoint state-file will be created. The file +will be called checkpoint.img and necessary directories will be created if they +do not yet exist. + +> Note: Two checkpoints cannot be saved to the save directory; every image-path +provided must be unique. + +```sh +runsc checkpoint --image-path= +``` + +There is also an optional --leave-running flag that allows the container to +continue to run after the checkpoint has been made. (By default, containers stop +their processes after committing a checkpoint.) + +> Note: All top-level runsc flags needed when calling run must be provided to +checkpoint if --leave-running is used. + +> Note: --leave-running functions by causing an immediate restore so the +container, although will maintain its given container id, may have a different +process id. + +```sh +runsc checkpoint --image-path= --leave-running +``` + +To restore, provide the image path to the checkpoint.img file created during the +checkpoint. Because containers stop by default after checkpointing, restore +needs to happen in a new container (restore is a command which parallels start). + +```sh +runsc create + +runsc restore --image-path= +``` + +### How to use checkpoint/restore in Docker: + +Currently checkpoint/restore through runsc is not entirely compatible with +Docker, although there has been progress made from both gVisor and Docker to +enable compatibility. Here, we document the ideal workflow. + +To run with Docker, first follow the [instructions](https://gvisor.googlesource.com/gvisor/+/master/README.md#configuring-docker) to use runsc as a runtime. + +Run a container: + +```sh +docker run [options] --runtime=runsc ` +``` + +Checkpoint a container: + +```sh +docker checkpoint create ` +``` + +Create a new container into which to restore: + +```sh +docker create [options] --runtime=runsc +``` + +Restore a container: + +```sh +docker start --checkpoint --checkpoint-dir= +``` + +**Issues Preventing Compatibility with Docker** +1. [Moby #37360][leave-running] + +Docker version 18.03.0-ce and earlier hangs when checkpointing and +does not create the checkpoint. To successfully use this feature, install a +custom version of docker-ce from the moby repository. This issue is caused by an +improper implementation of the `--leave-running` flag. This issue is now fixed +although is not yet part of an official release. + +2. Docker does not support restoration into new containers. + +Docker currently expects the container which created the checkpoint +to be the same container used to restore which is not possible in runsc. When +Docker supports container migration and therefore restoration into new +containers, this will be the flow. + +3. [Moby #37344][checkpoint-dir] + +Docker does not currently support the `--checkpoint-dir` flag but this will be +required when restoring from a checkpoint made in another container. + +[leave-running]: https://github.com/moby/moby/pull/37360 +[checkpoint-dir]: https://github.com/moby/moby/issues/37344 diff --git a/runsc/checkpoint_restore.md b/runsc/checkpoint_restore.md deleted file mode 100644 index 5fa3280a8..000000000 --- a/runsc/checkpoint_restore.md +++ /dev/null @@ -1,108 +0,0 @@ -# runsc checkpoint/restore - -gVisor supports checkpointing and restoring containers. A container’s state can -be checkpointed and later restored into one or more containers. This can be used -to save work and time in cases of failure and allow for container migration. A -single container can perform slower setup tasks and then be checkpointed so that -many containers with the same task can be “restored” and started more quickly. - -### How to checkpoint/restore - -To use the runsc checkpoint command, first run a container. - -```sh -runsc run -``` - -To checkpoint the container, the --image-path flag must be provided. This is the -directory path within which the checkpoint state-file will be created. The file -will be called checkpoint.img and necessary directories will be created if they -do not yet exist. - -> Note: Two checkpoints cannot be saved to the save directory; every image-path -provided must be unique. - -```sh -runsc checkpoint --image-path= -``` - -There is also an optional --leave-running flag that allows the container to -continue to run after the checkpoint has been made. (By default, containers stop -their processes after committing a checkpoint.) - -> Note: All top-level runsc flags needed when calling run must be provided to -checkpoint if --leave-running is used. - -> Note: --leave-running functions by causing an immediate restore so the -container, although will maintain its given container id, may have a different -process id. - -```sh -runsc checkpoint --image-path= --leave-running -``` - -To restore, provide the image path to the checkpoint.img file created during the -checkpoint. Because containers stop by default after checkpointing, restore -needs to happen in a new container (restore is a command which parallels start). - -```sh -runsc create - -runsc restore --image-path= -``` - -### How to use checkpoint/restore in Docker: - -Currently checkpoint/restore through runsc is not entirely compatible with -Docker, although there has been progress made from both gVisor and Docker to -enable compatibility. Here, we document the ideal workflow. - -To run with Docker, first follow the [instructions](https://gvisor.googlesource.com/gvisor/+/master/README.md#configuring-docker) to use runsc as a runtime. - -Run a container: - -```sh -docker run [options] --runtime=runsc ` -``` - -Checkpoint a container: - -```sh -docker checkpoint create ` -``` - -Create a new container into which to restore: - -```sh -docker create [options] --runtime=runsc -``` - -Restore a container: - -```sh -docker start --checkpoint --checkpoint-dir= -``` - -**Issues Preventing Compatibility with Docker** -1. [Moby #37360][leave-running] - -Docker version 18.03.0-ce and earlier hangs when checkpointing and -does not create the checkpoint. To successfully use this feature, install a -custom version of docker-ce from the moby repository. This issue is caused by an -improper implementation of the `--leave-running` flag. This issue is now fixed -although is not yet part of an official release. - -2. Docker does not support restoration into new containers. - -Docker currently expects the container which created the checkpoint -to be the same container used to restore which is not possible in runsc. When -Docker supports container migration and therefore restoration into new -containers, this will be the flow. - -3. [Moby #37344][checkpoint-dir] - -Docker does not currently support the `--checkpoint-dir` flag but this will be -required when restoring from a checkpoint made in another container. - -[leave-running]: https://github.com/moby/moby/pull/37360 -[checkpoint-dir]: https://github.com/moby/moby/issues/37344 -- cgit v1.2.3