gVisor

https://gvisor.dev/docs
Admin
gVisor is an application kernel that provides strong isolation between running applications and the...
Tokens:90,790
Snippets:722
Trust Score:9.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### End-to-end example in Go with socketpair

Source: https://gvisor.dev/docs/user_guide/fuse

Complete Go example for the host side: creates a socketpair, starts a FUSE server on the host, and launches the sandbox with the FD passed in. The example uses unix.Socketpair with SOCK_SEQPACKET and passes the sandbox end via cmd.ExtraFiles.

```go
// Create a socketpair for FUSE communication.
fds, _ := unix.Socketpair(unix.AF_UNIX, unix.SOCK_SEQPACKET, 0)

// fds[0] goes into the sandbox, fds[1] goes to the FUSE server.
sandboxFile := os.NewFile(uintptr(fds[0]), "fuse-sandbox")
serverFD := fds[1]

// Start the FUSE server on the host with the server-side FD.
go myFuseServer.Serve(serverFD, "/data/backing")

// Launch the sandbox with the FD passed in.
cmd := exec.Command("runsc", "run",
    "--pass-fd=3:100",      // host FD 3 → guest FD 100
    "--bundle="+bundleDir,
    containerID,
)
cmd.ExtraFiles = []*os.File{sandboxFile}  // FD 3 in the child process
cmd.Run()

```

--------------------------------

### Run the example with python3 main.py

Source: https://gvisor.dev/docs/sdk/python/quickstart

Run the application after saving the example code as main.py.

```bash
python3 main.py

```

--------------------------------

### Start Falco with gVisor monitoring (Docker)

Source: https://gvisor.dev/docs/tutorials/falco

Starts Falco with gVisor monitoring enabled. Uses the configuration file generated earlier and the Docker gVisor root. If you get 'Error: Cannot find runsc binary', ensure runsc is in the PATH.

```bash
sudo falco \
  -c /etc/falco/falco.yaml \
  --gvisor-config /etc/falco/pod-init.json \
  --gvisor-root /var/run/docker/runtime-runc/moby

```

--------------------------------

### Expected output of running the example

Source: https://gvisor.dev/docs/sdk/python/quickstart

Shows the expected output after running the example, indicating the command ran successfully inside the gVisor sandbox.

```text
Stdout: Linux  5.15.0-gvisor

```

--------------------------------

### Install gVisor as Docker runtime

Source: https://gvisor.dev/docs/user_guide/install

Configures runsc as a Docker runtime and tests it with hello-world. Requires Docker and the runsc binary installed in /usr/local/bin.

```bash
sudo /usr/local/bin/runsc install
sudo systemctl reload docker
docker run --rm --runtime=runsc hello-world

```

--------------------------------

### Initialize Go module

Source: https://gvisor.dev/docs/sdk/go/quickstart

Initializes a Go module for the quickstart project.

```bash
go mod init gvisor-quickstart

```

--------------------------------

### Minimal Sandbox example using context manager

Source: https://gvisor.dev/docs/sdk/python/quickstart

Initializes a sandbox and executes 'uname -a' using the Sandbox context manager. Prints the stripped stdout. This is a minimalist runnable example.

```python
from gvisor import Sandbox

with Sandbox() as sb:
    stdout, stderr = sb.exec("uname", "-a")
    print(f"Stdout: {stdout.strip()}")

```

--------------------------------

### Start WordPress containers with docker-compose up

Source: https://gvisor.dev/docs/tutorials/docker-compose

Starts the WordPress and database containers defined in docker-compose.yaml. After startup, WordPress is accessible at http://localhost:8080.

```bash
docker-compose up

```

--------------------------------

### Start gVisor sandbox with all capabilities

Source: https://gvisor.dev/docs/tutorials/docker-in-gvisor

Starts a detached gVisor sandbox with the 'runsc' runtime, all capabilities, and the name 'docker-in-gvisor'. Note that '--cap-add all' does not grant any host capabilities; it only controls capabilities perceived by the in-sandbox application.

