From 373ec2cf37bd5ef812b65a8f5c43e81001a61c8c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 7 Oct 2021 09:16:02 +0200 Subject: [PATCH] update engine reference docs with latest changes Signed-off-by: Sebastiaan van Stijn --- _data/engine-cli/docker_build.yaml | 2 +- _data/engine-cli/docker_checkpoint.yaml | 95 ++++++++++++++++++++++++- _data/engine-cli/docker_create.yaml | 2 +- _data/engine-cli/docker_search.yaml | 5 +- 4 files changed, 98 insertions(+), 6 deletions(-) diff --git a/_data/engine-cli/docker_build.yaml b/_data/engine-cli/docker_build.yaml index 29d0bbfa19..76373b92e4 100644 --- a/_data/engine-cli/docker_build.yaml +++ b/_data/engine-cli/docker_build.yaml @@ -905,7 +905,7 @@ examples: |- base image is still supported. - When using this option you may see significantly more space used due to storing two copies of the image, one for the build cache with all the cache - layers in tact, and one for the squashed version. + layers intact, and one for the squashed version. - While squashing layers may produce smaller images, it may have a negative impact on performance, as a single layer takes longer to extract, and downloading a single layer cannot be parallelized. diff --git a/_data/engine-cli/docker_checkpoint.yaml b/_data/engine-cli/docker_checkpoint.yaml index d170105891..5b614f3a22 100644 --- a/_data/engine-cli/docker_checkpoint.yaml +++ b/_data/engine-cli/docker_checkpoint.yaml @@ -1,6 +1,99 @@ command: docker checkpoint short: Manage checkpoints -long: Manage checkpoints +long: |- + 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. + + This is accomplished using a tool called [CRIU](http://criu.org), which is an + 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 + + 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](https://criu.org/Installation). + + You need at least version 2.0 of CRIU to run checkpoint and restore in Docker. + + ### Use cases for checkpoint and restore + + This feature is currently focused on single-host use cases for checkpoint and + restore. Here are a few: + + - Restarting the host machine without stopping/starting containers + - Speeding up the start time of slow start applications + - "Rewinding" processes to an earlier point in time + - "Forensic debugging" of running processes + + Another primary use case of checkpoint and restore outside of Docker is the live + 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 and restore + + A new top level command `docker checkpoint` is introduced, with three subcommands: + + - `docker checkpoint create` (creates a new checkpoint) + - `docker checkpoint ls` (lists existing checkpoints) + - `docker checkpoint rm` (deletes an existing checkpoint) + + Additionally, a `--checkpoint` flag is added to the `docker container start` command. + + The options for `docker checkpoint create`: + + ```console + Usage: docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT + + Create a checkpoint from a running container + + --leave-running=false Leave the container running after checkpoint + --checkpoint-dir Use a custom checkpoint storage directory + ``` + + And to restore a container: + + ```console + Usage: docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER + ``` + + Example of using checkpoint and 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 checkpoint create cr checkpoint1 + + # + $ docker start --checkpoint checkpoint1 cr + abc0123 + ``` + + This process just logs an incrementing counter to stdout. If you run `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. + + ### Known limitations + + seccomp is only supported by CRIU in very up to date kernels. + + 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: + + ```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 + ``` usage: docker checkpoint pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_create.yaml b/_data/engine-cli/docker_create.yaml index 84fb69d580..44d8a19795 100644 --- a/_data/engine-cli/docker_create.yaml +++ b/_data/engine-cli/docker_create.yaml @@ -990,7 +990,7 @@ examples: |- created into the container once it is run. This poses a problem when a new device needs to be added to running container. - One of the solution is to add a more permissive rule to a container + One of the solutions is to add a more permissive rule to a container allowing it access to a wider range of devices. For example, supposing our container needs access to a character device with major `42` and any number of minor number (added as new devices appear), the diff --git a/_data/engine-cli/docker_search.yaml b/_data/engine-cli/docker_search.yaml index 51c5b29d10..198bd84e83 100644 --- a/_data/engine-cli/docker_search.yaml +++ b/_data/engine-cli/docker_search.yaml @@ -141,9 +141,8 @@ examples: |- ```console $ docker search --filter is-official=true --filter stars=3 busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + busybox Busybox base image. 325 [OK] ``` ### Format the output