This guide will walk you through the installation of CRI-O, an Open Container Initiative-based implementation of the Kubernetes Container Runtime Interface. It is assumed you are running a Linux machine.

• Install packaged versions of CRI-O
• Install CRI-O on Flatcar with Sysexts
• Build and install CRI-O from source
  • Runtime dependencies
  • Build and Run Dependencies
    • Fedora - RHEL 7 - CentOS
      • Required
    • RHEL 8
    • Debian - Raspbian - Ubuntu
      • Debian up to buster - Raspbian - Ubuntu up to 18.04
      • Debian up to bullseye - Ubuntu up to 22.04
      • Debian bookworm or higher - Ubuntu 24.04 or higher
  • Get Source Code
  • Build
    • Install with Ansible
    • Build Tags
  • Static builds
  • Download conmon
• Setup CNI networking
• CRI-O configuration
  • Validate registries in registries.conf
  • Optional - Modify verbosity of logs
  • Optional - Modify capabilities and sysctls
• Starting CRI-O
• Using CRI-O
• Updating CRI-O
  • openSUSE
  • Fedora 31 or later
  • Other yum based operating systems
  • APT based operating systems

CRI-O follows the Kubernetes support cycle of three minor releases. CRI-O also attempts to package generically for Debian (deb) and Red Hat (RPM) based distributions and package managers.

If there's a version or operating system that is missing, please open an issue.

For more information, please follow the instructions in the CRI-O packaging repository.

Installing CRI-O on Flatcar Container Linux with support for systemd extensions (sysexts), enabling a supported installation method for environments that utilize Flatcar.

See the Flatcar documentation for more information on how to install.

