Skip to main content

Configuration

Learn how to configure gVisor for optimal performance, security, and compatibility in your environment.

Configuration Overview​

gVisor can be configured through:

  • Command-line flags
  • Configuration files (TOML format)
  • Runtime options in container engines
  • Environment variables

Configuration File Format​

gVisor uses TOML configuration files. Create a configuration file:

# Create configuration directory
sudo mkdir -p /etc/gvisor

# Create main configuration file
sudo tee /etc/gvisor/runsc.toml <<EOF
# gVisor Configuration File

[runsc]
# Platform to use (auto, ptrace, kvm, systrap)
platform = "auto"

# Enable debug logging
debug = false
debug-log = "/var/log/gvisor/debug.log"

# Network configuration
network = "host"

# File access method
file-access = "shared"

# Enable profiling
enable-profiling = false

# Overlay configuration
overlay = true
overlay2 = "root=/var/lib/gvisor/overlay"
EOF

Platform Configuration​

Automatic Platform Selection​

[runsc]
platform = "auto"

gVisor will automatically select the best available platform:

  1. KVM (if available and enabled)
  2. systrap (newer, optimized platform)
  3. ptrace (fallback)

Specific Platform Selection​

KVM Platform (Best Performance)​

[runsc]
platform = "kvm"

Requirements:

  • KVM kernel module loaded
  • /dev/kvm accessible
  • Hardware virtualization support

ptrace Platform (Broad Compatibility)​

[runsc]
platform = "ptrace"

Works on most Linux systems but has higher overhead.

systrap Platform (Modern Alternative)​

[runsc]
platform = "systrap"

Newer platform with better performance than ptrace.

Network Configuration​

Network Modes​

Host Network​

[runsc]
network = "host"

Container uses the host network stack directly.

Sandbox Network (Default)​

[runsc]
network = "sandbox"

gVisor implements its own network stack.

Network Performance Tuning​

[runsc]
# Enable GSO (Generic Segmentation Offload)
gso = true

# Enable software GSO
software-gso = true

# TX checksum offload
tx-checksum-offload = true

# RX checksum offload  
rx-checksum-offload = true

File System Configuration​

File Access Methods​

Shared Access (Default)​

[runsc]
file-access = "shared"

Host and sandbox share file descriptors. Best performance for most workloads.

Exclusive Access​

[runsc]
file-access = "exclusive"

Sandbox gets exclusive access to files. Better isolation but slower.

Overlay File System​

[runsc]
# Enable overlay filesystem
overlay = true

# Overlay2 configuration
overlay2 = "root=/var/lib/gvisor/overlay"

Volume Configuration​

[runsc]
# Root filesystem type
rootfs = "ext4"

# Disable mount syscalls (increased security)
disable-mount = false

# VFS2 (Virtual File System 2)
vfs2 = true

Resource Management​

Memory Configuration​

[runsc]
# Total memory limit for the sandbox
total-memory = "2GB"

# Memory file backing
memory-file = "/tmp/gvisor-memory"

# Huge pages support
huge-pages = false

CPU Configuration​

[runsc]
# Number of CPUs available to sandbox
num-cpus = 4

# CPU topology
cpu-topology = "2:2"  # 2 sockets, 2 cores each

Security Configuration​

Capability Configuration​

[runsc]
# Drop all capabilities by default
drop-caps = true

# Allow specific capabilities
add-caps = ["NET_ADMIN", "SYS_ADMIN"]

Namespace Configuration​

[runsc]
# Use host PID namespace
host-pid = false

# Use host network namespace  
host-network = false

# Use host IPC namespace
host-ipc = false

Seccomp Configuration​

[runsc]
# Enable seccomp-bpf
seccomp = true

# Custom seccomp profile
seccomp-profile = "/etc/gvisor/seccomp.json"

Debugging and Monitoring​

Debug Configuration​

[runsc]
# Enable debug mode
debug = true

# Debug log file
debug-log = "/var/log/gvisor/debug.log"

# Log level (debug, info, warning, error)
log-level = "info"

# Enable strace logging
strace = false

# Log packets (network debugging)
log-packets = false

Profiling Configuration​

[runsc]
# Enable CPU profiling
enable-profiling = true

# Profile CPU usage
profile-cpu = "/tmp/gvisor-cpu.prof"

# Profile memory usage
profile-heap = "/tmp/gvisor-heap.prof"

# Profile goroutines
profile-goroutine = "/tmp/gvisor-goroutine.prof"

Runtime-Specific Configuration​

Docker Configuration​

Configure gVisor runtime in Docker daemon:

