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/_index.md | 9 +- content/docs/user_guide/docker.md | 92 ------------ content/docs/user_guide/install.md | 162 ++++++++++++++++++++++ content/docs/user_guide/kubernetes.md | 38 ----- content/docs/user_guide/oci.md | 51 ------- 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 +++++++ 9 files changed, 358 insertions(+), 188 deletions(-) delete mode 100644 content/docs/user_guide/docker.md create mode 100644 content/docs/user_guide/install.md delete mode 100644 content/docs/user_guide/kubernetes.md delete mode 100644 content/docs/user_guide/oci.md 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') diff --git a/content/docs/user_guide/_index.md b/content/docs/user_guide/_index.md index 803ad00f1..c01220314 100644 --- a/content/docs/user_guide/_index.md +++ b/content/docs/user_guide/_index.md @@ -3,10 +3,5 @@ title = "User Guide" 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 Quick Start](./oci/): Expert mode. Customize gVisor for your environment. +Get started with either [installation instructions](./install/) or +[quick start guides](./quick_start). diff --git a/content/docs/user_guide/docker.md b/content/docs/user_guide/docker.md deleted file mode 100644 index 99cb766ff..000000000 --- a/content/docs/user_guide/docker.md +++ /dev/null @@ -1,92 +0,0 @@ -+++ -title = "Docker Quick Start" -weight = 10 -+++ -This guide will help you quickly get started running Docker containers using -gVisor. - -## Install gVisor - -> Note: gVisor supports only x86\_64 and requires Linux {{< required_linux >}} -> ([older Linux][old-linux]). - -{{% readfile file="docs/includes/install_gvisor.md" markdown="true" %}} - -## Configuring Docker - -> Note: This guide requires Docker version 17.09.0 or greater. Refer to the -> [Docker documentation][docker] for how to install it. - -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/ -[old-linux]: /docs/user_guide/networking/#gso -[storage-driver]: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-storage-driver diff --git a/content/docs/user_guide/install.md b/content/docs/user_guide/install.md new file mode 100644 index 000000000..cdfb0ff96 --- /dev/null +++ b/content/docs/user_guide/install.md @@ -0,0 +1,162 @@ ++++ +title = "Installation" +weight = 20 ++++ + +> Note: gVisor supports only x86\_64 and requires Linux {{< required_linux >}} +> ([older Linux][old-linux]). + +## Versions + +The `runsc` binaries and repositories are available in multiple versions and +release channels. First, 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. + +### Nightly + +Nightly releases are built most nights from the master branch, and are available +at the following URL: + + `https://storage.googleapis.com/gvisor/releases/nightly/latest` + +Specific nightly releases can be found at: + + `https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}` + +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. + +### Latest release + +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. + +### Specific release + +A given release release is available at the following URL: + + `https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}` + +See the [releases][releases] page for information about specific releases. + +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. + +### Point release + +A given point release is available at the following URL: + + `https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}` + +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. + +## From an `apt` repository + +First, appropriate dependencies must be installed to allow `apt` to install +packages via https: + +```bash +sudo apt-get update && \ +sudo apt-get install -y \ + apt-transport-https \ + ca-certificates \ + curl \ + gnupg-agent \ + software-properties-common +``` + +Next, the key used to sign archives should be added to your `apt` keychain: + +```bash +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. + +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 +``` + +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 +``` + +Now the runsc package can be installed: + +```bash +sudo apt-get update && sudo apt-get install -y runsc +``` + +If you have Docker installed, it will be automatically configured. + +## Manually + +After selecting an appropriate `URL` above, you can download `runsc` directly +from `${URL}/runsc` ([latest][latest-nightly]) and a checksum hash from +`${URL}/runsc.sha512` ([latest][latest-hash]). + +For example, this binary can be downloaded, validated, and placed in an +appropriate location by running: + +```bash +( + set -e + wget ${URL}/runsc + wget ${URL/runsc.sha512 + sha512sum -c runsc.sha512 + sudo mv runsc /usr/local/bin + sudo chown root:root /usr/local/bin/runsc + sudo chmod 0755 /usr/local/bin/runsc +) +``` + +**It is important to copy this binary to a location that is accessible to all +users, and ensure it is executable by 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. + +After installation, the`runsc` binary comes with an `install` command that can +optionally automatically configure Docker: + +```bash +runsc install +``` + +[latest-nightly]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc + +[latest-hash]: https://storage.googleapis.com/gvisor/releases/nightly/latest/runsc.sha512 + +[oci]: https://www.opencontainers.org + +[old-linux]: /docs/user_guide/networking/#gso + +[releases]: https://github.com/google/gvisor/releases diff --git a/content/docs/user_guide/kubernetes.md b/content/docs/user_guide/kubernetes.md deleted file mode 100644 index 3aa5c719b..000000000 --- a/content/docs/user_guide/kubernetes.md +++ /dev/null @@ -1,38 +0,0 @@ -+++ -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/oci.md b/content/docs/user_guide/oci.md deleted file mode 100644 index 288575fc4..000000000 --- a/content/docs/user_guide/oci.md +++ /dev/null @@ -1,51 +0,0 @@ -+++ -title = "OCI Quick Start" -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 - -> Note: gVisor supports only x86\_64 and requires Linux {{< required_linux >}} -> ([older Linux][old-linux]). - -{{% readfile file="docs/includes/install_gvisor.md" markdown="true" %}} - -## 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/ -[old-linux]: /docs/user_guide/networking/#gso 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