docs: Add containerd install guide

Create a containerd installation guide.

Fixes: kata-containers#738.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

docs/install/containerd/containerd-install.md

@@ -0,0 +1,169 @@
+# Install Kata Containers with containerd
+
+> **Note:**
+>
+> - If Kata Containers and containerd are packaged by your distribution, we
+>   recommend you install these versions.
+
+> **Warning:**
+>
+> - These instructions install the **newest** versions of Kata Containers and
+>   containerd from binary release packages. These versions may not have been
+>   tested with your distribution version.
+>
+> - Since your package manager is not being used, it is **your**
+>   responsibility to ensure these packages are kept up-to-date when new
+>   versions are released.
+>
+> - You can check the latest version of Kata Containers by running
+>   `kata-runtime kata-check --only-list-releases`.
+
+1. Define a helper function
+
+   ```bash
+   $ die()
+   {
+       echo >&2 "ERROR: $*"
+       exit 1
+   }
+   ```
+
+1. Perform initial checks
+
+   Check to see if Kata Containers is already installed:
+
+   ```bash
+   $ command -v kata-runtime &>/dev/null && die "Please remove existing Kata Containers installation"
+   ```
+
+1. Install dependencies
+
+   ```bash
+   $ source /etc/os-release || source /usr/lib/os-release
+   $ packages='curl git hub jq'
+   $ case "$ID" in
+       centos|rhel) sudo yum -y remove $packages ;;
+       debian|ubuntu) sudo apt-get -y install $packages ;;
+       fedora) sudo dnf -y install $packages ;;
+       opensuse*|sles) sudo zypper install -y $packages ;;
+   $   *) die "Unsupported distro: $ID"
+   $ esac
+   ```
+
+1. Install Kata Containers
+
+   ```bash
+   $ tmpdir=$(mktemp -d)
+   $ pushd "$tmpdir" >/dev/null
+
+   $ repo=https://github.com/kata-containers/kata-containers
+
+   $ git clone --depth 1 "$repo" && cd kata-containers
+   $ version=$(hub release -L1 --exclude-prereleases)
+   $ download_url=$(hub release show -f "%as" "$version")
+   $ arch=$(uname -m)
+   $ [ "$arch" = x86_64 ] && arch="($arch|amd64)"
+   $ echo "$download_url" | egrep -q "$arch" || die "No release for '$arch architecture ($url)"
+   $ hub release download "$version"
+   $ file=$(echo "$download_url" | awk -F\/ '{print $NF}')
+   $ sudo tar -C / -xvf "${file}"
+
+   $ popd >/dev/null
+   ```
+
+   Allow the containerd service to find the Kata shim and users to find
+   important commands:
+
+   ```bash
+   $ sudo ln -sf /opt/kata/bin/containerd-shim-kata-v2 /usr/bin/
+   $ sudo ln -sf /opt/kata/bin/kata-runtime /usr/bin
+   $ sudo ln -sf /opt/kata/bin/kata-collect-data.sh /usr/bin/
+   ```
+
+   Show version details:
+
+   ```bash
+   $ kata-runtime --version
+   ```
+
+1. Install containerd
+
+   ```bash
+   $ tmpdir=$(mktemp -d)
+   $ pushd "$tmpdir" >/dev/null
+
+   $ repo=https://github.com/containerd/containerd
+
+   $ git clone --depth 1 "$repo" && cd containerd
+   $ version=$(hub release -L1 --exclude-prereleases)
+   $ download_url=$(hub release show -f "%as" "$version")
+   $ hub release download "$version"
+   $ file=$(echo "$download_url" | awk -F\/ '{print $NF}')
+   $ sudo tar -C /usr/local -xvf "${file}"
+
+   $ popd >/dev/null
+   ```
+
+1. Configure containerd
+
+   ```bash
+   $ systemctl list-unit-files --type service | egrep -q "^containerd.service\>" && die "containerd already installed"
+
+   $ tmpdir=$(mktemp -d)
+   $ pushd "$tmpdir" >/dev/null
+
+   $ curl -O https://raw.githubusercontent.com/containerd/containerd/master/containerd.service
+   $ printf "# %s: Installed for Kata Containers\n" $(date -Iseconds) | tee -a containerd.service
+   $ sudo mkdir -p /etc/systemd/system/
+   $ sudo cp containerd.service /etc/systemd/system/
+   $ sudo systemctl daemon-reload
+
+   $ popd >/dev/null
+   ```
+
+   Backup the original containerd configuration:
+
+   ```bash
+   $ sudo mkdir -p /etc/containerd/
+   $ cfg="/etc/containerd/config.toml"
+   $ [ -e "$cfg" ] || sudo touch "$cfg"
+   $ sudo grep -q "io.containerd.kata.v2" "$cfg" || sudo cp "$cfg" "${cfg}.ORIGINAL"
+   ```
+
+   Add the Kata Containers configuration details:
+
+   ```bash
+   $ sudo grep -q "io.containerd.kata.v2" "$cfg" || cat <<EOT | sudo tee -a "$cfg"
+   $ [plugins]
+     	[plugins.cri]
+     		[plugins.cri.containerd]
+     			default_runtime_name = "kata"
+     		[plugins.cri.containerd.runtimes.kata]
+     			runtime_type = "io.containerd.kata.v2"
+     EOT
+   ```
+
+   Start the service:
+
+   ```bash
+   $ sudo systemctl start containerd
+   ```
+
+1. Clean up
+
+   ```bash
+   $ unset die
+   ```
+
+1. Run Kata Containers
+
+   You are now ready to run Kata Containers:
+
+   ```bash
+   $ image="docker.io/library/busybox:latest"
+   $ sudo ctr image pull "$image"
+   $ sudo ctr run --runtime "io.containerd.kata.v2" --rm -t "$image" test-kata uname -r
+   ```
+
+   The previous command shows details of the kernel version running inside the
+   container, which is different to the host kernel version.