mirror of
https://github.com/netbirdio/gvisor.git
synced 2026-05-22 17:12:49 -07:00
Update README.md to point to gvisor.dev
PiperOrigin-RevId: 242690968 Change-Id: I1ac2248b5ab3bcd95beed52ecddbb9f34eeb3775
This commit is contained in:
Adin Scannell
Shentubot
@@ -1,4 +1,6 @@
|
||||
Before filling an issue, please consult our FAQ: https://github.com/google/gvisor#faq--known-issues
|
||||
Before filling an issue, please consult our FAQ:
|
||||
https://gvisor.dev/docs/user_guide/faq/
|
||||
|
||||
Also check that the issue hasn't been reported before.
|
||||
|
||||
If you have a question, please email gvisor-users@googlegroups.com rather than filing a bug.
|
||||
@@ -7,11 +9,12 @@ If you believe you've found a security issue, please email gvisor-security@googl
|
||||
|
||||
If this is your first time compiling or running gVisor, please make sure that your system meets the minimum requirements: https://github.com/google/gvisor#requirements
|
||||
|
||||
For all other issues, please attach debug logs. To get debug logs, follow the instructions here: https://github.com/google/gvisor#debugging
|
||||
For all other issues, please attach debug logs. To get debug logs, follow the
|
||||
instructions here: https://gvisor.dev/docs/user_guide/debugging/
|
||||
|
||||
Other useful information to include is:
|
||||
- `docker version` or `docker info` if more relevant
|
||||
- `uname -a`
|
||||
- `git describe`
|
||||
- Full docker command you ran
|
||||
- Detailed repro steps
|
||||
|
||||
* `runsc -v`
|
||||
* `docker version` or `docker info` if more relevant
|
||||
* `uname -a` - `git describe`
|
||||
* Detailed reproduction steps
|
||||
|
||||
@@ -1,17 +1,15 @@
|
||||
# gVisor
|
||||
|
||||
|
||||
gVisor is a user-space kernel, written in Go, that implements a substantial
|
||||
## What is gVisor?
|
||||
|
||||
**gVisor** is a user-space kernel, written in Go, that implements a substantial
|
||||
portion of the Linux system surface. It includes an
|
||||
[Open Container Initiative (OCI)][oci] runtime called `runsc` that provides an
|
||||
isolation boundary between the application and the host kernel. The `runsc`
|
||||
runtime integrates with Docker and Kubernetes, making it simple to run sandboxed
|
||||
containers.
|
||||
|
||||
gVisor takes a distinct approach to container sandboxing and makes a different
|
||||
set of technical trade-offs compared to existing sandbox technologies, thus
|
||||
providing new tools and ideas for the container security landscape.
|
||||
|
||||
### Why does gVisor exist?
|
||||
## Why does gVisor exist?
|
||||
|
||||
Containers are not a [**sandbox**][sandbox]. While containers have
|
||||
revolutionized how we develop, package, and deploy applications, running
|
||||
@@ -31,223 +29,17 @@ against external threats, provide additional integrity checks, or limit the
|
||||
scope of access for a service. One should always be careful about what data is
|
||||
made available to a container.
|
||||
|
||||
### How is gVisor different from other container isolation mechanisms?
|
||||
## Documentation
|
||||
|
||||
Two other approaches are commonly taken to provide stronger isolation than
|
||||
native containers.
|
||||
User documentation and technical architecture, including quick start guides, can
|
||||
be found at [gvisor.dev][gvisor-dev].
|
||||
|
||||
**Machine-level virtualization**, such as [KVM][kvm] and [Xen][xen], exposes
|
||||
virtualized hardware to a guest kernel via a Virtual Machine Monitor (VMM). This
|
||||
virtualized hardware is generally enlightened (paravirtualized) and additional
|
||||
mechanisms can be used to improve the visibility between the guest and host
|
||||
(e.g. balloon drivers, paravirtualized spinlocks). Running containers in
|
||||
distinct virtual machines can provide great isolation, compatibility and
|
||||
performance (though nested virtualization may bring challenges in this area),
|
||||
but for containers it often requires additional proxies and agents, and may
|
||||
require a larger resource footprint and slower start-up times.
|
||||
## Installing from source
|
||||
|
||||
|
||||
gVisor currently requires x86\_64 Linux to build, though support for other
|
||||
architectures may become available in the future.
|
||||
|
||||
**Rule-based execution**, such as [seccomp][seccomp], [SELinux][selinux] and
|
||||
[AppArmor][apparmor], allows the specification of a fine-grained security policy
|
||||
for an application or container. These schemes typically rely on hooks
|
||||
implemented inside the host kernel to enforce the rules. If the surface can be
|
||||
made small enough (i.e. a sufficiently complete policy defined), then this is an
|
||||
excellent way to sandbox applications and maintain native performance. However,
|
||||
in practice it can be extremely difficult (if not impossible) to reliably define
|
||||
a policy for arbitrary, previously unknown applications, making this approach
|
||||
challenging to apply universally.
|
||||
|
||||
|
||||
|
||||
Rule-based execution is often combined with additional layers for
|
||||
defense-in-depth.
|
||||
|
||||
**gVisor** provides a third isolation mechanism, distinct from those mentioned
|
||||
above.
|
||||
|
||||
gVisor intercepts application system calls and acts as the guest kernel, without
|
||||
the need for translation through virtualized hardware. gVisor may be thought of
|
||||
as either a merged guest kernel and VMM, or as seccomp on steroids. This
|
||||
architecture allows it to provide a flexible resource footprint (i.e. one based
|
||||
on threads and memory mappings, not fixed guest physical resources) while also
|
||||
lowering the fixed costs of virtualization. However, this comes at the price of
|
||||
reduced application compatibility and higher per-system call overhead.
|
||||
|
||||
|
||||
|
||||
On top of this, gVisor employs rule-based execution to provide defense-in-depth
|
||||
(details below).
|
||||
|
||||
gVisor's approach is similar to [User Mode Linux (UML)][uml], although UML
|
||||
virtualizes hardware internally and thus provides a fixed resource footprint.
|
||||
|
||||
Each of the above approaches may excel in distinct scenarios. For example,
|
||||
machine-level virtualization will face challenges achieving high density, while
|
||||
gVisor may provide poor performance for system call heavy workloads.
|
||||
|
||||
### Why Go?
|
||||
|
||||
gVisor was written in Go in order to avoid security pitfalls that can plague
|
||||
kernels. With Go, there are strong types, built-in bounds checks, no
|
||||
uninitialized variables, no use-after-free, no stack overflow, and a built-in
|
||||
race detector. (The use of Go has its challenges too, and isn't free.)
|
||||
|
||||
## Architecture
|
||||
|
||||
gVisor intercepts all system calls made by the application, and does the
|
||||
necessary work to service them. Importantly, gVisor does not simply redirect
|
||||
application system calls through to the host kernel. Instead, gVisor implements
|
||||
most kernel primitives (signals, file systems, futexes, pipes, mm, etc.) and has
|
||||
complete system call handlers built on top of these primitives.
|
||||
|
||||
Since gVisor is itself a user-space application, it will make some host system
|
||||
calls to support its operation, but much like a VMM, it will not allow the
|
||||
application to directly control the system calls it makes.
|
||||
|
||||
### File System Access
|
||||
|
||||
In order to provide defense-in-depth and limit the host system surface, the
|
||||
gVisor container runtime is normally split into two separate processes. First,
|
||||
the *Sentry* process includes the kernel and is responsible for executing user
|
||||
code and handling system calls. Second, file system operations that extend
|
||||
beyond the sandbox (not internal proc or tmp files, pipes, etc.) are sent to a
|
||||
proxy, called a *Gofer*, via a 9P connection.
|
||||
|
||||
|
||||
|
||||
The Gofer acts as a file system proxy by opening host files on behalf of the
|
||||
application, and passing them to the Sentry process, which has no host file
|
||||
access itself. Furthermore, the Sentry runs in an empty user namespace, and the
|
||||
system calls made by gVisor to the host are restricted using seccomp filters in
|
||||
order to provide defense-in-depth.
|
||||
|
||||
### Network Access
|
||||
|
||||
The Sentry implements its own network stack (also written in Go) called
|
||||
[netstack][netstack]. All aspects of the network stack are handled inside the
|
||||
Sentry — including TCP connection state, control messages, and packet assembly —
|
||||
keeping it isolated from the host network stack. Data link layer packets are
|
||||
written directly to the virtual device inside the network namespace setup by
|
||||
Docker or Kubernetes.
|
||||
|
||||
A network passthrough mode is also supported, but comes at the cost of reduced
|
||||
isolation (see below).
|
||||
|
||||
### Platforms
|
||||
|
||||
The Sentry requires a *platform* to implement basic context switching and memory
|
||||
mapping functionality. Today, gVisor supports two platforms:
|
||||
|
||||
* The **Ptrace** platform uses SYSEMU functionality to execute user code
|
||||
without executing host system calls. This platform can run anywhere that
|
||||
`ptrace` works (even VMs without nested virtualization).
|
||||
|
||||
* The **KVM** platform (experimental) allows the Sentry to act as both guest
|
||||
OS and VMM, switching back and forth between the two worlds seamlessly. The
|
||||
KVM platform can run on bare-metal or on a VM with nested virtualization
|
||||
enabled. While there is no virtualized hardware layer -- the sandbox retains
|
||||
a process model -- gVisor leverages virtualization extensions available on
|
||||
modern processors in order to improve isolation and performance of address
|
||||
space switches.
|
||||
|
||||
### Performance
|
||||
|
||||
There are several factors influencing performance. The platform choice has the
|
||||
largest direct impact that varies depending on the specific workload. There is
|
||||
no best platform: Ptrace works universally, including on VM instances, but
|
||||
applications may perform at a fraction of their original levels. Beyond the
|
||||
platform choice, passthrough modes may be useful for improving performance at
|
||||
the cost of some isolation.
|
||||
|
||||
## Installation
|
||||
|
||||
These instructions will get you up-and-running sandboxed containers with gVisor
|
||||
and Docker.
|
||||
|
||||
Note that gVisor can only run on x86\_64 Linux 3.17+. In addition, gVisor only
|
||||
supports x86\_64 binaries inside the sandbox (i.e., it cannot run 32-bit
|
||||
binaries).
|
||||
|
||||
### Download a Build
|
||||
|
||||
The easiest way to get `runsc` is from the
|
||||
[latest nightly build][runsc-nightly]. After you download the binary, check it
|
||||
against the SHA512 [checksum file][runsc-nightly-sha]. Older builds can be found
|
||||
here:
|
||||
`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc` and
|
||||
`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc.sha512`
|
||||
|
||||
**It is important to copy this binary to some place that is accessible to all
|
||||
users, and make is executable to all users**, since `runsc` executes itself as
|
||||
user `nobody` to avoid unnecessary privileges. The `/usr/local/bin` directory is
|
||||
a good place to put the `runsc` binary.
|
||||
|
||||
```
|
||||
wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
|
||||
wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
|
||||
sha512sum -c runsc.sha512
|
||||
chmod a+x runsc
|
||||
sudo mv runsc /usr/local/bin
|
||||
```
|
||||
|
||||
### Running with Docker
|
||||
|
||||
To use gVisor with Docker you must add `runsc` as a runtime to your Docker
|
||||
configuration (`/etc/docker/daemon.json`). You may have to create this file if
|
||||
it does not exist. Also, some Docker versions also require you to
|
||||
[specify the `storage-driver` field][docker-storage-driver].
|
||||
|
||||
In the end, the file should look something like:
|
||||
|
||||
```
|
||||
{
|
||||
"runtimes": {
|
||||
"runsc": {
|
||||
"path": "/usr/local/bin/runsc"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You must restart the Docker daemon after making changes to this file, typically
|
||||
this is done via:
|
||||
|
||||
```
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
Now run your container in `runsc`:
|
||||
|
||||
```
|
||||
docker run --runtime=runsc hello-world
|
||||
```
|
||||
|
||||
Terminal support works too:
|
||||
|
||||
```
|
||||
docker run --runtime=runsc -it ubuntu /bin/bash
|
||||
```
|
||||
|
||||
### Running with Kubernetes
|
||||
|
||||
gVisor can run sandboxed containers in a Kubernetes cluster with Minikube. After
|
||||
the gVisor addon is enabled, pods with `io.kubernetes.cri.untrusted-workload`
|
||||
set to true will execute with `runsc`. Follow [these instructions][minikube] to
|
||||
enable gVisor addon.
|
||||
|
||||
You can also setup Kubernetes nodes to run pods in gvisor using the `containerd`
|
||||
CRI runtime and the `gvisor-containerd-shim`. Pods with the
|
||||
`io.kubernetes.cri.untrusted-workload` annotation will execute with `runsc`. You
|
||||
can find instructions [here][gvisor-containerd-shim].
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Installing from Source
|
||||
|
||||
gVisor currently requires x86\_64 Linux to build.
|
||||
|
||||
#### Requirements
|
||||
### Requirements
|
||||
|
||||
Make sure the following dependencies are installed:
|
||||
|
||||
@@ -257,9 +49,9 @@ Make sure the following dependencies are installed:
|
||||
* [Docker version 17.09.0 or greater][docker]
|
||||
* Gold linker (e.g. `binutils-gold` package on Ubuntu)
|
||||
|
||||
#### Getting the source
|
||||
### Getting the source
|
||||
|
||||
Clone the gVisor repo:
|
||||
Clone the repository:
|
||||
|
||||
```
|
||||
git clone https://gvisor.googlesource.com/gvisor gvisor
|
||||
@@ -268,7 +60,7 @@ cd gvisor
|
||||
|
||||
### Building
|
||||
|
||||
Build and install the `runsc` binary.
|
||||
Build and install the `runsc` binary:
|
||||
|
||||
```
|
||||
bazel build runsc
|
||||
@@ -277,47 +69,16 @@ sudo cp ./bazel-bin/runsc/linux_amd64_pure_stripped/runsc /usr/local/bin
|
||||
|
||||
### Testing
|
||||
|
||||
The gVisor test suite can be run with Bazel:
|
||||
The test suite can be run with Bazel:
|
||||
|
||||
```
|
||||
bazel test ...
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
To enable debug and system call logging, add the `runtimeArgs` below to your
|
||||
Docker configuration (`/etc/docker/daemon.json`):
|
||||
|
||||
```
|
||||
{
|
||||
"runtimes": {
|
||||
"runsc": {
|
||||
"path": "/usr/local/bin/runsc",
|
||||
"runtimeArgs": [
|
||||
"--debug-log=/tmp/runsc/",
|
||||
"--debug",
|
||||
"--strace"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You may also want to pass `--log-packets` to troubleshoot network problems. Then
|
||||
restart the Docker daemon:
|
||||
|
||||
```
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
Run your container again, and inspect the files under `/tmp/runsc`. The log file
|
||||
with name `boot` will contain the strace logs from your application, which can
|
||||
be useful for identifying missing or broken system calls in gVisor.
|
||||
|
||||
### Building/testing with Remote Execution
|
||||
### Using remote execution
|
||||
|
||||
If you have a [Remote Build Execution][rbe] environment, you can use it to speed
|
||||
up gVisor build and test cycles.
|
||||
up build and test cycles.
|
||||
|
||||
You must authenticate with the project first:
|
||||
|
||||
@@ -336,152 +97,33 @@ Then invoke bazel with the following flags:
|
||||
You can also add those flags to your local ~/.bazelrc to avoid needing to
|
||||
specify them each time on the command line.
|
||||
|
||||
### Enabling network passthrough
|
||||
## Community & Governance
|
||||
|
||||
For high-performance networking applications, you may choose to disable the user
|
||||
space network stack and instead use the host network stack. Note that this mode
|
||||
decreases the isolation to the host.
|
||||
The governance model is documented in our [community][community] repository.
|
||||
|
||||
Add the following `runtimeArgs` to your Docker configuration
|
||||
(`/etc/docker/daemon.json`) and restart the Docker daemon:
|
||||
The [gvisor-users mailing list][gvisor-users-list] and
|
||||
[gvisor-dev mailing list][gvisor-dev-list] are good starting points for
|
||||
questions and discussion.
|
||||
|
||||
```
|
||||
{
|
||||
"runtimes": {
|
||||
"runsc": {
|
||||
"path": "/usr/local/bin/runsc",
|
||||
"runtimeArgs": [
|
||||
"--network=host"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
## Security
|
||||
|
||||
### Selecting a different platform
|
||||
|
||||
Depending on hardware and performance characteristics, you may choose to use a
|
||||
different platform. The Ptrace platform is the default, but the KVM platform may
|
||||
be specified by passing the `--platform` flag to `runsc` in your Docker
|
||||
configuration (`/etc/docker/daemon.json`):
|
||||
|
||||
```
|
||||
{
|
||||
"runtimes": {
|
||||
"runsc": {
|
||||
"path": "/usr/local/bin/runsc",
|
||||
"runtimeArgs": [
|
||||
"--platform=kvm"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then restart the Docker daemon.
|
||||
|
||||
### Checkpoint/Restore
|
||||
|
||||
gVisor has the ability to checkpoint a process, save its current state in a
|
||||
state file, and restore into a new container using the state file. For more
|
||||
information about the checkpoint and restore commands, see the
|
||||
[checkpoint/restore readme][checkpoint-restore].
|
||||
|
||||
## FAQ & Known Issues
|
||||
|
||||
### Will my container work with gVisor?
|
||||
|
||||
gVisor implements a large portion of the Linux surface and while we strive to
|
||||
make it broadly compatible, there are (and always will be) unimplemented
|
||||
features and bugs. The only real way to know if it will work is to try. If you
|
||||
find a container that doesn’t work and there is no known issue, please
|
||||
[file a bug][bug] indicating the full command you used to run the image.
|
||||
Providing the debug logs is also helpful.
|
||||
|
||||
### What works?
|
||||
|
||||
The following applications/images have been tested:
|
||||
|
||||
* elasticsearch
|
||||
* golang
|
||||
* httpd
|
||||
* java8
|
||||
* jenkins
|
||||
* mariadb
|
||||
* memcached
|
||||
* mongo
|
||||
* mysql
|
||||
* nginx
|
||||
* node
|
||||
* php
|
||||
* postgres
|
||||
* prometheus
|
||||
* python
|
||||
* redis
|
||||
* registry
|
||||
* tomcat
|
||||
* wordpress
|
||||
|
||||
### My container runs fine with *runc* but fails with *runsc*.
|
||||
|
||||
If you’re having problems running a container with `runsc` it’s most likely due
|
||||
to a compatibility issue or a missing feature in gVisor. See **Debugging**,
|
||||
above.
|
||||
|
||||
### When I run my container, docker fails with `flag provided but not defined: -console`
|
||||
|
||||
You're using an old version of Docker. Refer to the
|
||||
[Requirements](#requirements) section for the minimum version supported.
|
||||
|
||||
### I can’t see a file copied with `docker cp`.
|
||||
|
||||
For performance reasons, gVisor caches directory contents, and therefore it may
|
||||
not realize a new file was copied to a given directory. To invalidate the cache
|
||||
and force a refresh, create a file under the directory in question and list the
|
||||
contents again.
|
||||
|
||||
This bug is tracked in [bug #4](https://github.com/google/gvisor/issues/4).
|
||||
|
||||
Note that `kubectl cp` works because it does the copy by exec'ing inside the
|
||||
sandbox, and thus gVisor cache is aware of the new files and dirs.
|
||||
|
||||
## Technical details
|
||||
|
||||
We plan to release a full paper with technical details and will include it here
|
||||
when available.
|
||||
|
||||
## Community
|
||||
|
||||
Join the [gvisor-users mailing list][gvisor-users-list] to discuss all things
|
||||
gVisor.
|
||||
|
||||
Sensitive security-related questions and comments can be sent to the private
|
||||
[gvisor-security mailing list][gvisor-security-list].
|
||||
Sensitive security-related questions, comments and disclosures can be sent to
|
||||
the [gvisor-security mailing list][gvisor-security-list]. The full security
|
||||
disclosure policy is defined in the [community][community] repository.
|
||||
|
||||
## Contributing
|
||||
|
||||
See [Contributing.md](CONTRIBUTING.md).
|
||||
|
||||
[apparmor]: https://wiki.ubuntu.com/AppArmor
|
||||
[bazel]: https://bazel.build
|
||||
[bug]: https://github.com/google/gvisor/issues
|
||||
[checkpoint-restore]: https://gvisor.googlesource.com/gvisor/+/master/g3doc/checkpoint_restore.md
|
||||
[docker-storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver
|
||||
[community]: https://gvisor.googlesource.com/community
|
||||
[docker]: https://www.docker.com
|
||||
[git]: https://git-scm.com
|
||||
[gvisor-containerd-shim]: https://github.com/google/gvisor-containerd-shim
|
||||
[gvisor-security-list]: https://groups.google.com/forum/#!forum/gvisor-security
|
||||
[gvisor-users-list]: https://groups.google.com/forum/#!forum/gvisor-users
|
||||
[kvm]: https://www.linux-kvm.org
|
||||
[minikube]: https://github.com/kubernetes/minikube/blob/master/deploy/addons/gvisor/README.md
|
||||
[netstack]: https://github.com/google/netstack
|
||||
[gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev
|
||||
[oci]: https://www.opencontainers.org
|
||||
[python]: https://python.org
|
||||
[rbe]: https://blog.bazel.build/2018/10/05/remote-build-execution.html
|
||||
[runsc-nightly-sha]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
|
||||
[runsc-nightly]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
|
||||
[sandbox]: https://en.wikipedia.org/wiki/Sandbox_(computer_security)
|
||||
[seccomp]: https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt
|
||||
[selinux]: https://selinuxproject.org
|
||||
[uml]: http://user-mode-linux.sourceforge.net/
|
||||
[xen]: https://www.xenproject.org
|
||||
[gvisor-dev]: https://gvisor.dev
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
# gVisor Documentation
|
||||
|
||||
**This doc is a work in progress. For the definitive documentation please see
|
||||
the [README](../README.md)**
|
||||
|
||||
gVisor is a user-space kernel, written in Go, that implements a substantial
|
||||
portion of the [Linux system call interface][linux-interface]. It provides an
|
||||
additional layer of isolation between running applications and the host
|
||||
operating system.
|
||||
|
||||
gVisor includes an [Open Container Initiative (OCI)][oci] runtime called `runsc`
|
||||
that makes it easy to work with existing container tooling. The `runsc` runtime
|
||||
integrates with Docker and Kubernetes, making it simple to run sandboxed
|
||||
containers.
|
||||
|
||||
Check out the [gVisor Quick Start](user_guide/quick_start.md) to get started
|
||||
using gVisor.
|
||||
|
||||
gVisor takes a distinct approach to container sandboxing and makes a different
|
||||
set of technical trade-offs compared to existing sandbox technologies, thus
|
||||
providing new tools and ideas for the container security landscape.
|
||||
|
||||
Check out [Why gVisor?](architecture_guide/why.md) for more on why we made
|
||||
gVisor.
|
||||
|
||||
## How this documentation is organized
|
||||
|
||||
- The [Architecture Guide](architecture_guide/README.md) explains about
|
||||
gVisor's architecture & design philosophy. Start here if you would like to
|
||||
know more about how gVisor works and why it was created.
|
||||
- The [User Guide](user_guide/README.md) contains info on how to use gVisor
|
||||
and integrate it into your application or platform.
|
||||
- The [Contributer Guide](contributer_guide/README.md) includes documentation
|
||||
on how to build gVisor, run tests, and contribute to gVisor's development.
|
||||
|
||||
[linux-interface]: https://en.wikipedia.org/wiki/Linux_kernel_interfaces
|
||||
[oci]: https://www.opencontainers.org
|
||||
@@ -1 +0,0 @@
|
||||
# Architecture Guide
|
||||
@@ -1,9 +0,0 @@
|
||||
# Why gVisor?
|
||||
|
||||
gVisor makes a different set of technical trade-offs compared to existing
|
||||
sandbox technologies, thus providing new tools and ideas for the container
|
||||
security landscape.
|
||||
|
||||
As the developers of gVisor, we wanted an execution environment that was secure,
|
||||
simple, and lightweight and were able to make trade offs in other areas. We were
|
||||
not able to achieve that with existing solutions.
|
||||
@@ -1 +0,0 @@
|
||||
# Contributor Guide
|
||||
@@ -1 +0,0 @@
|
||||
# User Guide
|
||||
@@ -1,41 +0,0 @@
|
||||
# Run gVisor with Docker
|
||||
|
||||
## Configuring Docker
|
||||
|
||||
Next, configure Docker to use `runsc` by adding a runtime entry to your Docker
|
||||
configuration (`/etc/docker/daemon.json`). You may have to create this file if
|
||||
it does not exist. Also, some Docker versions also require you to [specify the
|
||||
`storage-driver` field][docker-storage-driver].
|
||||
|
||||
In the end, the file should look something like:
|
||||
|
||||
```
|
||||
{
|
||||
"runtimes": {
|
||||
"runsc": {
|
||||
"path": "/usr/local/bin/runsc"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You must restart the Docker daemon after making changes to this file, typically
|
||||
this is done via:
|
||||
|
||||
```
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
## Running a container
|
||||
|
||||
Now run your container in `runsc`:
|
||||
|
||||
```
|
||||
docker run --runtime=runsc hello-world
|
||||
```
|
||||
|
||||
You can also run a terminal to explore the container.
|
||||
|
||||
```
|
||||
docker run --runtime=runsc -it ubuntu /bin/bash
|
||||
```
|
||||
@@ -1,71 +0,0 @@
|
||||
# Quick Start
|
||||
|
||||
This guide will quickly get you started running your first gVisor sandbox
|
||||
container.
|
||||
|
||||
Some requirements:
|
||||
|
||||
- gVisor requires Linux x86\_64 Linux 3.17+
|
||||
- This guide requires Docker. Read the Docker documentation for how to install
|
||||
it on how to [install Docker](https://docs.docker.com/install/)
|
||||
|
||||
## Install gVisor
|
||||
|
||||
The easiest way to get `runsc` is from the
|
||||
[latest nightly build][runsc-nightly]. After you download the binary, check it
|
||||
against the SHA512 [checksum file][runsc-nightly-sha]. Older builds can be found
|
||||
here:
|
||||
`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc` and
|
||||
`https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/runsc.sha512`
|
||||
|
||||
**It is important to copy this binary to some place that is accessible to all
|
||||
users, and make is executable to all users**, since `runsc` executes itself as
|
||||
user `nobody` to avoid unnecessary privileges. The `/usr/local/bin` directory is
|
||||
a good place to put the `runsc` binary.
|
||||
|
||||
```
|
||||
wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
|
||||
wget https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
|
||||
sha512sum -c runsc.sha512
|
||||
chmod a+x runsc
|
||||
sudo mv runsc /usr/local/bin
|
||||
```
|
||||
|
||||
## Run an OCI compatible container
|
||||
|
||||
Now we will create an [OCI][oci] container bundle to run our container. First we
|
||||
will create a root directory for our bundle.
|
||||
|
||||
```
|
||||
$ mkdir bundle
|
||||
$ cd bundle
|
||||
```
|
||||
|
||||
Create a root file system for the container. We will use the Docker hello-world
|
||||
image as the basis for our container.
|
||||
|
||||
```
|
||||
$ mkdir rootfs
|
||||
$ docker export $(docker create hello-world) | tar -xf - -C rootfs
|
||||
```
|
||||
|
||||
Next, create an specification file called `config.json` that contains our
|
||||
container specification. We will update the default command it runs to `/hello`
|
||||
in the `hello-world` container.
|
||||
|
||||
```
|
||||
$ runsc spec
|
||||
$ sed -i 's;"sh";"/hello";' config.json
|
||||
```
|
||||
|
||||
Finally run the container.
|
||||
|
||||
```
|
||||
$ sudo runsc run hello
|
||||
```
|
||||
|
||||
\[TODO]:# Add some next steps
|
||||
|
||||
[runsc-nightly-sha]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
|
||||
[runsc-nightly]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
|
||||
[oci]: https://www.opencontainers.org
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 13 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 6.6 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 8.9 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 51 KiB |
@@ -1,108 +0,0 @@
|
||||
# runsc checkpoint/restore
|
||||
|
||||
gVisor supports checkpointing and restoring containers. A container’s state can
|
||||
be checkpointed and later restored into one or more containers. This can be used
|
||||
to save work and time in cases of failure and allow for container migration. A
|
||||
single container can perform slower setup tasks and then be checkpointed so that
|
||||
many containers with the same task can be “restored” and started more quickly.
|
||||
|
||||
### How to checkpoint/restore
|
||||
|
||||
To use the runsc checkpoint command, first run a container.
|
||||
|
||||
```sh
|
||||
runsc run <container id>
|
||||
```
|
||||
|
||||
To checkpoint the container, the --image-path flag must be provided. This is the
|
||||
directory path within which the checkpoint state-file will be created. The file
|
||||
will be called checkpoint.img and necessary directories will be created if they
|
||||
do not yet exist.
|
||||
|
||||
> Note: Two checkpoints cannot be saved to the save directory; every image-path
|
||||
provided must be unique.
|
||||
|
||||
```sh
|
||||
runsc checkpoint --image-path=<path> <container id>
|
||||
```
|
||||
|
||||
There is also an optional --leave-running flag that allows the container to
|
||||
continue to run after the checkpoint has been made. (By default, containers stop
|
||||
their processes after committing a checkpoint.)
|
||||
|
||||
> Note: All top-level runsc flags needed when calling run must be provided to
|
||||
checkpoint if --leave-running is used.
|
||||
|
||||
> Note: --leave-running functions by causing an immediate restore so the
|
||||
container, although will maintain its given container id, may have a different
|
||||
process id.
|
||||
|
||||
```sh
|
||||
runsc checkpoint --image-path=<path> --leave-running <container id>
|
||||
```
|
||||
|
||||
To restore, provide the image path to the checkpoint.img file created during the
|
||||
checkpoint. Because containers stop by default after checkpointing, restore
|
||||
needs to happen in a new container (restore is a command which parallels start).
|
||||
|
||||
```sh
|
||||
runsc create <container id>
|
||||
|
||||
runsc restore --image-path=<path> <container id>
|
||||
```
|
||||
|
||||
### How to use checkpoint/restore in Docker:
|
||||
|
||||
Currently checkpoint/restore through runsc is not entirely compatible with
|
||||
Docker, although there has been progress made from both gVisor and Docker to
|
||||
enable compatibility. Here, we document the ideal workflow.
|
||||
|
||||
To run with Docker, first follow the [instructions](https://gvisor.googlesource.com/gvisor/+/master/README.md#configuring-docker) to use runsc as a runtime.
|
||||
|
||||
Run a container:
|
||||
|
||||
```sh
|
||||
docker run [options] --runtime=runsc <image>`
|
||||
```
|
||||
|
||||
Checkpoint a container:
|
||||
|
||||
```sh
|
||||
docker checkpoint create <container> <checkpoint_name>`
|
||||
```
|
||||
|
||||
Create a new container into which to restore:
|
||||
|
||||
```sh
|
||||
docker create [options] --runtime=runsc <image>
|
||||
```
|
||||
|
||||
Restore a container:
|
||||
|
||||
```sh
|
||||
docker start --checkpoint --checkpoint-dir=<directory> <container>
|
||||
```
|
||||
|
||||
**Issues Preventing Compatibility with Docker**
|
||||
1. [Moby #37360][leave-running]
|
||||
|
||||
Docker version 18.03.0-ce and earlier hangs when checkpointing and
|
||||
does not create the checkpoint. To successfully use this feature, install a
|
||||
custom version of docker-ce from the moby repository. This issue is caused by an
|
||||
improper implementation of the `--leave-running` flag. This issue is now fixed
|
||||
although is not yet part of an official release.
|
||||
|
||||
2. Docker does not support restoration into new containers.
|
||||
|
||||
Docker currently expects the container which created the checkpoint
|
||||
to be the same container used to restore which is not possible in runsc. When
|
||||
Docker supports container migration and therefore restoration into new
|
||||
containers, this will be the flow.
|
||||
|
||||
3. [Moby #37344][checkpoint-dir]
|
||||
|
||||
Docker does not currently support the `--checkpoint-dir` flag but this will be
|
||||
required when restoring from a checkpoint made in another container.
|
||||
|
||||
[leave-running]: https://github.com/moby/moby/pull/37360
|
||||
[checkpoint-dir]: https://github.com/moby/moby/issues/37344
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Reference in New Issue
Block a user