```bash
# NOTE: `--cap-add` does *NOT* grant any host capabilities. See below.
$ docker run --runtime runsc -d --rm --cap-add all --name docker-in-gvisor docker-in-gvisor

```

--------------------------------

### Start the nginx container with crictl start

Source: https://gvisor.dev/docs/user_guide/containerd/quick_start

Starts the nginx container using the container ID.

```bash
sudo crictl start ${CONTAINER_ID}

```

--------------------------------

### Start a gVisor container and create rootfs changes

Source: https://gvisor.dev/docs/user_guide/rootfs_snapshot

Starts an Alpine container with the runsc runtime, then creates a directory and a file to modify the rootfs. This is the prerequisite for taking a rootfs tar snapshot.

```bash
$ docker run --rm -it --runtime=runsc alpine
/ # mkdir dir
/ # echo "hello world" > dir/file

```

--------------------------------

### Expected Pod Output

Source: https://gvisor.dev/docs/tutorials/knative

Example output showing a Pod running with the gvisor runtime class.

```text
NAME                                              RUNTIME CLASS   STATUS
helloworld-go-00002-deployment-646c87b7f5-5v68s   gvisor          Running

```

--------------------------------

### Start runsc metric server

Source: https://gvisor.dev/docs/user_guide/observability

Starts the runsc metric server. Requires --root set to the OCI runtime root directory (for Docker, typically /var/run/docker/runtime-runc/moby) and --metric-server to specify the bind address or UDS path. Use sudo because the root directory is usually only accessible by the user Docker runs as. Add --debug --debug-log=/dev/stderr to troubleshoot.

```bash
$ sudo runsc \
    --root=/var/run/docker/runtime-runc/moby \
    --metric-server=localhost:1337 \
    metric-server

```

--------------------------------

### Start container and query metrics

Source: https://gvisor.dev/docs/user_guide/observability

Start a container with metrics enabled and query the metric server. The output shows the container ID (32beefcafe) and sample Prometheus metrics, each labeled with sandbox (container ID) and iteration (random string constant for the sandbox lifetime).

```bash
$ docker run -d --runtime=runsc --name=foobar debian sleep 1h
32beefcafe

$ curl http://localhost:1337/metrics
＃ Data for runsc metric server exporting data for sandboxes in root directory /var/run/docker/runtime-runc/moby
＃ Writing data from 3 snapshots: [...]


＃ HELP process_start_time_seconds Unix timestamp at which the process started. Used by Prometheus for counter resets.
＃ TYPE process_start_time_seconds gauge
process_start_time_seconds 1674599158.286067 1674599159819

＃ HELP runsc_fs_opens Number of file opens.
＃ TYPE runsc_fs_opens counter
runsc_fs_opens{iteration="42asdf",sandbox="32beefcafe"} 12 1674599159819

＃ HELP runsc_fs_read_wait Time waiting on file reads, in nanoseconds.
＃ TYPE runsc_fs_read_wait counter
runsc_fs_read_wait{iteration="42asdf",sandbox="32beefcafe"} 0 1674599159819

＃ [...]

＃ End of metric data.

```

--------------------------------

### Install CNI plugins

Source: https://gvisor.dev/docs/user_guide/containerd/quick_start

Clones the containerd repository and runs the install-cni script to install CNI plugins with default settings. Replace {CONTAINERD_VERSION} with the desired containerd version.

```bash
git clone --depth=1 -b {CONTAINERD_VERSION} https://github.com/containerd/containerd.git
cd containerd && ./script/setup/install-cni
```

--------------------------------

### New

Source: https://gvisor.dev/docs/sdk/go

Spawns a new sandbox as a subprocess. The sandbox will be started and running in detached mode.

```APIDOC
## New

### Description
Spawns a new sandbox as a subprocess. The sandbox will be started and running in detached mode.

### Function Signature
`func New(ctx context.Context, opts ...Option) (*Sandbox, error)`

### Parameters
- **ctx** (context.Context) - Required - Context for the execution.
- **opts** (variadic Option) - Optional - Variadic list of options to configure the sandbox.

### Returns
- **\*Sandbox** - A pointer to the created `Sandbox` object.
- **error** - An error if the sandbox creation fails.
```

