Install Mirantis Container Runtime for SLES¶

Prerequisites¶

Perform all prerequisites as required prior to installing MCR on SLES.

OS requirements¶

To install Mirantis Container Runtime, you need the 64-bit version of SLES 12.x or later, running on the x86_64 architecture. Mirantis Container Runtime is not supported on OpenSUSE.

The only supported storage driver for Mirantis Container Runtime on SLES is Btrfs, which is used by default if the underlying filesystem hosting /var/lib/docker/ is a BTRFS filesystem.

Note

IBM Z (s390x) is supported for Mirantis Container Runtime 17.06.xx only.

Firewall configuration¶

Docker creates a DOCKER iptables chain when it starts. The SUSE firewall may block access to this chain, which can prevent you from running containers with published ports. You may see errors such as the following:

WARNING: IPv4 forwarding is disabled. Networking will not work.
docker: Error response from daemon: driver failed programming external
        connectivity on endpoint adoring_ptolemy
        (0bb5fa80bc476f8a0d343973929bb3b7c039fc6d7cd30817e837bc2a511fce97):
        (iptables failed: iptables --wait -t nat -A DOCKER -p tcp -d 0/0 --dport 80 -j DNAT --to-destination 172.17.0.2:80 ! -i docker0: iptables: No chain/target/match by that name.
 (exit status 1)).

If you see errors like this, adjust the start-up script order so that the firewall is started before Docker, and Docker stops before the firewall stops. Refer to the SLES systemd daemon documentation.

Uninstall old versions¶

Older versions of Docker were called docker or docker-engine. If you use OS images from a cloud provider, you may need to remove the runc package, which conflicts with Docker. If these are installed, uninstall them, along with associated dependencies.

sudo zypper rm docker docker-engine runc

If removal of the docker-engine package fails, use the following command instead:

sudo rpm -e docker-engine

It’s OK if zypper reports that none of these packages are installed.

The contents of /var/lib/docker/, including images, containers, volumes, and networks, are preserved. The Mirantis Container Runtime package is now called docker-ee.

Configure the Btrfs filesystem¶

By default, SLES formats the / filesystem using Btrfs, so most people do not not need to do the steps in this section. If you use OS images from a cloud provider, you may need to do this step. If the filesystem that hosts /var/lib/docker/ is not a BTRFS filesystem, you must configure a BTRFS filesystem and mount it on /var/lib/docker/.

Check whether / (or /var/ or /var/lib/ or /var/lib/docker/ if they are separate mount points) are formatted using Btrfs. If you do not have separate mount points for any of these, a duplicate result for / is returned.
```
df -T / /var /var/lib /var/lib/docker
```
You need to complete the rest of these steps only if one of the following is true:
- You have a separate /var/ filesystem that is not formatted with Btrfs
- You do not have a separate /var/ or /var/lib/ or /var/lib/docker/ filesystem and / is not formatted with Btrfs
If /var/lib/docker is already a separate mount point and is not formatted with Btrfs, back up its contents so that you can restore them after step 3.
Format your dedicated block device or devices as a Btrfs filesystem. This example assumes that you are using two block devices called /dev/xvdf and /dev/xvdg. Make sure you are using the right device names.

Important

Double-check the block device names because this is a destructive operation.
```
sudo mkfs.btrfs -f /dev/xvdf /dev/xvdg
```
There are many more options for Btrfs, including striping and RAID. See the Btrfs documentation.
Mount the new Btrfs filesystem on the /var/lib/docker/ mount point. You can specify any of the block devices used to create the Btrfs filesystem.
```
sudo mount -t btrfs /dev/xvdf /var/lib/docker
```
Don’t forget to make the change permanent across reboots by adding an entry to /etc/fstab.
If /var/lib/docker previously existed and you backed up its contents during step 1, restore them onto /var/lib/docker.

Install Mirantis Container Runtime¶

You can install Mirantis Container Runtime in different ways, depending on your needs.

Most users set up Docker’s repositories and install from them, for ease of installation and upgrade tasks. This is the recommended approach.
Some users download the RPM package and install it manually and manage upgrades completely manually. This is useful in situations such as installing Docker on air-gapped systems with no access to the internet.

Install using the repository¶

Before you install Mirantis Container Runtime for the first time on a new host machine, you need to set up the Docker repository. Afterward, you can install and update Docker from the repository.

Set up the repository¶

Temporarily add the $DOCKER_EE_BASE_URL and $DOCKER_EE_URL variables into your environment. This only persists until you log out of the session.
```
DOCKER_EE_BASE_URL="https://repos.mirantis.com"
DOCKER_EE_URL="${DOCKER_EE_BASE_URL}/sles/<SLES_VERSION>/<ARCH>/stable-<DOCKER_VERSION>"
```
And substitute the following:
- SLES_VERSION is 15 or 12.3.
- ARCH is x86_64.
- DOCKER_VERSION is 23.0
As an example, your command should look like:
```
DOCKER_EE_BASE_URL="https://repos.mirantis.com"
DOCKER_EE_URL="${DOCKER_EE_BASE_URL}/sles/15/x86_64/stable-23.0"
```
Use the following command to set up the stable repository. Use the command as-is. It works because of the variable you set in the previous step.
```
sudo zypper addrepo $DOCKER_EE_URL docker-ee-stable
```

Import the GPG key from the repository.

sudo rpm --import "${DOCKER_EE_BASE_URL}/sles/gpg"