• runc, crun or any other OCI compatible runtime
• iproute
• nftables (on newer distros)
• iptables (on distros that don't support nftables, or for backward-compatibility)

Latest version of crun is expected to be installed on the system. It is picked up as the default runtime by CRI-O.

CRI-O will prefer nftables (if it is available) for new pod HostPort mappings, but will also attempt to clean up old iptables-based mappings when deleting a pod, if iptables is installed.

Fedora, RHEL 7, CentOS and related distributions:

yum install -y \
  containers-common \
  git \
  glib2-devel \
  glibc-devel \
  glibc-static \
  go \
  gpgme-devel \
  libassuan-devel \
  libgpg-error-devel \
  libseccomp-devel \
  libselinux-devel \
  pkgconfig \
  make \
  crun

Please note:

• CentOS 8 (or higher): pkgconfig package is replaced by pkgconf-pkg-config
• By default btrfs is not enabled. To add the btrfs support, install the following package: btrfs-progs-devel
• CentOS 8: gpgme-devel can be installed with the powertools repo. (yum install -y gpgme-devel --enablerepo=powertools)
• CentOS 9: gpgme-devel can be installed with the CodeReadyBuilder (crb) repo. (yum install -y gpgme-devel --enablerepo=crb)
• It is possible the distribution packaged version of runc is out of date.
• If you'd like to get the latest and greatest runc, consider using the one found in devel:kubic:libcontainers:stable

For RHEL 8 distributions (tested on RHEL 8.5).

Make sure you are subscribed to the following repositories:

• BaseOS/x86_64
• Appstream/x86_64
• CodeReady Linux Builder for x86_64

subscription-manager repos --enable=rhel-8-for-x86_64-baseos-rpms
subscription-manager repos --enable=rhel-8-for-x86_64-appstream-rpms
subscription-manager repos --enable=codeready-builder-for-rhel-8-x86_64-rpms

Follow this guide to subscribe to the repositories if not already subscribed.

This requires Go version as mentioned in the go.mod file. Follow these instructions to install Go

Install dependencies:

yum install -y \
  containers-common \
  git \
  make \
  glib2-devel \
  glibc-devel \
  glibc-static \
  crun

Install go-md2man:

go get github.com/cpuguy83/go-md2man

Install dependencies:

yum install -y \
  libassuan \
  libassuan-devel \
  libgpg-error \
  libseccomp-devel \
  libselinux \
  pkgconf-pkg-config \
  gpgme-devel \
  gcc-go

On Debian, Raspbian and Ubuntu distributions, enable the Kubic project repositories (for containers-common and cri-o-runc packages) and install the following packages:

apt update -qq && \
# For Debian 10(buster) or below: use "apt install -t buster-backports"
apt install -y  \
  btrfs-tools \
  containers-common \
  git \
  libassuan-dev \
  libglib2.0-dev \
  libc6-dev \
  libgpgme11-dev \
  libgpg-error-dev \
  libseccomp-dev \
  libsystemd-dev \
  libbtrfs-dev \
  libselinux1-dev \
  pkg-config \
  go-md2man \
  cri-o-runc \
  libudev-dev \
  software-properties-common \
  gcc \
  make

apt-get update -qq && apt-get install -y \
  libbtrfs-dev \
  containers-common \
  git \
  libassuan-dev \
  libglib2.0-dev \
  libc6-dev \
  libgpgme-dev \
  libgpg-error-dev \
  libseccomp-dev \
  libsystemd-dev \
  libselinux1-dev \
  pkg-config \
  go-md2man \
  cri-o-runc \
  libudev-dev \
  software-properties-common \
  gcc \
  make

apt update -qq && apt install -y \
  libbtrfs-dev \
  golang-go \
  golang-github-containers-common \
  git \
  libassuan-dev \
  libglib2.0-dev \
  libc6-dev \
  libgpgme-dev \
  libgpg-error-dev \
  libseccomp-dev \
  libsystemd-dev \
  libselinux1-dev \
  pkg-config \
  go-md2man \
  crun \
  libudev-dev \
  software-properties-common \
  gcc \
  make

Caveats and Notes:

If using an older release or a long-term support release, be careful to double-check that the version of runc is new enough (running runc --version should produce spec: 1.0.0 or greater), or else build your own.

Be careful to check the golang version inside the go.mod file. If needed, newer golang versions are available at the official download website.

Clone the source code using:

git clone https://github.com/cri-o/cri-o # or your fork
cd cri-o

Make sure your CRI-O and kubernetes versions are of matching major versions. For instance, if you want to be compatible with the latest kubernetes release, you'll need to use the latest tagged release of CRI-O on branch release-1.18.

To install with default buildtags using seccomp, use:

make
sudo make install

Otherwise, if you do not want to build CRI-O with seccomp support you can add BUILDTAGS="" when running make.

make BUILDTAGS=""
sudo make install

An Ansible Role is also available to automate the above steps:

sudo su -
mkdir -p ~/.ansible/roles
cd ~/.ansible/roles
git clone https://github.com/alvistack/ansible-role-cri_o.git cri_o
cd ~/.ansible/roles/cri_o
pip3 install --upgrade --ignore-installed --requirement requirements.txt
molecule converge
molecule verify

CRI-O supports optional build tags for compiling support of various features. To add build tags to the make option the BUILDTAGS variable must be set.

make BUILDTAGS='seccomp apparmor'

CRI-O manages images with container-libs/image, which uses the following buildtags.

CRI-O also uses container-libs/storage for managing container storage.

It is possible to build a statically linked binary of CRI-O by using the officially provided nix package and the derivation of it within this repository. The builds are completely reproducible and will create a x86_64/amd64 or aarch64/arm64, ppc64le or s390x stripped ELF binary for glibc or musl libc (for s390x). These binaries are integration tested (for amd64 and arm64) as well and support the following features:

• apparmor
• btrfs
• gpgme
• seccomp
• selinux

To build the binaries locally either install the nix package manager or use the make build-static target which relies on the nixos/nix container image.

The overall build process can take a tremendous amount of CPU time depending on the hardware. The resulting binaries should now be available within:

• bin/static/crio

To build the binaries without any prepared container and via the already installed nix package manager, simply run the following command from the root directory of this repository:

nix build -f nix

The resulting binaries should be now available in result/bin. To build the arm variant of the binaries, just run:

nix build -f nix/default-arm64.nix

Similarly, the ppc64le variant of binaries can be built using:

nix build -f nix/default-ppc64le.nix

In the same way, the s390x variant of binaries can be built using:

nix build -f nix/default-s390x.nix

conmon is a per-container daemon that CRI-O uses to monitor container logs and exit information. conmon needs to be downloaded with CRI-O.

running:

git clone https://github.com/containers/conmon
cd conmon
make
sudo make install

will download conmon to your $PATH.

A proper description of setting up CNI networking is given in the contrib/cni README. But the gist is that you need to have some basic network configurations enabled and CNI plugins installed on your system.

If you are installing for the first time, generate and install configuration files with:

sudo make install.config

Edit /etc/containers/registries.conf and verify that the registries option has valid values in it. For example:

[registries.search]
registries = ['registry.access.redhat.com', 'registry.fedoraproject.org', 'quay.io', 'docker.io']

[registries.insecure]
registries = []

[registries.block]
registries = []

For more information about this file see registries.conf(5).

Users can modify the log_level by specifying an overwrite like /etc/crio/crio.conf.d/01-log-level.conf to change the verbosity of the logs. Options are fatal, panic, error, warn, info (default), debug and trace.

[crio.runtime]
log_level = "info"

By default, CRI-O uses the following capabilities:

default_capabilities = [
  "CHOWN",
  "DAC_OVERRIDE",
  "FSETID",
  "FOWNER",
  "SETGID",
  "SETUID",
  "SETPCAP",
  "NET_BIND_SERVICE",
  "KILL",
]

and no sysctls

default_sysctls = [
]

Users can change either default by adding overwrites to /etc/crio/crio.conf.d.

Running make install will download CRI-O into the folder

/usr/local/bin/crio

You can run it manually there, or you can set up a systemd unit file with:

sudo make install.systemd

And let systemd take care of running CRI-O:

sudo systemctl daemon-reload
sudo systemctl enable crio
sudo systemctl start crio

• Follow this tutorial to quickly get started running simple pods and containers.
• To run a full cluster, see the instructions.
• To run with kubeadm, see kubeadm instructions.

sudo zypper update
sudo zypper update cri-o

sudo dnf update
sudo dnf update cri-o

sudo yum update
sudo yum update cri-o

sudo apt upgrade cri-o