From 015a1b57d6b701cb8b687fb70aa9a5dbcb1edc25 Mon Sep 17 00:00:00 2001 From: Adin Scannell Date: Thu, 12 Sep 2019 00:26:09 -0700 Subject: Add apt-based instructions. --- content/docs/user_guide/quick_start/_index.md | 12 +++ content/docs/user_guide/quick_start/docker.md | 93 +++++++++++++++++++++++ content/docs/user_guide/quick_start/kubernetes.md | 39 ++++++++++ content/docs/user_guide/quick_start/oci.md | 50 ++++++++++++ 4 files changed, 194 insertions(+) create mode 100644 content/docs/user_guide/quick_start/_index.md create mode 100644 content/docs/user_guide/quick_start/docker.md create mode 100644 content/docs/user_guide/quick_start/kubernetes.md create mode 100644 content/docs/user_guide/quick_start/oci.md (limited to 'content/docs/user_guide/quick_start') diff --git a/content/docs/user_guide/quick_start/_index.md b/content/docs/user_guide/quick_start/_index.md new file mode 100644 index 000000000..770fd8893 --- /dev/null +++ b/content/docs/user_guide/quick_start/_index.md @@ -0,0 +1,12 @@ ++++ +title = "Quick Start" +weight = 10 ++++ + +gVisor can be used with Docker, Kubernetes, or directly using `runsc` with +crafted OCI spec for your container. Use the links below to see detailed +instructions for each of them: + + * [Docker](./docker/): The quickest and easiest way to get started. + * [Kubernetes](./kubernetes/): Isolate Pods in your K8s cluster with gVisor. + * [OCI](./oci/): Expert mode. Customize gVisor for your environment. diff --git a/content/docs/user_guide/quick_start/docker.md b/content/docs/user_guide/quick_start/docker.md new file mode 100644 index 000000000..523831c1b --- /dev/null +++ b/content/docs/user_guide/quick_start/docker.md @@ -0,0 +1,93 @@ ++++ +title = "Docker" +weight = 10 ++++ + +> Note: This guide requires Docker version 17.09.0 or greater. Refer to the +> [Docker documentation][docker] for how to install it. + +This guide will help you quickly get started running Docker containers using +gVisor. + +## Install gVisor + +First, install gVisor using the [install instructions][install]. + +If you use the `apt` repository or the `automated` install, then you can skip +the next section and proceed straight to running a container. + +## Configuring Docker + +First you will need to 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][storage-driver]. + +In the end, the file should look something like: + +```json +{ + "runtimes": { + "runsc": { + "path": "/usr/local/bin/runsc" + } + } +} +``` + +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` runtime: + +```bash +docker run --runtime=runsc --rm hello-world +``` + +You can also run a terminal to explore the container. + +```bash +docker run --runtime=runsc --rm -it ubuntu /bin/bash +``` + +Many docker options are compatible with gVisor, try them out. Here is an example: + +```bash +docker run --runtime=runsc --rm --link backend:database -v ~/bin:/tools:ro -p 8080:80 --cpus=0.5 -it busybox telnet towel.blinkenlights.nl +``` + +## Verify the runtime + +You can verify that you are running in gVisor using the `dmesg` command. + +```text +$ docker run --runtime=runsc -it ubuntu dmesg +[ 0.000000] Starting gVisor... +[ 0.354495] Daemonizing children... +[ 0.564053] Constructing home... +[ 0.976710] Preparing for the zombie uprising... +[ 1.299083] Creating process schedule... +[ 1.479987] Committing treasure map to memory... +[ 1.704109] Searching for socket adapter... +[ 1.748935] Generating random numbers by fair dice roll... +[ 2.059747] Digging up root... +[ 2.259327] Checking naughty and nice process list... +[ 2.610538] Rewriting operating system in Javascript... +[ 2.613217] Ready! +``` + +Note that this is easily replicated by an attacker so applications should never +use `dmesg` to verify the runtime in a security sensitive context. + +Next, look at the different options available for gVisor: [platform](../platforms/), +[network](../networking/), [filesystem](../filesystem/). + +[docker]: https://docs.docker.com/install/ + +[storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver diff --git a/content/docs/user_guide/quick_start/kubernetes.md b/content/docs/user_guide/quick_start/kubernetes.md new file mode 100644 index 000000000..b3b5e0a55 --- /dev/null +++ b/content/docs/user_guide/quick_start/kubernetes.md @@ -0,0 +1,39 @@ ++++ +title = "Kubernetes" +weight = 20 ++++ + +gVisor can be used to run Kubernetes pods and has several integration points +with Kubernetes. + +## Using Minikube + +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. + +## Using Containerd + +You can also setup Kubernetes nodes to run pods in gvisor using the +[containerd][containerd] CRI runtime and the `gvisor-containerd-shim`. You can +use either the `io.kubernetes.cri.untrusted-workload` annotation or +[RuntimeClass][runtimeclass] to run Pods with `runsc`. You can find +instructions [here][gvisor-containerd-shim]. + +## Using GKE Sandbox + +[GKE Sandbox][gke-sandbox] is available in [Google Kubernetes Engine][gke]. You +just need to deploy a node pool with gVisor enabled in your cluster, and it will +run pods annotated with `runtimeClassName: gvisor` inside a gVisor sandbox for +you. [Here][wordpress-quick] is a quick example showing how to deploy a +WordPress site. You can view the full documentation [here][gke-sandbox-docs]. + +[containerd]: https://containerd.io/ +[minikube]: https://github.com/kubernetes/minikube/blob/master/deploy/addons/gvisor/README.md +[gke]: https://cloud.google.com/kubernetes-engine/ +[gke-sandbox]: https://cloud.google.com/kubernetes-engine/sandbox/ +[gke-sandbox-docs]: https://cloud.google.com/kubernetes-engine/docs/how-to/sandbox-pods +[gvisor-containerd-shim]: https://github.com/google/gvisor-containerd-shim +[runtimeclass]: https://kubernetes.io/docs/concepts/containers/runtime-class/ +[wordpress-quick]: /docs/tutorials/kubernetes/ \ No newline at end of file diff --git a/content/docs/user_guide/quick_start/oci.md b/content/docs/user_guide/quick_start/oci.md new file mode 100644 index 000000000..b39be069e --- /dev/null +++ b/content/docs/user_guide/quick_start/oci.md @@ -0,0 +1,50 @@ ++++ +title = "OCI" +weight = 30 ++++ + +This guide will quickly get you started running your first gVisor sandbox +container using the runtime directly with the default platform. + +## Install gVisor + +First, install gVisor using the [install instructions][install]. + +## 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. + +```bash +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. + +```bash +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. + +```bash +runsc spec +sed -i 's;"sh";"/hello";' config.json +``` + +Finally run the container. + +```bash +sudo runsc run hello +``` + +Next try [running gVisor using Docker](../docker/). + +[oci]: https://opencontainers.org/ + +[install]: /docs/user_guide/install -- cgit v1.2.3