Upgrading.md

• Introduction
• Unsupported scenarios
• Maintenance Warning
• Upgrade from Clear Containers
  • Stop all running Clear Container instances
  • Configuration migration
  • Remove Clear Containers packages
    • Fedora
    • Ubuntu
  • Disable old container manager configuration
  • Install Kata Containers
  • Create a Kata Container
• Upgrade from runV
• Upgrade Kata Containers
• Appendices
  • Assets
    • Guest kernel
    • Image
    • Determining asset versions

Introduction

This document explains how to upgrade from Clear Containers and runV to Kata Containers and how to upgrade an existing Kata Containers system to the latest version.

Unsupported scenarios

Upgrading a Clear Containers system on the following distributions is not supported since the installation process for these distributions makes use of unpackaged components:

• CentOS
• BCLinux
• RHEL
• SLES

Additionally, upgrading Clear Linux is not supported as Kata Containers packages do not yet exist.

Maintenance Warning

The Clear Containers codebase is no longer being developed. Only new releases will be considered for significant bug fixes.

The main development focus is now on Kata Containers. All Clear Containers users are encouraged to switch to Kata Containers.

Upgrade from Clear Containers

Since Kata Containers can co-exist on the same system as Clear Containers, if you already have Clear Containers installed, the upgrade process is simply to install Kata Containers. However, since Clear Containers is no longer being actively developed, you are encouraged to remove Clear Containers from your systems.

Stop all running Clear Container instances

Assuming a Docker* system, to stop all currently running Clear Containers:

$ for container in $(sudo docker ps -q); do sudo docker stop $container; done

Configuration migration

The automatic migration of Clear Containers configuration to Kata Containers configuration is not supported.

If you have made changes to your Clear Containers configuration, you should review those changes and decide whether to manually apply those changes to the Kata Containers configuration.

Note: This step must be completed before continuing to remove the Clear Containers packages since doing so will delete the default Clear Containers configuration file from your system.

Remove Clear Containers packages

Warning: If you have modified your Clear Containers configuration, you might want to make a safe copy of the configuration file before removing the packages since doing so will delete the default configuration file

Fedora

$ sudo -E dnf remove cc-runtime\* cc-proxy\* cc-shim\* linux-container clear-containers-image qemu-lite cc-ksm-throttler
$ sudo rm /etc/yum.repos.d/home:clearcontainers:clear-containers-3.repo

Ubuntu

$ sudo apt-get purge cc-runtime\* cc-proxy\* cc-shim\* linux-container clear-containers-image qemu-lite cc-ksm-throttler
$ sudo rm /etc/apt/sources.list.d/clear-containers.list

Disable old container manager configuration

Assuming a Docker installation, remove the docker configuration for Clear Containers:

$ sudo rm /etc/systemd/system/docker.service.d/clear-containers.conf

Install Kata Containers

Follow one of the installation guides.

Create a Kata Container

$ sudo docker run -ti busybox sh

Upgrade from runV

runV and Kata Containers can run together on the same system without affecting each other, as long as they are not configured to use the same container root storage. Currently, runV defaults to /run/runv and Kata Containers defaults to /var/run/kata-containers.

Now, to upgrade from runV you need to fresh install Kata Containers by following one of the installation guides.

Upgrade Kata Containers

As shown in the installation instructions, Kata Containers provide binaries for popular distributions in their native packaging formats. This allows Kata Containers to be upgraded using the standard package management tools for your distribution.

Appendices

Assets

Kata Containers requires additional resources to create a virtual machine container. These resources are called Kata Containers assets, which comprise a guest kernel and a root filesystem or initrd image. This section describes when these components are updated.

Since the official assets are packaged, they are automatically upgraded when new package versions are published.

Warning: Note that if you use custom assets (by modifying the Kata Runtime configuration > file), it is your responsibility to ensure they are updated as necessary.

Guest kernel

The kata-linux-container package contains a Linux* kernel based on the latest vanilla version of the longterm kernel plus a small number of patches.

The Longterm branch is only updated with important bug fixes meaning this package is only updated when necessary.

The guest kernel package is updated when a new longterm kernel is released and when any patch updates are required.

Image

The kata-containers-image package is updated only when critical updates are available for the packages used to create it, such as:

• systemd
• Kata Containers Agent

Determining asset versions

To see which versions of the assets being used:

$ kata-runtime kata-env