From b778a827ea8614ead93e00ae9cbad13aab7ba173 Mon Sep 17 00:00:00 2001 From: Marco Vedovati Date: Wed, 3 Oct 2018 15:35:36 +0200 Subject: [PATCH] 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 --- install/README.md | 71 ++++++++++++++----- install/centos-installation-guide.md | 18 ----- install/docker/centos-docker-install.md | 7 -- install/docker/fedora-docker-install.md | 7 -- install/docker/opensuse-docker-install.md | 7 -- install/docker/rhel-docker-install.md | 7 -- install/docker/sles-docker-install.md | 7 -- install/docker/ubuntu-docker-install.md | 7 -- install/fedora-installation-guide.md | 18 ----- install/installing-with-kata-doc-to-script.md | 37 ++++++++++ install/installing-with-kata-manager.md | 37 ++++++++++ install/opensuse-installation-guide.md | 18 ----- install/rhel-installation-guide.md | 18 ----- install/sles-installation-guide.md | 18 ----- install/ubuntu-installation-guide.md | 18 ----- 15 files changed, 127 insertions(+), 168 deletions(-) create mode 100644 install/installing-with-kata-doc-to-script.md create mode 100644 install/installing-with-kata-manager.md diff --git a/install/README.md b/install/README.md index 9cbd5ad3..f5cd937c 100644 --- a/install/README.md +++ b/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). diff --git a/install/centos-installation-guide.md b/install/centos-installation-guide.md index 448eecd0..07611e85 100644 --- a/install/centos-installation-guide.md +++ b/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 diff --git a/install/docker/centos-docker-install.md b/install/docker/centos-docker-install.md index e99b4c5a..c2248a6e 100644 --- a/install/docker/centos-docker-install.md +++ b/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: diff --git a/install/docker/fedora-docker-install.md b/install/docker/fedora-docker-install.md index 5c5c991a..3e4228cc 100644 --- a/install/docker/fedora-docker-install.md +++ b/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: diff --git a/install/docker/opensuse-docker-install.md b/install/docker/opensuse-docker-install.md index 3c6f9526..7425c9c2 100644 --- a/install/docker/opensuse-docker-install.md +++ b/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: diff --git a/install/docker/rhel-docker-install.md b/install/docker/rhel-docker-install.md index c21d9b8f..24155cc9 100644 --- a/install/docker/rhel-docker-install.md +++ b/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: diff --git a/install/docker/sles-docker-install.md b/install/docker/sles-docker-install.md index 497b793e..a543e344 100644 --- a/install/docker/sles-docker-install.md +++ b/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: diff --git a/install/docker/ubuntu-docker-install.md b/install/docker/ubuntu-docker-install.md index 707b2cc2..0b6e01a2 100644 --- a/install/docker/ubuntu-docker-install.md +++ b/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: diff --git a/install/fedora-installation-guide.md b/install/fedora-installation-guide.md index e5036d3a..2d022bef 100644 --- a/install/fedora-installation-guide.md +++ b/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) diff --git a/install/installing-with-kata-doc-to-script.md b/install/installing-with-kata-doc-to-script.md new file mode 100644 index 00000000..19d14469 --- /dev/null +++ b/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`. diff --git a/install/installing-with-kata-manager.md b/install/installing-with-kata-manager.md new file mode 100644 index 00000000..9a3ea340 --- /dev/null +++ b/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. diff --git a/install/opensuse-installation-guide.md b/install/opensuse-installation-guide.md index 085065d2..5dfc6eae 100644 --- a/install/opensuse-installation-guide.md +++ b/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) diff --git a/install/rhel-installation-guide.md b/install/rhel-installation-guide.md index fe785218..ed0bde73 100644 --- a/install/rhel-installation-guide.md +++ b/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) diff --git a/install/sles-installation-guide.md b/install/sles-installation-guide.md index 5e285f35..f200d836 100644 --- a/install/sles-installation-guide.md +++ b/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" diff --git a/install/ubuntu-installation-guide.md b/install/ubuntu-installation-guide.md index ea624819..e91e4a7c 100644 --- a/install/ubuntu-installation-guide.md +++ b/install/ubuntu-installation-guide.md @@ -1,25 +1,7 @@ # Install Kata Containers on Ubuntu -> **Notes:** -> -> - Kata Containers packages are available for [Ubuntu\*](https://www.ubuntu.com) -> versions **16.04** and **18.04**. -> -> - 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 sh -c "echo 'deb http://download.opensuse.org/repositories/home:/katacontainers:/releases:/${ARCH}:/master/xUbuntu_$(lsb_release -rs)/ /' > /etc/apt/sources.list.d/kata-containers.list"