Add a new docs directory. refs #109
Add a new 'docs' directory for that can be built on in the future. Docs are divided into a 'user guide', 'contributor guide', and 'architecture guide'. This is currently a work in progress. PiperOrigin-RevId: 223326836 Change-Id: I78d08d6a89d686e92d3415d4269463e8e74bddee
This commit is contained in:
parent
4d0da37cbb
commit
db0473b1be
|
@ -0,0 +1,37 @@
|
||||||
|
# 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
|
|
@ -0,0 +1 @@
|
||||||
|
# Architecture Guide
|
|
@ -0,0 +1,9 @@
|
||||||
|
# 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.
|
|
@ -0,0 +1 @@
|
||||||
|
# Contributor Guide
|
|
@ -0,0 +1 @@
|
||||||
|
# User Guide
|
|
@ -0,0 +1,41 @@
|
||||||
|
# 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
|
||||||
|
```
|
|
@ -0,0 +1,71 @@
|
||||||
|
# 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
|
Loading…
Reference in New Issue