github.com/SagerNet/gvisor@v0.0.0-20210707092255-7731c139d75c/g3doc/user_guide/checkpoint_restore.md (about)

     1  # Checkpoint/Restore
     2  
     3  [TOC]
     4  
     5  gVisor has the ability to checkpoint a process, save its current state in a
     6  state file, and restore into a new container using the state file.
     7  
     8  ## How to use checkpoint/restore
     9  
    10  Checkpoint/restore functionality is currently available via raw `runsc`
    11  commands. To use the checkpoint command, first run a container.
    12  
    13  ```bash
    14  runsc run <container id>
    15  ```
    16  
    17  To checkpoint the container, the `--image-path` flag must be provided. This is
    18  the directory path within which the checkpoint state-file will be created. The
    19  file will be called `checkpoint.img` and necessary directories will be created
    20  if they do not yet exist.
    21  
    22  > Note: Two checkpoints cannot be saved to the same directory; every image-path
    23  > provided must be unique.
    24  
    25  ```bash
    26  runsc checkpoint --image-path=<path> <container id>
    27  ```
    28  
    29  There is also an optional `--leave-running` flag that allows the container to
    30  continue to run after the checkpoint has been made. (By default, containers stop
    31  their processes after committing a checkpoint.)
    32  
    33  > Note: All top-level runsc flags needed when calling run must be provided to
    34  > checkpoint if --leave-running is used.
    35  
    36  > Note: --leave-running functions by causing an immediate restore so the
    37  > container, although will maintain its given container id, may have a different
    38  > process id.
    39  
    40  ```bash
    41  runsc checkpoint --image-path=<path> --leave-running <container id>
    42  ```
    43  
    44  To restore, provide the image path to the `checkpoint.img` file created during
    45  the checkpoint. Because containers stop by default after checkpointing, restore
    46  needs to happen in a new container (restore is a command which parallels start).
    47  
    48  ```bash
    49  runsc create <container id>
    50  
    51  runsc restore --image-path=<path> <container id>
    52  ```
    53  
    54  ## How to use checkpoint/restore in Docker:
    55  
    56  Currently checkpoint/restore through `runsc` is not entirely compatible with
    57  Docker, although there has been progress made from both gVisor and Docker to
    58  enable compatibility. Here, we document the ideal workflow.
    59  
    60  Run a container:
    61  
    62  ```bash
    63  docker run [options] --runtime=runsc <image>`
    64  ```
    65  
    66  Checkpoint a container:
    67  
    68  ```bash
    69  docker checkpoint create <container> <checkpoint_name>`
    70  ```
    71  
    72  Create a new container into which to restore:
    73  
    74  ```bash
    75  docker create [options] --runtime=runsc <image>
    76  ```
    77  
    78  Restore a container:
    79  
    80  ```bash
    81  docker start --checkpoint --checkpoint-dir=<directory> <container>
    82  ```
    83  
    84  ### Issues Preventing Compatibility with Docker
    85  
    86  -   **[Moby #37360][leave-running]:** Docker version 18.03.0-ce and earlier
    87      hangs when checkpointing and does not create the checkpoint. To successfully
    88      use this feature, install a custom version of docker-ce from the moby
    89      repository. This issue is caused by an improper implementation of the
    90      `--leave-running` flag. This issue is fixed in newer releases.
    91  -   **Docker does not support restoration into new containers:** Docker
    92      currently expects the container which created the checkpoint to be the same
    93      container used to restore which is not possible in runsc. When Docker
    94      supports container migration and therefore restoration into new containers,
    95      this will be the flow.
    96  -   **[Moby #37344][checkpoint-dir]:** Docker does not currently support the
    97      `--checkpoint-dir` flag but this will be required when restoring from a
    98      checkpoint made in another container.
    99  
   100  [leave-running]: https://github.com/moby/moby/pull/37360
   101  [checkpoint-dir]: https://github.com/moby/moby/issues/37344