netbird/gvisor
0
0
Fork 0
mirror of https://github.com/netbirdio/gvisor.git synced 2026-05-22 17:12:49 -07:00
Code Issues Packages Projects Releases Wiki Activity

Systrap is now the default gVisor platform. Update platform documentation.

Browse Source 
PiperOrigin-RevId: 547983290
This commit is contained in:
Etienne Perot
2023-07-13 18:27:34 -07:00
committed by gVisor bot
parent ffcbc70b9a
commit 501a9aaf49
2 changed files with 43 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
g3doc/architecture_guide/platforms.md
+29 -28
View File
@@ -30,33 +30,11 @@ various trade-offs, generally around performance and hardware requirements.
The choice of platform depends on the context in which `runsc` is executing. In
general, when running on bare-metal (not inside a VM), the KVM platform will
provide the best performance. The `ptrace` platform is a better choice when
provide the best performance. The `systrap` platform is a better choice when
running inside a VM, or on a machine without virtualization support.
![Platforms](platforms.png "Platform examples.")
### ptrace
The ptrace platform uses [`PTRACE_SYSEMU`][ptrace] to execute user code without
allowing it to execute host system calls. This platform can run anywhere that
`ptrace` works (even VMs without nested virtualization), which is ubiquitous.
Unfortunately, the ptrace platform has high context switch overhead, so system
call-heavy applications may pay a [performance penalty](./performance.md).
### systrap
The systrap platform is an **experimental, non-production-ready** platform aimed
at replacing the ptrace platform (i.e. in VMs without nested virtualization). It
relies `seccomp`'s `SECCOMP_RET_TRAP` feature in order to intercept system
calls. This makes the kernel send `SIGSYS` to the triggering thread, which hands
over control to gVisor to handle the system call. For more details, please see
[the systrap `README` file](https://github.com/google/gvisor/blob/master/pkg/sentry/platform/systrap/README.md).
As of 2023-03, this platform has not been battle-tested as `ptrace`, and is not
recommended for production use. Users are encouraged to try it out in
non-production environments and [report bugs and feedback](../community.md).
### KVM
The KVM platform uses the kernel's [KVM][kvm] functionality to allow the Sentry
@@ -67,13 +45,36 @@ processors in order to improve isolation and performance of address space
switches.
Note that while running within a nested VM is feasible with the KVM platform,
the `ptrace` platform will often provide better performance in such a setup, due
to the overhead of nested virtualization.
the `systrap` platform will often provide better performance in such a setup,
due to the overhead of nested virtualization.
### GKE Sandbox
### systrap
[GKE Sandbox] uses a custom gVisor platform implementation which provides better
performance than `ptrace` and KVM.
The `systrap` platform relies `seccomp`'s `SECCOMP_RET_TRAP` feature in order to
intercept system calls. This makes the kernel send `SIGSYS` to the triggering
thread, which hands over control to gVisor to handle the system call. For more
details, please see
[the systrap `README` file](https://github.com/google/gvisor/blob/master/pkg/sentry/platform/systrap/README.md).
`systrap` replaced `ptrace` as the default gVisor platform in mid-2023. If you
depend on `ptrace`, and `systrap` doesn't fulfill your needs, please
[voice your feedback](../community.md).
### ptrace
The ptrace platform uses [`PTRACE_SYSEMU`][ptrace] to execute user code without
allowing it to execute host system calls. This platform can run anywhere that
`ptrace` works (even VMs without nested virtualization), which is ubiquitous.
Unfortunately, the ptrace platform has high context switch overhead, so system
call-heavy applications may pay a [performance penalty](./performance.md). For
this reason, `systrap` is almost always the better choice.
`systrap` replaced `ptrace` as the default gVisor platform in mid-2023. While
`ptrace` continues to exist in the codebase, it is no longer supported and is
expected to eventually be removed entirely. If you depend on `ptrace`, and
`systrap` doesn't fulfill your needs, please
[voice your feedback](../community.md).
## Changing Platforms
g3doc/user_guide/platforms.md
+14 -17
View File
@@ -14,8 +14,8 @@ more.
If you intend to run the KVM platform, you will also to have KVM installed on
your system. If you are running a Debian based system like Debian or Ubuntu you
can usually do this by ensuring the module is loaded, and your user has
permissions to access the `/dev/kvm` device. Usually, it means that the user is
in the `kvm` group.
permissions to access the `/dev/kvm` device. Usually, this means that your user
is in the `kvm` group.
```shell
# Check that /dev/kvm is owned by the kvm group
@@ -28,7 +28,7 @@ ok
```
**For best performance, use the KVM platform on bare-metal machines only**. If
you have to run gVisor within a virtual machine, the `ptrace` platform will
you have to run gVisor within a virtual machine, the `systrap` platform will
often yield better performance than KVM. If you still want to use KVM within a
virtual machine, you will need to make sure that nested virtualization is
configured. Here are links to documents on how to set up nested virtualization
@@ -45,17 +45,20 @@ cause of security issues (e.g.
[CVE-2018-12904](https://nvd.nist.gov/vuln/detail/CVE-2018-12904)). It is not
recommended for production.***
A third platform, `systrap`, is expected to eventually replace the `ptrace`
platform. As of this writing (2023-03), **this platform is not
production-ready**, but we encourage `ptrace` users to try it out in
non-production settings and [report bugs and feedback](../community.md).
A third platform, `ptrace`, also has the versatility of running on any
environment. However, it has higher performance overhead than `systrap` in
almost all cases. `systrap` replaced `ptrace` as the default platform in
mid-2023. While `ptrace` continues to exist in the codebase, it is no longer
supported and is expected to eventually be removed entirely. If you depend on
`ptrace`, and `systrap` doesn't fulfill your needs, please
[voice your feedback](../community.md).
## Configuring Docker
The platform is selected by the `--platform` command line flag passed to
`runsc`. By default, the ptrace platform is selected. For example, to select the
KVM platform, modify your Docker configuration (`/etc/docker/daemon.json`) to
pass the `--platform` argument:
`runsc`. By default, the `systrap` platform is selected. For example, to select
the KVM platform, modify your Docker configuration (`/etc/docker/daemon.json`)
to pass the `--platform` argument:
```json
{
@@ -78,18 +81,12 @@ $ sudo systemctl restart docker
```
Note that you may configure multiple runtimes using different platforms. For
example, the following configuration has one configuration for ptrace and one
example, the following configuration has one configuration for systrap and one
for the KVM platform:
```json
{
"runtimes": {
"runsc-ptrace": {
"path": "/usr/local/bin/runsc",
"runtimeArgs": [
"--platform=ptrace"
]
},
"runsc-kvm": {
"path": "/usr/local/bin/runsc",
"runtimeArgs": [