mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-04-27 19:35:32 +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
parent
62b0522b33
commit
43d70a32df
@ -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).
|
||||
55
utils/README.md
Normal file
55
utils/README.md
Normal file
@ -0,0 +1,55 @@
|
||||
# Utilities
|
||||
|
||||
# Kata Manager
|
||||
|
||||
> **Warning:**
|
||||
>
|
||||
> - Kata Manager 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.
|
||||
|
||||
> **Note:**
|
||||
>
|
||||
> We recommend users install Kata Containers using
|
||||
> [official distribution packages](../docs/install/README.md#official-packages), where available.
|
||||
|
||||
The [`kata-manager.sh`](kata-manager.sh) script automatically installs and
|
||||
configures Kata Containers and containerd.
|
||||
|
||||
This scripted method installs the latest versions of Kata Containers and
|
||||
containerd. However, be aware of the following before proceeding:
|
||||
|
||||
- Packages will **not** be automatically updated
|
||||
|
||||
Since a package manager is not being used, it is **your** responsibility
|
||||
to ensure these packages are kept up-to-date when new versions are released
|
||||
to ensure you are using a version that includes the latest security and bug fixes.
|
||||
|
||||
- Potentially untested versions or version combinations
|
||||
|
||||
This script installs the *newest* versions of Kata Containers
|
||||
and containerd from binary release packages. These versions may
|
||||
not have been tested with your distribution version.
|
||||
|
||||
If you still wish to continue, but prefer a manual installation, see
|
||||
[the containerd installation guide](/docs/install/container-manager/containerd/containerd-install.md).
|
||||
|
||||
## Install a minimal Kata Containers system
|
||||
|
||||
To install and configure a system with Kata Containers and containerd, run:
|
||||
|
||||
```bash
|
||||
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/2.0-dev/utils/kata-manager.sh)"
|
||||
```
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - The script must be run on a system that does not have Kata Containers or
|
||||
> containerd already installed on it.
|
||||
>
|
||||
> - The script accepts up to two parameters which can be used to test
|
||||
> pre-release versions (a Kata Containers version, and a containerd
|
||||
> version). If either version is unspecified or specified as `""`, the
|
||||
> latest official version will be installed.
|
||||
580
utils/kata-manager.sh
Executable file
580
utils/kata-manager.sh
Executable file
@ -0,0 +1,580 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# Copyright (c) 2020 Intel Corporation
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
#
|
||||
|
||||
set -o errexit
|
||||
set -o nounset
|
||||
set -o pipefail
|
||||
set -o errtrace
|
||||
|
||||
[ -n "${DEBUG:-}" ] && set -o xtrace
|
||||
|
||||
readonly script_name=${0##*/}
|
||||
|
||||
readonly kata_project="Kata Containers"
|
||||
readonly containerd_project="containerd"
|
||||
|
||||
readonly kata_slug="kata-containers/kata-containers"
|
||||
readonly containerd_slug="containerd/containerd"
|
||||
|
||||
readonly kata_project_url="https://github.com/${kata_slug}"
|
||||
readonly containerd_project_url="https://github.com/${containerd_slug}"
|
||||
|
||||
readonly kata_releases_url="https://api.github.com/repos/${kata_slug}/releases"
|
||||
readonly containerd_releases_url="https://api.github.com/repos/${containerd_slug}/releases"
|
||||
|
||||
# Directory created when unpacking a binary release archive downloaded from
|
||||
# $kata_releases_url.
|
||||
readonly kata_install_dir="${kata_install_dir:-/opt/kata}"
|
||||
|
||||
# containerd shim v2 details
|
||||
readonly kata_runtime_name="kata"
|
||||
readonly kata_runtime_type="io.containerd.${kata_runtime_name}.v2"
|
||||
readonly kata_shim_v2="containerd-shim-${kata_runtime_name}-v2"
|
||||
|
||||
# Systemd unit name for containerd daemon
|
||||
readonly containerd_service_name="containerd.service"
|
||||
|
||||
# Directory in which to create symbolic links
|
||||
readonly link_dir=${link_dir:-/usr/bin}
|
||||
|
||||
readonly tmpdir=$(mktemp -d)
|
||||
|
||||
readonly warnings=$(cat <<EOT
|
||||
WARNINGS:
|
||||
|
||||
- Use distro-packages where possible
|
||||
|
||||
If your distribution packages $kata_project, you should use these packages rather
|
||||
than running this script.
|
||||
|
||||
- Packages will **not** be automatically updated
|
||||
|
||||
Since a package manager is not being used, it is **your** responsibility
|
||||
to ensure these packages are kept up-to-date when new versions are released
|
||||
to ensure you are using a version that includes the latest security and bug fixes.
|
||||
|
||||
- Potentially untested versions or version combinations
|
||||
|
||||
This script installs the *newest* versions of $kata_project
|
||||
and $containerd_project from binary release packages. These versions may
|
||||
not have been tested with your distribution version.
|
||||
|
||||
EOT
|
||||
)
|
||||
|
||||
die()
|
||||
{
|
||||
echo -e >&2 "ERROR: $*"
|
||||
exit 1
|
||||
}
|
||||
|
||||
info()
|
||||
{
|
||||
echo -e "INFO: $*"
|
||||
}
|
||||
|
||||
cleanup()
|
||||
{
|
||||
[ -d "$tmpdir" ] && rm -rf "$tmpdir"
|
||||
}
|
||||
|
||||
# Determine the latest GitHub release for a project.
|
||||
#
|
||||
# Parameter: GitHub API URL for a projects releases.
|
||||
# Note: Releases are assumed to use semver (https://semver.org) version
|
||||
# numbers.
|
||||
github_get_latest_release()
|
||||
{
|
||||
local url="${1:-}"
|
||||
|
||||
# Notes:
|
||||
#
|
||||
# - The sort(1) call; none of the standard utilities support semver
|
||||
# so attempt to perform a semver sort manually.
|
||||
# - Pre-releases are excluded via the select() call.
|
||||
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"
|
||||
}
|
||||
|
||||
# Returns the actual version to download based on the specified one; if the
|
||||
# specified version is blank, return the latest version.
|
||||
github_resolve_version_to_download()
|
||||
{
|
||||
local url="${1:-}"
|
||||
local requested_version="${2:-}"
|
||||
|
||||
local version=""
|
||||
|
||||
if [ -n "$requested_version" ]
|
||||
then
|
||||
version="$requested_version"
|
||||
else
|
||||
version=$(github_get_latest_release "$url" || true)
|
||||
fi
|
||||
|
||||
echo "$version"
|
||||
}
|
||||
|
||||
# Return the GitHub URL for a particular release's pre-built binary package.
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# - GitHub API URL for a project's releases.
|
||||
# - Release version to look for.
|
||||
github_get_release_file_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)
|
||||
|
||||
[ "$download_url" = null ] && download_url=""
|
||||
[ -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"
|
||||
}
|
||||
|
||||
# Download the release file for the specified projects release version and
|
||||
# return the full path to the downloaded file.
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# - GitHub API URL for a project's releases.
|
||||
# - Release version to download.
|
||||
github_download_release()
|
||||
{
|
||||
local url="${1:-}"
|
||||
local version="${2:-}"
|
||||
|
||||
pushd "$tmpdir" >/dev/null
|
||||
|
||||
local download_url=$(github_get_release_file_url \
|
||||
"$url" \
|
||||
"$version" || true)
|
||||
|
||||
[ -z "$download_url" ] && \
|
||||
die "Cannot determine download URL for version $version"
|
||||
|
||||
# Don't specify quiet mode here so the user can observe download
|
||||
# progress.
|
||||
curl -LO "$download_url"
|
||||
|
||||
local filename=$(echo "$download_url" | awk -F'/' '{print $NF}')
|
||||
|
||||
ls -d "${PWD}/${filename}"
|
||||
|
||||
popd >/dev/null
|
||||
}
|
||||
|
||||
usage()
|
||||
{
|
||||
cat <<EOT
|
||||
Usage: $script_name [options] [<kata-version> [<containerd-version>]]
|
||||
|
||||
Description: Install $kata_project [1] and $containerd_project [2] from GitHub release binaries.
|
||||
|
||||
Options:
|
||||
|
||||
-h : Show this help statement.
|
||||
|
||||
Notes:
|
||||
|
||||
- The version strings must refer to official GitHub releases for each project.
|
||||
If not specified or set to "", install the latest available version.
|
||||
|
||||
See also:
|
||||
|
||||
[1] - $kata_project_url
|
||||
[2] - $containerd_project_url
|
||||
|
||||
$warnings
|
||||
|
||||
Advice:
|
||||
|
||||
- You can check the latest version of Kata Containers by running:
|
||||
|
||||
$ kata-runtime kata-check --only-list-releases
|
||||
|
||||
EOT
|
||||
}
|
||||
|
||||
# Determine if the system only supports cgroups v2.
|
||||
#
|
||||
# - Writes "true" to stdout if only cgroups v2 are supported.
|
||||
# - Writes "false" to stdout if cgroups v1 or v1+v2 are available.
|
||||
# - Writes a blank string to stdout if cgroups are not available.
|
||||
only_supports_cgroups_v2()
|
||||
{
|
||||
local v1=$(mount|awk '$5 ~ /^cgroup$/ { print; }' || true)
|
||||
local v2=$(mount|awk '$5 ~ /^cgroup2$/ { print; }' || true)
|
||||
|
||||
[ -n "$v1" ] && [ -n "$v2" ] && { echo "false"; return 0; } || true
|
||||
[ -n "$v1" ] && { echo "false"; return 0; } || true
|
||||
[ -n "$v2" ] && { echo "true"; return 0; } || true
|
||||
|
||||
return 0
|
||||
}
|
||||
|
||||
pre_checks()
|
||||
{
|
||||
info "Running pre-checks"
|
||||
|
||||
command -v "${kata_shim_v2}" &>/dev/null \
|
||||
&& die "Please remove existing $kata_project installation"
|
||||
|
||||
command -v containerd &>/dev/null \
|
||||
&& die "$containerd_project already installed"
|
||||
|
||||
systemctl list-unit-files --type service |\
|
||||
egrep -q "^${containerd_service_name}\>" \
|
||||
&& die "$containerd_project already installed"
|
||||
|
||||
local cgroups_v2_only=$(only_supports_cgroups_v2 || true)
|
||||
|
||||
local url="https://github.com/kata-containers/kata-containers/issues/927"
|
||||
|
||||
[ "$cgroups_v2_only" = "true" ] && \
|
||||
die "$kata_project does not yet fully support cgroups v2 - see $url"
|
||||
|
||||
return 0
|
||||
}
|
||||
|
||||
check_deps()
|
||||
{
|
||||
info "Checking dependencies"
|
||||
|
||||
# Maps command names to package names using a colon delimiter
|
||||
local elems=()
|
||||
|
||||
elems+=("curl:curl")
|
||||
elems+=("git:git")
|
||||
elems+=("jq:jq")
|
||||
elems+=("tar:tar")
|
||||
|
||||
local pkgs_to_install=()
|
||||
|
||||
local elem
|
||||
|
||||
for elem in "${elems[@]}"
|
||||
do
|
||||
local cmd=$(echo "$elem"|cut -d: -f1)
|
||||
local pkg=$(echo "$elem"|cut -d: -f2-)
|
||||
|
||||
command -v "$cmd" &>/dev/null && continue
|
||||
|
||||
pkgs_to_install+=("$pkg")
|
||||
done
|
||||
|
||||
[ "${#pkgs_to_install[@]}" -eq 0 ] && return 0
|
||||
|
||||
local packages="${pkgs_to_install[@]}"
|
||||
|
||||
info "Installing packages '$packages'"
|
||||
|
||||
case "$ID" in
|
||||
centos|rhel) sudo yum -y install $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
|
||||
}
|
||||
|
||||
setup()
|
||||
{
|
||||
trap cleanup EXIT
|
||||
source /etc/os-release || source /usr/lib/os-release
|
||||
|
||||
pre_checks
|
||||
check_deps
|
||||
}
|
||||
|
||||
# Download the requested version of the specified project.
|
||||
#
|
||||
# Returns the resolve version number and the full path to the downloaded file
|
||||
# separated by a colon.
|
||||
github_download_package()
|
||||
{
|
||||
local releases_url="${1:-}"
|
||||
local requested_version="${2:-}"
|
||||
local project="${3:-}"
|
||||
|
||||
[ -z "$releases_url" ] && die "need releases URL"
|
||||
[ -z "$project" ] && die "need project URL"
|
||||
|
||||
local version=$(github_resolve_version_to_download \
|
||||
"$releases_url" \
|
||||
"$version" || true)
|
||||
|
||||
[ -z "$version" ] && die "Unable to determine $project version to download"
|
||||
|
||||
local file=$(github_download_release \
|
||||
"$releases_url" \
|
||||
"$version")
|
||||
|
||||
echo "${version}:${file}"
|
||||
}
|
||||
|
||||
install_containerd()
|
||||
{
|
||||
local requested_version="${1:-}"
|
||||
|
||||
local project="$containerd_project"
|
||||
|
||||
local version_desc="latest version"
|
||||
[ -n "$requested_version" ] && version_desc="version $requested_version"
|
||||
|
||||
info "Downloading $project release ($version_desc)"
|
||||
|
||||
local results=$(github_download_package \
|
||||
"$containerd_releases_url" \
|
||||
"$requested_version" \
|
||||
"$project")
|
||||
|
||||
[ -z "$results" ] && die "Cannot download $project release file"
|
||||
|
||||
local version=$(echo "$results"|cut -d: -f1)
|
||||
local file=$(echo "$results"|cut -d: -f2-)
|
||||
|
||||
[ -z "$version" ] && die "Cannot determine $project resolved version"
|
||||
[ -z "$file" ] && die "Cannot determine $project release file"
|
||||
|
||||
info "Installing $project release $version from $file"
|
||||
|
||||
sudo tar -C /usr/local -xvf "${file}"
|
||||
|
||||
sudo ln -s /usr/local/bin/ctr "${link_dir}"
|
||||
|
||||
info "$project installed\n"
|
||||
}
|
||||
|
||||
configure_containerd()
|
||||
{
|
||||
local project="$containerd_project"
|
||||
|
||||
info "Configuring $project"
|
||||
|
||||
local cfg="/etc/containerd/config.toml"
|
||||
|
||||
pushd "$tmpdir" >/dev/null
|
||||
|
||||
local service_url=$(printf "%s/%s/%s/%s" \
|
||||
"https://raw.githubusercontent.com" \
|
||||
"${containerd_slug}" \
|
||||
"master" \
|
||||
"${containerd_service_name}")
|
||||
|
||||
curl -LO "$service_url"
|
||||
|
||||
printf "# %s: Service installed for Kata Containers\n" \
|
||||
"$(date -Iseconds)" |\
|
||||
tee -a "$containerd_service_name"
|
||||
|
||||
local systemd_unit_dir="/etc/systemd/system"
|
||||
sudo mkdir -p "$systemd_unit_dir"
|
||||
|
||||
local dest="${systemd_unit_dir}/${containerd_service_name}"
|
||||
|
||||
sudo cp "${containerd_service_name}" "${dest}"
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
info "Installed ${dest}"
|
||||
|
||||
popd >/dev/null
|
||||
|
||||
# Backup the original containerd configuration:
|
||||
sudo mkdir -p "$(dirname $cfg)"
|
||||
|
||||
sudo test -e "$cfg" || {
|
||||
sudo touch "$cfg"
|
||||
info "Created $cfg"
|
||||
}
|
||||
|
||||
local original="${cfg}-pre-kata-$(date -I)"
|
||||
|
||||
sudo grep -q "$kata_runtime_type" "$cfg" || {
|
||||
sudo cp "$cfg" "${original}"
|
||||
info "Backed up $cfg to $original"
|
||||
}
|
||||
|
||||
# Add the Kata Containers configuration details:
|
||||
|
||||
sudo grep -q "$kata_runtime_type" "$cfg" || {
|
||||
cat <<-EOT | sudo tee -a "$cfg"
|
||||
[plugins]
|
||||
[plugins.cri]
|
||||
[plugins.cri.containerd]
|
||||
default_runtime_name = "${kata_runtime_name}"
|
||||
[plugins.cri.containerd.runtimes.${kata_runtime_name}]
|
||||
runtime_type = "${kata_runtime_type}"
|
||||
EOT
|
||||
|
||||
info "Modified $cfg"
|
||||
}
|
||||
|
||||
sudo systemctl start containerd
|
||||
|
||||
info "Configured $project\n"
|
||||
}
|
||||
|
||||
install_kata()
|
||||
{
|
||||
local requested_version="${1:-}"
|
||||
|
||||
local project="$kata_project"
|
||||
|
||||
local version_desc="latest version"
|
||||
[ -n "$requested_version" ] && version_desc="version $requested_version"
|
||||
|
||||
info "Downloading $project release ($version_desc)"
|
||||
|
||||
local results=$(github_download_package \
|
||||
"$kata_releases_url" \
|
||||
"$requested_version" \
|
||||
"$project")
|
||||
|
||||
[ -z "$results" ] && die "Cannot download $project release file"
|
||||
|
||||
local version=$(echo "$results"|cut -d: -f1)
|
||||
local file=$(echo "$results"|cut -d: -f2-)
|
||||
|
||||
[ -z "$version" ] && die "Cannot determine $project resolved version"
|
||||
[ -z "$file" ] && die "Cannot determine $project release file"
|
||||
|
||||
# Allow the containerd service to find the Kata shim and users to find
|
||||
# important commands:
|
||||
local create_links_for=()
|
||||
|
||||
create_links_for+=("$kata_shim_v2")
|
||||
create_links_for+=("kata-collect-data.sh")
|
||||
create_links_for+=("kata-runtime")
|
||||
|
||||
local from_dir=$(printf "%s/bin" "$kata_install_dir")
|
||||
|
||||
# Since we're unpacking to the root directory, perform a sanity check
|
||||
# on the archive first.
|
||||
local unexpected=$(tar -tf "${file}" |\
|
||||
egrep -v "^(\./opt/$|\.${kata_install_dir}/)" || true)
|
||||
|
||||
[ -n "$unexpected" ] && die "File '$file' contains unexpected paths: '$unexpected'"
|
||||
|
||||
info "Installing $project release $version from $file"
|
||||
|
||||
sudo tar -C / -xvf "${file}"
|
||||
|
||||
[ -d "$from_dir" ] || die "$project does not exist in expected directory $from_dir"
|
||||
|
||||
for file in "${create_links_for[@]}"
|
||||
do
|
||||
local from_path=$(printf "%s/%s" "$from_dir" "$file")
|
||||
[ -e "$from_path" ] || die "File $from_path not found"
|
||||
|
||||
sudo ln -sf "$from_path" "$link_dir"
|
||||
done
|
||||
|
||||
info "$project installed\n"
|
||||
}
|
||||
|
||||
handle_kata()
|
||||
{
|
||||
local version="${1:-}"
|
||||
|
||||
install_kata "$version"
|
||||
|
||||
kata-runtime --version
|
||||
}
|
||||
|
||||
handle_containerd()
|
||||
{
|
||||
local version="${1:-}"
|
||||
|
||||
install_containerd "$version"
|
||||
|
||||
configure_containerd
|
||||
|
||||
containerd --version
|
||||
}
|
||||
|
||||
test_installation()
|
||||
{
|
||||
info "Testing $kata_project\n"
|
||||
|
||||
local image="docker.io/library/busybox:latest"
|
||||
sudo ctr image pull "$image"
|
||||
|
||||
local container_name="test-kata"
|
||||
|
||||
# Used to prove that the kernel in the container
|
||||
# is different to the host kernel.
|
||||
local container_kernel=$(sudo ctr run \
|
||||
--runtime "$kata_runtime_type" \
|
||||
--rm \
|
||||
"$image" \
|
||||
"$container_name" \
|
||||
uname -r || true)
|
||||
|
||||
[ -z "$container_kernel" ] && die "Failed to test $kata_project"
|
||||
|
||||
local host_kernel=$(uname -r)
|
||||
|
||||
info "Test successful:\n"
|
||||
|
||||
info " Host kernel version : $host_kernel"
|
||||
info " Container kernel version : $container_kernel"
|
||||
echo
|
||||
}
|
||||
|
||||
handle_installation()
|
||||
{
|
||||
local kata_version="${1:-}"
|
||||
local containerd_version="${2:-}"
|
||||
|
||||
setup
|
||||
|
||||
handle_kata "$kata_version"
|
||||
handle_containerd "$containerd_version"
|
||||
|
||||
test_installation
|
||||
|
||||
info "$kata_project and $containerd_project are now installed"
|
||||
|
||||
echo -e "\n${warnings}\n"
|
||||
}
|
||||
|
||||
handle_args()
|
||||
{
|
||||
case "${1:-}" in
|
||||
-h|--help|help) usage; exit 0;;
|
||||
esac
|
||||
|
||||
local kata_version="${1:-}"
|
||||
local containerd_version="${2:-}"
|
||||
|
||||
handle_installation \
|
||||
"$kata_version" \
|
||||
"$containerd_version"
|
||||
}
|
||||
|
||||
main()
|
||||
{
|
||||
handle_args "$@"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
Loading…
Reference in New Issue
Block a user