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,181 @@
+# Install Kata Containers with containerd
+
+> **Warning:**
+>
+> These instructions install containerd and Kata Containers from binary
+> release packages. It is your responsibility to ensure these packages are
+> kept current as new versions are released.
+>
+> To check for the latest version of Kata Containers,
+> run `kata-runtime kata-check --only-list-releases`.
+
+1. Define helper functions
+
+   ```bash
+   $ die()
+   {
+       echo >&2 "ERROR: $*"
+       exit 1
+   }
+
+   $ github_get_latest_release()
+   {
+      local url="$1"
+
+      local latest=$(curl -sL "$url" | jq -r '.[].tag_name | select(contains("-") | not)' | sort -t "." -k1,1n -k2,2n -k3,3n | tail -1 || true)
+      [ -z "$latest" ] && die "Cannot determine latest release from $url"
+
+      echo "$latest"
+   }
+
+   $ github_get_release_url()
+   {
+      local url="$1"
+      local version="$2"
+
+      download_url=$(curl -sL "$url" | jq --arg version "$version" -r '.[] | select(.tag_name == $version) | .assets[0].browser_download_url' || true)
+      [ -z "$download_url" ] && die "Cannot determine download URL for version $version ($url)"
+
+      local arch=$(uname -m)
+      [ "$arch" = x86_64 ] && arch="($arch|amd64)"
+      echo "$download_url" | egrep -q "$arch" || die "No release for '$arch architecture ($url)"
+
+      echo "$download_url"
+   }
+
+   $ github_download_latest_release()
+   {
+       local url="$1"
+
+       local tmpdir=$(mktemp -d)
+       pushd "$tmpdir" >/dev/null
+
+       local latest=$(github_get_latest_release "$url")
+       local download_url=$(github_get_release_url "$url" "$latest")
+
+       curl -sLO "$download_url"
+       local filename=$(echo "$download_url" | awk -F\/ '{print $NF}')
+
+       ls -d $PWD/${filename}
+
+       popd >/dev/null
+   }
+   ```
+
+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 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
+
+   $ url="https://api.github.com/repos/kata-containers/runtime/releases"
+   $ file=$(github_download_latest_release "$url")
+   $ sudo tar -C / -xvf "${file}"
+   ```
+
+   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
+   $ url=https://api.github.com/repos/containerd/containerd/releases
+   $ file=$(github_download_latest_release "$url")
+   $ sudo tar -C /usr/local -xvf "${file}"
+   ```
+
+1. Configure containerd
+
+   ```bash
+   $ systemctl list-unit-files --type service | egrep -q "^containerd.service\>" && die "containerd already installed"
+   $ tmpdir=$(mktemp -d)
+   $ pushd "$tmpdir"
+   $ 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
+   ```
+
+   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
+   $ unset github_get_latest_release
+   $ unset github_get_release_url
+   $ unset github_download_latest_release
+   ```
+
+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.