gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/g3doc/user_guide/filesystem.md (about)

     1  # Filesystem
     2  
     3  [TOC]
     4  
     5  gVisor accesses the filesystem through a file proxy, called the Gofer. The gofer
     6  runs as a separate process, that is isolated from the sandbox. Gofer instances
     7  communicate with their respective sentry using the LISAFS protocol.
     8  
     9  Configuring the filesystem provides performance benefits, but isn't the only
    10  step to optimizing gVisor performance. See the [Production guide] for more.
    11  
    12  ## Sandbox overlay
    13  
    14  To isolate the host filesystem from the sandbox, you can set a writable tmpfs
    15  overlay on top of the entire filesystem. All modifications are made to the
    16  overlay, keeping the host filesystem unmodified.
    17  
    18  > **Note**: All created and modified files are stored in memory inside the
    19  > sandbox.
    20  
    21  To use the tmpfs overlay, add the following `runtimeArgs` to your Docker
    22  configuration (`/etc/docker/daemon.json`) and restart the Docker daemon:
    23  
    24  ```json
    25  {
    26      "runtimes": {
    27          "runsc": {
    28              "path": "/usr/local/bin/runsc",
    29              "runtimeArgs": [
    30                  "--overlay2=all:memory"
    31              ]
    32         }
    33      }
    34  }
    35  ```
    36  
    37  ### Root Filesystem Overlay
    38  
    39  Any modifications to the root filesystem is destroyed with the container. So it
    40  almost always makes sense to apply an overlay on top of the root filesystem.
    41  This can drastically boost performance, as runsc will handle root filesystem
    42  changes completely in memory instead of making costly round trips to the gofer
    43  and make syscalls to modify the host.
    44  
    45  However, holding so much file data in memory for the root filesystem can bloat
    46  up container memory usage. To circumvent this, you can have root mount's upper
    47  layer (tmpfs) be backed by a host file, so all file data is stored on disk.
    48  
    49  The newer `--overlay2` flag allows you to achieve these. You can specify
    50  `--overlay2=root:self` in `runtimeArgs`. The overlay backing host file will be
    51  created in the container's root filesystem. This file will be hidden from the
    52  containerized application. Placing the host file in the container's root
    53  filesystem is important because k8s scans the container's root filesystem from
    54  the host to enforce local ephemeral storage limits. You can also place the
    55  overlay host file in another directory using `--overlay2=root:/path/dir`.
    56  
    57  ## Shared root filesystem
    58  
    59  The root filesystem is where the image is extracted and is not generally
    60  modified from outside the sandbox. This allows for some optimizations, like
    61  skipping checks to determine if a directory has changed since the last time it
    62  was cached, thus missing updates that may have happened. If you need to `docker
    63  cp` files inside the root filesystem, you may want to enable shared mode. Just
    64  be aware that file system access will be slower due to the extra checks that are
    65  required.
    66  
    67  > Note: External mounts are always shared.
    68  
    69  To use set the root filesystem shared, add the following `runtimeArgs` to your
    70  Docker configuration (`/etc/docker/daemon.json`) and restart the Docker daemon:
    71  
    72  ```json
    73  {
    74      "runtimes": {
    75          "runsc": {
    76              "path": "/usr/local/bin/runsc",
    77              "runtimeArgs": [
    78                  "--file-access=shared"
    79              ]
    80         }
    81      }
    82  }
    83  ```
    84  
    85  [Production guide]: ../production/