howto: k8s grammar and format changes

OGtrilliams · OGtrilliams · commit 7a99b7047148 · 2018-07-30T11:36:59.000-05:00
Went through and made a few grammar and format updates to make how-to guide easier to follow, as well as add direct links to project Github pages where applicable. Fixes: kata-containers#127 Signed-off-by: trilliams <tribecca@tribecc.us> howto: k8s grammar and format changes Went through and made a few grammar and format updates to make how-to guide easier to follow, as well as add direct links to project Github pages where applicable. Fixes: kata-containers#127 Signed-off-by: trilliams <tribecca@tribecc.us>
diff --git a/how-to/how-to-use-k8s-with-cri-containerd-and-kata.md b/how-to/how-to-use-k8s-with-cri-containerd-and-kata.md
@@ -1,65 +1,64 @@
 # How to use Kata Containers and CRI (containerd plugin) with Kubernetes
 
-This document describes how to set up a single-machine Kubernetes cluster. 
-The Kubernetes cluster will use the CRI containerd plugin and Kata Containers to launch untrusted workloads.
+This document describes how to set up a single-machine Kubernetes cluster. The Kubernetes cluster will use the [CRI containerd plugin](https://github.com/containerd/cri) and [Kata Containers](https://katacontainers.io) to launch untrusted workloads.
+
+## Requirements
 
-## Requirements 
 - Kubernetes, kubelet, kubeadm
 - cri-containerd
 - Kata Containers
 
-For information about the supported version of these components see 
-Kata Containers [versions.yaml](https://github.com/kata-containers/runtime/blob/master/versions.yaml) file.
+Note|
+----------------- |
+|For information about the supported versions of these components, see the  Kata Containers [versions.yaml](https://github.com/kata-containers/runtime/blob/master/versions.yaml) file. |
+
 
 ## Install containerd(with CRI plugin enabled)
 
 Follow the instructions from [CRI installation guide](http://github.com/containerd/cri/blob/master/docs/installation.md)
 
-<!---
 ```bash
 # Check if containerd is installed
 $ command -v containerd
 ```
---->
 
-## Install Kata Containers 
+## Install Kata Containers
 
 Follow the instructions to [install Kata](https://github.com/kata-containers/documentation/blob/master/install/README.md).
 
-<!---
 ```bash
 # Check if kata-runtime is installed
 $ command -v kata-runtime
 # Check kata is well configured
 $ kata-runtime kata-env
 ```
---->
 
 ## Install Kubernetes
-Install Kubernetes in your host.  See kubeadm [installation](https://kubernetes.io/docs/tasks/tools/install-kubeadm/)
-<!---
+Install Kubernetes in your host. See [kubeadm installation](https://kubernetes.io/docs/setup/independent/install-kubeadm/)
+
 ```bash
 # Check if kubadm is installed
 $ command -v kubeadm
 ```
---->
 
 ### Configure containerd to use Kata Containers
 
-The CRI containerd plugin support configuration for two runtime types.
+The CRI containerd plugin supports configuration for two runtime types.
 
-- Default runtime: A runtime that is used by default to run workloads.
-- Untrusted workload runtime: A runtime that will be used run untrusted workloads.
+- **Default runtime:** A runtime that is used by default to run workloads.
+- **Untrusted workload runtime:** A runtime that will be used to run untrusted workloads.
 
-#### Define the Kata runtime as `untrusted_workload_runtime` 
+#### Define the Kata runtime as `untrusted_workload_runtime`
 
-Configure the Kata runtime for untrusted workload with the [config option](https://github.com/containerd/cri/blob/v1.0.0-rc.0/docs/config.md)
-`plugins.cri.containerd.untrusted_workload_runtime`.
+Configure the Kata runtime for untrusted workloads with the [config option](https://github.com/containerd/cri/blob/v1.0.0-rc.0/docs/config.md) `plugins.cri.containerd.untrusted_workload_runtime`.
 
 Unless configured otherwise, the default runtime is set to `runc`.
+
 ```bash
 # Configure containerd to use Kata as untrusted_workload_runtime
 $ sudo mkdir -p /etc/containerd/
+```
+```bash
 $ cat << EOT | sudo tee /etc/containerd/config.toml
 [plugins]
     [plugins.cri.containerd]
@@ -71,23 +70,33 @@ EOT
 
 ### Configure Kubelet to use containerd
 
-In order to allow kubelet use containerd (using CRI interface) configure the service to
-point to containerd socket.
+
+
+
+
+
+In order to allow kubelet to use containerd (using CRI interface), configure the service to point to the `containerd` socket.
+
+- Configure k8s to use containerd
 
 ```bash
-# Configure k8s to use containerd
 $ sudo mkdir -p  /etc/systemd/system/kubelet.service.d/
+```
+```bash
 $ cat << EOF | sudo tee  /etc/systemd/system/kubelet.service.d/0-containerd.conf
 [Service]                                                 
 Environment="KUBELET_EXTRA_ARGS=--container-runtime=remote --runtime-request-timeout=15m --container-runtime-endpoint=unix:///run/containerd/containerd.sock"
 EOF
+```
+```bash
 $ sudo systemctl daemon-reload
 ```
 
 ### Optional: Configure proxy
 
-If you are behind a proxy this script will configure your proxy for docker
-kubelet and containerd.
+
+If you are behind a proxy, use the following script to configure your proxy for docker, kubelet, and containerd:
+
 
 ```bash
 # Set proxys
@@ -109,20 +118,30 @@ Environment="HTTPS_PROXY=${https_proxy}"
 Environment="NO_PROXY=${no_proxy}"
 EOT
 done
+```
+```bash
 $ sudo systemctl daemon-reload
 ```
 
-###  Start Kubernetes with kubeadm 
+###  Start Kubernetes with `kubeadm`
+
+
+- Make sure containerd is up and running
 
 ```bash
-# Mark sure containerd is up and running
 $ sudo systemctl restart containerd
 $ sudo systemctl status containerd
+```
+
+- Prevent conflicts of docker iptables rules & k8s pod communication
 
-# Prevent docker iptables rules conflict with k8s pod communication
+```bash
 $ sudo iptables -P FORWARD ACCEPT
+```
 
-# Start cluster using kubeadm
+-  Start cluster using `kubeadm`
+
+```bash
 $ sudo kubeadm init --skip-preflight-checks \
 --cri-socket /run/containerd/containerd.sock --pod-network-cidr=10.244.0.0/16
 
@@ -132,22 +151,19 @@ $ sudo -E kubectl get nodes
 $ sudo -E kubectl get pods
 ```
 
-### Install a pod network
-Install a pod network plugin is needed to allow pods communicate with each other.
+### Install a Pod Network
+
+A pod network plugin is needed to allow pods to communicate with each other.
+
+Install the `flannel` plugin by following the [Using kubeadm to Create a Cluster](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#instructions) guide, starting from the **Installing a pod network** section.
 
-Install flannel plugging, by following the instructions in the section *Installing a pod network*
-from [Using kubeadm to Create a Cluster ](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/)
-guide.
 
-<!---
 ```bash
 # Install a pod network using flannel
 # There is not a programmatic way to know last what flannel commit use
 # See https://github.com/coreos/flannel/issues/995
 $ sudo -E kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
 ```
---->
-
 
 ```bash
 # wait for pod network
@@ -166,19 +182,18 @@ $ sudo -E kubectl get pods --all-namespaces | grep dns | grep Running && echo "O
 
 ### Allow run pods in master node
 
-By default, the cluster will not schedule pods in the master node to allow that run:
+By default, the cluster will not schedule pods in the master node. To enable master node scheduling, run:
 
 ```bash
-# allow master node run pods
+# allow master node to run pods
 $ sudo -E kubectl taint nodes --all node-role.kubernetes.io/master-
 ```
 
 
-### Create a unstrusted pod using Kata Containers
+### Create an unstrusted pod using Kata Containers
+
+By default, all pods are created with the default runtime configured in CRI containerd plugin. If a pod has the `io.kubernetes.cri.untrusted-workload` annotation set to `"true"`, the CRI plugin runs the pod with the [Kata Containers runtime](https://github.com/kata-containers/runtime/blob/master/README.md).
 
-By default, all pods are created with the default runtime configured in CRI containerd plugin.
-If a pod has the `io.kubernetes.cri.untrusted-workload annotation` set as
-`"true"`, the CRI plugin will run the pod with the Kata Containers runtime.
 
 ```bash
 # Create untrusted pod configuration
@@ -195,19 +210,24 @@ spec:
     image: nginx
     
 EOT
+```
 
+```bash
 # Create untrusted pod
 $ sudo -E kubectl apply -f nginx-untrusted.yaml
-
+```
+```bash
 # Check pod is running
 $ sudo -E kubectl get pods
+```
 
+```bash
 # Check qemu is running
 $ ps aux | grep qemu
 ```
-### Delete created pod
 
 ```bash
+### Delete created pod
 # Delete pod
 $ sudo -E kubectl delete -f  nginx-untrusted.yaml
 ```
