2019-04-09 17:19:17 +00:00
|
|
|
![gVisor](g3doc/logo.png)
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2021-01-05 20:38:12 +00:00
|
|
|
[![Build status](https://badge.buildkite.com/3b159f20b9830461a71112566c4171c0bdfd2f980a8e4c0ae6.svg?branch=master)](https://buildkite.com/gvisor/pipeline)
|
2020-06-03 23:50:15 +00:00
|
|
|
[![gVisor chat](https://badges.gitter.im/gvisor/community.png)](https://gitter.im/gvisor/community)
|
2020-08-29 01:07:14 +00:00
|
|
|
[![code search](https://img.shields.io/badge/code-search-blue)](https://cs.opensource.google/gvisor/gvisor)
|
2019-06-06 23:57:18 +00:00
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
## What is gVisor?
|
|
|
|
|
2020-05-18 16:48:13 +00:00
|
|
|
**gVisor** is an application kernel, written in Go, that implements a
|
|
|
|
substantial portion of the Linux system surface. It includes an
|
2018-07-12 17:36:16 +00:00
|
|
|
[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.
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
## Why does gVisor exist?
|
2018-04-27 17:37:02 +00:00
|
|
|
|
|
|
|
Containers are not a [**sandbox**][sandbox]. While containers have
|
2020-05-16 03:03:54 +00:00
|
|
|
revolutionized how we develop, package, and deploy applications, using them to
|
|
|
|
run untrusted or potentially malicious code without additional isolation is not
|
|
|
|
a good idea. While using a single, shared kernel allows for efficiency and
|
|
|
|
performance gains, it also means that container escape is possible with a single
|
|
|
|
vulnerability.
|
|
|
|
|
|
|
|
gVisor is an application kernel for containers. It limits the host kernel
|
|
|
|
surface accessible to the application while still giving the application access
|
|
|
|
to all the features it expects. Unlike most kernels, gVisor does not assume or
|
|
|
|
require a fixed set of physical resources; instead, it leverages existing host
|
|
|
|
kernel functionality and runs as a normal process. In other words, gVisor
|
2018-04-27 17:37:02 +00:00
|
|
|
implements Linux by way of Linux.
|
|
|
|
|
|
|
|
gVisor should not be confused with technologies and tools to harden containers
|
|
|
|
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.
|
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
## Documentation
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
User documentation and technical architecture, including quick start guides, can
|
|
|
|
be found at [gvisor.dev][gvisor-dev].
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
## Installing from source
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
gVisor builds on x86_64 and ARM64. Other architectures may become available in
|
|
|
|
the future.
|
|
|
|
|
|
|
|
For the purposes of these instructions, [bazel][bazel] and other build
|
|
|
|
dependencies are wrapped in a build container. It is possible to use
|
|
|
|
[bazel][bazel] directly, or type `make help` for standard targets.
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
### Requirements
|
2018-05-11 17:22:15 +00:00
|
|
|
|
|
|
|
Make sure the following dependencies are installed:
|
|
|
|
|
2019-04-24 00:45:34 +00:00
|
|
|
* Linux 4.14.77+ ([older linux][old-linux])
|
2018-07-12 17:36:16 +00:00
|
|
|
* [Docker version 17.09.0 or greater][docker]
|
2018-05-11 17:22:15 +00:00
|
|
|
|
|
|
|
### Building
|
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
Build and install the `runsc` binary:
|
2018-05-11 17:22:15 +00:00
|
|
|
|
2020-08-03 16:07:43 +00:00
|
|
|
```sh
|
2019-05-03 21:11:55 +00:00
|
|
|
make runsc
|
|
|
|
sudo cp ./bazel-bin/runsc/linux_amd64_pure_stripped/runsc /usr/local/bin
|
|
|
|
```
|
|
|
|
|
2018-04-27 17:37:02 +00:00
|
|
|
### Testing
|
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
To run standard test suites, you can use:
|
2019-05-03 21:11:55 +00:00
|
|
|
|
2020-08-03 16:07:43 +00:00
|
|
|
```sh
|
2019-05-03 21:11:55 +00:00
|
|
|
make unit-tests
|
|
|
|
make tests
|
|
|
|
```
|
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
To run specific tests, you can specify the target:
|
2019-04-05 22:47:36 +00:00
|
|
|
|
2020-08-03 16:07:43 +00:00
|
|
|
```sh
|
2020-05-19 03:20:03 +00:00
|
|
|
make test TARGETS="//runsc:version_test"
|
2019-04-05 22:47:36 +00:00
|
|
|
```
|
|
|
|
|
2019-06-13 23:49:09 +00:00
|
|
|
### Using `go get`
|
|
|
|
|
|
|
|
This project uses [bazel][bazel] to build and manage dependencies. A synthetic
|
|
|
|
`go` branch is maintained that is compatible with standard `go` tooling for
|
|
|
|
convenience.
|
|
|
|
|
2020-08-03 16:07:43 +00:00
|
|
|
For example, to build and install `runsc` directly from this branch:
|
2019-06-13 23:49:09 +00:00
|
|
|
|
2020-08-03 16:07:43 +00:00
|
|
|
```sh
|
2019-06-13 23:49:09 +00:00
|
|
|
echo "module runsc" > go.mod
|
|
|
|
GO111MODULE=on go get gvisor.dev/gvisor/runsc@go
|
2020-08-03 16:07:43 +00:00
|
|
|
CGO_ENABLED=0 GO111MODULE=on sudo -E go build -o /usr/local/bin/runsc gvisor.dev/gvisor/runsc
|
|
|
|
```
|
|
|
|
|
2021-01-13 01:50:33 +00:00
|
|
|
Subsequently, you can build and install the shim binary for `containerd`:
|
2020-08-03 16:07:43 +00:00
|
|
|
|
|
|
|
```sh
|
2021-01-13 01:50:33 +00:00
|
|
|
GO111MODULE=on sudo -E go build -o /usr/local/bin/containerd-shim-runsc-v1 gvisor.dev/gvisor/shim
|
2019-06-13 23:49:09 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Note that this branch is supported in a best effort capacity, and direct
|
|
|
|
development on this branch is not supported. Development should occur on the
|
|
|
|
`master` branch, which is then reflected into the `go` branch.
|
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
## Community & Governance
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2020-05-23 19:33:27 +00:00
|
|
|
See [GOVERNANCE.md](GOVERNANCE.md) for project governance information.
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2019-04-09 17:19:17 +00:00
|
|
|
The [gvisor-users mailing list][gvisor-users-list] and
|
|
|
|
[gvisor-dev mailing list][gvisor-dev-list] are good starting points for
|
|
|
|
questions and discussion.
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2019-10-07 04:06:53 +00:00
|
|
|
## Security Policy
|
2018-04-27 17:37:02 +00:00
|
|
|
|
2019-10-07 04:06:53 +00:00
|
|
|
See [SECURITY.md](SECURITY.md).
|
2018-04-27 17:37:02 +00:00
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
|
|
|
See [Contributing.md](CONTRIBUTING.md).
|
|
|
|
|
|
|
|
[bazel]: https://bazel.build
|
2018-06-02 22:21:42 +00:00
|
|
|
[docker]: https://www.docker.com
|
|
|
|
[gvisor-users-list]: https://groups.google.com/forum/#!forum/gvisor-users
|
2020-05-16 03:03:54 +00:00
|
|
|
[gvisor-dev]: https://gvisor.dev
|
2019-04-09 17:19:17 +00:00
|
|
|
[gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev
|
2018-04-27 17:37:02 +00:00
|
|
|
[oci]: https://www.opencontainers.org
|
2019-04-24 00:45:34 +00:00
|
|
|
[old-linux]: https://gvisor.dev/docs/user_guide/networking/#gso
|
2018-04-27 17:37:02 +00:00
|
|
|
[sandbox]: https://en.wikipedia.org/wiki/Sandbox_(computer_security)
|