--------------------------------

### Enable TBF via Docker runtimeArgs

Source: https://gvisor.dev/docs/user_guide/networking

Enable TBF globally in Docker's daemon.json. Requires restarting the Docker daemon. The example sets a 100 Mbps rate (12,500,000 bytes/sec) with a 1 MiB burst. Both --qdisc-tbf-rate and --qdisc-tbf-burst are required when --qdisc=tbf; the sandbox refuses to start otherwise.

```json
{
    "runtimes": {
        "runsc": {
            "path": "/usr/local/bin/runsc",
            "runtimeArgs": [
                "--network=sandbox",
                "--qdisc=tbf",
                "--qdisc-tbf-rate=12500000",
                "--qdisc-tbf-burst=1048576"
            ]
       }
    }
}

```

--------------------------------

### Install runsc package via apt

Source: https://gvisor.dev/docs/user_guide/install

Installs the runsc package. If Docker is installed, it will be automatically configured.

```bash
sudo apt-get update && sudo apt-get install -y runsc

```

--------------------------------

### Run container with multiple Docker options

Source: https://gvisor.dev/docs/user_guide/quick_start/docker

Example showing many Docker options compatible with gVisor, including --link, -v, -p, --cpus, and -it.

```bash
docker run --runtime=runsc --rm --link backend:database -v ~/bin:/tools:ro -p 8080:80 --cpus=0.5 -it busybox telnet towel.blinkenlights.nl

```

--------------------------------

### Install gvisor package with pip

Source: https://gvisor.dev/docs/sdk/python/quickstart

Install the gvisor package using pip. Requires Python 3.9 or higher and runsc installed and available in PATH.

```bash
pip install gvisor

```

--------------------------------

### Sandbox.__init__

Source: https://gvisor.dev/docs/sdk/python

Initializes and starts a new sandbox with configurable runtime directory, sandbox ID, network mode, environment variables, mounts, and working directory.

```APIDOC
## Sandbox.__init__

### Description
Initializes and starts a new sandbox.

### Method
`def __init__(self, runtime_dir: Optional[str] = None, sandbox_id: Optional[str] = None, network: Union[NetworkMode, str] = NetworkMode.NONE, env: Optional[Union[List[str], Dict[str, str]]] = None, mounts: Optional[Sequence[Union[Mount, Dict[str, Any]]]] = None, working_dir: str = "/")`

### Parameters
- **runtime_dir** (Optional[str]) - Optional - Custom runtime directory where bundle and state files are written. If not set, a temporary directory is created.
- **sandbox_id** (Optional[str]) - Optional - Specific sandbox ID. If not set, a unique ID is generated automatically.
- **network** (Union[NetworkMode, str]) - Optional - The networking mode for runsc ('none', 'sandbox', 'host', or NetworkMode enum). Defaults to NetworkMode.NONE ('none').
- **env** (Optional[Union[List[str], Dict[str, str]]]) - Optional - Optional environment variables for the sandbox container.
- **mounts** (Optional[Sequence[Union[Mount, Dict[str, Any]]]]) - Optional - Optional sequence of Mount objects or dicts defining mounts.
- **working_dir** (str) - Optional - The initial working directory inside the sandbox. Relative paths are normalized relative to container root ('/'). Defaults to "/".

### Raises
- **Error**: If sandbox creation fails.
- **ValueError**: If an invalid network mode, working_dir, mount, or environment variable format is provided.
- **TypeError**: If env, mounts, or network has an invalid type.
```

--------------------------------

### Download WordPress and MySQL deployment YAML files

Source: https://gvisor.dev/docs/tutorials/kubernetes

Downloads the deployment configuration files for WordPress and MySQL from the Kubernetes examples repository.

```bash
curl -LO https://k8s.io/examples/application/wordpress/wordpress-deployment.yaml
curl -LO https://k8s.io/examples/application/wordpress/mysql-deployment.yaml

```

--------------------------------

### Build and install NVIDIA kernel modules

