install: Refactor installation instructions

Refactor installation instruction to minimize duplicate content,
to document package source verification process, and to remove
some of the typos.

Fixes: #263

Signed-off-by: Marco Vedovati <mvedovati@suse.com>

install/README.md

@@ -1,21 +1,49 @@
 # Kata Containers installation user guides
 
-* [Prerequisites](#prerequisites)
-* [Installing Kata Containers](#installing-kata-containers)
-    * [Distros](#distros)
-    * [Cloud services](#cloud-services)
-* [Further information](#further-information)
+- [Prerequisites](#prerequisites)
+- [Installing on a Linux System](#installing-on-a-linux-system)
+    * [Automatic Installation](#automatic-installation)
+    * [Scripted Installation](#scripted-installation)
+    * [Manual Installation](#manual-installation)
+        + [Supported Distributions](#supported-distributions)
+- [Installing on a Cloud Service Platform](#installing-on-a-cloud-service-platform)
+- [Further information](#further-information)
 
 ## Prerequisites
-
 Kata Containers requires nested virtualization or bare metal.
 See the
 [hardware requirements](https://github.com/kata-containers/runtime/blob/master/README.md#hardware-requirements)
 to see if your system is capable of running Kata Containers.
 
-## Installing Kata Containers
+## Installing on a Linux System
+Here's an overview of the different installation methods available. All of these will equally result in a system
+configured to run Kata Containers.
+
+|Installation method                                        |Suggested for                            |Supported on                             |
+|-----------------------------------------------------------|-----------------------------------------|-----------------------------------------|
+|[Automatic](#automatic-installation)                       |Quick installation; new users            |[distros list](#supported-distributions) |
+|[Scripted](#scripted-installation)                         |Generating installation scripts          |[distros list](#supported-distributions) |
+|[Manual](#manual-installation)                             |Full control over each installation step |[distros list](#supported-distributions) |
+|[Build from sources](#../Developer-Guide.md#initial-setup) |Developers and hackers                   |any distro                               |
+
+### Automatic Installation
+You can easily install Kata packages [using kata-manager](installing-with-kata-manager.md).
+
+### Scripted Installation
+You can generate installation scripts [using kata-doc-to-script](installing-with-kata-doc-to-script.md).
+
+### Manual Installation
+Manual installation instructions are available for [these distributions](#supported-distributions) and document how to:
+1. Add the Kata Containers repository to your distro package manager and import the packages signing key.
+2. Install the Kata Containers packages.
+3. Install a supported container manager.
+4. Configure the container manager to use `kata-runtime` as the default OCI runtime.
 
-> **Notes:**
+> **Notes on upgrading**:
+> - If you are installing Kata Containers on a system that already has Clear Containers or `runv` installed,
+>  first read [the upgrading document](../Upgrading.md).
+
+> **Notes on releases**:
 > - [This download server](http://download.opensuse.org/repositories/home:/katacontainers:/releases:/)
 > hosts the Kata Containers packages built by OBS for all the supported architectures.
 > Packages are available for the latest and stable releases (more info [here](https://github.com/kata-containers/documentation/blob/master/Stable-Branch-Strategy.md)).
@@ -26,21 +54,28 @@ to see if your system is capable of running Kata Containers.
 > - When choosing a stable release, replace all `master` occurrences in the URLs
 > with a `stable-x.y` version available on the [download server](http://download.opensuse.org/repositories/home:/katacontainers:/releases:/).
 
-### Distros
-
-* [CentOS](centos-installation-guide.md)
-* [Fedora](fedora-installation-guide.md)
-* [Red Hat](rhel-installation-guide.md)
-* [OpenSuse](opensuse-installation-guide.md)
-* [Ubuntu](ubuntu-installation-guide.md)
-* [SLES](sles-installation-guide.md)
+> **Notes on packages source verification**:
+> - The Kata packages hosted on the download server are signed with GPG to ensure integrity and authenticity.
+>
+> - The public key used to sign packages is available [at this link](https://github.com/kata-containers/tests/data/rpm-signkey.pub); the fingerprint is `9FDC0CB6 3708CF80 3696E2DC D0B37B82 6063F3ED`.
+>
+> - Only trust these signing key and fingerprint and don't disable GPG checks, otherwise packages
+> source and authenticity cannot be guaranteed.
 
-### Cloud services
+#### Supported Distributions
+|Distro specific installation instructions                          | Versions        |
+|-------------------------------------------------------------------|-----------------|
+|[CentOS](centos-installation-guide.md)                             | 7               |
+|[Fedora](fedora-installation-guide.md)                             | 27, 28          |
+|[openSUSE](opensuse-installation-guide.md)                         | Leap (42.3)     |
+|[Red Hat Enterprise Linux (RHEL)](rhel-installation-guide.md)      | 7               |
+|[SUSE Linux Enterprise Server (SLES)](sles-installation-guide.md)  | SLES 12 SP3     |
+|[Ubuntu](ubuntu-installation-guide.md)                             | 16.04, 18.04    |
 
+## Installing on a Cloud Service Platform
 * [Google Compute Engine (GCE)](gce-installation-guide.md)
 
 ## Further information
-
 * The [upgrading document](../Upgrading.md).
 * The [developer guide](../Developer-Guide.md).
 * The [runtime documentation](https://github.com/kata-containers/runtime/blob/master/README.md).

install/centos-installation-guide.md

@@ -1,25 +1,7 @@
 # Install Kata Containers on CentOS
 
-> **Notes:**
->
-> - Kata Containers packages are available for [CentOS\*](https://www.centos.org)
->   version 7.
->
-> - If you are installing on a system that already has Clear Containers or `runv` installed,
->   first read [the upgrading document](../Upgrading.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
-
 1. Install the Kata Containers components with the following commands:
 
-   > **Note:** This installation channel is not secure since the repository currently
-   > redirects download URLs to `http`.
-
    ```bash
    $ source /etc/os-release
    $ sudo yum -y install yum-utils

install/docker/centos-docker-install.md

@@ -4,13 +4,6 @@
 >
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../centos-installation-guide.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
 
 1. Install the latest version of Docker with the following commands:
 

install/docker/fedora-docker-install.md

@@ -4,13 +4,6 @@
 >
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../fedora-installation-guide.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
 
 1. Install the latest version of Docker with the following commands:
 

install/docker/opensuse-docker-install.md

@@ -4,13 +4,6 @@
 >
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../opensuse-installation-guide.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
 
 1. Install the latest version of Docker with the following commands:
 

install/docker/rhel-docker-install.md

@@ -4,13 +4,6 @@
 >
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../rhel-installation-guide.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
 
 1. Install the latest version of Docker with the following commands:
 

install/docker/sles-docker-install.md

@@ -4,13 +4,6 @@
 >
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../sles-installation-guide.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
 
 1. Install the latest version of Docker with the following commands:
 

install/docker/ubuntu-docker-install.md

@@ -4,13 +4,6 @@
 >
 > - This guide assumes you have
 >   [already installed the Kata Containers packages](../ubuntu-installation-guide.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
 
 1. Install the latest version of Docker with the following commands:
 

install/fedora-installation-guide.md

@@ -1,25 +1,7 @@
 # Install Kata Containers on Fedora
 
-> **Notes:**
->
-> - Kata Containers packages are available for [Fedora\*](https://fedoraproject.org)
->   versions **27** and **28**.
->
-> - If you are installing on a system that already has Clear Containers or `runv` installed,
->   first read [the upgrading document](../Upgrading.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
-
 1. Install the Kata Containers components with the following commands:
 
-   > **Note:** This installation channel is not secure since the repository currently
-   > redirects download URLs to `http`.
-
    ```bash
    $ source /etc/os-release
    $ ARCH=$(arch)

install/installing-with-kata-doc-to-script.md

@@ -0,0 +1,37 @@
+# Installing with kata-doc-to-script
+
+* [Introduction](#introduction)
+* [Packages Installation](#packages-installation)
+* [Docker Installation and Setup](#docker-installation-and-setup)
+
+## Introduction
+[`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh)
+can be used to generate installation bash scripts from [these installation instructions](README.md#supported-distributions).
+
+> Note:
+> - Only the Docker container manager installation can be scripted. For other setups you will need to
+install and configure the container manager manually.
+
+## Packages Installation
+```
+$ source /etc/os-release
+$ curl -fsSL -O https://raw.githubusercontent.com/kata-containers/documentation/master/install/${ID}-installation-guide.md
+$ bash -c "$(curl -fsSL \
+    https://raw.githubusercontent.com/kata-containers/tests/master/.ci/kata-doc-to-script.sh) \
+    ${ID}-installation-guide.md \
+    ${ID}-install.sh"
+```
+
+If for example your distribution is CentOS, this will generate a runnable shell script called `centos-install.sh`.
+
+## Docker Installation and Setup
+```
+$ source /etc/os-release
+$ curl -fsSL -O https://raw.githubusercontent.com/kata-containers/documentation/master/install/docker/${ID}-docker-install.md
+$ bash -c "$(curl -fsSL \
+    https://raw.githubusercontent.com/kata-containers/tests/master/.ci/kata-doc-to-script.sh) \
+    ${ID}-docker-install.md \
+    ${ID}-docker-install.sh"
+```
+
+If for example your distribution is CentOS, this will generate a runnable shell script called `centos-docker-install.sh`.

install/installing-with-kata-manager.md

@@ -0,0 +1,37 @@
+# Installing with kata-manager
+
+* [Introduction](#Introduction)
+* [Full Installation](#full-installation)
+* [Install the Kata packages only](#install-the-kata-packages-only)
+* [Further Information](#further-information)
+
+## Introduction
+`kata-manager` automates the Kata Containers installation procedure documented for [these Linux distributions](README.md#supported-distributions).
+
+> Note:
+> - Full installation mode is only available for Docker container manager. For other setups, you
+> can still use `kata-manager` to [install Kata package](#install-kata-packages-only), and then setup your container manager manually.
+
+## Full Installation
+This command will:
+1. install Kata Containers packages,
+2. install Docker,
+3. configure Docker to use the kata OCI runtime by default.
+
+```
+$ bash -c "$(curl -fsSL \
+$ https://raw.githubusercontent.com/kata-containers/tests/master/cmd/kata-manager/kata-manager.sh) \
+ install-docker-system"
+```
+
+## Install the Kata packages only
+This command will only install Kata Containers packages.
+
+```
+$ bash -c "$(curl -fsSL \
+$ https://raw.githubusercontent.com/kata-containers/tests/master/cmd/kata-manager/kata-manager.sh) \
+ install-packages"
+```
+
+## Further Information
+`kata-manager` can do much more; refer to [`kata-manager` page](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager) for more information.

install/opensuse-installation-guide.md

@@ -1,25 +1,7 @@
 # Install Kata Containers on openSUSE Leap
 
-> **Notes:**
->
-> - Kata Containers packages are available for [openSUSE\*](https://www.opensuse.org/)
->   version 43.2.
->
-> - If you are installing on a system that already has Clear Containers or `runv` installed,
->   first read [the upgrading document](../Upgrading.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
-
 1. Install the Kata Containers components with the following commands:
 
-   > **Note:** This installation channel is not secure since the repository currently
-   > redirects download URLs to `http`.
-
    ```bash
    $ source /etc/os-release
    $ ARCH=$(arch)

install/rhel-installation-guide.md

@@ -1,25 +1,7 @@
 # Install Kata Containers on RHEL
 
-> **Notes:**
->
-> - Kata Containers packages are available for [RHEL\*](https://www.redhat.com)
->   version 7.
->
-> - If you are installing on a system that already has Clear Containers or `runv` installed,
->   first read [the upgrading document](../Upgrading.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
-
 1. Install the Kata Containers components with the following commands:
 
-   > **Note:** This installation channel is not secure since the repository currently
-   > redirects download URLs to `http`.
-
    ```bash
    $ source /etc/os-release
    $ ARCH=$(arch)

install/sles-installation-guide.md

@@ -1,25 +1,7 @@
 # Install Kata Containers on SLES
 
-> **Notes:**
->
-> - Kata Containers packages are available for [openSUSE\*](https://www.opensuse.org/)
->   version 43.2.
->
-> - If you are installing on a system that already has Clear Containers or `runv` installed,
->   first read [the upgrading document](../Upgrading.md).
->
-> - If you do not want to copy or type all these instructions by hand, you can use the
->   [`kata-manager`](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager/kata-manager.sh)
->   script to install the packaged system including your chosen container
->   manager. Alternatively, you can generate a runnable shell script from
->   individual documents using the
->   [`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh) script.
-
 1. Install the Kata Containers components with the following commands:
 
-   > **Note:** This installation channel is not secure since the repository currently
-   > redirects download URLs to `http`.
-
    ```bash
    $ ARCH=$(arch)
    $ sudo -E zypper addrepo "http://download.opensuse.org/repositories/home:/katacontainers:/releases:/${ARCH}:/master/SLE_12_SP3/home:katacontainers:releases:${ARCH}:master.repo"