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

     1  # Changing Platforms
     2  
     3  [TOC]
     4  
     5  This guide describes how to change the
     6  [platform](../architecture_guide/platforms.md) used by `runsc`.
     7  
     8  Configuring the platform provides significant performance benefits, but isn't
     9  the only step to optimizing gVisor performance. See the [Production guide] for
    10  more.
    11  
    12  ## Prerequisites
    13  
    14  If you intend to run the KVM platform, you will also need to have KVM installed
    15  on your system. If you are running a Debian based system like Debian or Ubuntu
    16  you can usually do this by ensuring the module is loaded, and your user has
    17  permissions to access the `/dev/kvm` device. Usually, this means that your user
    18  is in the `kvm` group.
    19  
    20  ```shell
    21  # Check that /dev/kvm is owned by the kvm group
    22  $ ls -l /dev/kvm
    23  crw-rw----+ 1 root kvm 10, 232 Jul 26 00:04 /dev/kvm
    24  
    25  # Make sure that the current user is part of the kvm group
    26  $ groups | grep -qw kvm && echo ok
    27  ok
    28  ```
    29  
    30  **For best performance, use the KVM platform on bare-metal machines only**. If
    31  you have to run gVisor within a virtual machine, the `systrap` platform will
    32  often yield better performance than KVM. If you still want to use KVM within a
    33  virtual machine, you will need to make sure that nested virtualization is
    34  configured. Here are links to documents on how to set up nested virtualization
    35  in several popular environments:
    36  
    37  *   Google Cloud: [Enabling Nested Virtualization for VM Instances][nested-gcp]
    38  *   Microsoft Azure:
    39      [How to enable nested virtualization in an Azure VM][nested-azure]
    40  *   VirtualBox: [Nested Virtualization][nested-virtualbox]
    41  *   KVM: [Nested Guests][nested-kvm]
    42  
    43  ***Note: nested virtualization will have poor performance and is historically a
    44  cause of security issues (e.g.
    45  [CVE-2018-12904](https://nvd.nist.gov/vuln/detail/CVE-2018-12904)). It is not
    46  recommended for production.***
    47  
    48  A third platform, `ptrace`, also has the versatility of running on any
    49  environment. However, it has higher performance overhead than `systrap` in
    50  almost all cases. `systrap` replaced `ptrace` as the default platform in
    51  mid-2023. While `ptrace` continues to exist in the codebase, it is no longer
    52  supported and is expected to eventually be removed entirely. If you depend on
    53  `ptrace`, and `systrap` doesn't fulfill your needs, please
    54  [voice your feedback](../community.md).
    55  
    56  ## Configuring Docker
    57  
    58  The platform is selected by the `--platform` command line flag passed to
    59  `runsc`. By default, the `systrap` platform is selected. For example, to select
    60  the KVM platform, modify your Docker configuration (`/etc/docker/daemon.json`)
    61  to pass the `--platform` argument:
    62  
    63  ```json
    64  {
    65      "runtimes": {
    66          "runsc": {
    67              "path": "/usr/local/bin/runsc",
    68              "runtimeArgs": [
    69                  "--platform=kvm"
    70              ]
    71         }
    72      }
    73  }
    74  ```
    75  
    76  You must restart the Docker daemon after making changes to this file, typically
    77  this is done via `systemd`:
    78  
    79  ```shell
    80  $ sudo systemctl restart docker
    81  ```
    82  
    83  Note that you may configure multiple runtimes using different platforms. For
    84  example, the following configuration has one configuration for systrap and one
    85  for the KVM platform:
    86  
    87  ```json
    88  {
    89      "runtimes": {
    90          "runsc-kvm": {
    91              "path": "/usr/local/bin/runsc",
    92              "runtimeArgs": [
    93                  "--platform=kvm"
    94              ]
    95          },
    96          "runsc-systrap": {
    97              "path": "/usr/local/bin/runsc",
    98              "runtimeArgs": [
    99                  "--platform=systrap"
   100              ]
   101          }
   102      }
   103  }
   104  ```
   105  
   106  [Production guide]: ../production/
   107  [nested-azure]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/nested-virtualization
   108  [nested-gcp]: https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances
   109  [nested-virtualbox]: https://www.virtualbox.org/manual/UserManual.html#nested-virt
   110  [nested-kvm]: https://www.linux-kvm.org/page/Nested_Guests