gVisor

gVisor is an application kernel that provides a strong layer of isolation between running applications and the host operating system. Written in Go, it implements a Linux-like interface in userspace. Unlike traditional containers that share the host kernel, gVisor intercepts application system calls and handles them in its own userspace kernel, significantly reducing the host kernel surface area exposed to untrusted code.

System Design Philosophy

gVisor takes a "third approach" to virtualization, sitting between traditional containers and full virtual machines. It maintains the low resource footprint and fast startup of containers while providing the security boundaries of a VM.

Core Components and Relationships

The system is composed of several distinct processes and packages that work together to provide the sandbox environment:

  • runsc: The entrypoint and OCI runtime.
  • Sentry: The "application kernel" that implements the Linux syscall interface, process management, and memory management.
  • Gofer: A file filesystem proxy that mediates access to host resources.
  • Netstack: A userspace TCP/IP stack implemented in Go.
Host OS (Ring 0)

Host OS (Ring 3)

Sandbox (Sentry Process)

creates

manages

Syscalls

9P/Lisafs

Syscalls

Platform Interface

runsc (OCI Runtime)

containerd-shim-runsc-v1

Gofer (File Proxy)

kernel.Kernel (Sentry)

vfs.VirtualFilesystem

stack.Stack (Netstack)

User Application Processes

Linux Host Kernel

Sandbox

Sources: README.md runsc/boot/loader.go runsc/boot/vfs.go

Component Details

runsc OCI Runtime

runsc is the command-line interface for gVisor. It implements the OCI runtime specification, allowing it to integrate seamlessly with Docker and Kubernetes. It manages the lifecycle of the sandbox, including creation, execution, and state management.

Sentry Kernel

The Sentry is the heart of gVisor. It is a multi-threaded userspace kernel that emulates Linux. It contains:

  • Task Management: Emulates Linux processes and threads using Go goroutines.
  • VFS: A virtual filesystem layer that provides a unified interface for various filesystems like tmpfs, procfs, and the remote gofer.
  • Memory Management: Manages application address spaces and page allocation.

Gofer (File Proxy)

To maintain isolation, the Sentry does not have direct access to host files. Instead, it communicates with a separate Gofer process via a secure protocol (9P or Lisafs). The Gofer process runs in a restricted seccomp sandbox and mediates all filesystem operations.

Integrations and APIs

containerd Shim

For Kubernetes and containerd environments, gVisor provides a shim binary (containerd-shim-runsc-v1). This shim translates containerd's TTRPC requests into runsc commands, managing the sandbox lifecycle within a pod.

Kubernetes Mutating Admission Webhook

gVisor includes a webhook component that can automatically inject the necessary runtimeClassName into Kubernetes Pod specifications. This allows administrators to transparently sandbox specific workloads based on labels or namespaces.

sandboxexec Go API

For developers who want to use gVisor as a library rather than a standalone runtime, the sandboxexec API provides a way to launch sandboxed processes directly from Go code, bypassing the OCI requirement for specific use cases.

Architecture Mapping

"manages"

"starts"

"initializes"

"invokes"

«runsc/cli/maincli»

RuntimeCLI

+Main()

«runsc/sandbox/sandbox.go»

Sandbox

+ID string

+Pid int

+CreateSubcontainer()

«runsc/boot/loader.go»

Loader

+k kernel.Kernel

+Run()

«pkg/sentry/kernel/kernel.go»

SentryKernel

+tasks TaskSet

+vfs vfs.VirtualFilesystem

«pkg/shim/v1/runsc/service.go»

ShimService

+Create()

+Start()

Sources: runsc/sandbox/sandbox.go runsc/boot/loader.go pkg/shim/v1/runsc/service.go runsc/container/container.go

Platform Abstraction Layer

gVisor supports multiple "platforms" to intercept syscalls from the application and context switch into the Sentry:

  1. ptrace: Uses the standard Linux ptrace mechanism to trap syscalls.
  2. KVM: Uses /dev/kvm to run the application in a guest virtual machine mode while the Sentry acts as the guest kernel.
  3. systrap: A high-performance platform that uses a stub process and shared memory to handle transitions.

Sources: runsc/boot/loader.go g3doc/user_guide/platforms.md

Build and Installation

gVisor is built using Bazel. It can be installed as a Docker runtime using runsc install. A synthetic "Go branch" is also maintained for users who prefer standard go get workflows.

Sources: README.md tools/go_branch.sh images/default/Dockerfile