Source: https://gvisor.dev/docs/user_guide/gpu

Commands to uninstall the existing NVIDIA driver, build kernel modules from local source, and install them. Also installs user-space components using the .run file.

```bash
sudo /usr/bin/nvidia-uninstall
make modules -j$(nproc)
sudo make modules_install -j$(nproc)
sudo insmod kernel-open/nvidia.ko
sudo insmod kernel-open/nvidia-uvm.ko
sudo insmod kernel-open/nvidia-drm.ko
sudo insmod kernel-open/nvidia-modeset.ko

# Install the user-space NVIDIA GPU driver components using the .run file.
sudo sh NVIDIA-Linux-x86_64-$DRIVER_VERSION.run --no-kernel-modules

```

--------------------------------

### Sandbox.__init__ signature

Source: https://gvisor.dev/docs/sdk/python

Initializes and starts a new sandbox. Parameters include runtime_dir, sandbox_id, network, env, mounts, and working_dir. Raises Error, ValueError, or TypeError on invalid input.

```python
def __init__(self, runtime_dir: Optional[str] = None, sandbox_id: Optional[str] = None, network: Union[NetworkMode, str] = NetworkMode.NONE, env: Optional[Union[List[str], Dict[str, str]]] = None, mounts: Optional[Sequence[Union[Mount, Dict[str, Any]]]] = None, working_dir: str = "/")

```

--------------------------------

### Verify the Pod is running with kubectl get pod

Source: https://gvisor.dev/docs/user_guide/containerd/quick_start

Gets the pod details to confirm it is running.

```bash
kubectl get pod nginx-gvisor -o wide

```

--------------------------------

### Download and install crictl binary

Source: https://gvisor.dev/docs/user_guide/containerd/quick_start

Downloads the crictl v1.13.0 binary from the cri-tools release and installs it to /usr/local/bin.

```bash
{
wget https://github.com/kubernetes-sigs/cri-tools/releases/download/v1.13.0/crictl-v1.13.0-linux-amd64.tar.gz
tar xf crictl-v1.13.0-linux-amd64.tar.gz
sudo mv crictl /usr/local/bin
}

```

--------------------------------

### Signal test to start after attaching debugger

Source: https://gvisor.dev/docs/user_guide/debugging

Send SIGUSR1 to the test runner to start the test after the debugger is attached and breakpoints are set.

```bash
kill -SIGUSR1 $(ps aux | grep -m 1 -e 'bash.*test/syscalls' | awk '{print $2}')
```

--------------------------------

### Create OCI bundle and root filesystem

Source: https://gvisor.dev/docs/tutorials/cni

Creates the bundle directory, extracts a Python container rootfs, and adds an index.html file.

```bash
sudo mkdir -p bundle
cd bundle
sudo mkdir rootfs
sudo docker export $(docker create python) | sudo tar --same-owner -pxf - -C rootfs
sudo mkdir -p rootfs/var/www/html
sudo sh -c 'echo "Hello World!" > rootfs/var/www/html/index.html'

```

--------------------------------

### Start WordPress frontend container with gVisor

Source: https://gvisor.dev/docs/tutorials/docker

Runs the WordPress container with the runsc runtime, linking it to the MySQL container and exposing port 8080. Uses the environment variables defined earlier.

```bash
$ docker run --runtime=runsc --name wordpress -d \
    --link mysql:mysql \
    -p 8080:80 \
    -e WORDPRESS_DB_HOST=mysql \
    -e WORDPRESS_DB_USER="${MYSQL_USER}" \
    -e WORDPRESS_DB_PASSWORD="${MYSQL_PASSWORD}" \
    -e WORDPRESS_DB_NAME="${MYSQL_DB}" \
    -e WORDPRESS_TABLE_PREFIX=wp_ \
    wordpress

```

--------------------------------

### Install apt dependencies for HTTPS

Source: https://gvisor.dev/docs/user_guide/install

Installs required packages (apt-transport-https, ca-certificates, curl, gnupg) to allow apt to use HTTPS repositories.

```bash
sudo apt-get update && \
sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg

```

