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