mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-09-13 21:09:31 +00:00
docs: Add containerd install guide
Create a containerd installation guide and a new `kata-manager` script
for 2.0 that automated the steps outlined in the guide.
Also cleaned up and improved the installation documentation in various
ways, the most significant being:
- Added legacy install link for 1.x installs.
- Official packages section:
- Removed "Contact" column (since it was empty!)
- Reworded "Versions" column to clarify the versions are a minimum
(to reduce maintenance burden).
- Add a column to show which installation methods receive automatic updates.
- Modified order of installation options in table and document to
de-emphasise automatic installation and promote official packages
and snap more.
- Removed sections no longer relevant for 2.0.
Fixes: #738.
Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt
@@ -1,98 +1,82 @@
|
||||
# Kata Containers installation user guides
|
||||
|
||||
- [Kata Containers installation user guides](#kata-containers-installation-user-guides)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Packaged installation methods](#packaged-installation-methods)
|
||||
- [Official packages](#official-packages)
|
||||
- [Automatic Installation](#automatic-installation)
|
||||
- [Snap Installation](#snap-installation)
|
||||
- [Scripted Installation](#scripted-installation)
|
||||
- [Manual Installation](#manual-installation)
|
||||
- [Build from source installation](#build-from-source-installation)
|
||||
- [Installing on a Cloud Service Platform](#installing-on-a-cloud-service-platform)
|
||||
- [Further information](#further-information)
|
||||
* [Kata Containers installation user guides](#kata-containers-installation-user-guides)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [Legacy installation](#legacy-installation)
|
||||
* [Packaged installation methods](#packaged-installation-methods)
|
||||
* [Official packages](#official-packages)
|
||||
* [Snap Installation](#snap-installation)
|
||||
* [Automatic Installation](#automatic-installation)
|
||||
* [Manual Installation](#manual-installation)
|
||||
* [Build from source installation](#build-from-source-installation)
|
||||
* [Installing on a Cloud Service Platform](#installing-on-a-cloud-service-platform)
|
||||
* [Further information](#further-information)
|
||||
|
||||
The following is an overview of the different installation methods available. All of these methods equally result
|
||||
in a system configured to run Kata Containers.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Kata Containers requires nested virtualization or bare metal.
|
||||
See the
|
||||
[hardware requirements](../../src/runtime/README.md#hardware-requirements)
|
||||
[hardware requirements](/src/runtime/README.md#hardware-requirements)
|
||||
to see if your system is capable of running Kata Containers.
|
||||
|
||||
## Legacy installation
|
||||
|
||||
If you wish to install a legacy 1.x version of Kata Containers, see
|
||||
[the Kata Containers 1.x installation documentation](https://github.com/kata-containers/documentation/tree/master/install/).
|
||||
|
||||
## Packaged installation methods
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - Packaged installation methods uses your distribution's native package format (such as RPM or DEB).
|
||||
> - You are strongly encouraged to choose an installation method that provides
|
||||
> automatic updates, to ensure you benefit from security updates and bug fixes.
|
||||
|
||||
| Installation method | Description | Distributions supported |
|
||||
|------------------------------------------------------|-----------------------------------------------------------------------------------------|--------------------------------------|
|
||||
| [Automatic](#automatic-installation) |Run a single command to install a full system | |
|
||||
| [Using snap](#snap-installation) |Easy to install and automatic updates |any distro that supports snapd |
|
||||
| [Using official distro packages](#official-packages) |Kata packages provided by Linux distributions official repositories | |
|
||||
| [Scripted](#scripted-installation) |Generates an installation script which will result in a working system when executed | |
|
||||
| [Manual](#manual-installation) |Allows the user to read a brief document and execute the specified commands step-by-step | |
|
||||
| Installation method | Description | Automatic updates | Use case |
|
||||
|------------------------------------------------------|---------------------------------------------------------------------|-------------------|----------------------------------------------------------|
|
||||
| [Using official distro packages](#official-packages) | Kata packages provided by Linux distributions official repositories | yes | Recommended for most users. |
|
||||
| [Using snap](#snap-installation) | Easy to install | yes | Good alternative to official distro packages. |
|
||||
| [Automatic](#automatic-installation) | Run a single command to install a full system | **No!** | For those wanting the latest release quickly. |
|
||||
| [Manual](#manual-installation) | Follow a guide step-by-step to install a working system | **No!** | For those who want the latest release with more control. |
|
||||
| [Build from source](#build-from-source-installation) | Build the software components manually | **No!** | Power users and developers only. |
|
||||
|
||||
### Official packages
|
||||
|
||||
Kata packages are provided by official distribution repositories for:
|
||||
|
||||
| Distribution (link to packages) | Versions | Contacts |
|
||||
| -------------------------------------------------------- | ------------------------------------------------------------------------------ | -------- |
|
||||
| [CentOS](centos-installation-guide.md) | 8 | |
|
||||
| [Fedora](fedora-installation-guide.md) | 32, Rawhide | |
|
||||
| [SUSE Linux Enterprise (SLE)](sle-installation-guide.md) | SLE 15 SP1, 15 SP2 | |
|
||||
| [openSUSE](opensuse-installation-guide.md) | [Leap 15.1](opensuse-leap-15.1-installation-guide.md)<br>Leap 15.2, Tumbleweed | |
|
||||
| Distribution (link to installation guide) | Minimum versions |
|
||||
|----------------------------------------------------------|--------------------------------------------------------------------------------|
|
||||
| [CentOS](centos-installation-guide.md) | 8 |
|
||||
| [Fedora](fedora-installation-guide.md) | 32, Rawhide |
|
||||
| [openSUSE](opensuse-installation-guide.md) | [Leap 15.1](opensuse-leap-15.1-installation-guide.md)<br>Leap 15.2, Tumbleweed |
|
||||
| [SUSE Linux Enterprise (SLE)](sle-installation-guide.md) | SLE 15 SP1, 15 SP2 |
|
||||
|
||||
|
||||
### Automatic Installation
|
||||
|
||||
[Use `kata-manager`](installing-with-kata-manager.md) to automatically install Kata packages.
|
||||
> **Note::**
|
||||
>
|
||||
> All users are encouraged to uses the official distribution versions of Kata
|
||||
> Containers unless they understand the implications of alternative methods.
|
||||
|
||||
### Snap Installation
|
||||
|
||||
> **Note:** The snap installation is available for all distributions which support `snapd`.
|
||||
|
||||
[](https://snapcraft.io/kata-containers)
|
||||
|
||||
[Use snap](snap-installation-guide.md) to install Kata Containers from https://snapcraft.io.
|
||||
|
||||
### Scripted Installation
|
||||
[Use `kata-doc-to-script`](installing-with-kata-doc-to-script.md) to generate installation scripts that can be reviewed before they are executed.
|
||||
### Automatic Installation
|
||||
|
||||
[Use `kata-manager`](/utils/README.md) to automatically install a working Kata Containers system.
|
||||
|
||||
### Manual Installation
|
||||
Manual installation instructions are available for [these distributions](#packaged-installation-methods) 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 Containers as the default OCI runtime. Or, for Kata Containers 1.5.0 or above, configure the
|
||||
`io.containerd.kata.v2` to be the runtime shim (see [containerd runtime v2 (shim API)](https://github.com/containerd/containerd/tree/master/runtime/v2)
|
||||
and [How to use Kata Containers and CRI (containerd plugin) with Kubernetes](../how-to/how-to-use-k8s-with-cri-containerd-and-kata.md)).
|
||||
|
||||
> **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](../Stable-Branch-Strategy.md)).
|
||||
>
|
||||
> - The following guides apply to the latest Kata Containers release
|
||||
> (a.k.a. `master` release).
|
||||
>
|
||||
> - 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:/).
|
||||
|
||||
> **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://raw.githubusercontent.com/kata-containers/tests/master/data/rpm-signkey.pub); the fingerprint is `9FDC0CB6 3708CF80 3696E2DC D0B37B82 6063F3ED`.
|
||||
>
|
||||
> - Only trust the signing key and fingerprint listed in the previous bullet point. Do not disable GPG checks,
|
||||
> otherwise packages source and authenticity is not guaranteed.
|
||||
Follow the [containerd installation guide](container-manager/containerd/containerd-install.md).
|
||||
|
||||
## Build from source installation
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - Power users who decide to build from sources should be aware of the
|
||||
@@ -104,6 +88,7 @@ who are comfortable building software from source to use the latest component
|
||||
versions. This is not recommended for normal users.
|
||||
|
||||
## Installing on a Cloud Service Platform
|
||||
|
||||
* [Amazon Web Services (AWS)](aws-installation-guide.md)
|
||||
* [Google Compute Engine (GCE)](gce-installation-guide.md)
|
||||
* [Microsoft Azure](azure-installation-guide.md)
|
||||
@@ -111,6 +96,7 @@ versions. This is not recommended for normal users.
|
||||
* [VEXXHOST OpenStack Cloud](vexxhost-installation-guide.md)
|
||||
|
||||
## Further information
|
||||
|
||||
* The [upgrading document](../Upgrading.md).
|
||||
* The [developer guide](../Developer-Guide.md).
|
||||
* The [runtime documentation](../../src/runtime/README.md).
|
||||
|
||||
128
docs/install/container-manager/containerd/containerd-install.md
Normal file
128
docs/install/container-manager/containerd/containerd-install.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# Install Kata Containers with containerd
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> - If Kata Containers and / or containerd are packaged by your distribution,
|
||||
> we recommend you install these versions to ensure they are updated when
|
||||
> new releases are available.
|
||||
|
||||
> **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.
|
||||
>
|
||||
> - If you decide to proceed and install a Kata Containers release, you can
|
||||
> still check for the latest version of Kata Containers by running
|
||||
> `kata-runtime kata-check --only-list-releases`.
|
||||
>
|
||||
> - These instructions will not work for Fedora 31 and higher since those
|
||||
> distribution versions only support cgroups version 2 by default. However,
|
||||
> Kata Containers currently requires cgroups version 1 (on the host side). See
|
||||
> https://github.com/kata-containers/kata-containers/issues/927 for further
|
||||
> details.
|
||||
|
||||
## Install Kata Containers
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> If your distribution packages Kata Containers, we recommend you install that
|
||||
> version. If it does not, or you wish to perform a manual installation,
|
||||
> continue with the steps below.
|
||||
|
||||
- Download a release from:
|
||||
|
||||
- https://github.com/kata-containers/kata-containers/releases
|
||||
|
||||
Note that Kata Containers uses [semantic versioning](https://semver.org) so
|
||||
you should install a version that does *not* include a dash ("-"), since this
|
||||
indicates a pre-release version.
|
||||
|
||||
- Unpack the downloaded archive.
|
||||
|
||||
Kata Containers packages use a `/opt/kata/` prefix so either add that to
|
||||
your `PATH`, or create symbolic links for the following commands. The
|
||||
advantage of using symbolic links is that the `systemd(1)` configuration file
|
||||
for containerd will not need to be modified to allow the daemon to find this
|
||||
binary (see the [section on installing containerd](#install-containerd) below).
|
||||
|
||||
| Command | Description |
|
||||
|-|-|
|
||||
| `/opt/kata/bin/containerd-shim-kata-v2` | The main Kata 2.x binary |
|
||||
| `/opt/kata/bin/kata-collect-data.sh` | Data collection script used for [raising issues](https://github.com/kata-containers/kata-containers/issues) |
|
||||
| `/opt/kata/bin/kata-runtime` | Utility command |
|
||||
|
||||
- Check installation by showing version details:
|
||||
|
||||
```bash
|
||||
$ kata-runtime --version
|
||||
```
|
||||
|
||||
## Install containerd
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> If your distribution packages containerd, we recommend you install that
|
||||
> version. If it does not, or you wish to perform a manual installation,
|
||||
> continue with the steps below.
|
||||
|
||||
- Download a release from:
|
||||
|
||||
- https://github.com/containerd/containerd/releases
|
||||
|
||||
- Unpack the downloaded archive.
|
||||
|
||||
- Configure containerd
|
||||
|
||||
- Download the standard `systemd(1)` service file and install to
|
||||
`/etc/systemd/system/`:
|
||||
|
||||
- https://raw.githubusercontent.com/containerd/containerd/master/containerd.service
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - You will need to reload the systemd configuration after installing this
|
||||
> file.
|
||||
>
|
||||
> - If you have not created a symbolic link for
|
||||
> `/opt/kata/bin/containerd-shim-kata-v2`, you will need to modify this
|
||||
> file to ensure the containerd daemon's `PATH` contains `/opt/kata/`.
|
||||
> See the `Environment=` command in `systemd.exec(5)` for further
|
||||
> details.
|
||||
|
||||
- Add the Kata Containers configuration to the containerd configuration file:
|
||||
|
||||
```toml
|
||||
[plugins]
|
||||
[plugins.cri]
|
||||
[plugins.cri.containerd]
|
||||
default_runtime_name = "kata"
|
||||
|
||||
[plugins.cri.containerd.runtimes.kata]
|
||||
runtime_type = "io.containerd.kata.v2"
|
||||
```
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> The containerd daemon needs to be able to find the
|
||||
> `containerd-shim-kata-v2` binary to allow Kata Containers to be created.
|
||||
|
||||
- Start the containerd service.
|
||||
|
||||
## Test the installation
|
||||
|
||||
You are now ready to run Kata Containers. You can perform a simple test by
|
||||
running the following commands:
|
||||
|
||||
```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 last command above shows details of the kernel version running inside the
|
||||
container, which will likely be different to the host kernel version.
|
||||
@@ -1,47 +0,0 @@
|
||||
# Installing with `kata-doc-to-script`
|
||||
|
||||
* [Introduction](#introduction)
|
||||
* [Packages Installation](#packages-installation)
|
||||
* [Docker Installation and Setup](#docker-installation-and-setup)
|
||||
|
||||
## Introduction
|
||||
Use [these installation instructions](README.md#packaged-installation-methods) together with
|
||||
[`kata-doc-to-script`](https://github.com/kata-containers/tests/blob/master/.ci/kata-doc-to-script.sh)
|
||||
to generate installation bash scripts.
|
||||
|
||||
> Note:
|
||||
> - Only the Docker container manager installation can be scripted. For other setups you must
|
||||
> install and configure the container manager manually.
|
||||
|
||||
## Packages Installation
|
||||
|
||||
```bash
|
||||
$ 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"
|
||||
```
|
||||
|
||||
For example, if your distribution is CentOS, the previous example will generate a runnable shell script called `centos-install.sh`.
|
||||
To proceed with the installation, run:
|
||||
|
||||
```bash
|
||||
$ source /etc/os-release
|
||||
$ bash "./${ID}-install.sh"
|
||||
```
|
||||
|
||||
## Docker Installation and Setup
|
||||
|
||||
```bash
|
||||
$ 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"
|
||||
```
|
||||
|
||||
For example, if your distribution is CentOS, this will generate a runnable shell script called `centos-docker-install.sh`.
|
||||
|
||||
To proceed with the Docker installation, run:
|
||||
|
||||
```bash
|
||||
$ source /etc/os-release
|
||||
$ bash "./${ID}-docker-install.sh"
|
||||
```
|
||||
@@ -1,47 +0,0 @@
|
||||
# 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#packaged-installation-methods).
|
||||
|
||||
> **Note**:
|
||||
> - `kata-manager` requires `curl` and `sudo` installed on your system.
|
||||
>
|
||||
> - Full installation mode is only available for Docker container manager. For other setups, you
|
||||
> can still use `kata-manager` to [install Kata package](#install-the-kata-packages-only), and then setup your container manager manually.
|
||||
>
|
||||
> - You can run `kata-manager` in dry run mode by passing the `-n` flag. Dry run mode allows you to review the
|
||||
> commands that `kata-manager` would run, without doing any change to your system.
|
||||
|
||||
|
||||
## Full Installation
|
||||
This command does the following:
|
||||
1. Installs Kata Containers packages
|
||||
2. Installs Docker
|
||||
3. Configure Docker to use the Kata OCI runtime by default
|
||||
|
||||
```bash
|
||||
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/tests/master/cmd/kata-manager/kata-manager.sh) install-docker-system"
|
||||
```
|
||||
|
||||
<!--
|
||||
You can ignore the content of this comment.
|
||||
(test code run by test-install-docs.sh to validate code blocks this document)
|
||||
|
||||
```bash
|
||||
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/tests/master/cmd/kata-manager/kata-manager.sh) remove-packages"
|
||||
```
|
||||
-->
|
||||
## Install the Kata packages only
|
||||
Use the following command to only install Kata Containers packages.
|
||||
|
||||
```bash
|
||||
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/tests/master/cmd/kata-manager/kata-manager.sh) install-packages"
|
||||
```
|
||||
|
||||
## Further Information
|
||||
For more information on what `kata-manager` can do, refer to the [`kata-manager` page](https://github.com/kata-containers/tests/blob/master/cmd/kata-manager).
|
||||
Reference in New Issue
Block a user