diff --git a/.github/issue_template.md b/.github/issue_template.md index 73afe1317..77c401d22 100644 --- a/.github/issue_template.md +++ b/.github/issue_template.md @@ -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 diff --git a/README.md b/README.md index e960614ff..8eac9833b 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,15 @@ -# gVisor +![gVisor](g3doc/logo.png) -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 -![Machine-level virtualization](g3doc/Machine-Virtualization.png "Machine-level virtualization") +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](g3doc/Rule-Based-Execution.png "Rule-based execution") - -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. - -![gVisor](g3doc/Layers.png "gVisor") - -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. - -![Sentry](g3doc/Sentry-Gofer.png "Sentry and Gofer") - -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 diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 6f847fa4b..000000000 --- a/docs/README.md +++ /dev/null @@ -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 diff --git a/docs/architecture_guide/README.md b/docs/architecture_guide/README.md deleted file mode 100644 index fe0569721..000000000 --- a/docs/architecture_guide/README.md +++ /dev/null @@ -1 +0,0 @@ -# Architecture Guide diff --git a/docs/architecture_guide/why.md b/docs/architecture_guide/why.md deleted file mode 100644 index 2bf9c60fd..000000000 --- a/docs/architecture_guide/why.md +++ /dev/null @@ -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. diff --git a/docs/contributor_guide/README.md b/docs/contributor_guide/README.md deleted file mode 100644 index 83840bba3..000000000 --- a/docs/contributor_guide/README.md +++ /dev/null @@ -1 +0,0 @@ -# Contributor Guide diff --git a/docs/user_guide/README.md b/docs/user_guide/README.md deleted file mode 100644 index cd3d45227..000000000 --- a/docs/user_guide/README.md +++ /dev/null @@ -1 +0,0 @@ -# User Guide diff --git a/docs/user_guide/docker.md b/docs/user_guide/docker.md deleted file mode 100644 index fefb5f993..000000000 --- a/docs/user_guide/docker.md +++ /dev/null @@ -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 -``` diff --git a/docs/user_guide/quick_start.md b/docs/user_guide/quick_start.md deleted file mode 100644 index 219c1ed63..000000000 --- a/docs/user_guide/quick_start.md +++ /dev/null @@ -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 diff --git a/g3doc/Layers.png b/g3doc/Layers.png deleted file mode 100644 index 308c6c451..000000000 Binary files a/g3doc/Layers.png and /dev/null differ diff --git a/g3doc/Layers.svg b/g3doc/Layers.svg deleted file mode 100644 index 0a366f841..000000000 --- a/g3doc/Layers.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/g3doc/Machine-Virtualization.png b/g3doc/Machine-Virtualization.png deleted file mode 100644 index 1ba2ed6b2..000000000 Binary files a/g3doc/Machine-Virtualization.png and /dev/null differ diff --git a/g3doc/Machine-Virtualization.svg b/g3doc/Machine-Virtualization.svg deleted file mode 100644 index 5352da07b..000000000 --- a/g3doc/Machine-Virtualization.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/g3doc/Rule-Based-Execution.png b/g3doc/Rule-Based-Execution.png deleted file mode 100644 index b42654a90..000000000 Binary files a/g3doc/Rule-Based-Execution.png and /dev/null differ diff --git a/g3doc/Rule-Based-Execution.svg b/g3doc/Rule-Based-Execution.svg deleted file mode 100644 index bd6717043..000000000 --- a/g3doc/Rule-Based-Execution.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/g3doc/Sentry-Gofer.png b/g3doc/Sentry-Gofer.png deleted file mode 100644 index ca2c27ef7..000000000 Binary files a/g3doc/Sentry-Gofer.png and /dev/null differ diff --git a/g3doc/Sentry-Gofer.svg b/g3doc/Sentry-Gofer.svg deleted file mode 100644 index 5c10750d2..000000000 --- a/g3doc/Sentry-Gofer.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/g3doc/checkpoint_restore.md b/g3doc/checkpoint_restore.md deleted file mode 100644 index 5fa3280a8..000000000 --- a/g3doc/checkpoint_restore.md +++ /dev/null @@ -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 -``` - -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= -``` - -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= --leave-running -``` - -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 - -runsc restore --image-path= -``` - -### 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 ` -``` - -Checkpoint a container: - -```sh -docker checkpoint create ` -``` - -Create a new container into which to restore: - -```sh -docker create [options] --runtime=runsc -``` - -Restore a container: - -```sh -docker start --checkpoint --checkpoint-dir= -``` - -**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 diff --git a/g3doc/logo.png b/g3doc/logo.png new file mode 100644 index 000000000..bd1a1e4b7 Binary files /dev/null and b/g3doc/logo.png differ