gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/g3doc/README.md (about) 1 # What is gVisor? 2 3 gVisor is an application kernel, written in Go, that implements a substantial 4 portion of the [Linux system call interface][linux]. It provides an additional 5 layer of isolation between running applications and the host operating system. 6 7 gVisor includes an [Open Container Initiative (OCI)][oci] runtime called `runsc` 8 that makes it easy to work with existing container tooling. The `runsc` runtime 9 integrates with Docker and Kubernetes, making it simple to run sandboxed 10 containers. 11 12 gVisor can be used with Docker, Kubernetes, or directly using `runsc`. Use the 13 links below to see detailed instructions for each of them: 14 15 * [Docker](./user_guide/quick_start/docker.md): The quickest and easiest way 16 to get started. 17 * [Kubernetes](./user_guide/quick_start/kubernetes.md): Isolate Pods in your 18 K8s cluster with gVisor. 19 * [OCI Quick Start](./user_guide/quick_start/oci.md): Expert mode. Customize 20 gVisor for your environment. 21 22 ## What does gVisor do? 23 24 gVisor provides a virtualized environment in order to sandbox containers. The 25 system interfaces normally implemented by the host kernel are moved into a 26 distinct, per-sandbox application kernel in order to minimize the risk of a 27 container escape exploit. gVisor does not introduce large fixed overheads 28 however, and still retains a process-like model with respect to resource 29 utilization. 30 31 ## How is this different? 32 33 Two other approaches are commonly taken to provide stronger isolation than 34 native containers. 35 36 **Machine-level virtualization**, such as [KVM][kvm] and [Xen][xen], exposes 37 virtualized hardware to a guest kernel via a Virtual Machine Monitor (VMM). This 38 virtualized hardware is generally enlightened (paravirtualized) and additional 39 mechanisms can be used to improve the visibility between the guest and host 40 (e.g. balloon drivers, paravirtualized spinlocks). Running containers in 41 distinct virtual machines can provide great isolation, compatibility and 42 performance (though nested virtualization may bring challenges in this area), 43 but for containers it often requires additional proxies and agents, and may 44 require a larger resource footprint and slower start-up times. 45 46 ![Machine-level virtualization](Machine-Virtualization.png "Machine-level virtualization") 47 48 **Rule-based execution**, such as [seccomp][seccomp], [SELinux][selinux] and 49 [AppArmor][apparmor], allows the specification of a fine-grained security policy 50 for an application or container. These schemes typically rely on hooks 51 implemented inside the host kernel to enforce the rules. If the surface can be 52 made small enough, then this is an excellent way to sandbox applications and 53 maintain native performance. However, in practice it can be extremely difficult 54 (if not impossible) to reliably define a policy for arbitrary, previously 55 unknown applications, making this approach challenging to apply universally. 56 57 ![Rule-based execution](Rule-Based-Execution.png "Rule-based execution") 58 59 Rule-based execution is often combined with additional layers for 60 defense-in-depth. 61 62 **gVisor** provides a third isolation mechanism, distinct from those above. 63 64 gVisor intercepts application system calls and acts as the guest kernel, without 65 the need for translation through virtualized hardware. gVisor may be thought of 66 as either a merged guest kernel and VMM, or as seccomp on steroids. This 67 architecture allows it to provide a flexible resource footprint (i.e. one based 68 on threads and memory mappings, not fixed guest physical resources) while also 69 lowering the fixed costs of virtualization. However, this comes at the price of 70 reduced application compatibility and higher per-system call overhead. 71 72 ![gVisor](Layers.png "gVisor") 73 74 On top of this, gVisor employs rule-based execution to provide defense-in-depth 75 (details below). 76 77 gVisor's approach is similar to [User Mode Linux (UML)][uml], although UML 78 virtualizes hardware internally and thus provides a fixed resource footprint. 79 80 Each of the above approaches may excel in distinct scenarios. For example, 81 machine-level virtualization will face challenges achieving high density, while 82 gVisor may provide poor performance for system call heavy workloads. 83 84 ## Why Go? 85 86 gVisor is written in [Go][golang] in order to avoid security pitfalls that can 87 plague kernels. With Go, there are strong types, built-in bounds checks, no 88 uninitialized variables, no use-after-free, no stack overflow, and a built-in 89 race detector. However, the use of Go has its challenges, and the runtime often 90 introduces performance overhead. 91 92 ## What are the different components? 93 94 A gVisor sandbox consists of multiple processes. These processes collectively 95 comprise an environment in which one or more containers can be run. 96 97 Each sandbox has its own isolated instance of: 98 99 * The **Sentry**, which is a kernel that runs the containers and intercepts 100 and responds to system calls made by the application. 101 102 Each container running in the sandbox has its own isolated instance of: 103 104 * A **Gofer** which provides file system access to the containers. 105 106 ![gVisor architecture diagram](Sentry-Gofer.png "gVisor architecture diagram") 107 108 ## What is runsc? 109 110 The entrypoint to running a sandboxed container is the `runsc` executable. 111 `runsc` implements the [Open Container Initiative (OCI)][oci] runtime 112 specification, which is used by Docker and Kubernetes. This means that OCI 113 compatible _filesystem bundles_ can be run by `runsc`. Filesystem bundles are 114 comprised of a `config.json` file containing container configuration, and a root 115 filesystem for the container. Please see the [OCI runtime spec][runtime-spec] 116 for more information on filesystem bundles. `runsc` implements multiple commands 117 that perform various functions such as starting, stopping, listing, and querying 118 the status of containers. 119 120 ### Sentry {#sentry} 121 122 The Sentry is the largest component of gVisor. It can be thought of as a 123 application kernel. The Sentry implements all the kernel functionality needed by 124 the application, including: system calls, signal delivery, memory management and 125 page faulting logic, the threading model, and more. 126 127 When the application makes a system call, the 128 [Platform](./architecture_guide/platforms.md) redirects the call to the Sentry, 129 which will do the necessary work to service it. It is important to note that the 130 Sentry does not pass system calls through to the host kernel. As a userspace 131 application, the Sentry will make some host system calls to support its 132 operation, but it does not allow the application to directly control the system 133 calls it makes. For example, the Sentry is not able to open files directly; file 134 system operations that extend beyond the sandbox (not internal `/proc` files, 135 pipes, etc) are sent to the Gofer, described below. 136 137 ### Gofer {#gofer} 138 139 The Gofer is a standard host process which is started with each container and 140 communicates with the Sentry via the [9P protocol][9p] over a socket or shared 141 memory channel. The Sentry process is started in a restricted seccomp container 142 without access to file system resources. The Gofer mediates all access to these 143 resources, providing an additional level of isolation. 144 145 ### Application {#application} 146 147 The application is a normal Linux binary provided to gVisor in an OCI runtime 148 bundle. gVisor aims to provide an environment equivalent to Linux v4.4, so 149 applications should be able to run unmodified. However, gVisor does not 150 presently implement every system call, `/proc` file, or `/sys` file so some 151 incompatibilities may occur. See [Compatibility](./user_guide/compatibility.md) 152 for more information. 153 154 [9p]: https://en.wikipedia.org/wiki/9P_(protocol) 155 [apparmor]: https://wiki.ubuntu.com/AppArmor 156 [golang]: https://golang.org 157 [kvm]: https://www.linux-kvm.org 158 [linux]: https://en.wikipedia.org/wiki/Linux_kernel_interfaces 159 [oci]: https://www.opencontainers.org 160 [runtime-spec]: https://github.com/opencontainers/runtime-spec 161 [seccomp]: https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt 162 [selinux]: https://selinuxproject.org 163 [uml]: http://user-mode-linux.sourceforge.net/ 164 [xen]: https://www.xenproject.org