summaryrefslogtreecommitdiffhomepage
path: root/g3doc/user_guide/platforms.md
diff options
context:
space:
mode:
authorgVisor bot <gvisor-bot@google.com>2020-05-12 12:55:23 -0700
committergVisor bot <gvisor-bot@google.com>2020-05-12 12:55:23 -0700
commita3f97a757a8d6e18f03acecb68b484cc1608c3ae (patch)
tree293c51eb9786bc1b8371daaeec2985b17b5b3ec9 /g3doc/user_guide/platforms.md
parent6a4466a46cd551825198fbafc3b734ab5608019a (diff)
parent5f3a256425f4fa99fd3e5363418c5978659cecf3 (diff)
Merge pull request #2513 from amscanne:website-integrated
PiperOrigin-RevId: 311184385
Diffstat (limited to 'g3doc/user_guide/platforms.md')
-rw-r--r--g3doc/user_guide/platforms.md119
1 files changed, 119 insertions, 0 deletions
diff --git a/g3doc/user_guide/platforms.md b/g3doc/user_guide/platforms.md
new file mode 100644
index 000000000..eefb6b222
--- /dev/null
+++ b/g3doc/user_guide/platforms.md
@@ -0,0 +1,119 @@
+# Platforms (KVM)
+
+[TOC]
+
+This document will help you set up your system to use a different gVisor
+platform.
+
+## What is a Platform?
+
+gVisor requires a *platform* to implement interception of syscalls, basic
+context switching, and memory mapping functionality. These are described in more
+depth in the [Platform Design](../../architecture_guide/platforms/).
+
+## Selecting a Platform
+
+The platform is selected by the `--platform` command line flag passed to
+`runsc`. By default, the ptrace platform is selected. To select a different
+platform, modify your Docker configuration (`/etc/docker/daemon.json`) to pass
+this argument:
+
+```json
+{
+ "runtimes": {
+ "runsc": {
+ "path": "/usr/local/bin/runsc",
+ "runtimeArgs": [
+ "--platform=kvm"
+ ]
+ }
+ }
+}
+```
+
+You must restart the Docker daemon after making changes to this file, typically
+this is done via `systemd`:
+
+```bash
+sudo systemctl restart docker
+```
+
+## Example: Using the KVM Platform
+
+The KVM platform is currently experimental; however, it provides several
+benefits over the default ptrace platform.
+
+### Prerequisites
+
+You will also to have KVM installed on your system. If you are running a Debian
+based system like Debian or Ubuntu you can usually do this by installing the
+`qemu-kvm` package.
+
+```bash
+sudo apt-get install qemu-kvm
+```
+
+If you are using a virtual machine you will need to make sure that nested
+virtualization is configured. Here are links to documents on how to set up
+nested virtualization in several popular environments:
+
+* Google Cloud: [Enabling Nested Virtualization for VM Instances][nested-gcp]
+* Microsoft Azure:
+ [How to enable nested virtualization in an Azure VM][nested-azure]
+* VirtualBox: [Nested Virtualization][nested-virtualbox]
+* KVM: [Nested Guests][nested-kvm]
+
+***Note: nested virtualization will have poor performance and is historically a
+cause of security issues (e.g.
+[CVE-2018-12904](https://nvd.nist.gov/vuln/detail/CVE-2018-12904)). It is not
+recommended for production.***
+
+### Configuring Docker
+
+Per above, you will need to configure Docker to use `runsc` with the KVM
+platform. You will remember from the Docker Quick Start that you configured
+Docker to use `runsc` as the runtime. Docker allows you to add multiple runtimes
+to the Docker configuration.
+
+Add a new entry for the KVM platform entry to your Docker configuration
+(`/etc/docker/daemon.json`) in order to provide the `--platform=kvm` runtime
+argument.
+
+In the end, the file should look something like:
+
+```json
+{
+ "runtimes": {
+ "runsc": {
+ "path": "/usr/local/bin/runsc"
+ },
+ "runsc-kvm": {
+ "path": "/usr/local/bin/runsc",
+ "runtimeArgs": [
+ "--platform=kvm"
+ ]
+ }
+ }
+}
+```
+
+You must restart the Docker daemon after making changes to this file, typically
+this is done via `systemd`:
+
+```bash
+sudo systemctl restart docker
+```
+
+## Running a container
+
+Now run your container using the `runsc-kvm` runtime. This will run the
+container using the KVM platform:
+
+```bash
+docker run --runtime=runsc-kvm --rm hello-world
+```
+
+[nested-azure]: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/nested-virtualization
+[nested-gcp]: https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances
+[nested-virtualbox]: https://www.virtualbox.org/manual/UserManual.html#nested-virt
+[nested-kvm]: https://www.linux-kvm.org/page/Nested_Guests