diff options
Diffstat (limited to 'g3doc/user_guide/tutorials')
| -rw-r--r-- | g3doc/user_guide/tutorials/BUILD | 55 | ||||
| -rw-r--r-- | g3doc/user_guide/tutorials/add-node-pool.png | bin | 70208 -> 0 bytes | |||
| -rw-r--r-- | g3doc/user_guide/tutorials/cni.md | 174 | ||||
| -rw-r--r-- | g3doc/user_guide/tutorials/docker-compose.md | 100 | ||||
| -rw-r--r-- | g3doc/user_guide/tutorials/docker.md | 70 | ||||
| -rw-r--r-- | g3doc/user_guide/tutorials/knative.md | 88 | ||||
| -rw-r--r-- | g3doc/user_guide/tutorials/kubernetes.md | 236 | ||||
| -rw-r--r-- | g3doc/user_guide/tutorials/node-pool-button.png | bin | 13757 -> 0 bytes |
8 files changed, 0 insertions, 723 deletions
diff --git a/g3doc/user_guide/tutorials/BUILD b/g3doc/user_guide/tutorials/BUILD deleted file mode 100644 index a862c76f4..000000000 --- a/g3doc/user_guide/tutorials/BUILD +++ /dev/null @@ -1,55 +0,0 @@ -load("//website:defs.bzl", "doc") - -package( - default_visibility = ["//website:__pkg__"], - licenses = ["notice"], -) - -doc( - name = "docker", - src = "docker.md", - category = "User Guide", - permalink = "/docs/tutorials/docker/", - subcategory = "Tutorials", - weight = "10", -) - -doc( - name = "docker_compose", - src = "docker-compose.md", - category = "User Guide", - permalink = "/docs/tutorials/docker-compose/", - subcategory = "Tutorials", - weight = "20", -) - -doc( - name = "kubernetes", - src = "kubernetes.md", - category = "User Guide", - data = [ - "add-node-pool.png", - "node-pool-button.png", - ], - permalink = "/docs/tutorials/kubernetes/", - subcategory = "Tutorials", - weight = "30", -) - -doc( - name = "knative", - src = "knative.md", - category = "User Guide", - permalink = "/docs/tutorials/knative/", - subcategory = "Tutorials", - weight = "40", -) - -doc( - name = "cni", - src = "cni.md", - category = "User Guide", - permalink = "/docs/tutorials/cni/", - subcategory = "Tutorials", - weight = "50", -) diff --git a/g3doc/user_guide/tutorials/add-node-pool.png b/g3doc/user_guide/tutorials/add-node-pool.png Binary files differdeleted file mode 100644 index e4560359b..000000000 --- a/g3doc/user_guide/tutorials/add-node-pool.png +++ /dev/null diff --git a/g3doc/user_guide/tutorials/cni.md b/g3doc/user_guide/tutorials/cni.md deleted file mode 100644 index ee8d0ac92..000000000 --- a/g3doc/user_guide/tutorials/cni.md +++ /dev/null @@ -1,174 +0,0 @@ -# Using CNI - -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.3.1", - "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.3.1", - "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 the 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 runsc spec \ - --cwd /var/www/html \ - --netns /var/run/netns/${CNI_CONTAINERID} \ - -- python -m http.server -``` - -## 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/g3doc/user_guide/tutorials/docker-compose.md b/g3doc/user_guide/tutorials/docker-compose.md deleted file mode 100644 index 3284231f8..000000000 --- a/g3doc/user_guide/tutorials/docker-compose.md +++ /dev/null @@ -1,100 +0,0 @@ -# Wordpress with Docker Compose - -This page shows you how to deploy a sample [WordPress][wordpress] site using -[Docker Compose][docker-compose]. - -### Before you begin - -[Follow these instructions][docker-install] to install runsc with Docker. This -document assumes that Docker and Docker Compose are installed and the runtime -name chosen for gVisor is `runsc`. - -### Configuration - -We'll start by creating the `docker-compose.yaml` file to specify our services. -We will specify two services, a `wordpress` service for the Wordpress Apache -server, and a `db` service for MySQL. We will configure Wordpress to connect to -MySQL via the `db` service host name. - -> **Note:** Docker Compose uses it's own network by default and allows services -> to communicate using their service name. Docker Compose does this by setting -> up a DNS server at IP address 127.0.0.11 and configuring containers to use it -> via [resolv.conf][resolv.conf]. This IP is not addressable inside a gVisor -> sandbox so it's important that we set the DNS IP address to the alternative -> `8.8.8.8` and use a network that allows routing to it. See -> [Networking in Compose][compose-networking] for more details. - -> **Note:** The `runtime` field was removed from services in the 3.x version of -> the API in versions of docker-compose < 1.27.0. You will need to write your -> `docker-compose.yaml` file using the 2.x format or use docker-compose >= -> 1.27.0. See this [issue](https://github.com/docker/compose/issues/6239) for -> more details. - -```yaml -version: '2.3' - -services: - db: - image: mysql:5.7 - volumes: - - db_data:/var/lib/mysql - restart: always - environment: - MYSQL_ROOT_PASSWORD: somewordpress - MYSQL_DATABASE: wordpress - MYSQL_USER: wordpress - MYSQL_PASSWORD: wordpress - # All services must be on the same network to communicate. - network_mode: "bridge" - - wordpress: - depends_on: - - db - # When using the "bridge" network specify links. - links: - - db - image: wordpress:latest - ports: - - "8080:80" - restart: always - environment: - WORDPRESS_DB_HOST: db:3306 - WORDPRESS_DB_USER: wordpress - WORDPRESS_DB_PASSWORD: wordpress - WORDPRESS_DB_NAME: wordpress - # Specify the dns address if needed. - dns: - - 8.8.8.8 - # All services must be on the same network to communicate. - network_mode: "bridge" - # Specify the runtime used by Docker. Must be set up in - # /etc/docker/daemon.json. - runtime: "runsc" - -volumes: - db_data: {} -``` - -Once you have a `docker-compose.yaml` in the current directory you can start the -containers: - -```bash -docker-compose up -``` - -Once the containers have started you can access wordpress at -http://localhost:8080. - -Congrats! You now how a working wordpress site up and running using Docker -Compose. - -### What's next - -Learn how to deploy [WordPress with Kubernetes][wordpress-k8s]. - -[docker-compose]: https://docs.docker.com/compose/ -[docker-install]: ../quick_start/docker.md -[wordpress]: https://wordpress.com/ -[resolv.conf]: https://man7.org/linux/man-pages/man5/resolv.conf.5.html -[wordpress-k8s]: kubernetes.md -[compose-networking]: https://docs.docker.com/compose/networking/ diff --git a/g3doc/user_guide/tutorials/docker.md b/g3doc/user_guide/tutorials/docker.md deleted file mode 100644 index 9ca01da2a..000000000 --- a/g3doc/user_guide/tutorials/docker.md +++ /dev/null @@ -1,70 +0,0 @@ -# WordPress with Docker - -This page shows you how to deploy a sample [WordPress][wordpress] site using -[Docker][docker]. - -### Before you begin - -[Follow these instructions][docker-install] to install runsc with Docker. This -document assumes that the runtime name chosen is `runsc`. - -### Running WordPress - -Now, let's deploy a WordPress site using Docker. WordPress site requires two -containers: web server in the frontend, MySQL database in the backend. - -First, let's define a few environment variables that are shared between both -containers: - -```bash -export MYSQL_PASSWORD=${YOUR_SECRET_PASSWORD_HERE?} -export MYSQL_DB=wordpress -export MYSQL_USER=wordpress -``` - -Next, let's start the database container running MySQL and wait until the -database is initialized: - -```bash -docker run --runtime=runsc --name mysql -d \ - -e MYSQL_RANDOM_ROOT_PASSWORD=1 \ - -e MYSQL_PASSWORD="${MYSQL_PASSWORD}" \ - -e MYSQL_DATABASE="${MYSQL_DB}" \ - -e MYSQL_USER="${MYSQL_USER}" \ - mysql:5.7 - -# Wait until this message appears in the log. -docker logs mysql |& grep 'port: 3306 MySQL Community Server (GPL)' -``` - -Once the database is running, you can start the WordPress frontend. We use the -`--link` option to connect the frontend to the database, and expose the -WordPress to port 8080 on the localhost. - -```bash -docker run --runtime=runsc --name wordpress -d \ - --link mysql:mysql \ - -p 8080:80 \ - -e WORDPRESS_DB_HOST=mysql \ - -e WORDPRESS_DB_USER="${MYSQL_USER}" \ - -e WORDPRESS_DB_PASSWORD="${MYSQL_PASSWORD}" \ - -e WORDPRESS_DB_NAME="${MYSQL_DB}" \ - -e WORDPRESS_TABLE_PREFIX=wp_ \ - wordpress -``` - -Now, you can access the WordPress website pointing your favorite browser to -<http://localhost:8080>. - -Congratulations! You have just deployed a WordPress site using Docker. - -### What's next - -Learn how to deploy WordPress with [Kubernetes][wordpress-k8s] or -[Docker Compose][wordpress-compose]. - -[docker]: https://www.docker.com/ -[docker-install]: ../quick_start/docker.md -[wordpress]: https://wordpress.com/ -[wordpress-k8s]: kubernetes.md -[wordpress-compose]: docker-compose.md diff --git a/g3doc/user_guide/tutorials/knative.md b/g3doc/user_guide/tutorials/knative.md deleted file mode 100644 index 3f5207fcc..000000000 --- a/g3doc/user_guide/tutorials/knative.md +++ /dev/null @@ -1,88 +0,0 @@ -# Knative Services - -[Knative](https://knative.dev/) is a platform for running serverless workloads -on Kubernetes. This guide will show you how to run basic Knative workloads in -gVisor. - -## Prerequisites - -This guide assumes you have have a cluster that is capable of running gVisor -workloads. This could be a -[GKE Sandbox](https://cloud.google.com/kubernetes-engine/sandbox/) enabled -cluster on Google Cloud Platform or one you have set up yourself using -[containerd Quick Start](https://gvisor.dev/docs/user_guide/containerd/quick_start/). - -This guide will also assume you have Knative installed using -[Istio](https://istio.io/) as the network layer. You can follow the -[Knative installation guide](https://knative.dev/docs/install/install-serving-with-yaml/) -to install Knative. - -## Enable the RuntimeClass feature flag - -Knative allows the use of various parameters on Pods via -[feature flags](https://knative.dev/docs/serving/feature-flags/). We will enable -the -[runtimeClassName](https://knative.dev/docs/serving/feature-flags/#kubernetes-runtime-class) -feature flag to enable the use of the Kubernetes -[Runtime Class](https://kubernetes.io/docs/concepts/containers/runtime-class/). - -Edit the feature flags ConfigMap. - -```bash -kubectl edit configmap config-features -n knative-serving -``` - -Add the `kubernetes.podspec-runtimeclassname: enabled` to the `data` field. Once -you are finished the ConfigMap will look something like this (minus all the -system fields). - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-features - namespace: knative-serving - labels: - serving.knative.dev/release: v0.22.0 -data: - kubernetes.podspec-runtimeclassname: enabled -``` - -## Deploy the Service - -After you have set the Runtime Class feature flag you can now create Knative -services that specify a `runtimeClassName` in the spec. - -```bash -cat <<EOF | kubectl apply -f - -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: helloworld-go -spec: - template: - spec: - runtimeClassName: gvisor - containers: - - image: gcr.io/knative-samples/helloworld-go - env: - - name: TARGET - value: "gVisor User" -EOF -``` - -You can see the pods running and their Runtime Class. - -```bash -kubectl get pods -o=custom-columns='NAME:.metadata.name,RUNTIME CLASS:.spec.runtimeClassName,STATUS:.status.phase' -``` - -Output should look something like the following. Note that your service might -scale to zero. If you access it via it's URL you should get a new Pod. - -``` -NAME RUNTIME CLASS STATUS -helloworld-go-00002-deployment-646c87b7f5-5v68s gvisor Running -``` - -Congrats! Your Knative service is now running in gVisor! diff --git a/g3doc/user_guide/tutorials/kubernetes.md b/g3doc/user_guide/tutorials/kubernetes.md deleted file mode 100644 index 1ec6e71e9..000000000 --- a/g3doc/user_guide/tutorials/kubernetes.md +++ /dev/null @@ -1,236 +0,0 @@ -# WordPress with Kubernetes - -This page shows you how to deploy a sample [WordPress][wordpress] site using -[GKE Sandbox][gke-sandbox]. - -### Before you begin - -Take the following steps to enable the Kubernetes Engine API: - -1. Visit the [Kubernetes Engine page][project-selector] in the Google Cloud - Platform Console. -1. Create or select a project. - -### Creating a node pool with gVisor enabled - -Create a node pool inside your cluster with option `--sandbox type=gvisor` added -to the command, like below: - -```bash -gcloud beta container node-pools create sandbox-pool --cluster=${CLUSTER_NAME} --image-type=cos_containerd --sandbox type=gvisor -``` - -If you prefer to use the console, select your cluster and select the **ADD NODE -POOL** button: - - - -Then select the **Image type** with **Containerd** and select **Enable sandbox -with gVisor** option. Select other options as you like: - - - -### Check that gVisor is enabled - -The gvisor RuntimeClass is instantiated during node creation. You can check for -the existence of the gvisor RuntimeClass using the following command: - -```bash -kubectl get runtimeclasses -``` - -### Wordpress deployment - -Now, let's deploy a WordPress site using GKE Sandbox. WordPress site requires -two pods: web server in the frontend, MySQL database in the backend. Both -applications use PersistentVolumes to store the site data data. In addition, -they use secret store to share MySQL password between them. - -First, let's download the deployment configuration files to add the runtime -class annotation to them: - -```bash -curl -LO https://k8s.io/examples/application/wordpress/wordpress-deployment.yaml -curl -LO https://k8s.io/examples/application/wordpress/mysql-deployment.yaml -``` - -Add a **spec.template.spec.runtimeClassName** set to **gvisor** to both files, -as shown below: - -**wordpress-deployment.yaml:** - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: wordpress - labels: - app: wordpress -spec: - ports: - - port: 80 - selector: - app: wordpress - tier: frontend - type: LoadBalancer ---- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: wp-pv-claim - labels: - app: wordpress -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 20Gi ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: wordpress - labels: - app: wordpress -spec: - selector: - matchLabels: - app: wordpress - tier: frontend - strategy: - type: Recreate - template: - metadata: - labels: - app: wordpress - tier: frontend - spec: - runtimeClassName: gvisor # ADD THIS LINE - containers: - - image: wordpress:4.8-apache - name: wordpress - env: - - name: WORDPRESS_DB_HOST - value: wordpress-mysql - - name: WORDPRESS_DB_PASSWORD - valueFrom: - secretKeyRef: - name: mysql-pass - key: password - ports: - - containerPort: 80 - name: wordpress - volumeMounts: - - name: wordpress-persistent-storage - mountPath: /var/www/html - volumes: - - name: wordpress-persistent-storage - persistentVolumeClaim: - claimName: wp-pv-claim -``` - -**mysql-deployment.yaml:** - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: wordpress-mysql - labels: - app: wordpress -spec: - ports: - - port: 3306 - selector: - app: wordpress - tier: mysql - clusterIP: None ---- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: mysql-pv-claim - labels: - app: wordpress -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 20Gi ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: wordpress-mysql - labels: - app: wordpress -spec: - selector: - matchLabels: - app: wordpress - tier: mysql - strategy: - type: Recreate - template: - metadata: - labels: - app: wordpress - tier: mysql - spec: - runtimeClassName: gvisor # ADD THIS LINE - containers: - - image: mysql:5.6 - name: mysql - env: - - name: MYSQL_ROOT_PASSWORD - valueFrom: - secretKeyRef: - name: mysql-pass - key: password - ports: - - containerPort: 3306 - name: mysql - volumeMounts: - - name: mysql-persistent-storage - mountPath: /var/lib/mysql - volumes: - - name: mysql-persistent-storage - persistentVolumeClaim: - claimName: mysql-pv-claim -``` - -Note that apart from `runtimeClassName: gvisor`, nothing else about the -Deployment has is changed. - -You are now ready to deploy the entire application. Just create a secret to -store MySQL's password and *apply* both deployments: - -```bash -kubectl create secret generic mysql-pass --from-literal=password=${YOUR_SECRET_PASSWORD_HERE?} -kubectl apply -f mysql-deployment.yaml -kubectl apply -f wordpress-deployment.yaml -``` - -Wait for the deployments to be ready and an external IP to be assigned to the -Wordpress service: - -```bash -watch kubectl get service wordpress -``` - -Now, copy the service `EXTERNAL-IP` from above to your favorite browser to view -and configure your new WordPress site. - -Congratulations! You have just deployed a WordPress site using GKE Sandbox. - -### What's next - -To learn more about GKE Sandbox and how to run your deployment securely, take a -look at the [documentation][gke-sandbox-docs]. - -[gke-sandbox-docs]: https://cloud.google.com/kubernetes-engine/docs/how-to/sandbox-pods -[gke-sandbox]: https://cloud.google.com/kubernetes-engine/sandbox/ -[project-selector]: https://console.cloud.google.com/projectselector/kubernetes -[wordpress]: https://wordpress.com/ diff --git a/g3doc/user_guide/tutorials/node-pool-button.png b/g3doc/user_guide/tutorials/node-pool-button.png Binary files differdeleted file mode 100644 index bee0c11dc..000000000 --- a/g3doc/user_guide/tutorials/node-pool-button.png +++ /dev/null |