--------------------------------

### Mount.bind

Source: https://gvisor.dev/docs/sdk/python

Creates a host bind mount.

```APIDOC
## Mount.bind

### Description
Creates a host bind mount.

### Method
`@classmethod
def bind(cls, source: str, destination: str, readonly: bool = False) -> Mount`

### Parameters
- **source** (str) - Required - Source path on the host.
- **destination** (str) - Required - Destination path inside the sandbox.
- **readonly** (bool) - Optional - Whether the mount is read-only. Defaults to False.

### Returns
- **Mount**: A Mount object representing the bind mount.
```

--------------------------------

### Install runsc-debug runtime with options

Source: https://gvisor.dev/docs/user_guide/quick_start/docker

Installs a runtime named 'runsc-debug' with debugging flags. Ensure SELinux is disabled before running with debugging enabled.

```bash
sudo runsc install --runtime runsc-debug -- \
  --debug \
  --debug-log=/tmp/runsc-debug.log \
  --strace \
  --log-packets

```

--------------------------------

### Create sandbox and execute uname -a

Source: https://gvisor.dev/docs/sdk/go/quickstart

Complete Go program that creates a sandbox with networking disabled, executes `uname -a`, and cleans up. Requires `runsc` in PATH and Go 1.16+. Note that `WithNetworking(true)` requires root; this example disables networking to run as non-root.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "gvisor.dev/gvisor/sandboxexec/sandbox"
)

func main() {
    ctx := context.Background()

    // Initialize a new sandbox.
    // Note: WithNetworking(true) requires running as root.
    // For this quickstart, we disable networking to allow running as non-root.
    sb, err := sandbox.New(ctx, sandbox.WithNetworking(false))
    if err != nil {
        log.Fatalf("Failed to create sandbox: %v", err)
    }
    defer func() {
        if err := sb.Close(ctx); err != nil {
            log.Fatalf("Failed to close sandbox: %v", err)
        }
    }()

    // Execute a command inside the sandbox.
    stdout, stderr, err := sb.Exec(ctx, "uname", "-a")
    if err != nil {
        log.Fatalf("Exec failed: %v, stderr: %s", err, stderr)
    }

    fmt.Printf("Stdout: %s", stdout)
}

```

--------------------------------

### Install runsc Docker runtime

Source: https://gvisor.dev/docs/user_guide/quick_start/docker

Run this command to install a Docker runtime named 'runsc' by default. Requires Docker 17.09.0 or greater.

```bash
sudo runsc install

```

--------------------------------

### Create root filesystem from Docker hello-world image

Source: https://gvisor.dev/docs/user_guide/quick_start/oci

Creates a rootfs directory with mode 0755 and exports the Docker hello-world image into it, preserving ownership and permissions.

```bash
mkdir --mode=0755 rootfs
docker export $(docker create hello-world) | sudo tar -xf - -C rootfs --same-owner --same-permissions

```

--------------------------------

### Start a container to debug with runsc

Source: https://gvisor.dev/docs/user_guide/debugging

Start a container using the runsc runtime with debug options. The runtime name is derived from the current git branch.

```bash
docker run --runtime=$(git branch --show-current)-d --rm --name=test -p 8080:80 -d nginx
```

--------------------------------

### Apply TBF annotations to Kubernetes pod

Source: https://gvisor.dev/docs/user_guide/networking

Example of applying TBF annotations to a Kubernetes pod. The same annotation constraints apply as in the OCI runtime annotation example.

```yaml
metadata:
  annotations:
    dev.gvisor.flag.qdisc: "tbf"
    dev.gvisor.flag.qdisc-tbf-rate: "12500000"
    dev.gvisor.flag.qdisc-tbf-burst: "1048576"

```

--------------------------------

### List supported NVIDIA drivers via make

Source: https://gvisor.dev/docs/user_guide/gpu

Alternatively, you can view the source code or download it and run this make command to list supported drivers.

```bash
$ make run TARGETS=runsc:runsc ARGS="nvproxy list-supported-drivers"

```
Tokens:
Raw