gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/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 related files will be created.
    19  All necessary directories will be created if they do not yet exist.
    20  
    21  > Note: Two checkpoints cannot be saved to the same directory; every image-path
    22  > provided must be unique.
    23  
    24  ```bash
    25  runsc checkpoint --image-path=<path> <container id>
    26  ```
    27  
    28  There is also an optional `--leave-running` flag that allows the container to
    29  continue to run after the checkpoint has been made. (By default, containers stop
    30  their processes after committing a checkpoint.)
    31  
    32  > Note: All top-level runsc flags needed when calling run must be provided to
    33  > checkpoint if `--leave-running` is used.
    34  
    35  > Note: `--leave-running` functions by causing an immediate restore so the
    36  > container, although will maintain its given container id, may have a different
    37  > process id.
    38  
    39  ```bash
    40  runsc checkpoint --image-path=<path> --leave-running <container id>
    41  ```
    42  
    43  To restore, provide the image path to the directory containing all the files
    44  created during the checkpoint. Because containers stop by default after
    45  checkpointing, restore needs to happen in a new container (restore is a command
    46  which parallels start).
    47  
    48  ```bash
    49  runsc create <container id>
    50  
    51  runsc restore --image-path=<path> <container id>
    52  ```
    53  
    54  > Note: All top-level runsc flags needed when calling run must be provided to
    55  > `restore`.
    56  
    57  ## How to use checkpoint/restore in Docker:
    58  
    59  Run a container:
    60  
    61  ```bash
    62  docker run [options] --runtime=runsc --name=<container-name> <image>
    63  ```
    64  
    65  Checkpoint the container:
    66  
    67  ```bash
    68  docker checkpoint create <container-name> <checkpoint-name>
    69  ```
    70  
    71  Restore into the same container:
    72  
    73  ```bash
    74  docker start --checkpoint <checkpoint-name> <container-name>
    75  ```
    76  
    77  ### Issues Preventing Compatibility with Docker
    78  
    79  -   **[Moby #37360][leave-running]:** Docker version 18.03.0-ce and earlier
    80      hangs when checkpointing and does not create the checkpoint. To successfully
    81      use this feature, install a custom version of docker-ce from the moby
    82      repository. This issue is caused by an improper implementation of the
    83      `--leave-running` flag. This issue is fixed in newer releases.
    84  -   **Docker does not support restoration into new containers:** Docker
    85      currently expects the container which created the checkpoint to be the same
    86      container used to restore. This is needed to support container migration.
    87  -   **[Moby #37344][checkpoint-dir]:** Docker does not currently support the
    88      `--checkpoint-dir` flag but this will be required when restoring from a
    89      checkpoint made in another container.
    90  
    91  [leave-running]: https://github.com/moby/moby/pull/37360
    92  [checkpoint-dir]: https://github.com/moby/moby/issues/37344