Install Mirantis Container Runtime¶

Update the zypper package index.
```
sudo zypper refresh
```
If this is the first time you have refreshed the package index since adding the Docker repositories, you are prompted to accept the GPG key, and the key’s fingerprint is shown. Verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9 and if so, accept the key.
Install the latest patch release, or proceed to the next step to install a specific version.
```
sudo yum -y install docker-ee docker-ee-cli \
docker-ee-rootless-extras containerd.io
```
Note

MCR nodes in rootless mode cannot currently be a member of an MKE cluster.

Start Docker.

SLES 15:

sudo systemctl start docker

SLES 12:

sudo service docker start

On production systems, you should install a specific version of Mirantis Container Runtime instead of always using the latest. List the available versions. The following example only lists binary packages and is truncated. To also list source packages, omit the -t package flag from the command.

zypper search -s --match-exact -t package docker-ee

The contents of the list depend upon which repositories you have enabled. Choose a specific version to install. The fourth column is the version string. The last column is the repository name, which indicates which repository the package is from and by extension its stability level. To install a specific version, append the version string to the package name and separate them by a hyphen (-):

On SLES15

Requires the addition of the docker-ee-rootless-extras package.

sudo zypper install docker-ee-<VERSION_STRING> \
docker-ee-cli-<VERSION_STRING> \
docker-ee-rootless-extras-<VERSION_STRING> containerd.io

Note

MCR nodes in rootless mode cannot currently be a member of an MKE cluster.

On SLES12

sudo zypper install docker-ee-<VERSION_STRING> \
docker-ee-cli-<VERSION_STRING> containerd.io

Docker is installed but not started. The docker group is created, but no users are added to the group.

Configure Docker to use the Btrfs filesystem. This is only required if the ``/`` filesystem is not using BTRFS. However, explicitly specifying the storage-driver has no harmful side effects.
Edit the file /etc/docker/daemon.json (create it if it does not exist) and add the following contents:
```
{
  "storage-driver": "btrfs"
}
```
Save and close the file.
Start Docker.
```
sudo service docker start
```
Verify that Docker is installed correctly by running the hello-world image.
```
sudo docker run hello-world
```
This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.

Mirantis Container Runtime is installed and running. You need to use sudo to run Docker commands.

Upgrade Mirantis Container Runtime¶

To upgrade Mirantis Container Runtime, follow the steps below:

If upgrading to a new major Mirantis Container Runtime version, such as when going from Docker 20.10.x to Docker 23.0.x, add the new repository.
Run sudo zypper refresh.
Follow the installation instructions, choosing the new version you want to install.

Install from a package¶

If you cannot use the official Docker repository to install Mirantis Container Runtime, you can download the .rpm file for your release and install it manually. You need to download a new file each time you want to upgrade Docker.

Go to repos.mirantis.com in your browser.
Go to sles/15/x86_64/stable-23.0/ and choose the directory corresponding to the desired Mirantis Container Runtime version. Download the .rpm file from the Packages directory.

Import the official Docker official GPG key.

sudo rpm --import https://repos.mirantis.com/sles/gpg

Install Docker, changing the path below to the path where you downloaded the Docker package.
```
sudo zypper install <path_to_downloaded_sles_package_.rpm>
```
Docker is installed but not started. The docker group is created, but no users are added to the group.
Configure Docker to use the Btrfs filesystem. This is only required if the ``/`` filesystem is not using Btrfs. However, explicitly specifying the storage-driver has no harmful side effects.
Edit the file /etc/docker/daemon.json (create it if it does not exist) and add the following contents:
```
{
  "storage-driver": "btrfs"
}
```
Save and close the file.
Start Docker.
```
sudo service docker start
```
Verify that Docker is installed correctly by running the hello-world image.
```
sudo docker run hello-world
```
This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.

Mirantis Container Runtime is installed and running. You need to use sudo to run Docker commands.

Upgrade Mirantis Container Runtime¶

To upgrade Mirantis Container Runtime, download the newer package file and repeat the installation procedure, using zypper update instead of zypper install, and pointing to the new file.

Enable MCR Telemetry¶

By default, MCR automatically records and transmits data to Mirantis for monitoring and analysis purposes. The data collected provides the Mirantis Customer Success Organization with information that helps us to better understand the operational use of MCR by our customers. It also provides key feedback in the form of product usage statistics, which enable our product teams to enhance Mirantis products and services.

To disable the telemetry function, set features.telemetry to false in your /etc/docker/daemon.json file. Change the setting to true to re-enable telemetry.

{"features":{"telemetry": false}}

Caution

To send the telemetry, verify that dockerd can resolve api.segment.io and create a TCP (HTTPS) connection on port 443.

Run MCR as a non-root user (Rootless mode)¶

Note

MCR nodes in rootless mode cannot belong to a MKE cluster.

For information on rootless mode installation and configuration, refer to the Docker documentation Run the Docker daemon as a non-root user (Rootless mode).

Uninstall Mirantis Container Runtime¶

Uninstall the Mirantis Container Runtime package using the command below.
```
sudo zypper rm docker-ee docker-ee-cli containerd.io
```
Images, containers, volumes, or customized configuration files on your host are not automatically removed. To delete all images, containers, and volumes.
```
sudo rm -rf /var/lib/docker/*
```
If you used a separate BTRFS filesystem to host the contents of /var/lib/docker/, you can unmount and format the Btrfs filesystem.

You must delete any edited configuration files manually.