{
  "runtimes": {
    "runsc": {
      "path": "/usr/local/bin/runsc",
      "runtimeArgs": [
        "--config=/etc/gvisor/runsc.toml",
        "--debug=true"
      ]
    },
    "runsc-kvm": {
      "path": "/usr/local/bin/runsc",
      "runtimeArgs": [
        "--platform=kvm",
        "--config=/etc/gvisor/runsc.toml"
      ]
    }
  }
}

containerd Configuration​

Configure in /etc/containerd/config.toml:

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
  runtime_type = "io.containerd.runsc.v1"
  
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc.options]
  TypeUrl = "io.containerd.runsc.v1.options"
  ConfigPath = "/etc/gvisor/runsc.toml"

Kubernetes Configuration​

RuntimeClass with custom configuration:

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor-custom
handler: runsc
overhead:
  podFixed:
    memory: "256Mi"
    cpu: "250m"
scheduling:
  nodeClassMap:
    gvisor: "gvisor-nodes"

Performance Optimization​

High-Performance Configuration​

[runsc]
# Use KVM platform
platform = "kvm"

# Optimize network
gso = true
software-gso = true
tx-checksum-offload = true
rx-checksum-offload = true

# Use shared file access
file-access = "shared"

# Enable VFS2
vfs2 = true

# Disable debug logging
debug = false

# Optimize memory
huge-pages = true
total-memory = "4GB"

Memory-Optimized Configuration​

[runsc]
# Use ptrace to reduce memory overhead
platform = "ptrace"

# Limit memory usage
total-memory = "1GB"

# Use memory file
memory-file = "/tmp/gvisor-memory"

# Enable overlay
overlay = true

Security-Focused Configuration​

[runsc]
# Use ptrace for maximum isolation
platform = "ptrace"

# Exclusive file access
file-access = "exclusive"

# Drop capabilities
drop-caps = true

# Enable seccomp
seccomp = true

# Disable host access
host-pid = false
host-network = false
host-ipc = false

# Disable mount
disable-mount = true

Environment-Specific Configurations​

Development Environment​

[runsc]
# Use auto platform selection
platform = "auto"

# Enable debugging
debug = true
debug-log = "/tmp/gvisor-dev.log"
strace = true

# Allow profiling
enable-profiling = true

# Shared file access for better performance
file-access = "shared"

Production Environment​

[runsc]
# Use KVM for best performance
platform = "kvm"

# Production logging
debug = false
log-level = "warning"

# Optimized settings
gso = true
vfs2 = true
file-access = "shared"

# Resource limits
total-memory = "8GB"
num-cpus = 8

CI/CD Environment​

[runsc]
# Use ptrace for compatibility
platform = "ptrace"

# Fast startup
file-access = "shared"
overlay = true

# Limited resources
total-memory = "2GB"
num-cpus = 2

# Minimal logging
debug = false
log-level = "error"

Configuration Validation​

Validate Configuration​

# Test configuration file
runsc --config=/etc/gvisor/runsc.toml spec

# Validate with a simple container
docker run --rm --runtime=runsc \
  --runtime-opt config=/etc/gvisor/runsc.toml \
  alpine:latest echo "Configuration test"

Monitor Configuration Impact​

# Monitor performance with different configs
time docker run --rm --runtime=runsc \
  --runtime-opt config=/etc/gvisor/performance.toml \
  alpine:latest echo "Performance test"

# Monitor memory usage
docker stats $(docker run -d --runtime=runsc \
  --runtime-opt config=/etc/gvisor/runsc.toml \
  nginx)

Troubleshooting Configuration Issues​

Common Configuration Problems​

Platform Issues

# Check platform availability
ls -la /dev/kvm
dmesg | grep kvm

# Test platform selection
runsc --platform=kvm do echo "KVM test"
runsc --platform=ptrace do echo "ptrace test"

File Access Issues

# Test file access methods
docker run --rm -v /tmp:/test \
  --runtime=runsc \
  --runtime-opt file-access=shared \
  alpine:latest ls /test

docker run --rm -v /tmp:/test \
  --runtime=runsc \
  --runtime-opt file-access=exclusive \
  alpine:latest ls /test

Network Issues

# Test network configurations
docker run --rm --runtime=runsc \
  --runtime-opt network=host \
  alpine:latest ip addr

docker run --rm --runtime=runsc \
  --runtime-opt network=sandbox \
  alpine:latest ip addr

Configuration Debugging​

Enable detailed logging for troubleshooting:

[runsc]
debug = true
debug-log = "/var/log/gvisor/debug.log"
strace = true
log-level = "debug"
log-packets = true

Check logs:

# View debug logs
tail -f /var/log/gvisor/debug.log

# Monitor system calls
docker run --rm --runtime=runsc \
  --runtime-opt config=/etc/gvisor/debug.toml \
  alpine:latest ls / 2>&1 | grep syscall

Next Steps​

With gVisor properly configured, explore: