Skip to main content

Installation and Setup

This guide will walk you through installing gVisor on various platforms and configuring it with different container runtimes.

Prerequisites​

Before installing gVisor, ensure you have:

  • A supported Linux distribution
  • Container runtime (Docker, containerd, or CRI-O)
  • Administrative (root) privileges
  • At least 1GB of free disk space

Supported Platforms​

gVisor supports multiple platforms:

  • ptrace: Works on most Linux distributions
  • KVM: Requires KVM support (better performance)
  • systrap: Newer platform with improved performance

Installation Methods​

The easiest way to install gVisor is using the official installation script:

# Download and install gVisor
curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | sudo tee /etc/apt/sources.list.d/gvisor.list > /dev/null

# Update package list and install
sudo apt-get update
sudo apt-get install -y runsc

Method 2: Manual Installation​

Download the latest release directly from GitHub:

# Set the version (check https://github.com/google/gvisor/releases for latest)
GVISOR_VERSION="20231113.0"
ARCH="x86_64"

# Download runsc binary
wget https://storage.googleapis.com/gvisor/releases/release/20231113.0/${ARCH}/runsc
wget https://storage.googleapis.com/gvisor/releases/release/20231113.0/${ARCH}/runsc.sha512

# Verify the download
sha512sum -c runsc.sha512

# Install runsc
chmod +x runsc
sudo mv runsc /usr/local/bin/

Method 3: Build from Source​

For the latest features or custom builds:

# Install dependencies
sudo apt-get install -y git build-essential

# Clone the repository
git clone https://github.com/google/gvisor.git
cd gvisor

# Build runsc
make runsc

# Install the binary
sudo cp ./bazel-bin/runsc/linux_amd64_pure_stripped/runsc /usr/local/bin/

Platform Configuration​

If your system supports KVM, configure it for better performance:

# Check KVM support
ls /dev/kvm

# If KVM is available, ensure proper permissions
sudo chmod 666 /dev/kvm

# Or add your user to the kvm group
sudo usermod -a -G kvm $USER

Configure ptrace Platform (Fallback)​

If KVM is not available, gVisor will use ptrace:

# Verify ptrace is available (should return 0)
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Container Runtime Integration​

Docker Integration​

Configure Docker to use gVisor:

# Create daemon configuration
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
    "runtimes": {
        "runsc": {
            "path": "/usr/local/bin/runsc"
        }
    }
}
EOF

# Restart Docker
sudo systemctl restart docker

# Verify the runtime is available
docker info | grep -i runtime

containerd Integration​

Configure containerd to use gVisor:

# Edit containerd configuration
sudo mkdir -p /etc/containerd

# Generate default config
sudo containerd config default | sudo tee /etc/containerd/config.toml

# Add gVisor runtime configuration
sudo tee -a /etc/containerd/config.toml <<EOF

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
  runtime_type = "io.containerd.runsc.v1"
EOF

# Restart containerd
sudo systemctl restart containerd

Kubernetes Integration​

For Kubernetes with containerd:

# Create RuntimeClass
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor
handler: runsc

Apply the RuntimeClass:

kubectl apply -f gvisor-runtimeclass.yaml

Verification​

Test Basic Installation​

Verify gVisor is installed correctly:

# Check version
runsc --version

# Run a simple test
runsc do echo "Hello, gVisor!"

Test with Docker​

Run a container with gVisor:

# Run a simple container
docker run --rm --runtime=runsc hello-world

# Run an interactive container
docker run --rm -it --runtime=runsc ubuntu:20.04 /bin/bash

Test System Call Handling​

Verify gVisor is intercepting system calls:

# Run with debug logging to see system call interception
docker run --rm --runtime=runsc \
  --runtime-opt runsc-config-path=/tmp/runsc.toml \
  alpine:latest echo "Testing gVisor"

Platform Selection​

You can specify which platform to use:

# Use KVM platform (better performance)
docker run --rm --runtime=runsc \
  --runtime-opt platform=kvm \
  alpine:latest echo "Using KVM platform"

# Use ptrace platform (broader compatibility)
docker run --rm --runtime=runsc \
  --runtime-opt platform=ptrace \
  alpine:latest echo "Using ptrace platform"

Troubleshooting​

Common Issues​

Permission Denied for /dev/kvm

sudo chmod 666 /dev/kvm
# or
sudo usermod -a -G kvm $USER
newgrp kvm

Docker Runtime Not Found

# Restart Docker daemon
sudo systemctl restart docker

# Check Docker daemon logs
sudo journalctl -u docker.service

containerd Runtime Issues

# Check containerd logs
sudo journalctl -u containerd.service

# Restart containerd
sudo systemctl restart containerd

Enable Debug Logging​

For troubleshooting, enable debug logging:

# Create debug configuration
mkdir -p /tmp
cat > /tmp/runsc.toml <<EOF
[runsc]
debug = true
debug-log = "/tmp/runsc.log"
strace = true
EOF

# Run with debug config
docker run --rm --runtime=runsc \
  --runtime-opt runsc-config-path=/tmp/runsc.toml \
  alpine:latest echo "Debug test"

# Check logs
cat /tmp/runsc.log

Next Steps​

Now that you have gVisor installed, proceed to: