diff --git a/experimental/checkpoint-restore.md b/docs/reference/commandline/checkpoint.md similarity index 57% rename from experimental/checkpoint-restore.md rename to docs/reference/commandline/checkpoint.md index 2f7cdf46b8..9d99a7a9c8 100644 --- a/experimental/checkpoint-restore.md +++ b/docs/reference/commandline/checkpoint.md @@ -1,6 +1,13 @@ -# Docker Checkpoint & Restore +--- +title: docker checkpoint +description: "The checkpoint command description and usage" +keywords: experimental, checkpoint, restore, criu +experimental: true +--- -Checkpoint & Restore is a new feature that allows you to freeze a running +## Description + +Checkpoint and Restore is an experimental feature that allows you to freeze a running container by checkpointing it, which turns its state into a collection of files on disk. Later, the container can be restored from the point it was frozen. @@ -9,16 +16,16 @@ external dependency of this feature. A good overview of the history of checkpoint and restore in Docker is available in this [Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/). -## Installing CRIU +### Installing CRIU If you use a Debian system, you can add the CRIU PPA and install with apt-get [from the criu launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa). -Alternatively, you can [build CRIU from source](http://criu.org/Installation). +Alternatively, you can [build CRIU from source](https://criu.org/Installation). You need at least version 2.0 of CRIU to run checkpoint/restore in Docker. -## Use cases for checkpoint & restore +### Use cases for checkpoint & restore This feature is currently focused on single-host use cases for checkpoint and restore. Here are a few: @@ -33,7 +40,7 @@ migration of a server from one machine to another. This is possible with the current implementation, but not currently a priority (and so the workflow is not optimized for the task). -## Using checkpoint & restore +### Using checkpoint & restore A new top level command `docker checkpoint` is introduced, with three subcommands: - `create` (creates a new checkpoint) @@ -44,35 +51,40 @@ Additionally, a `--checkpoint` flag is added to the container start command. The options for checkpoint create: - Usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT +```console +Usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT - Create a checkpoint from a running container +Create a checkpoint from a running container - --leave-running=false Leave the container running after checkpoint - --checkpoint-dir Use a custom checkpoint storage directory + --leave-running=false Leave the container running after checkpoint + --checkpoint-dir Use a custom checkpoint storage directory +``` And to restore a container: - Usage: docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER +```console +Usage: docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER +``` +Example of using checkpoint & restore on a container: -A simple example of using checkpoint & restore on a container: +```console +$ docker run --security-opt=seccomp:unconfined --name cr -d busybox /bin/sh -c 'i=0; while true; do echo $i; i=$(expr $i + 1); sleep 1; done' +abc0123 - $ docker run --security-opt=seccomp:unconfined --name cr -d busybox /bin/sh -c 'i=0; while true; do echo $i; i=$(expr $i + 1); sleep 1; done' - > abc0123 +$ docker checkpoint create cr checkpoint1 - $ docker checkpoint create cr checkpoint1 - - # - $ docker start --checkpoint checkpoint1 cr - > abc0123 +# +$ docker start --checkpoint checkpoint1 cr +abc0123 +``` This process just logs an incrementing counter to stdout. If you `docker logs` in between running/checkpoint/restoring you should see that the counter increases while the process is running, stops while it's checkpointed, and resumes from the point it left off once you restore. -## Current limitation +### Known limitations seccomp is only supported by CRIU in very up to date kernels. @@ -80,9 +92,10 @@ External terminal (i.e. `docker run -t ..`) is not supported at the moment. If you try to create a checkpoint for a container with an external terminal, it would fail: - $ docker checkpoint create cr checkpoint1 - Error response from daemon: Cannot checkpoint container c1: rpc error: code = 2 desc = exit status 1: "criu failed: type NOTIFY errno 0\nlog file: /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log\n" - - $ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log - Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount +```console +$ docker checkpoint create cr checkpoint1 +Error response from daemon: Cannot checkpoint container c1: rpc error: code = 2 desc = exit status 1: "criu failed: type NOTIFY errno 0\nlog file: /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log\n" +$ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log +Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount +``` diff --git a/experimental/README.md b/experimental/README.md index 21753f5c9e..d3727b4e36 100644 --- a/experimental/README.md +++ b/experimental/README.md @@ -11,8 +11,6 @@ please feel free to provide any feedback on these features you wish. ## Use Docker experimental -Experimental features are now included in the standard Docker binaries as of -version 1.13.0. To enable experimental features, start the Docker daemon with the `--experimental` flag or enable the daemon flag in the `/etc/docker/daemon.json` configuration file: @@ -39,5 +37,5 @@ Checkpoint and restore support for Containers. Metrics (Prometheus) output for basic container, image, and daemon operations. * [External graphdriver plugins](../docs/extend/plugins_graphdriver.md) - * [Checkpoint & Restore](checkpoint-restore.md) + * [Checkpoint & Restore](../docs/reference/commandline/checkpoint-restore.md) * [Docker build with --squash argument](../docs/reference/commandline/build.md#squash-an-images-layers---squash-experimental)