Merge branch 'master' into lint-md

5 files changed, 209 insertions, 43 deletions

diff --git a/content/docs/tutorials/cni.md b/content/docs/tutorials/cni.md
new file mode 100644
index 000000000..b8abc8689
--- /dev/null
+++ b/content/docs/tutorials/cni.md
@@ -0,0 +1,175 @@
++++
+title = "Using CNI"
+weight = 12
++++
+
+This tutorial will show you how to set up networking for a gVisor sandbox using
+the [Container Networking Interface (CNI)](https://github.com/containernetworking/cni).
+
+## Install CNI Plugins
+
+First you will need to install the CNI plugins. CNI plugins are used to set up
+a network namespace that `runsc` can use with the sandbox.
+
+Start by creating the directories for CNI plugin binaries:
+
+```
+sudo mkdir -p /opt/cni/bin
+```
+
+Download the CNI plugins:
+
+```
+wget https://github.com/containernetworking/plugins/releases/download/v0.8.3/cni-plugins-linux-amd64-v0.8.3.tgz
+```
+
+Next, unpack the plugins into the CNI binary directory:
+
+```
+sudo tar -xvf cni-plugins-linux-amd64-v0.8.3.tgz -C /opt/cni/bin/
+```
+
+## Configure CNI Plugins
+
+This section will show you how to configure CNI plugins. This tutorial will use
+the "bridge" and "loopback" plugins which will create the necessary bridge and
+loopback devices in our network namespace. However, you should be able to use
+any CNI compatible plugin to set up networking for gVisor sandboxes.
+
+The bridge plugin configuration specifies the IP address subnet range for IP
+addresses that will be assigned to sandboxes as well as the network routing
+configuration. This tutorial will assign IP addresses from the `10.22.0.0/16`
+range and allow all outbound traffic, however you can modify this configuration
+to suit your use case.
+
+Create the bridge and loopback plugin configurations:
+
+```
+sudo mkdir -p /etc/cni/net.d
+
+sudo sh -c 'cat > /etc/cni/net.d/10-bridge.conf << EOF
+{
+  "cniVersion": "0.4.0",
+  "name": "mynet",
+  "type": "bridge",
+  "bridge": "cni0",
+  "isGateway": true,
+  "ipMasq": true,
+  "ipam": {
+    "type": "host-local",
+    "subnet": "10.22.0.0/16",
+    "routes": [
+      { "dst": "0.0.0.0/0" }
+    ]
+  }
+}
+EOF'
+
+sudo sh -c 'cat > /etc/cni/net.d/99-loopback.conf << EOF
+{
+  "cniVersion": "0.4.0",
+  "name": "lo",
+  "type": "loopback"
+}
+EOF'
+```
+
+## Create a Network Namespace
+
+For each gVisor sandbox you will create a network namespace and configure it
+using CNI. First, create a random network namespace name and then create
+the namespace.
+
+The network namespace path will then be `/var/run/netns/${CNI_CONTAINERID}`.
+
+```
+export CNI_PATH=/opt/cni/bin
+export CNI_CONTAINERID=$(printf '%x%x%x%x' $RANDOM $RANDOM $RANDOM $RANDOM)
+export CNI_COMMAND=ADD
+export CNI_NETNS=/var/run/netns/${CNI_CONTAINERID}
+
+sudo ip netns add ${CNI_CONTAINERID}
+```
+
+Next, run the bridge and loopback plugins to apply the configuration that was
+created earlier to the namespace. Each plugin outputs some JSON indicating the
+results of executing hte plugin. For example, The bridge plugin's response
+includes the IP address assigned to the ethernet device created in the network
+namespace. Take note of the IP address for use later.
+
+```
+export CNI_IFNAME="eth0"
+sudo -E /opt/cni/bin/bridge < /etc/cni/net.d/10-bridge.conf
+export CNI_IFNAME="lo"
+sudo -E /opt/cni/bin/loopback < /etc/cni/net.d/99-loopback.conf
+```
+
+Get the IP address assigned to our sandbox:
+
+```
+POD_IP=$(sudo ip netns exec ${CNI_CONTAINERID} ip -4 addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}')
+```
+
+## Create the OCI Bundle
+
+Now that our network namespace is created and configured, we can create the OCI
+bundle for our container. As part of the bundle's `config.json` we will specify
+that the container use the network namespace that we created.
+
+The container will run a simple python webserver that we will be able to
+connect to via the IP address assigned to it via the bridge CNI plugin.
+
+Create the bundle and root filesystem directories:
+
+```
+sudo mkdir -p bundle
+cd bundle
+sudo mkdir rootfs
+sudo docker export $(docker create python) | sudo tar --same-owner -pxf - -C rootfs
+sudo mkdir -p rootfs/var/www/html
+sudo sh -c 'echo "Hello World!" > rootfs/var/www/html/index.html'
+```
+
+Next create the `config.json` specifying the network namespace.
+```   
+sudo /usr/local/bin/runsc spec
+sudo sed -i 's;"sh";"python", "-m", "http.server";' config.json
+sudo sed -i "s;\"cwd\": \"/\";\"cwd\": \"/var/www/html\";" config.json
+sudo sed -i "s;\"type\": \"network\";\"type\": \"network\",\n\t\t\t\t\"path\": \"/var/run/netns/${CNI_CONTAINERID}\";" config.json
+```
+
+## Run the Container
+
+Now we can run and connect to the webserver. Run the container in gVisor. Use
+the same ID used for the network namespace to be consistent:
+
+```
+sudo runsc run -detach ${CNI_CONTAINERID}
+```
+
+Connect to the server via the sandbox's IP address:
+
+```
+curl http://${POD_IP}:8000/
+```
+
+You should see the server returning `Hello World!`.
+
+## Cleanup
+
+After you are finished running the container, you can clean up the network
+namespace .
+
+```
+sudo runsc kill ${CNI_CONTAINERID}
+sudo runsc delete ${CNI_CONTAINERID}
+
+export CNI_COMMAND=DEL
+
+export CNI_IFNAME="lo"
+sudo -E /opt/cni/bin/loopback < /etc/cni/net.d/99-loopback.conf
+export CNI_IFNAME="eth0"
+sudo -E /opt/cni/bin/bridge < /etc/cni/net.d/10-bridge.conf
+
+sudo ip netns delete ${CNI_CONTAINERID}
+```
diff --git a/content/docs/tutorials/kubernetes.md b/content/docs/tutorials/kubernetes.md
index 5a931bae3..36ab59c1c 100644
--- a/content/docs/tutorials/kubernetes.md
+++ b/content/docs/tutorials/kubernetes.md
@@ -1,5 +1,6 @@
 +++
 title = "WordPress with Kubernetes"
+weight = 11
 +++
 
 ## Deploy a WordPress site using GKE Sandbox
diff --git a/content/docs/user_guide/FAQ.md b/content/docs/user_guide/FAQ.md
index 05455a70f..da742a41b 100644
--- a/content/docs/user_guide/FAQ.md
+++ b/content/docs/user_guide/FAQ.md
@@ -23,13 +23,13 @@ gVisor supports Linux
 Binaries run in gVisor should be built for the
 [AMD64](https://en.wikipedia.org/wiki/X86-64) CPU architecture.
 
-### Can I run Docker images using gVisor.
+### Can I run Docker images using gVisor?
 
 Yes. Please see the [Docker Quick Start][docker].
 
-### Can I run Kubernetes pods using gVisor.
+### Can I run Kubernetes pods using gVisor?
 
-Yes. Please see the [Docker Quick Start][k8s].
+Yes. Please see the [Kubernetes Quick Start][k8s].
 
 ### What's the security model?
 
diff --git a/content/docs/user_guide/install.md b/content/docs/user_guide/install.md
index cd6430a5e..d1bf79dd5 100644
--- a/content/docs/user_guide/install.md
+++ b/content/docs/user_guide/install.md
@@ -13,12 +13,21 @@ release channels. You should pick the version you'd like to install. For
 experimentation, the nightly release is recommended. For production use, the
 latest release is recommended.
 
-<!--
-
 After selecting an appropriate release channel from the options below, proceed
 to the preferred installation mechanism: manual or from an `apt` repository.
 
- -->
+### HEAD
+
+Binaries are available for every commit on the `master` branch, and are
+available at the following URL:
+
+   `https://storage.googleapis.com/gvisor/releases/master/latest/runsc`
+
+Checksums for the release binary are at:
+
+   `https://storage.googleapis.com/gvisor/releases/master/latest/runsc.sha512`
+
+For `apt` installation, use the `master` as the `${DIST}` below.
 
 ### Nightly
 
@@ -37,10 +46,7 @@ Specific nightly releases can be found at:
 
 Note that a release may not be available for every day.
 
-<!--
-
-To use a nightly release, use one of the above URLs for `URL` in the manual
-instructions below. For `apt`, use `nightly` for `DIST` below.
+For `apt` installation, use the `nightly` as the `${DIST}` below.
 
 ### Latest release
 
@@ -48,8 +54,7 @@ The latest official release is available at the following URL:
 
    `https://storage.googleapis.com/gvisor/releases/release/latest`
 
-To use the latest release, use the above URL for `URL` in the manual
-instructions below. For `apt`, use `latest` for `DIST` below.
+For `apt` installation, use the `release` as the `${DIST}` below.
 
 ### Specific release
 
@@ -59,11 +64,10 @@ A given release release is available at the following URL:
 
 See the [releases][releases] page for information about specific releases.
 
+For `apt` installation of a specific release, which may include point updates,
+use the date of the release, e.g. `${yyyymmdd}`, as the `${DIST}` below.
 
-This will include point updates for the release, if required. To use a specific
-release, use the above URL for `URL` in the manual instructions below. For
-`apt`, use `${yyyymmdd}` for `DIST` below.
-
+> Note: only newer releases may be available as `apt` repositories.
 
 ### Point release
 
@@ -71,14 +75,9 @@ A given point release is available at the following URL:
 
   `https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}`
 
+Note that `apt` installation of a specific point release is not supported.
 
-Unlike the specific release above, which may include updates, this release will
-not change. To use a specific point release, use the above URL for `URL` in the
-manual instructions below. For apt, use `${yyyymmdd}.${rc}` for `DIST` below.
-
- -->
-
-<!-- Install from an `apt` repository
+## Install from an `apt` repository
 
 First, appropriate dependencies must be installed to allow `apt` to install
 packages via https:
@@ -102,27 +101,21 @@ curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add -
 Based on the release type, you will need to substitute `${DIST}` below, using
 one of:
 
-*   `nightly`: For all nightly releases.
-*   `latest`: For the latest release.
-*   `${yyyymmdd}`: For specific releases.
-*   `${yyyymmdd}.${rc}`: For a specific point release.
+* `master`: For HEAD.
+* `nightly: For nightly releases.
+* `release: For the latest release.
+* `${yyyymmdd}: For a specific releases (see above).
 
 The repository for the release you wish to install should be added:
 
 ```bash
-sudo add-apt-repository \
-   "deb https://storage.googleapis.com/gvisor/releases" \
-   "${DIST}" \
-   main
+sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases ${DIST} main"
 ```
 
 For example, to install the latest official release, you can use:
 
 ```bash
-sudo add-apt-repository \
-   "deb https://storage.googleapis.com/gvisor/releases" \
-   latest \
-   main
+sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main"
 ```
 
 Now the runsc package can be installed:
@@ -133,10 +126,11 @@ sudo apt-get update && sudo apt-get install -y runsc
 
 If you have Docker installed, it will be automatically configured.
 
--->
+## Install directly
 
-For example, the latest nightly binary can be downloaded, validated, 
-and placed in an appropriate location by running:
+The binary URLs provided above can be used to install directly. For example, the
+latest nightly binary can be downloaded, validated, and placed in an appropriate
+location by running:
 
 ```bash
 (
@@ -165,8 +159,4 @@ runsc install
 ```
 
 [old-linux]: /docs/user_guide/networking/#gso
-<!--
-[latest-nightly]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc
-[latest-hash]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512
 [releases]: https://github.com/google/gvisor/releases
--->
diff --git a/content/docs/user_guide/quick_start/oci.md b/content/docs/user_guide/quick_start/oci.md
index b39be069e..fc39525d0 100644
--- a/content/docs/user_guide/quick_start/oci.md
+++ b/content/docs/user_guide/quick_start/oci.md
@@ -43,7 +43,7 @@ Finally run the container.
 sudo runsc run hello
 ```
 
-Next try [running gVisor using Docker](../docker/).
+Next try [using CNI to set up networking](../../../tutorials/cni/) or [running gVisor using Docker](../docker/).
 
 [oci]: https://opencontainers.org/