Introduction

This documentation provides information on how to deploy Mirantis Container Runtime (MCR). The documentation is intended to help operators to understand the core concepts of the product.

The information provided in this documentation set is being constantly improved and amended based on the feedback and kind requests from the consumers of MCR.

Product Overview

Mirantis Container Runtime (MCR) enables you to power your business-critical applications with the industry-leading enterprise container engine. You can run containers on any platform with a fully supported and highly secure container runtime. MCR provides the core functionality and security compliance needed to enable your container orchestration solution of choice with certified proven support for both Kubernetes and Swarm. The most common use cases include:

Container orchestration solution

Organisations often have unique container orchestration requirements and may choose to utilise alternative systems to manage their containers. MCR provides freedom to select the best orchestration solution for your needs whilst still ensuring you have a secure, trusted, and supported container runtime to run your mission-critical workloads.

Secure and validated containers

The challenges in ensuring that the software supply chain is secure does not stop at the container orchestration solution. The key part of securing your container solution is ensuring that only validated and trusted containers can be deployed and run. MCR combined with Mirantis Secure Registry (MSR) gives you the ability to validate and sign your container images to ensure that only approved images can be run in your environment.

Secure validated encryption

Regulated industries need to meet federal regulations to ensure that appropriate levels of encryption are enabled. MCR provides FIPS 140-2 Validated cryptography ensuring that you meet the highest standards necessary to comply with the federal requirements.

Multiple operating systems and infrastructures

With the drive towards multi-cloud and hybrid cloud, computing organisations need to support multiple operating systems on multiple platforms. MCR is certified to run on multiple operating systems, including CentOS, RHEL, Ubuntu, and Windows, for consistent runtime regardless of the platform.

Reference Architecture

The MCR Reference Architecture is a work in progress, the intent of which is to keep MCR users apprised of the technical details that pertain to the differences between Mirantis Container Runtime and Docker Engine.

Storage driver compatibility

overlay2 is the only storage driver supported by MCR 23.0, with the exception of btrfs, which MCR supports on SLES.

Note

  • A number of unsupported storage driver options that are available in MCR 20.10 are unavailable in MCR 23.0, as Mirantis is moving users away from unsupported configurations.

  • The vfs storage driver is available in MCR 23.0 for debugging purposes only.

MCR storage driver compatibility

Graphdriver

MCR 20.10

MCR 23.0

overlay2

Supported

Supported

btrfs

Supported only on SLES. Unsupported on all other Linux platforms.

Supported only on SLES. Unavailable on all other Linux platforms.

zfs

Unsupported

Unavailable

fuseoverlayfs

Unsupported

Unavailable

aufs

Unsupported

Unavailable

overlay

Unsupported

Unavailable

devicemapper

Unsupported

Unavailable

vfs

Unsupported

Unsupported

Deployment Guide

Mirantis Container Runtime (MCR) is a client-server application with these major components:

  • A server which is a type of long-running program called a daemon process (the dockerd command).

  • A REST API which specifies interfaces that programs can use to talk to the daemon and instruct it what to do.

  • A command line interface (CLI) client (the docker command).

MCR can be installed on several Linux distros as well as on Windows.

Note

MCR is derived from the Moby project, an open framework created by Docker Inc. As such, most of the product commands and setup instruction are identical to those for Docker Engine.

Install the license

Warning

Users are not authorized to run MCR without a valid license. For more information, refer to Mirantis Agreements and Terms.

For MCR to recognize your license, you must apply your customer license file at runtime.

To make MCR aware of your license and entitlement, perform the following for each node that will host MCR:

  1. Download the license file.

    If you purchased a license from the Mirantis Store, the license file is available through a link in your confirmation email. Otherwise, contact Mirantis Sales and Support to gain access to the file.

  2. Apply the license file.

    Platform

    Applying the license

    Linux distributions

    1. Determine the location of the data root directory. This information is available in the daemon.json file associated with MCR. Alternatively, you can specify the data root directory using the --data-root flag at MCR start up. Note that the default data-root directory is /var/lib/docker.

    2. Copy the license file to the data root directory and name it docker.lic. It is imperative that the license be readable by the account/user that runs the docker daemon.

    Windows servers

    Currently, you do not need to apply a license for Windows server systems, as Mirantis Container Runtime can be run using the installation script.

  3. Start MCR. If MCR is already running, restart it.

Note

MKE, MSR, and Mirantis Container Cloud have implied MCR licenses.

Install MCR on Linux distros

Install Mirantis Container Runtime for CentOS

There are two ways to install and upgrade Mirantis Container Runtime (MCR):

  • YUM repository: Set up a Docker repository and install Mirantis Container Runtime from it. This is the recommended approach because installation and upgrades are managed with YUM and easier to do.

  • RPM package: Download the RPM package, install it manually, and manage upgrades manually. This is useful when installing Mirantis Container Runtime on air-gapped systems with no access to the internet.

Prerequisites

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

Architectures and storage drivers

Mirantis Container Runtime supports CentOS 64-bit, latest version, running on x86_64.

On CentOS, Mirantis Container Runtime supports the overlay2 storage drivers. The following limitations apply:

  • If selinux is enabled, overlay2 is supported on CentOS 7.4 or higher.

  • If selinux is disabled, overlay2 is supported on CentOS 7.2 or higher with kernel version 3.10.0-693 and higher.

Uninstall old Docker versions

The Mirantis Container Runtime package is called docker-ee. Older versions were called docker or docker-engine. Uninstall all older versions and associated dependencies. The contents of /var/lib/docker/ are preserved, including images, containers, volumes, and networks.

sudo yum remove docker \
                docker-client \
                docker-client-latest \
                docker-common \
                docker-latest \
                docker-latest-logrotate \
                docker-logrotate \
                docker-selinux \
                docker-engine-selinux \
                docker-engine\
                docker-ee\
                docker-ee-cli
Repo install and upgrade

The advantage of using a repository from which to install Mirantis Container Runtime (or any software) is that it provides a certain level of automation. RPM-based distributions such as CentOS, use a tool called YUM that work with your repositories to manage dependencies and provide automatic updates.

Set up the repository

You only need to set up the repository once, after which you can install Mirantis Container Runtime from the repo and repeatedly upgrade as necessary.

  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Temporarily store https://repos.mirantis.com in an environment variable. This variable assignment does not persist when the session ends:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/centos" > /etc/yum/vars/dockerurl'
    
  4. Store your OS version string in /etc/yum/vars/dockerosversion:

    sudo sh -c 'echo "7" > /etc/yum/vars/dockerosversion'
    
  5. Install the yum-utils that provides the yum-config-manager utility.

    sudo yum install -y yum-utils
    
  6. Enable the extras RHEL repository. This ensures access to the container-selinux package required by docker-ee.

    The repository can differ per your architecture and cloud provider , so review the options in this step before running one of the following commands.

    For all architectures except IBM Power

    sudo yum-config-manager --enable rhel-7-server-extras-rpms
    

    For IBM Power only (little endian)

    sudo yum-config-manager --enable extras
    sudo subscription-manager repos --enable=rhel-7-for-power-le-extras-rpms
    sudo yum makecache fast
    sudo yum -y install container-selinux
    
  7. Depending on cloud provider, you may also need to enable another repository. Refer to the official product documentation for more information.

    AWS (where REGION is a literal and does not represent the region your machine is running in)

    Product Documentation for Red Hat Update Infrastructure 4.

    Azure

    Red Hat Update Infrastructure for on-demand Red Hat Enterprise Linux VMs in Azure

  8. Add the Mirantis Container Runtime stable repository:

    sudo -E yum-config-manager \
        --add-repo \
        "$DOCKERURL/centos/docker-ee.repo"
    
Install from the repository
  1. 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.

    If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9, and if so, accept it.

  2. To install a specific version of Mirantis Container Runtime (recommended in production), list versions and install:

    1. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:

      sudo yum list docker-ee  --showduplicates | sort -r
      
      docker-ee.x86_64      23.0.ee.2-1.el7.centos      docker-ee-stable-19.03
      

      The list returned depends on which repositories you enabled, and is specific to your version of CentOS (indicated by .el7 in this example).

    2. Install a specific version by its fully qualified package name, which is the package name (docker-ee) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ee-23.0.1.

      sudo yum -y 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.

      For example, if you want to install the 23.0.1 version run the following:

      sudo yum -y install docker-ee-23.0.1 docker-ee-cli-23.0.1 containerd.io
      

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

  3. Start Docker:

    sudo systemctl start docker
    
  4. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is installed and running. Use sudo to run Docker commands.

Package install and upgrade

To manually install MCR, download the .rpm file for your release. You need to download a new file each time you want to upgrade MCR.

Install with a package
  1. Go to repos.mirantis.com in your browser.

  2. Navigate to centos/7/x86_64/stable-<VERSION>/Packages and download the .rpm file for the Docker version you want to install.

  3. Install MCR.

    sudo yum install <path_to_downloaded_centos_package_.rpm>
    

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

  4. Start Docker

    sudo systemctl start docker
    
  5. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is installed and running. Use sudo to run Docker commands.

Upgrade with a package
  1. Download the newer package file.

  2. Repeat the installation procedure, using yum -y upgrade instead of yum -y install, and point 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
  1. Uninstall the Mirantis Container Runtime package:

    sudo yum -y remove docker-ee \
    docker-ee-cli \
    containerd.io \
    container-selinux
    
  2. Delete all images, containers, and volumes (because these are not automatically removed from your host):

    sudo rm -rf /var/lib/docker
    
  3. Delete other Docker related resources:

    sudo rm -rf /run/docker
    sudo rm -rf /etc/docker
    
  4. Delete any edited configuration files manually.

Install Mirantis Container Runtime for Oracle Linux

There are two ways to install and upgrade Mirantis Container Runtime (MCR).

  • YUM repository: Set up a Docker repository and install Mirantis Container Runtime from it. This is the recommended approach because installation and upgrades are managed with YUM and easier to do.

  • RPM package: Download the RPM package, install it manually, and manage upgrades manually. This is useful when installing Mirantis Container Runtime on air-gapped systems with no access to the internet.

Prerequisites

Perform all prerequisites as required prior to installing MCR on Oracle Linux.

Architectures and storage drivers

Mirantis Container Runtime supports the following Oracle Linux 64-bit versions:

Note

MCR does not support the Oracle Linux Unbreakable Enteprise Kernel (UEK).

Mirantis recommends the use of fast storage, such as solid-state media (SSD).

FIPS 140-2 cryptographic module support

Federal Information Processing Standards (FIPS) Publication 140-2 is a United States Federal security requirement for cryptographic modules.

With Mirantis Container Runtime license for versions 23.0.x, Mirantis provides FIPS 140-2 support in Oracle Linux 7.x and 8.x (as per the MCR 23.0 Compatibility Matrix). This includes a FIPS supported cryptographic module. If the Oracle Linux implementation already has FIPS support enabled, FIPS is also automatically enabled in MCR. If FIPS support is not already enabled in your Oracle Linux implementation, refer to the Oracle Linux product documentation for enablement instructions.

To verify the FIPS 140-2 module is enabled in the Linux kernel, confirm the file /proc/sys/crypto/fips_enabled contains 1.

cat /proc/sys/crypto/fips_enabled
1

Note

FIPS is only supported in Mirantis Container Runtime. MKE and MSR currently do not have support for FIPS 140-2.

You can override FIPS 140-2 compliance on a system that is not in FIPS 140-2 mode. Note, this does not change FIPS 140-2 mode on the system. To override the FIPS 140-2 mode, follow ths steps below.

Create a file called /etc/systemd/system/docker.service.d/fips-module.conf. Add the following:

[Service]
Environment="DOCKER_FIPS=1"

Reload the Docker configuration to systemd.

sudo systemctl daemon-reload

Restart the Docker service as root.

sudo systemctl restart docker

To confirm Docker is running with FIPS 140-2 enabled, run the docker info command.

Disabling FIPS 140-2

If the system has the FIPS 140-2 cryptographic module installed on the operating system, it is possible to disable FIPS 140-2 compliance.

To disable FIPS 140-2 in Docker but not the operating system, set the value DOCKER_FIPS=0 in the /etc/systemd/system/docker.service.d/fips-module.conf.

Reload the Docker configuration to systemd.

sudo systemctl daemon-reload

Restart the Docker service as root.

sudo systemctl restart docker

Uninstall old Docker versions

The Mirantis Container Runtime package is called docker-ee. Older versions were called docker or docker-engine. Uninstall all older versions and associated dependencies. The contents of /var/lib/docker/ are preserved, including images, containers, volumes, and networks.

sudo yum remove docker \
                docker-engine \
                docker-engine-selinux \
                docker-ee-cli \
                checkpolicy \
                libcgroup \
                libseccomp \
                libsemanage-python \
                policycoreutils-python \
                python-IPy \
                setools-libs
Repo install and upgrade

The advantage of using a repository from which to install Mirantis Container Runtime (or any software) is that it provides a certain level of automation. RPM-based distributions such as Oracle Linux, use a tool called YUM that work with your repositories to manage dependencies and provide automatic updates.

Set up the repository

You only need to set up the repository once, after which you can install Mirantis Container Runtime from the repo and repeatedly upgrade as necessary.

  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Temporarily store https://repos.mirantis.com in an environment variable. This variable assignment does not persist when the session ends:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/oraclelinux" > /etc/yum/vars/dockerurl'
    

    Also, store your OS version string in /etc/yum/vars/dockerosversion. Most users should use 7, but you can also use the more specific minor version.

    sudo sh -c 'echo "7" > /etc/yum/vars/dockerosversion'
    
  4. Install required packages: yum-utils provides the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  5. Enable the ol7_addons Oracle repository. This ensures access to the container-selinux package required by docker-ee.

    sudo yum-config-manager --enable ol7_addons
    
  6. Add the Mirantis Container Runtime stable repository:

    sudo -E yum-config-manager \
    --add-repo \
    "$DOCKERURL/oraclelinux/docker-ee.repo"
    
  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Temporarily store https://repos.mirantis.com in an environment variable. This variable assignment does not persist when the session ends:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/oraclelinux" > /etc/yum/vars/dockerurl'
    

    Also, store your OS version string in /etc/yum/vars/dockerosversion. Most users should use 8, but you can also use the more specific minor version.

    sudo sh -c 'echo "8" > /etc/yum/vars/dockerosversion'
    
  4. Install the yum-utils that provides the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  5. Add the Mirantis Container Runtime stable repository:

    sudo -E yum-config-manager \
      --add-repo \
      "$DOCKERURL/oraclelinux/docker-ee.repo"
    
Install from the repository
  1. Install the latest patch release, or go to the next step to install a specific version:

    sudo yum -y install docker-ee docker-ee-cli containerd.io
    

    Note

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

    If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9, and if so, accept it.

  2. To install a specific version of Mirantis Container Runtime (recommended in production), list versions and install:

    1. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:

      sudo yum list docker-ee  --showduplicates | sort -r
      
      docker-ee.x86_64      23.0.ee.2-1.el7.oraclelinux      docker-ee-stable-18.09
      

      The list returned depends on which repositories you enabled, and is specific to your version of Oracle Linux (indicated by .el7 in this example).

    2. Install a specific version by its fully qualified package name, which is the package name (docker-ee) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ee-18.09.1.

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

      Note

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

      For example, if you want to install the 23.0.3 version run the following:

      sudo yum -y install docker-ee-23.0.3 docker-ee-cli-23.0.3 containerd.io
      

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

  3. Start Docker:

    sudo systemctl start docker
    
  4. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is installed and running. Use sudo to run Docker commands.

  1. Install the latest patch release, or go 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.

    If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9, and if so, accept it.

  2. To install a specific version of Mirantis Container Runtime (recommended in production), list versions and install:

    1. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:

      sudo yum list docker-ee  --showduplicates | sort -r
      
      docker-ee.x86_64      23.0.ee.2-1.el7.oraclelinux      docker-ee-stable-18.09
      

      The list returned depends on which repositories you enabled, and is specific to your version of Oracle Linux (indicated by .el7 in this example).

    2. Install a specific version by its fully qualified package name, which is the package name (docker-ee) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ee-18.09.1.

      sudo yum -y 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.

      For example, if you want to install the 23.0.3 version run the following:

      sudo yum -y install docker-ee-23.0.3 docker-ee-cli-23.0.3 containerd.io
      

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

  3. Start Docker:

    sudo systemctl start docker
    
  4. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is installed and running. Use sudo to run Docker commands.

Upgrade from the repository
  1. Add the new repository.

  2. Follow the installation instructions and install a new version.

Package install and upgrade

To manually install MCR, download the .rpm file for your release. You need to download a new file each time you want to upgrade MCR.

Install with a package
  1. Go to repos.mirantis.com in your browser.

  2. Navigate to oraclelinux/7/x86_64/. Choose your Oracle Linux version, architecture, and MCR version. Download the .rpm file from the Packages directory.

  3. Install MCR.

    sudo yum install <path_to_downloaded_oracle_package_.rpm>
    

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

  4. Start Docker:

    sudo systemctl start docker
    
  5. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is installed and running. Use sudo to run Docker commands.

  1. Go to repos.mirantis.com in your browser. Navigate to oraclelinux/. Choose your Oracle Linux version, architecture, and MCR version. Download the .rpm file from the Packages directory.

    If you have trouble with selinux using the packages under the 8 directory, try choosing the version-specific directory instead.

  2. Install Mirantis Container Runtime, changing the path below to the path where you downloaded the Docker package.

    sudo yum install <path_to_downloaded_oraclelinux_package_.rpm>
    

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

  3. Start Docker:

    sudo systemctl start docker
    
  4. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is now installed and running. Make sure to use sudo to run Docker commands (refer to the Docker documentation for Linux postinstall for information on how to allow non-privileged users to run Docker commands.

Upgrade with a package
  1. Download the newer package file.

  2. Repeat the installation procedure, using yum -y upgrade instead of yum  -y install, and point 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
  1. Uninstall the Mirantis Container Runtime package:

    sudo yum -y remove docker-ee
    
  2. Delete all images, containers, and volumes (because these are not automatically removed from your host):

    sudo rm -rf /var/lib/docker
    
  3. Delete other Docker related resources:

    sudo rm -rf /run/docker sudo rm -rf /var/run/docker sudo rm -rf /etc/docker``

You must delete any edited configuration files manually.

Install Mirantis Container Runtime for Red Hat Enterprise Linux

There are two ways to install and upgrade Mirantis Container Runtime (MCR).

  • YUM repository: Set up a Docker repository and install Mirantis Container Runtime from it. This is the recommended approach because installation and upgrades are managed with YUM and easier to do.

  • RPM package: Download the RPM package, install it manually, and manage upgrades manually. This is useful when installing Mirantis Container Runtime on air-gapped systems with no access to the internet.

Prerequisites

Perform all prerequisites as required prior to installing MCR on Red Hat Enterprise Linux.

Architectures and storage drivers

Mirantis Container Runtime supports Red Hat Enterprise Linux 64-bit, versions 7.4 and higher running on x86_64. Refer to the MCR 23.0 Compatibility Matrix for specific details.

On Red Hat Enterprise Linux, Mirantis Container Runtime supports the overlay2 storage driver. The following limitations apply:

  • OverlayFS: If selinux is enabled, the overlay2 storage driver is supported on RHEL 7.4 or higher.

  • If selinux is disabled, overlay2 is supported on RHEL 7.2 or higher with kernel version 3.10.0-693 and higher.

FIPS 140-2 cryptographic module support

Federal Information Processing Standards (FIPS) Publication 140-2 is a United States Federal security requirement for cryptographic modules.

With Mirantis Container Runtime license for versions 23.0.x, Mirantis provides FIPS 140-2 support in RHEL 7.x, 8.x, and 9.x (as per the MCR 23.0 Compatibility Matrix). This includes a FIPS supported cryptographic module. If the RHEL implementation already has FIPS support enabled, FIPS is also automatically enabled in MCR. If FIPS support is not already enabled in your RHEL implementation, see the Red Hat Product Documentation for instructions on how to enable it.

To verify the FIPS 140-2 module is enabled in the Linux kernel, confirm the file /proc/sys/crypto/fips_enabled contains 1.

cat /proc/sys/crypto/fips_enabled
1

Note

FIPS is only supported in Mirantis Container Runtime. MKE and MSR currently do not have support for FIPS 140-2.

You can override FIPS 140-2 compliance on a system that is not in FIPS 140-2 mode. Note, this does not change FIPS 140-2 mode on the system. To override the FIPS 140-2 mode, follow ths steps below.

Create a file called /etc/systemd/system/docker.service.d/fips-module.conf. Add the following:

[Service]
Environment="DOCKER_FIPS=1"

Reload the Docker configuration to systemd.

sudo systemctl daemon-reload

Restart the Docker service as root.

sudo systemctl restart docker

To confirm Docker is running with FIPS 140-2 enabled, run the docker info command.

Disabling FIPS 140-2

If the system has the FIPS 140-2 cryptographic module installed on the operating system, it is possible to disable FIPS 140-2 compliance.

To disable FIPS 140-2 in Docker but not the operating system, set the value DOCKER_FIPS=0 in the /etc/systemd/system/docker.service.d/fips-module.conf.

Reload the Docker configuration to systemd.

sudo systemctl daemon-reload

Restart the Docker service as root.

sudo systemctl restart docker

Uninstall old Docker versions

The Mirantis Container Runtime package is called docker-ee. Older versions were called docker or docker-engine. Uninstall all older versions and associated dependencies. The contents of /var/lib/docker/ are preserved, including images, containers, volumes, and networks.

sudo yum remove docker \
                docker-client \
                docker-client-latest \
                docker-common \
                docker-latest \
                docker-latest-logrotate \
                docker-logrotate \
                docker-selinux \
                docker-engine-selinux \
                docker-engine
Repo install and upgrade

The advantage of using a repository from which to install Mirantis Container Runtime (or any software) is that it provides a certain level of automation. RPM-based distributions such as Red Hat Enterprise Linux, use a tool called YUM that work with your repositories to manage dependencies and provide automatic updates.

Set up the repository

You only need to set up the repository once, after which you can install Mirantis Container Runtime from the repo and repeatedly upgrade as necessary.

  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Temporarily store https://repos.mirantis.com in an environment variable. This variable assignment does not persist when the session ends:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/rhel" > /etc/yum/vars/dockerurl'
    

    Also, store your OS version string in /etc/yum/vars/dockerosversion. Most users should use 7, 8, or 9 but you can also use the more specific minor version, starting from 7.2.

    sudo sh -c 'echo "7" > /etc/yum/vars/dockerosversion'
    
  4. Install the yum-utils that provides the yum-config-manager utility.

    sudo yum install -y yum-utils
    
  5. Enable the extras RHEL repository. This ensures access to the container-selinux package required by docker-ee.

    The repository can differ per your architecture and cloud provider, so review the options in this step before running:

    For all architectures except IBM Power:

    sudo yum-config-manager --enable rhel-7-server-extras-rpms
    

    For IBM Power only (little endian):

    sudo yum-config-manager --enable extras
      sudo subscription-manager repos --enable=rhel-7-for-power-le-extras-rpms
      sudo yum makecache fast
      sudo yum -y install container-selinux
    

    Depending on cloud provider, you may also need to enable another repository:

    For AWS:

    sudo yum-config-manager --enable rhel-7-server-rhui-extras-rpms
    

    For Azure:

    sudo yum-config-manager --enable rhui-rhel-7-server-rhui-extras-rpms
    

    Add the Mirantis Container Runtime stable repository:

    sudo -E yum-config-manager \
         --add-repo \
         "$DOCKERURL/rhel/docker-ee.repo"
    
  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Temporarily store https://repos.mirantis.com in an environment variable. This variable assignment does not persist when the session ends:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/rhel" > /etc/yum/vars/dockerurl'
    

    Also, store your OS version string in /etc/yum/vars/dockerosversion. Most users should use 8, but you can also use the more specific minor version.

    sudo sh -c 'echo "8" > /etc/yum/vars/dockerosversion'
    
  4. Install the yum-utils that provides the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  5. Add the Mirantis Container Runtime stable repository:

    sudo -E yum-config-manager \
      --add-repo \
      "$DOCKERURL/rhel/docker-ee.repo"
    
  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Temporarily store https://repos.mirantis.com in an environment variable. This variable assignment does not persist when the session ends:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/rhel" > /etc/yum/vars/dockerurl'
    

    Also, store your OS version string in /etc/yum/vars/dockerosversion. Most users should use 9, but you can also use the more specific minor version.

    sudo sh -c 'echo "9" > /etc/yum/vars/dockerosversion'
    
  4. Install the yum-utils that provides the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  5. Add the Mirantis Container Runtime stable repository:

    sudo -E yum-config-manager \
      --add-repo \
      "$DOCKERURL/rhel/docker-ee.repo"
    
Install from the repository
  1. 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.

    If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9, and if so, accept it.

  2. To install a specific version of Mirantis Container Runtime (recommended in production), list versions and install:

    1. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:

      sudo yum list docker-ee  --showduplicates | sort -r
      
      docker-ee.x86_64      23.0.ee.2-1.el7.rhel      docker-ee-stable-18.09
      

      The list returned depends on which repositories you enabled, and is specific to your version of Red Hat Enterprise Linux (indicated by .el7 in this example).

    2. Install a specific version by its fully qualified package name, which is the package name (docker-ee) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ee-23.0.1.

      sudo yum -y 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.

      For example, if you want to install the 23.0.1 version run the following:

      sudo yum -y install docker-ee-23.0.1 docker-ee-cli-23.0.1 containerd.io
      

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

  3. Start Docker:

    sudo systemctl start docker
    
  4. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

Mirantis Container Runtime is installed and running. Use sudo to run Docker commands.

Upgrade from the repository
  1. Add the new repository.

  2. Follow the installation instructions and install a new version.

Package install and upgrade

To manually install Mirantis Container Runtime, download the .rpm file for your release. You need to download a new file each time you want to upgrade.

Install with a package
  1. Enable the extras RHEL repository. This ensures access to the container-selinux package which is required by docker-ee:

    sudo yum-config-manager --enable rhel-7-server-extras-rpms
    

    Alternately, obtain that package manually from Red Hat. There is no way to publicly browse this repository.

  2. Go to repos.mirantis.com in your browser. Navigate to rhel/. Choose your Red Hat Enterprise Linux version, architecture, and Docker version. Download the .rpm file from the Packages directory.

    If you have trouble with selinux using the packages under the 7 directory, try choosing the version-specific directory instead, such as 7.3.

  3. Install MCR, changing the path below to the path where you downloaded the Docker package.

    sudo yum install <path_to_downloaded_rhel_package_.rpm>
    

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

  4. Start Docker:

    sudo systemctl start docker
    
  5. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is now installed and running. Make sure to use sudo to run Docker commands (refer to the Docker documentation for Linux postinstall for information on how to allow non-privileged users to run Docker commands.

  1. Go to repos.mirantis.com in your browser. Navigate to rhel/. Choose your Red Hat Enterprise Linux version, architecture, and Docker version. Download the .rpm file from the Packages directory.

    If you have trouble with selinux using the packages under the 8 directory, try choosing the version-specific directory instead.

  2. Install Mirantis Container Runtime, changing the path below to the path where you downloaded the Docker package.

    sudo yum install <path_to_downloaded_rhel_package_.rpm>
    

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

  3. Start Docker:

    sudo systemctl start docker
    
  4. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is now installed and running. Make sure to use sudo to run Docker commands (refer to the Docker documentation for Linux postinstall for information on how to allow non-privileged users to run Docker commands.

  1. Go to repos.mirantis.com in your browser. Navigate to rhel/. Choose your Red Hat Enterprise Linux version, architecture, and Docker version. Download the .rpm file from the Packages directory.

    If you have trouble with selinux using the packages under the 9 directory, try choosing the version-specific directory instead.

  2. Install Mirantis Container Runtime, changing the path below to the path where you downloaded the Docker package.

    sudo yum install <path_to_downloaded_rhel_package_.rpm>
    

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

  3. Start Docker:

    sudo systemctl start docker
    
  4. Verify that Mirantis Container Runtime is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

    sudo docker run hello-world
    

    Mirantis Container Runtime is now installed and running. Make sure to use sudo to run Docker commands (refer to the Docker documentation for Linux postinstall for information on how to allow non-privileged users to run Docker commands.

Upgrade with a package
  1. Download the newer package file.

  2. Repeat the installation procedure, using yum -y upgrade instead of yum -y install, and point 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
  1. Uninstall the Mirantis Container Runtime package:

    sudo yum -y remove docker-ee
    
  2. Delete all images, containers, and volumes (because these are not automatically removed from your host):

    sudo rm -rf /var/lib/docker
    
  3. Delete other Docker related resources:

    sudo rm -rf /run/docker
    sudo rm -rf /var/run/docker
    sudo rm -rf /etc/docker
    
  4. You must delete any edited configuration files manually.

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/.

  1. 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.

  2. 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.

  3. 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.

  4. 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
  1. 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"
    
  2. 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
    
  3. Import the GPG key from the repository.

    sudo rpm --import "${DOCKER_EE_BASE_URL}/sles/gpg"
    
Install Mirantis Container Runtime
  1. 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.

  2. 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.

  3. Start Docker.

    SLES 15:

    sudo systemctl start docker
    

    SLES 12:

    sudo service docker start
    
  4. 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.

  5. 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.

  6. Edit the file /etc/docker/daemon.json (create it if it does not exist) and add the following contents:

    {
      "storage-driver": "btrfs"
    }
    
  7. Save and close the file.

  8. Start Docker.

    sudo service docker start
    
  9. 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:

  1. 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.

  2. Run sudo zypper refresh.

  3. 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.

  1. Go to repos.mirantis.com in your browser.

  2. 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.

  3. Import the official Docker official GPG key.

    sudo rpm --import https://repos.mirantis.com/sles/gpg
    
  4. 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.

  5. 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.

  6. Edit the file /etc/docker/daemon.json (create it if it does not exist) and add the following contents:

    {
      "storage-driver": "btrfs"
    }
    
  7. Save and close the file.

  8. Start Docker.

    sudo service docker start
    
  9. 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
  1. Uninstall the Mirantis Container Runtime package using the command below.

    sudo zypper rm docker-ee docker-ee-cli containerd.io
    
  2. 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.

Install Mirantis Container Runtime for Ubuntu

Prerequisites

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

Uninstall old versions

Use the apt-get remove command to uninstall Docker Community versions, if present.

sudo apt-get remove docker docker-engine docker-ce docker-ce-cli docker.io

The apt-get command may report that none of the packages are installed.

Note

The contents of /var/lib/docker/, including images, containers, volumes, and networks, are preserved.

Extra steps for aufs

For Ubuntu 16.04 and higher, the Linux kernel includes support for overlay2, and Mirantis Container Runtime uses it as the default storage driver. If you need to use aufs instead, it must be manually configured.

Install Mirantis Container Runtime

Mirantis Container Runtime can be installed either by using Mirantis repositories, or by downloading and installing the DEB package and thereafter manually managing all upgrades. The Mirantis repository method is recommended, for the ease it lends in terms of both installation and upgrade tasks. The more manual DEB package approach, however, is useful in certain situations, such as installing MCR on air-gapped system that have no access to the Internet.

Continue from this point if you are using Mirantis repositories on Ubuntu, or to install from a Debian package go to Install from a Debian package.

Install using the repository

To install Mirantis Container Runtime on a new host machine using the Mirantis repository you must first set the repository up on the machine.

Set up the repository
  1. Update the apt package index.

    sudo apt-get update
    
  2. Install packages to allow apt to use a repository over HTTPS.

    sudo apt-get install \
      apt-transport-https \
      ca-certificates \
      curl \
      software-properties-common
    
  3. Temporarily store https://repos.mirantis.com in an environment variable. This variable assignment does not persist when the session ends:

    DOCKER_EE_URL="https://repos.mirantis.com"
    
  4. Temporarily add a $DOCKER_EE_VERSION variable into your environment.

    DOCKER_EE_VERSION=23.0
    
  5. Add Docker’s official GPG key using your customer Mirantis Container Runtime repository URL.

    curl -fsSL "${DOCKER_EE_URL}/ubuntu/gpg" | sudo apt-key add -
    
  6. Verify that you now have the key with the fingerprint DD91 1E99 5A64 A202 E859  07D6 BC14 F10B 6D08 5F96, by searching for the last eight characters of the fingerprint. Use the command as-is. It works because of the variable you set earlier.

    sudo apt-key fingerprint 6D085F96
    
    pub   4096R/0EBFCD88 2017-02-22
          Key fingerprint = DD91 1E99 5A64 A202 E859  07D6 BC14 F10B 6D08 5F96
    uid                  Docker Release (EE deb) <docker@docker.com>
    sub   4096R/6D085F96 2017-02-22
    
  7. Set up the stable repository, using the following command as-is (which works due to the variable set up earlier in the process).

    sudo add-apt-repository \
      "deb [arch=$(dpkg --print-architecture)] $DOCKER_EE_URL/ubuntu \
      $(lsb_release -cs) \
      stable-$DOCKER_EE_VERSION"
    

    Note

    The included lsb_release -cs sub command returns the name of your Ubuntu distribution, for example, focal.

Install Mirantis Container Runtime
  1. Update the apt package index.

    sudo apt-get update
    
  2. Install the latest version of Mirantis Container Runtime and containerd, or go to the next step to install a specific version. Any existing installation of MCR is replaced.

    sudo apt-get install docker-ee docker-ee-cli  docker-ee-rootless-extras containerd.io
    

    Warning

    If you have multiple Mirantis repositories enabled, installing or updating without specifying a version in the apt-get install or apt-get update command always installs the highest possible version, which may not be appropriate for your stability needs.

  3. On production systems, you should install a specific version of Mirantis Container Runtime instead of always using the latest. The following output is truncated.

    apt-cache madison docker-ee
    
    docker-ee | *:23.0~ee-0~ubuntu-focal | https://repos.mirantis.com/ubuntu focal/stable amd64 Packages
    

    The contents of the list depend upon which repositories are enabled, and are specific to your version of Ubuntu (indicated by the focal suffix on the version, in this example). Choose a specific version to install. The second column is the version string. The third 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 an equals sign (=).

    sudo apt-get 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.

    The MCR daemon starts automatically.

  4. Verify that MCR 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. The docker group is created but no users are added to it. You need to use sudo to run MCR commands.

Upgrade Mirantis Container Runtime
  1. If upgrading to a new major Mirantis Container Runtime version (such as when going from version 20.10 to 23.0), add the new repository.

  2. Run sudo apt-get update.

  3. Follow the installation instructions, choosing the new version you want to install.

Install from a Debian package

If you cannot use the Mirantis repository to install Mirantis Container Runtime, you can download the .deb files for your release and install them manually. You need to download a new file or set of files each time you want to upgrade Mirantis Container Runtime.

  1. Go to repos.mirantis.com in your browser.

  2. Go to /ubuntu/dists/bionic/pool/stable-<VERSION>/amd64/ and download the .deb file for the Ubuntu release and architecture you want to install.

    Note

    Starting with 19.03, you have to download three .deb files. They are docker-ee-cli_<version>.deb, containerd.io_<version>.deb, and docker-ee_<version>.deb.

  3. Install MCR, changing the path below to the path where you downloaded the Mirantis Container Runtime package.

    sudo dpkg -i <path_to_downloaded_ubuntu_package_.deb>
    

    Or, if you downloaded the three .deb files, you must install them in the following order:

    sudo dpkg -i /path/to/docker-ee-cli_<version>.deb
    sudo dpkg -i /path/to/containerd.io_<version>.deb
    sudo dpkg -i /path/to/docker-ee_<version>.deb
    

    The MCR daemon starts automatically.

  4. Verify that MCR 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. The docker group is created but no users are added to it. You need to use sudo to run MCR commands.

Upgrade Mirantis Container Runtime

To upgrade Mirantis Container Runtime, download the newer package file and repeat the installation procedure, 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
  1. Uninstall the Mirantis Container Runtime package.

    sudo apt-get purge docker-ee docker-ee-cli containerd.io
    
  2. Images, containers, volumes, or customized configuration files on your host are not automatically removed. Run the following command to delete all images, containers, and volumes.

    sudo rm -rf /var/lib/docker
    

You must delete any edited configuration files manually.

Install MCR on Windows Servers

Mirantis Container Runtime (MCR) enables native Docker containers on Windows Server. Windows Server 2019 and later versions are supported. The Mirantis Container Runtime installation package includes everything you need to run Docker on Windows Server. This topic describes pre-install considerations, and how to download and install Mirantis Container Runtime.

System requirements

Windows OS CPU and RAM requirements that must be met are specified in the Windows Server Requirements.

Install MCR with an Internet connection

Mirantis provides an installation script to ease MCR installation on a Windows Server machine. The script uses default values, thus allowing it to be run without configuration. You can, however, override the default values with script parameters and env variables. Parameter values take precedence over env variables. Both take precedence over inbuilt default values.

The installation script must be executed from an elevated command prompt. If you want to change the default daemon values, ensure that you have the alternative cofigurations and the related collateral in place prior to executing the script. For example, if you want to enable TLS, store the certificates and write the daemon configuration file before invoking the script.

  1. Obtain the installation script for MCR for Windows Server at https://get.mirantis.com/install.ps1.

  2. (Optional): Allow downloaded script files to run in the current session

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force -Scope Process;
    
  3. Run the installation script.

    The installer will issue a prompt, should it require a reboot.

    Note

    The installation script installs a numerically higher version by default. The latest tag, however, explicitly denotes the binary that was last pushed, which may not be a numerically higher version.

  4. Test your MCR installation by running the hello-world container.

    docker run hello-world:nanoserver
    

    The container starts, prints the Hello from Docker! message, and then exits.

    Unable to find image 'hello-world:nanoserver' locally
    nanoserver: Pulling from library/hello-world
    bce2fbc256ea: Pull complete
    3ac17e2e6106: Pull complete
    8cac44e17f16: Pull complete
    5e160e4d8db3: Pull complete
    Digest: sha256:25eac12ba40f7591969085ab3fb9772e8a4307553c14ea72d0e6f98b2c8ced9d
    Status: Downloaded newer image for hello-world:nanoserver
    
    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    
FIPS 140-2 cryptographic module support

Federal Information Processing Standards (FIPS) Publication 140-2 is a United States Federal security requirement for cryptographic modules.

MCR provides FIPS 140-2 support in Windows Server, which includes a FIPS supported cryptographic module. If the Windows implementation already has FIPS support enabled, FIPS is automatically enabled in MCR.

Note

FIPS 140-2 is only supported in MCR. MKE and MSR currently do not support FIPS 140-2.

To enable FIPS 140-2 compliance on a system that is not in FIPS 140-2 mode, run the following command in PowerShell:

[System.Environment]::SetEnvironmentVariable("DOCKER_FIPS", "1", "Machine")

You can also enable FIPS 140-2 mode using the Windows Registry. To update the pertinent registry key, execute the following PowerShell command as an Administrator:

Set-ItemProperty -Path "HKLM:\System\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy\" -Name "Enabled" -Value "1"

Restart the Docker service.

Stop-Service docker
Start-Service docker

To confirm Docker is running with FIPS-140-2 enabled, run the docker info.

Labels:
 com.docker.security.fips=enabled

Note

FIPS-140-2 compliance can be disabled if the FIPS-140-2 cryptographic module is installed on the operating system. To disable FIPS-140-2 in Docker but not the operating system, set the value "DOCKER_FIPS","0" in [System.Environment].\

Install MCR offline

If your hardware is air-gapped you can still install MCR. To do so, download the installer and copy the files to the air-gapped machine (the default installation assumes that the zipped files and script are in the same location).

  1. On any Internet connected system, go to https://get.mirantis.com/install.ps1 to obtain the MCR for Windows Server installation script.

  2. (Optional): Allow the downloaded script files to run in the current session.

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force -Scope Process;
    
  3. Run the installation script with the -DownloadOnly parameter. As per the parameter name, this action only downloads the zip file (no installation is performed).

    .\<installation-script> -DownloadOnly
    
  4. Copy the installation script and the installation zip file over to the air-gapped machine and run the install with the -Offline parameter.

    .\<installation-script> -Offline
    
  5. If prompted, reboot the installer.

Install a specific version

Use the following three parameters separately or in tandem to install a specific version of MCR for Windows Server.

Caution

MCR does not support using earlier versions of containerd than the version with which it is released. For supported containerd versions, refer to the Major component versions section of the required MCR version in Release Notes.

.\install.ps1 -Channel
.\install.ps1 -ContainerdVersion
.\install.ps1 -DockerVersion

For example, the installation script will always use the latest GA.

For parameter descriptions, refer to Install script usage.

Update MCR

To update MCR to the most recent release, download the latest copy of the installation script and rerun the installation steps.

  1. Go to the Mirantis Container Runtime for Windows Server web page to obtain the installation script for MCR for Windows Server.

  2. (Optional): Allow downloaded script files to run in the current session.

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force -Scope Process
    
  3. Run the installation script.

Install script usage

The installation script uses the parameters detailed below.

Parameter

Description

.PARAMETER DownloadUrl

[Alternately specified by $Env:DOWNLOAD_URL] Specifies an alternative repository in which to download container runtime packages.

.PARAMETER Channel

[Alternately specified by $Env:CHANNEL] Specifies which channel to use for picking the binaries (examples include stable and test). Default: stable.

.PARAMETER DockerVersion

[Alternately specified by $Env:DOCKER_VERSION] Specifies the version number for the DockerEE binaries to install. The latest version is the default.

.PARAMETER ContainerdVersion

[Alternately specified by $Env:CONTAINERD_VERSION] Specifies the version number for the containerd binaries to install The latest version is the default.

.PARAMETER DryRun

If specified, list different steps to use without actually invoking those steps.

.PARAMETER Uninstall

If specified, uninstalls all packages. This includes unregistering the corresponding services and removing paths for the package from the registry. All other script parameters (except DryRun and DestPath) are ignored if this switch is specified. Common parameters such as -Verbose are still honored.

.PARAMETER Ver

Print version info for the script and exit.

.PARAMETER NoServiceStarts

If specified, services are not started on successful install. By default, all services installed by the script are left in a running state before exit.

.PARAMETER DestPath

Path to the directory under which binaries will be installed. Default: %PROGRAMDATA%

.PARAMETER OfflinePackagesPath

The folder for airgap/offline scenarios. For use when the offline or DownloadOnly parameters are specified. Used to either save the downloaded packages for later offline use or for pointing to previously downloaded packages for offline install.

.PARAMETER Offline

Install packages in offline/airgap mode. By default the current directory is used to locate previously downloaded packages, a setting that can be overridden by using the OfflinePackagesPath parameter.

.PARAMETER DownloadOnly

Download and save packages for later offline/airgap install.

.PARAMETER EngineOnly

Skip all steps except those related to MCR.

Install script notes

  1. In scenarios where you have existing software installed that has its own copies of OpenSSL libraries, you may encounter the following error:

    OpenSSL error: error:0F06D065:common libcrypto
    routines:FIPS_mode_set:fips mode not supported
    

    This is often arises if you have ming/mingw64 as a part of your PATH env variable. As a workaround, ensure that the offending software is not on the PATH and run the script again.

  2. The script supports airgap functionality by providing access to download packages while online, as well as to install those selfsame packages while offline.

    For downloads, please ensure that the script has access to the internet. Use the -DownloadOnly parameter. By default the script will use the current directory to store the packages after download, a setting that can be changed by specifying the path explicitly with the -OfflinePackagesPath parameter.

    For offline/airgap install, please use the -Offline parameter. By default the script searches for pacakages in the current directory, a setting that can be changed by specifying the -OfflinePackagesPath parameter.

    While downloading using -DownloadOnly parameter, confirm that the download path is accessible to the script, especially if you run the script without administrative rights.

The following is required so that the script can be invoked with named parameters (for example, -ContainerdVersion 1.3.4...). If a parameter is used, its type is checked by powershell - we give a higher precedence to the parameters specified in this manner versus the same value specified by env vars.

Parameters received at invocation time. Some of these values are merged with values specified by env vars - see reconcileParams. Others are used as-is.

Disable 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 Mirantis to better understand the operational use of MCR by our customers. It also provides key feedback in the form of product usage statistics, which enables our product teams to enhance Mirantis products and services.

To disable the telemetry function, set features.telemetry to false in the daemon.json file, which is located in C:\ProgramData\docker\config\.

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

You can change the setting back to true to re-enable telemetry

Caution

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

Uninstall MCR

Use the following commands to remove MCR from a Windows Server.

  1. Leave any active Docker Swarms.

    docker swarm leave --force
    
  2. Prune container data.

    docker system prune -all
    
  3. Run the installation script using the uninstall flag to remove MCR from the system.

Use MCR with Kubernetes

Customers who use MCR with Kubernetes directly (without MKE) must use a plugin maintained by Kubernetes called dockershim for Kubernetes 1.23 and below or a plugin maintained by Mirantis called cri-docker (included in MCR) for Kubernetes 1.24 and above.

To configure cri-docker:

systemctl enable cri-docker.service

Use MCR with Docker Swarm

Mirantis Container Runtime (MCR) supports the use of Docker Swarm.

The following Docker documentation topics offer detailed information that can help you to run MCR in swarm mode:

Security

Several Docker resources are available which cover the basics of Mirantis Container Runtime security, including:

Antivirus and antimalware

When antivirus and antimalware software products scan files in use by MCR, these files can lock in a way that causes Docker commands to hang or causes orphaned snapshots to leak disk space. To circumvent these problems, you can add the Docker data directory to the software’s exclusion list, which is by default /var/lib/docker on Linux systems and %ProgramData%\docker on Windows Server systems. As a result of this action, though, viruses or malware in local Docker images, writable layers of containers, or volumes will go undetected.

Note

If you choose to exclude the Docker data directory from background virus scanning, Mirantis recommends that you schedule recurring tasks for stopping MCR, for scanning the data directory, and for restarting MCR. Make sure to stagger these recurring tasks, though, as running them in sync can cause a system outage.

Docker Content Trust

When transferring data among networked systems, trust is a central concern. In particular, when communicating over an untrusted medium such as the internet, it is critical to ensure the integrity and the publisher of all the data a system operates on. You use Docker Engine to push and pull images to a public or private registry. Docker Content Trust (DCT) gives you the ability to verify both the integrity and the publisher of all the data received from a registry over any channel.

Docker Content Trust provides the ability to use digital signatures for data sent to and received from remote Docker registries. These signatures allow client-side or runtime verification of the integrity and publisher of specific image tags.

Through DCT, image publishers can sign their images and image consumers can verify the signatures of the images they pull. Publishers could be individuals or organizations manually signing their content or automated software supply chains signing content as part of their release process.

Image tags and DCT

An individual image record has the following identifier:

[REGISTRY_HOST[:REGISTRY_PORT]/]REPOSITORY[:TAG]

A particular image REPOSITORY can have multiple tags. For example, latest and 3.1.2 are both tags on the mongo image. An image publisher can build an image and tag combination many times changing the image with each build.

DCT is associated with the TAG portion of an image. Each image repository has a set of keys that image publishers use to sign an image tag. Image publishers have discretion on which tags they sign.

An image repository can contain an image with one tag that is signed and another tag that is not. For example, consider the Mongo image repository. The latest tag could be unsigned while the 3.1.6 tag could be signed. It is the responsibility of the image publisher to decide if an image tag is signed or not. In this representation, some image tags are signed, others are not:

_images/tag_signing.png

Publishers can choose to sign a specific tag or not. As a result, the content of an unsigned tag and that of a signed tag with the same name may not match. For example, a publisher can push a tagged image someimage:latest and sign it. Later, the same publisher can push an unsigned someimage:latest image. This second push replaces the last unsigned tag latest but does not affect the signed latest version. The ability to choose which tags they can sign allows publishers to iterate over the unsigned version of an image before officially signing it.

Image consumers can enable DCT to ensure that images they use are signed. If a consumer enables DCT, they can only pull, run, or build with trusted images. Enabling DCT is a bit like applying a “filter” to your registry. Consumers “see” only signed image tags while the less desirable, unsigned image tags are “invisible” to them.

_images/trust_view.png

To the consumer who has not enabled DCT, nothing changes with regard to how they work with Docker images. Every image is visible regardless of whether it is signed or not.

Docker Content Trust Keys

Trust for an image tag is managed through the use of signing keys. A key set is created when an operation using DCT is first invoked. A key set consists of the following classes of keys:

  • an offline key that is the root of DCT for an image tag

  • repository or tagging keys that sign tags

  • server-managed keys such as the timestamp key, which provides freshness security guarantees for your repository

The following image depicts the various signing keys and their relationships:

_images/trust_components.png

Warning

Once lost, the root key is not recoverable.

You should back up the root key somewhere safe. Given that it is only required to create new repositories, you should store it offline in hardware. For details on securing, and backing up your keys, make sure you read Manage keys for content trust.

Signing Images with Docker Content Trust

Within the Docker CLI, you can sign and push a container image with the $ docker trust command syntax. This is built on top of the Notary feature set, more information for which can be found in the Notary Github Repository.

A prerequisite for signing an image is a container image Registry with a Notary server attached, such as a Mirantis Secure Registry or Docker Hub. Instructions for standing up a self-hosted environment can be found in the Docker official documentation, Deploy Notary Server with Compose.

A delegation key pair is required to sign a container image. These keys can be generated locally using $ docker trust key generate or generated by a certificate authority. If you are using Mirantis Kubernetes Engine, the Client Bundle provides adequate keys for a delegation.

To sign images with Docker Content Trust:

  1. Add the delegation private key to the local Docker trust repository, which by default is stored in ~/.docker/trust/.

    • If you are generating delegation keys with $ docker trust key generate, the private key is automatically added to the local trust store.

    • If you are importing a separate key, such as one from a MKE Client Bundle, you must use the $ docker trust key load command:

      $ docker trust key generate jeff
      Generating key for jeff...
      Enter passphrase for new jeff key with ID 9deed25:
      Repeat passphrase for new jeff key with ID 9deed25:
      Successfully generated and loaded private key. Corresponding public key
      available: /home/ubuntu/Documents/mytrustdir/jeff.pub
      
    • If you have an existing key, run the following command:

      $ docker trust key load key.pem --name jeff
      Loading key from "key.pem"...
      Enter passphrase for new jeff key with ID 8ae710e:
      Repeat passphrase for new jeff key with ID 8ae710e:
      Successfully imported key from key.pem
      
  2. Add the delegation public key to the Notary server. Each delegation key in Notary is specific to a particular image repository. If this is the first time you are adding a delegation to that repository, this command will also initiate the repository, using a local Notary canonical root key. To understand more about initiating a repository, and the role of delegations, refer to the official Docker documentation, Delegations for content trust.

    $ docker trust signer add --key cert.pem jeff msr.example.com/admin/demo
    Adding signer "jeff" to msr.example.com/admin/demo...
    Enter passphrase for new repository key with ID 10b5e94:
    
  3. Use the delegation private key to sign a particular tag and push the signature up to the registry.

    $ docker trust sign msr.example.com/admin/demo:1
    Signing and pushing trust data for local image msr.example.com/admin/demo:1, may overwrite remote trust data
    The push refers to repository [msr.example.com/admin/demo]
    7bff100f35cb: Pushed
    1: digest: sha256:3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e size: 528
    Signing and pushing trust metadata
    Enter passphrase for signer key with ID 8ae710e:
    Successfully signed msr.example.com/admin/demo:1
    

    Alternatively, once the keys have been imported an image can be pushed with the $ docker push command:

    $ export DOCKER_CONTENT_TRUST=1
    
    $ docker push msr.example.com/admin/demo:1
    The push refers to repository [msr.example.com/admin/demo:1]
    7bff100f35cb: Pushed
    1: digest: sha256:3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e size: 528
    Signing and pushing trust metadata
    Enter passphrase for signer key with ID 8ae710e:
    Successfully signed msr.example.com/admin/demo:1
    

To view remote trust data for a tag or repository:

Run the $ docker trust inspect command to view remote trust data for a tag or a repository:

$ docker trust inspect --pretty msr.example.com/admin/demo:1

Signatures for msr.example.com/admin/demo:1

SIGNED TAG          DIGEST                                                             SIGNERS
1                   3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e   jeff

List of signers and their keys for msr.example.com/admin/demo:1

SIGNER              KEYS
jeff                8ae710e3ba82

Administrative keys for msr.example.com/admin/demo:1

  Repository Key:    10b5e94c916a0977471cc08fa56c1a5679819b2005ba6a257aa78ce76d3a1e27
  Root Key:  84ca6e4416416d78c4597e754f38517bea95ab427e5f95871f90d460573071fc

To remove remote trust data for a tag:

Run the $ docker trust revoke command to remove remote trust data for a tag:

$ docker trust revoke msr.example.com/admin/demo:1
Enter passphrase for signer key with ID 8ae710e:
Successfully deleted signature for msr.example.com/admin/demo:1
Runtime Enforcement with Docker Content Trust

Note

  • Runtime enforcement is a feature that is exclusive to MCR. It is not available in Moby or Docker CE.

  • The implementation is separate from the only run signed images feature of Mirantis Kubernetes Engine.

Docker Content Trust within the Mirantis Container Runtime prevents a user from using a container image from an untrusted source. It will also prevent a user from building a container image from a base layer from an untrusted source. Trusted sources can include Official Docker Images, found on the Docker Hub or User trusted sources, with repositories and tags signed with the commands detailed in Signing Images with Docker Content Trust.

Engine Signature Verification prevents the following:

  • $ docker container run of an unsigned or altered image.

  • $ docker pull of an unsigned or altered image.

  • $ docker build where the FROM image is not signed or is not scratch.

Note

The implicit pulls and runs performed by worker nodes for a Swarm service on $ docker service create and $ docker service update are also verified. Tag resolution of services requires that all nodes in the Swarm including managers have content trust enabled and similarly configured.

DCT does not verify that the filesystem of a running container has not been altered from what was in the image. For example, it does not prevent a container from writing to the filesystem, once the container is running. Moreover, it does not prevent the image filesystem from being altered on the disk of a Docker host. DCT will also not prevent unsigned images from being imported, loaded, or created.

Enabling DCT within the Mirantis Container Runtime

DCT is controlled by the Docker Engine configuration file, which by default is located at /etc/docker/daemon.json. For more information on the configuration file, refer to the official docker documentation, Daemon configuration file.

Note

The configuration can be set only on Linux machines.

The content-trust section is based around a mode option that instructs the engine on whether to enforce signed images, and a trust-pinning section that instructs the engine on which sources to trust.

Mode can take one of three values: disabled, permissive, or enforced.

disabled

Verification is not active and the remainder of the content-trust related configuration is ignored. This is the default value if mode is not specified.

permissive

Verification will be performed, while failures are only logged. Images that cannot be verified successfully can still be pulled and run. This configuration is intended for testing of changes related to content-trust. The results of the signature verification are displayed in the MCR daemon logs.

enforced

Content trust is enforced, thus an image that cannot be verified successfully is not pulled or run.

{
    "content-trust": {
        "mode": "<variable-type>"
    }
}
Official Docker images

Note

The IDs of all Notary root keys that are used to verify Docker Official Images are embedded in MCR.

If you want to configure MCR so that only Docker Official Images can be used, you can configure your daemon to do so using the embedded key IDs:

{
  "content-trust": {
    "trust-pinning": {
      "official-library-images": true
    },
    "mode": "enforced"
  }
}
User-signed images

There are two options for trust pinning user-signed images: Notary Canonical Root Key ID and Notary Root key ID.

Notary canonical root key ID

The Notary Canonical Root Key ID, or DCT Root Key, describes only the root key used to sign a repository, or rather its respective keys. This is the root key on the host that originally signed the repository, such as your workstation. It can be retrieved from the workstation that signed the repository through $ grep -r "root" ~/.docker/trust/private/ (assuming your trust data is at ~/.docker/trust/*). It is expected that this canonical ID has initiated multiple image repositories (mymsr/user1/image1 and mymsr/user1/image2).

  1. Retrieve root ID:

    $ grep -r "root" ~/.docker/trust/private
    /home/ubuntu/.docker/trust/private/0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403.key:role:
    root
    
  2. Use a canonical ID. In the example that follows, the canonical ID has signed two repos, mymsr/user1/repo1 and mymsr/user1/repo2. Note that wildcards are allowed.

    {
      "content-trust": {
        "trust-pinning": {
          "root-keys": {
            "mymsr/user1/*": [
              "0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403"
            ]
          }
        },
        "mode": "enforced"
      }
    }
    
Notary root key ID

The Notary Root key ID, or DCT Certificate ID, describes the same as the Notary Canonical Root Key ID; the ID is unique per repository. For example, mymsr/user1/image1 and mymsr/usr1/image2 will each have a unique certificate ID. A certificate ID can be retrieved through a $ docker trust inspect command, labeled as a root-key, referring back to the Notary key name. This is designed for when different users are signing their own repositories, such as when there is no central signing server. As a cert-id is more granular, it would take priority if a conflict occurs over a root ID.

  1. Retrieve root ID:

    $ docker trust inspect mymsr/user1/repo1 | jq -r '.[].AdministrativeKeys[] | select(.Name=="Root") | .Keys[].ID'
    9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168
    
  2. Use cert IDs by specifying two repositories with their DCT root ID.

     {
       "content-trust": {
         "trust-pinning": {
           "cert-ids": {
              "mymsr/user1/repo1": [
                "9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168"
              ],
              "mymsr/user2/repo1": [
                "544cf09f294860f9d5bc953ad80b386063357fd206b37b541bb2c54166f38d08"
              ]
           }
         },
         "mode": "enforced"
       }
    }
    
Using DCT in an offline environment

If your engine is unable to communicate to the registry, DCT can be enabled to trust cached signature data. This is configured through the allow-expired-cached-trust-data option.

{
  "content-trust": {
    "trust-pinning": {
      "official-library-images": true,
      "root-keys": {
        "mymsr/user1/*": [
          "0b6101527b2ac766702e4b40aa2391805b70e5031c04714c748f914e89014403"
        ]
      },
      "cert-ids": {
        "mymsr/user2/repo1": [
          "9430d6e31e3b3e240957a1b62bbc2d436aafa33726d0fcb50addbf7e2dfa2168"
        ],
      }
    },
    "mode": "enforced",
    "allow-expired-cached-trust-data": true
  }
}
Client Enforcement with Docker Content Trust

Content trust is disabled by default in the Docker Client. To enable it, set the DOCKER_CONTENT_TRUST environment variable to 1. This prevents users from working with tagged images unless they contain a signature.

When DCT is enabled in the Docker client, docker CLI commands that operate on tagged images must either have content signatures or explicit content hashes. The commands that operate with DCT are:

  • push

  • build

  • create

  • pull

  • run

For example, with DCT enabled a docker pull someimage:latest command only succeeds if someimage:latest is signed. However, an operation with an explicit content hash always succeeds as long as the hash exists:

$ docker pull msr.example.com/user/image:1
Error: remote trust data does not exist for msr.example.com/user/image: msr.example.com does not have trust data for msr.example.com/user/image

$ docker pull msr.example.com/user/image@sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a
sha256:ee7491c9c31db1ffb7673d91e9fac5d6354a89d0e97408567e09df069a1687c1: Pulling from user/image
ff3a5c916c92: Pull complete
a59a168caba3: Pull complete
Digest: sha256:ee7491c9c31db1ffb7673d91e9fac5d6354a89d0e97408567e09df069a1687c1
Status: Downloaded newer image for msr.example.com/user/image@sha256:ee7491c9c31db1ffb7673d91e9fac5d6354a89d0e97408567e09df069a1687c1

Open Source Components and Licenses

Click any product component license below to download a text file of that license to your local system.

Get Support

Subscriptions for MKE, MSR, and MCR provide access to prioritized support for designated contacts from your company, agency, team, or organization. Mirantis service levels for MKE, MSR, and MCR are based on your subscription level and the Cloud (or cluster) you designate in your technical support case. Our support offerings are described here, and if you do not already have a support subscription, you may inquire about one via the contact us form.

Mirantis’ primary means of interacting with customers who have technical issues with MKE, MSR, or MCR is our CloudCare Portal. Access to our CloudCare Portal requires prior authorization by your company, agency, team, or organization, and a brief email verification step. After Mirantis sets up its back end systems at the start of the support subscription, a designated administrator at your company, agency, team or organization, can designate additional contacts. If you have not already received and verified an invitation to our CloudCare Portal, contact your local designated administrator, who can add you to the list of designated contacts. Most companies, agencies, teams, and organizations have multiple designated administrators for the CloudCare Portal, and these are often the persons most closely involved with the software. If you don’t know who is a local designated administrator, or are having problems accessing the CloudCare Portal, you may also send us an email.

Once you have verified your contact details via our verification email, and changed your password as part of your first login, you and all your colleagues will have access to all of the cases and resources purchased. We recommend you retain your ‘Welcome to Mirantis’ email, because it contains information on accessing our CloudCare Portal, guidance on submitting new cases, managing your resources, and so forth. Thus, it can serve as a reference for future visits.

We encourage all customers with technical problems to use the knowledge base, which you can access on the Knowledge tab of our CloudCare Portal. We also encourage you to review the MKE, MSR, and MCR products documentation which includes release notes, solution guides, and reference architectures. These are available in several formats. We encourage use of these resources prior to filing a technical case; we may already have fixed the problem in a later release of software, or provided a solution or technical workaround to a problem experienced by other customers.

One of the features of the CloudCare Portal is the ability to associate cases with a specific MKE cluster; these are known as “Clouds” in our portal. Mirantis has pre-populated customer accounts with one or more Clouds based on your subscription(s). Customers may also create and manage their Clouds to better match how you use your subscription.

We also recommend and encourage our customers to file new cases based on a specific Cloud in your account. This is because most Clouds also have associated support entitlements, licenses, contacts, and cluster configurations. These greatly enhance Mirantis’ ability to support you in a timely manner.

You can locate the existing Clouds associated with your account by using the “Clouds” tab at the top of the portal home page. Navigate to the appropriate Cloud, and click on the Cloud’s name. Once you’ve verified that Cloud represents the correct MKE cluster and support entitlement, you can create a new case via the New Case button towards the top of the Cloud’s page.

One of the key items required for technical support of most MKE, MSR, and MCR cases is the support dump. This is a compressed archive of configuration data and log files from the cluster. There are several ways to gather a support dump, each described in the paragraphs below. After you have collected a support dump, you can upload the dump to your new technical support case by following this guidance and using the “detail” view of your case.

Use the Web UI to get a support dump

To get the support dump from the web UI:

  1. Log into the MKE web UI with an administrator account.

  2. In the top-left menu, click your username and choose Support Dump.

It may take a few minutes for the download to complete.

To submit the support dump to Mirantis Customer Support:

  1. Click Share support bundle on the success prompt that displays when the support dump finishes downloading.

  2. Fill in the Jira feedback dialog, and click Submit.

Use the CLI to get a support dump

To get the support dump from the CLI, use SSH to log into a node and run:

MKE_VERSION=$((docker container inspect ucp-proxy --format '{{index .Config.Labels "com.docker.ucp.version"}}' 2>/dev/null || echo -n 3.2.6)|tr -d [[:space:]])

docker container run --rm \
--name ucp \
-v /var/run/docker.sock:/var/run/docker.sock \
--log-driver none \
mirantis/ucp:${MKE_VERSION} \
support > \
docker-support-${HOSTNAME}-$(date +%Y%m%d-%H_%M_%S).tgz

Note

The support dump only contains logs for the node where you’re running the command. If your MKE is highly available, you should collect support dumps from all of the manager nodes.

To submit the support dump to Mirantis Customer Support, add the --submit option to the support command. This will send the support dump along with the following information:

  • Cluster ID

  • MKE version

  • MCR version

  • OS/architecture

  • Cluster size

Use PowerShell to get a support dump

Run the following command on Windows worker nodes to collect the support information and automatically place it in a zip file:

$MKE_SUPPORT_DIR = Join-Path -Path (Get-Location) -ChildPath 'dsinfo'
$MKE_SUPPORT_ARCHIVE = Join-Path -Path (Get-Location) -ChildPath $('docker-support-' + (hostname) + '-' + (Get-Date -UFormat "%Y%m%d-%H_%M_%S") + '.zip')
$MKE_PROXY_CONTAINER = & docker container ls --filter "name=ucp-proxy" --format "{{.Image}}"
$MKE_REPO = if ($MKE_PROXY_CONTAINER) { ($MKE_PROXY_CONTAINER -split '/')[0] } else { 'mirantis' }
$MKE_VERSION = if ($MKE_PROXY_CONTAINER) { ($MKE_PROXY_CONTAINER -split ':')[1] } else { '3.5.5' }
docker container run --name windowssupport `
-e UTILITY_CONTAINER="$MKE_REPO/ucp-containerd-shim-process-win:$MKE_VERSION" `
-v \\.\pipe\docker_engine:\\.\pipe\docker_engine `
-v \\.\pipe\containerd-containerd:\\.\pipe\containerd-containerd `
-v 'C:\Windows\system32\winevt\logs:C:\eventlogs:ro' `
-v 'C:\Windows\Temp:C:\wintemp:ro' $MKE_REPO/ucp-dsinfo-win:$MKE_VERSION
docker cp windowssupport:'C:\dsinfo' .
docker rm -f windowssupport
Compress-Archive -Path $MKE_SUPPORT_DIR -DestinationPath $MKE_SUPPORT_ARCHIVE

Release Notes

Important

Mirantis Container Runtime 23.0 follows the version numbering scheme of the upstream Moby and Docker CLI projects. Mirantis may skip upstream versions released in short succession, though, and opt instead to release a patch that contains the content of all upstream versions released in the intervening period since the previous MCR 23.0 patch release.

MCR 23.0.10 current

Patch release for MCR 23.0, which focuses on the delivery of CVE and bug fixes.

  • Updated containerd to version 1.6.30~rc.2

  • Updated runc to 1.1.12-rc1.m1

  • Updated cri-dockerd to version 0.3.11

  • Updated Fipster (Go runtime) to version go1.21.8m1

MCR 23.0.9-1

Patch release for MCR 23.0 that delivers a runc update that fixes CVE-2024-21626.

MCR 23.0.9

Patch release for MCR 23.0, which focuses on the delivery of CVE and bug fixes.

  • Fixed an issue that pertains to the enabling of FIPS for Swarm.

  • Fixed an issue that prevented docker exec from working in FIPS mode.

  • Updated Fipster (Go runtime) to version 1.20.12m1

  • Updated containerd to version 1.6.28-rc.1

  • Update cri-dockerd to version 0.3.9

  • Updated buildx version 0.12.0m (4932eecc)

MCR 23.0.8

Patch release for MCR 23.0, which introduces the following key product improvements:

  • Updated Fipster (Go runtime) to version go1.20.10m1

  • Updated containerd to version 1.6.25-rc.1

  • Update cri-dockerd to version 0.3.7

  • Updated buildx version 0.12.0-rc1

  • Resolved CVEs in the Go runtime

MCR 23.0.7

Patch release for MCR 23.0, which introduces the following key product improvements:

  • Updated Fipster (Go runtime) to version go1.19.12m1

  • Updated containerd to version 1.6.22

  • Resolved CVEs in the Go runtime

MCR 23.0.6

Patch release for MCR 23.0, which introduces the following key product improvements:

  • Updated Fipster (Go runtime) to version go1.19.10m1

  • Updated containerd to version 1.6.21

  • Updated docker buildx to version 0.10.5

  • Updated cri-dockerd to version 0.3.4

  • Resolved CVEs in the Go runtime

MCR 23.0.5

Patch release for MCR 23.0, which introduces the following key product improvements:

  • Updated Fipster (Go runtime) to version go1.19.8m1

  • Bug fixes in the daemon and CLI

  • Resolved CVEs in the Go runtime

MCR 23.0.3

Patch release for MCR 23.0, which introduces the following key product improvements:

  • Updated Fipster (Go runtime) to version go1.19.7m3

  • Updated containerd to version 1.6.19

  • Updated docker buildx to version 0.10.4

  • Updated cri-dockerd to version 0.3.1

  • Resolved CVEs in Moby

  • Resolved CVEs in the Go runtime and FIPS module

MCR 23.0.1

Initial release for MCR 23.0, which introduces the following features and improvements:

  • Storage driver removals

  • Semantic Versioning (SemVer) format

  • CSI drivers

  • BuildKit and buildx by default

  • Volume Prune and API 1.42

  • Windows Server 2019 required

  • Health checks

  • Rootless and seccomp

23.0.10

Release date

Name

Upstream release

2024-MAR-20

MCR 23.0.10

Moby 23.0.10 and Docker CLI 23.0.10

Important

Following the initial MCR 23.0.10 patch release, as testing and internal usage continued, it was discovered that Mirantis customers on Linux could be impacted by an upstream race condition issue in the 1.6.30-rc.1 version of containerd. To remedy the matter, Mirantis quickly replaced that version of containerd with a new version, containerd 1.6.30~rc.2.

Mirantis recommends that you check the containerd version on your MCR 23.0.10 deployment. If you have containerd 1.6.30-rc.1, download and install containerd 1.6.30-rc.2.

To learn more about the upstream race container issue, refer to Mirantis patches containerd to address race condition on the Mirantis blog.

Changelog

MCR 23.0.10 comprises the Moby 23.0.10 upstream release.

Changes specific to MCR
  • MCR contains the following component updates:

    • containerd 1.6.30~rc.2

    • runc 1.1.12-rc1.m1

    • cri-dockerd 0.3.11

    • Fipster (Go runtime) go1.21.8m1

Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.10 release:

Major component versions

Version detail for the major components that comprise MCR 23.0.10 is presented in the table below:

23.0.9-1

For information on the MCR 23.0.9-1 release and its effect on MKE, refer to the the following technical bulletins:

Important

Launchpad users should confirm that they have installed the latest version before using the product to install MCR 23.0.9-1.

Release date

Name

Upstream release

2024-FEB-08

MCR 23.0.9-1

Moby 23.0.9 and Docker CLI 23.0.9

Changelog

MCR 23.0.9-1 comprises the Moby 23.0.9 upstream release.

Changes specific to MCR

An upgrade to runc 1.1.11-rc1.m1 resolves CVE-2024-21626.

Major component versions

Version detail for the major components that comprise MCR 23.0.9-1 is presented in the table below:

23.0.9

Release date

Name

Upstream release

2024-JAN-31

MCR 23.0.9

Moby 23.0.9 and Docker CLI 23.0.9

Changelog

MCR 23.0.9 comprises the Moby 23.0.9 upstream release.

Changes specific to MCR

Fixed an issue that pertains to the enabling of FIPS for Swarm. Users need to be aware that with this fix in place, FIPS-disabled nodes can no longer join a FIPS-enabled cluster.

Fixed an issue that prevented docker exec from working in FIPS mode.

  • MCR contains the following component updates:

    • containerd 1.6.28-rc.1

    • cri-dockerd 0.3.9

    • buildx 0.12.0m (4932eecc)

    • Fipster (Go runtime) 1.20.12m1

Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.9 release:

Major component versions

Version detail for the major components that comprise MCR 23.0.9 is presented in the table below:

23.0.8

Release date

Name

Upstream release

2023-11-20

MCR 23.0.8

Moby 23.0.8 and Docker CLI 23.0.8

Changelog

MCR 23.0.8 comprises the Moby 23.0.8 upstream release.

Changes specific to MCR
  • MCR contains the following component updates:

    • containerd 1.6.25-rc.1

    • cri-dockerd 0.3.7

    • buildx 0.12.0-rc1

    • Fipster (Go runtime) go1.20.10m1

Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.8 release:

Major component versions

Version detail for the major components that comprise MCR 23.0.8 is presented in the table below:

Component

Version

Moby

23.0.8

containerd

1.6.25-rc.1

runc

1.1.9

cri-dockerd

0.3.7

buildx

0.12.0-rc1

Fipster (Go runtime)

go1.20.10m1

buildkit

0.10.7-0.20230412161310-d52b2d584242

rootlesskit

1.1.0

23.0.7

Release date

Name

Upstream release

2023-09-26

MCR 23.0.7

Moby 23.0.7 and Docker CLI 23.0.7

Changelog

MCR 23.0.7 comprises the Moby 23.0.7 upstream release.

Changes specific to MCR
Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.7 release:

Major component versions

Version detail for the major components that comprise MCR 23.0.7 is presented in the table below:

Component

Version

Moby

23.0.7

Docker CLI

23.0.7

containerd

1.6.22

runc

1.1.8

cri-dockerd

0.3.4

buildx

0.10.7

Fipster (Go runtime)

go1.19.12m1

buildkit

0.10.7-0.20230412161310-d52b2d584242

rootlesskit

1.1.0

23.0.6

Release date

Name

Upstream release

2023-07-13

MCR 23.0.6

Moby 23.0.6 and Docker CLI 23.0.6

Changelog

MCR 23.0.6 comprises the Moby 23.0.6 upstream release.

Changes specific to MCR
Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.6 release:

Major component versions

Version detail for the major components that comprise MCR 23.0.5 is presented in the table below:

Component

Version

Moby

23.0.6

Docker CLI

23.0.6

containerd

1.6.21

runc

1.1.7

cri-dockerd

0.3.4

buildx

0.10.5

Fipster (Go runtime)

go1.19.10m1

buildkit

0.10.7-0.20230412161310-d52b2d584242

rootlesskit

1.1.0

23.0.5

Release date

Name

Upstream release

2023-05-16

MCR 23.0.5

Moby 23.0.5 and 23.0.4, Docker CLI 23.0.5 and 23.0.4

Changelog

MCR 23.0.5 combines the Moby 23.0.4 and Moby 23.0.5 upstream releases.

Changes specific to MCR
Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.4 and Moby 23.0.5 releases:

Major component versions

Version detail for the major components that comprise MCR 23.0.5 is presented in the table below:

Component

Version

Moby

23.0.5

Docker CLI

23.0.5

containerd

1.6.20

runc

1.1.4

cri-dockerd

0.3.1

buildx

0.10.4

Fipster (Go runtime)

go1.19.8m1

buildkit

0.10.7-0.20230208155512-4f0ee09c40e2

rootlesskit

1.1.0

23.0.3

Release date

Name

Upstream release

2023-04-04

MCR 23.0.3

Moby 23.0.3 and 23.0.2, Docker CLI 23.0.3 and 23.0.2

Changelog

MCR 23.0.3 combines the Moby 23.0.2 and Moby 23.0.3 upstream releases.

Changes specific to MCR
Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.2 release:

In addition, as a security-only release, Moby 23.0.3 is tracked by a GitHub security advisory rather than a milestone:

Major component versions

Version detail for the major components that comprise MCR 23.0.3 is presented in the table below:

Component

Version

Moby

23.0.3

Docker CLI

23.0.3

containerd

1.6.19

runc

1.1.4

cri-dockerd

0.3.1

buildx

0.10.4

Fipster (Go runtime)

go1.19.7m3

buildkit

0.10.7-0.20230208155512-4f0ee09c40e2

rootlesskit

1.1.0

23.0.1

Release date

Name

Upstream release

2023-02-23

MCR 23.0.1

Moby 23.0.1 and 23.0.0, Docker CLI 23.0.1 and 23.0.0

Highlights

Enhancement

Detail

Storage driver removals

Beginning with the release of MCR 23.0, Mirantis no longer delivers unsupported storage drivers to customers. While this creates an upgrade barrier for customers using MCR 20.10 with an unsupported storage driver, it is certain to prevent the late discovery of an unsupportable MCR deployment.

overlay2 is the only storage driver MCR builds and supports, with the exception of the btrfs storage driver, which Mirantis will continue to build and support exclusively for the SLES platform (for which overlay2 is also viable).

In addition, Mirantis continues to make the vfs storage driver available, but only for the purpose of helping to debug the storage back end. The vfs driver remains unsupported and is entirely unfit for use in production environments.

In removing the unsupported storage drivers, Mirantis aims to align customers with a longer-term migration to new storage back ends that are currently under development in the Moby project.

Other points of interest:

  • overlay2 is now preferred to btrfs and zfs, which affects new MCR deployments running on SLES systems.

  • overlay2 can no longer be used on a file system without d_type,which may prevent in-place upgrades.

Semantic Versioning (SemVer) format

Beginning with the MCR 23.0 release, in alignment with Moby, Semantic Versioning (SemVer) replaces Calendar Versioning (CalVer). Upstream Moby is moving to SemVer as part of the migration to a Go module, however Moby 23.0 is not yet Go module compatible.

CSI drivers

MCR 23.0 introduces experimental support for Container Storage Interface (CSI) drivers in Swarm. CSI drivers are the same storage drivers that Kubernetes uses, and as Swarm matures as a CSI-compliant implementation it is expected that an entire ecosystem of persistent storage back ends will become available.

For use with Swarm, a CSI driver must not have a direct coupling to the Kubernetes control plane. The driver must also be packaged natively for Swarm as an Engine plugin.

At this time, CSI on Swarm is only fit for development and experimental use. Mirantis is working actively with the Moby development community to evangelize Swarm CSI and further develop its implementation, quickly addressing any bugs and missing features as these become apparent.

BuildKit and buildx by default

MCR 23.0 defaults to the BuildKit builder (DOCKER_BUILDKIT=1) on Linux. In addition, the 23.0 CLI makes docker build an alias for docker buildx build. This reflects the growing maturity of BuildKit, and it will help customers to take advantage of the significant improvements that BuidlKit brings in caching, performance, and flexibility. Though this is a large change in behavior, it is also a mostly transparent one, and users should be aware that they can still request the previous behavior through DOCKER_BUILDKIT=0.

Refer to the upstream documentation, Differences between legacy builder and BuildKit for more information.

Volume prune and API 1.42

The MCR 23.0 release increments the supported Docker Engine API version to 1.42. With this version of the API, the volume prune action only considers anonymous volumes, ignoring those that were given a name at creation. This change in behavior only occurs when both the CLI and daemon support API version 1.42. Only MCR 23.0 supports API 1.42 at this time, and thus an updated API client such as the MCR 23.0 CLI is required to encounter this new behavior. Users should be aware that older versions of the Docker Engine API continue to consider both anonymous and named volumes when performing a volume prune.

A new all=1 filter is available for use with Docker Engine API 1.42, to widen the filtering so that it once again considers named volumes. Specifically, using an MCR 23.0 CLI, docker volume prune --filter all=1 produces the same result as docker volume prune with an older CLI. docker system prune -a is not able to specify this filter, and as such will always reflect the default behavior of the negotiated API version.

Refer to Docker Engine API (1.42) for the full API documentation, and to Engine API version history for the full list of changes.

Windows Server 2019 required

Support for Windows Server 2016 is dropped in MCR 23.0. Windows Server RS5 / LTSC 2019 (build 17763) is the new baseline version.

Health checks

In MCR 23.0, the overhead that is required to perform a health check is no longer counted as part of the time threshold. Health checks now properly resume when the daemon is restarted with running containers. Also, rather than being left to hang indefinitely, timed-out health checks are now more reliably killed.

Rootless and seccomp

MCR 23.0 further develops rootless mode by improving support for privileged features, and by making significant enhancements to the capabilities of the seccomp filtering implementation.

Advanced MCR users should consider the following changes when diagnosing issues with privilege and permissions:

  • Engine plugins are discoverable at well known user-specific paths in rootless mode.

  • --privileged rootless containers can use host devices.

  • --ipc=host now works in rootless mode.

  • seccomp profiles can now pass additional flags to the seccomp userspace binary.

  • ErrnoRet can now be set in seccomp profiles.

  • clone3 is correctly blocked so that glibc will instead use clone.

  • AF_VSOCK is blocked in the default profile as it cannot be containerized.

  • Other enhancements to the built-in seccomp profile for new system calls, such as BPF and clock_settime64.

Changelog

MCR 23.0.1 represents the first iteration of the MCR 23.0 major release, combining the Moby 23.0.0 and Moby 23.0.1 upstream releases.

Changes specific to MCR
  • MCR no longer builds unsupported storage drivers, also known as graphdrivers.

  • apparmor is now unconditionally installed on Ubuntu systems.

  • MCR contains the following component versions:

    • Fipster (Go runtime) go1.19.5m1

    • containerd v1.6.17

    • buildx v0.10.0

    • cri-dockerd v0.3.0

Changes from upstream

The upstream pull requests detailed in the sections that follow are those that pertain to the MCR product. For the complete list of changes and pull requests upstream, refer to the GitHub milestones.

GitHub milestones

The Github milestones offer full detail on the pull requests and changes as they correlate to the upstream Moby 23.0.0 and Moby 23.0.1 releases:

Major component versions

Version detail for the major components that comprise MCR 23.0.1 is presented in the table below:

Component

Version

Moby

23.0.1

Docker CLI

23.0.1

containerd

1.6.17

runc

1.1.4

cri-dockerd

0.3.0

buildx

0.10.0

Fipster (Go runtime)

go1.19.5m1

buildkit

0.10.7-0.20230208155512-4f0ee09c40e2

rootlesskit

1.1.0

Release Compatibility Matrix

MCR 23.0 Compatibility Matrix

Mirantis Container Runtime (MCR) enables containers to run efficiently on any substrate, powering business critical applications at leading companies worldwide.

Mirantis validates MCR for the operating system environments specified here, adhering to the MKE, MSR, and MCR Maintenance Lifecycle. Support for MCR is defined in the Mirantis Cloud Native Platform Subscription Services agreement.

Note

  • MCR 23.0.5 is the final 23.0.x version to support Ubuntu 18.04.x, as standard LTS support for the distribution ended on 2023-May-31.

  • MKE 3.5.x and 3.4.x do not support Windows Server 2022.

  • OS distributed versions not listed in the following matrix are not supported under Standard Support Subscriptions. For such versions, contact your Mirantis rep to discuss support options.

Caution

CentOS 8 entered EOL status as of 31-December-2021. For this reason, Mirantis no longer supports CentOS 8 for all versions of MCR. We encourage customers who are using CentOS 8 to migrate onto any one of the supported operating systems, as further bug fixes will not be forthcoming.

MCR

Max. supported Client API

Platform

Versions

23.0.10

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

9.2, 9.1, 9.0, 8.6, 7.9, 7.8

RHEL

9.3, 9.2, 9.1, 9.0, 8.9, 8.8, 8.7, 8.6, 8.5, 7.9, 7.8

Rocky Linux

9.2, 9.1, 9.0, 8.8, 8.7, 8.6, 8.5

SLES

15 SP5, 12 SP5

Ubuntu

22.04.3, 20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.9-1

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

9.2, 9.1, 9.0, 8.6, 7.9, 7.8

RHEL

9.3, 9.2, 9.1, 9.0, 8.9, 8.8, 8.7, 8.6, 8.5, 7.9, 7.8

Rocky Linux

9.2, 9.1, 9.0, 8.8, 8.7, 8.6, 8.5

SLES

15 SP5, 12 SP5

Ubuntu

22.04.3, 20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.9

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

9.2, 9.1, 9.0, 8.6, 7.9, 7.8

RHEL

9.3, 9.2, 9.1, 9.0, 8.9, 8.8, 8.7, 8.6, 8.5, 7.9, 7.8

Rocky Linux

9.2, 9.1, 9.0, 8.8, 8.7, 8.6, 8.5

SLES

15 SP5, 12 SP5

Ubuntu

22.04.3, 20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.8

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

9.2, 9.1, 9.0, 8.6, 7.9, 7.8

RHEL

9.2, 9.1, 9.0, 8.8, 8.7, 8.6, 8.5, 7.9, 7.8

Rocky Linux

9.2, 9.1, 9.0, 8.8, 8.7, 8.6, 8.5

SLES

15 SP5, 15 SP4, 12 SP5

Ubuntu

22.04.3, 20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.7

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

9.2, 9.1, 9.0, 8.6, 7.9, 7.8

RHEL

9.2, 9.1, 9.0, 8.8, 8.7, 8.6, 8.5, 7.9, 7.8

Rocky Linux

9.2, 9.1, 9.0, 8.8, 8.7, 8.6, 8.5

SLES

15 SP4, 12 SP5

Ubuntu

22.04.3, 20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.6

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

8.6, 7.9, 7.8

RHEL

9.0, 8.8, 8.7, 8.6, 8.5, 7.9, 7.8

Rocky Linux

8.8, 8.7, 8.6, 8.5

SLES

15 SP4, 12 SP5

Ubuntu

20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.5

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

8.6, 7.9, 7.8

RHEL

9.0, 8.7, 8.6, 8.5, 8.4, 7.9, 7.8

Rocky Linux

8.7, 8.6, 8.5

SLES

15 SP4, 12 SP5

Ubuntu

20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0, 18.04.6, 18.04.5, 18.04.4, 18.04.3, 18.04.2, 18.04.1, 18.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.3

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

8.6, 7.9, 7.8

RHEL

9.0, 8.7, 8.6, 8.5, 8.4, 7.9, 7.8

Rocky Linux

8.7, 8.6, 8.5

SLES

15 SP4, 12 SP5

Ubuntu

20.04.6, 20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0, 18.04.6, 18.04.5, 18.04.4, 18.04.3, 18.04.2, 18.04.1, 18.04.0

Microsoft Windows Enterprise Server

2022, 2019

23.0.1

1.42

CentOS

7.9.2009, 7.8.2003

Oracle Linux 1

8.6, 7.9, 7.8

RHEL

9.0, 8.7, 8.6, 8.5, 8.4, 7.9, 7.8

Rocky Linux

8.7, 8.6, 8.5

SLES

15 SP4, 12 SP5

Ubuntu

20.04.5, 20.04.4 2, 20.04.3, 20.04.2, 20.04.1, 20.04.0, 18.04.6, 18.04.5, 18.04.4, 18.04.3, 18.04.2, 18.04.1, 18.04.0

Microsoft Windows Enterprise Server

2022, 2019

1(1,2,3,4,5,6,7,8,9)

Regarding the Oracle Linux kernel, only Red Hat Compatible Kernel (RHCK) 3.10.x is supported. Unbreakable Enterprise Kernel (UEK) is not supported.

2(1,2,3,4,5,6,7,8,9)

A known critical issue is present in the 5.13.0-1028-aws and 5.13.0-1029-aws kernels of the Ubuntu AMIs on AWS. The issue was resolved in the 5.13.0-1030-aws kernel. If you are an AWS user, refer to Docker container creation causes kernel oops on linux-aws 5.13.0.1028.31~20.04.22 and Docker container ports cannot be allocated, otherwise check with your cloud provider.

MKE, MSR, and MCR Maintenance Lifecycle

The MKE, MSR, and MCR platform subscription provides software, support, and certification to enterprise development and IT teams that build and manage critical apps in production at scale. It provides a trusted platform for all apps which supply integrated management and security across the app lifecycle, comprised primarily of Mirantis Kubernetes Engine, Mirantis Secure Registry (MSR), and Mirantis Container Runtime (MCR).

Mirantis validates the MKE, MSR, and MCR platform for the operating system environments specified in the MCR 23.0 Compatibility Matrix, adhering to the Maintenance Lifecycle detailed here. Support for the MKE, MSR, and MCR platform is defined in the Mirantis Cloud Native Platform Subscription Services agreement.

Detailed here are all currently supported product versions, as well as the product versions most recently deprecated. It can be assumed that all earlier product versions are at End of Life (EOL).

Important Definitions

  • “Major Releases” (X.y.z): Vehicles for delivering major and minor feature development and enhancements to existing features. They incorporate all applicable Error corrections made in prior Major Releases, Minor Releases, and Maintenance Releases.

  • “Minor Releases” (x.Y.z): Vehicles for delivering minor feature developments, enhancements to existing features, and defect corrections. They incorporate all applicable Error corrections made in prior Minor Releases, and Maintenance Releases.

  • “Maintenance Releases” (x.y.Z): Vehicles for delivering Error corrections that are severely affecting a number of customers and cannot wait for the next major or minor release. They incorporate all applicable defect corrections made in prior Maintenance Releases.

  • “End of Life” (EOL): Versions are no longer supported by Mirantis, updating to a later version is recommended.

Support lifecycle

GA to 12 months

12 to 18 months

18 to 24 months

Full support

Full support 1

Limited Support for existing installations 2

1 Software patches for critical bugs and security issues only; no feature enablement.

2 Software patches for critical security issues only.

Mirantis Kubernetes Engine (MKE)

3.6.z

3.7.z

General Availability (GA)

2022-OCT-13 (3.6.0)

2023-AUG-30 (3.7.0)

End of Life (EOL)

2024-OCT-13

2025-AUG-29

Release frequency

x.y.Z every 6 weeks

x.y.Z every 6 weeks

Patch release content

As needed:

  • Maintenance releases

  • Security patches

  • Custom hotfixes

As needed:

  • Maintenance releases

  • Security patches

  • Custom hotfixes

Supported lifespan

2 years 1

2 years 1

1 Refer to the Support lifecycle table for details.

EOL MKE Versions

MKE Version

EOL date

2.0.z

2017-AUG-16

2.1.z

2018-FEB-07

2.2.z

2019-NOV-01

3.0.z

2020-APR-16

3.1.z

2020-NOV-06

3.2.z

2021-JUL-21

3.3.z

2022-MAY-27

3.4.z

2023-APR-11

3.5.z

2023-NOV-22

Mirantis Secure Registry (MSR)

2.9.z

3.0.z

3.1.z

General Availability (GA)

2021-APR-12 (2.9.0)

2021-DEC-21 (3.0.0)

2023-SEP-28 (3.1.0)

End of Life (EOL)

2024-OCT-13

2024-APR-20

2025-SEP-27

Release frequency

x.y.Z every 6 weeks

x.y.Z every 6 weeks

x.y.Z every 6 weeks

Patch release content

As needed:

  • Maintenance releases

  • Security patches

  • Custom hotfixes

As needed:

  • Maintenance releases

  • Security patches

  • Custom hotfixes

As needed:

  • Maintenance releases

  • Security patches

  • Custom hotfixes

Supported lifespan

2 years 1

2 years 1

2 years 1

1 Refer to the Support lifecycle table for details.

EOL MSR Versions

MSR Version

EOL date

2.1.z

2017-AUG-16

2.2.z

2018-FEB-07

2.3.z

2019-FEB-15

2.4.z

2019-NOV-01

2.5.z

2020-APR-16

2.6.z

2020-NOV-06

2.7.z

2021-JUL-21

2.8.z

2022-MAY-27

Mirantis Container Runtime (MCR)

Enterprise 23.0

General Availability (GA)

2023-FEB-23 (23.0.1)

End of Life (EOL)

2025-FEB-22

Release frequency

x.y.Z every 6 weeks

Patch release content

As needed:

  • Maintenance releases

  • Security patches

  • Custom hotfixes

Supported lifespan

2 years 1

1 Refer to the Support lifecycle table for details.

EOL MCR Versions

MCR Version

EOL date

CSE 1.11.z

2017-MAR-02

CSE 1.12.z

2017-NOV-14

CSE 1.13.z

2018-FEB-07

EE 17.03.z

2018-MAR-01

Docker Engine - Enterprise v17.06

2020-APR-16

Docker Engine - Enterprise 18.03

2020-JUN-16

Docker Engine - Enterprise 18.09

2020-NOV-06

Docker Engine - Enterprise 19.03

2021-JUL-21

MCR 19.03.8+

2022-MAY-27

MCR 20.10.0+

2023-DEC-10

Release Cadence and Support Lifecycle

With the intent of improving the customer experience, Mirantis strives to offer maintenance releases for the Mirantis Container Runtime (MCR) software every six to eight weeks. Primarily, these maintenance releases will aim to resolve known issues and issues reported by customers, quash CVEs, and reduce technical debt. The version of each MCR maintenance release is reflected in the third digit position of the version number (as an example, for MCR 23.0 the most current maintenance release is MCR 23.0.9).

Regarding major releases, MCR is dependent on Docker Engine major releases upstream. Following such a release, the Mirantis support lifespan of the resulting major version of MCR will adhere to our legacy two year standard.

End of Life Date

For information on MCR version lifecycles, refer to the MKE, MSR, and MCR Maintenance Lifecycle.

As necessary, Mirantis may produce an MCR release between upstream releases. These so-called dash releases can contain hotfixes, packaging changes or depenency changes. In such cases, these dash releases replace the previous release of the same version (as an example, MCR 23.0.9-1 replaces MCR 23.0.9).

Note

In general, MCR dash releases for a particular patch version share the same OS and kernel compatibility.

The MCR team will make every effort to hold to the release cadence stated here. Customers should be aware, though, that development and release cycles can change, and without advance notice.

Technology Preview features

A Technology Preview feature provides early access to upcoming product innovations, allowing customers to experiment with the functionality and provide feedback.

Technology Preview features may be privately or publicly available and neither are intended for production use. While Mirantis will provide assistance with such features through official channels, normal Service Level Agreements do not apply.

As Mirantis considers making future iterations of Technology Preview features generally available, we will do our best to resolve any issues that customers experience when using these features.

During the development of a Technology Preview feature, additional components may become available to the public for evaluation. Mirantis cannot guarantee the stability of such features. As a result, if you are using Technology Preview features, you may not be able to seamlessly upgrade to subsequent product releases.

Mirantis makes no guarantees that Technology Preview features will graduate to generally available features.

QuickStart: MCR on Ubuntu

Use this QuickStart guide to quickly deploy Mirantis Container Runtime (MCR) to Ubuntu systems from the repository.

Introduction

MCR installations includes the following components:

  • MCR engine

  • MCR CLI

  • containerd

  • runc

After installing MCR, you will be able to:

The following diagram illustrates the workflow for installing MCR on Ubuntu:

_images/workflow-qs.png

Set up the repository

To install MCR using the Mirantis repository you must first set up the repository on the host machine.

Note

MCR only supports x86_64/amd64.

  1. Update the apt package index:

    sudo apt-get update
    
  2. Install packages that allow apt to use a repository over HTTPS:

    sudo apt-get install \
      apt-transport-https \
      ca-certificates \
      curl \
      software-properties-common
    
  3. Store https://repos.mirantis.com in an environment variable:

    DOCKER_EE_URL="https://repos.mirantis.com"
    
  4. Add a $DOCKER_EE_VERSION variable into your environment.

    DOCKER_EE_VERSION=<mcr-version>
    
  5. Add Docker’s official GPG key:

    curl -fsSL "${DOCKER_EE_URL}/ubuntu/gpg" | sudo apt-key add -
    
  6. Verify that you now have the key with the fingerprint DD91 1E99 5A64 A202 E859  07D6 BC14 F10B 6D08 5F96 by searching for the last eight characters of the fingerprint:

    sudo apt-key fingerprint 6D085F96
    
    pub   4096R/0EBFCD88 2017-02-22
          Key fingerprint = DD91 1E99 5A64 A202 E859  07D6 BC14 F10B 6D08 5F96
    uid                  Docker Release (EE deb) <docker@docker.com>
    sub   4096R/6D085F96 2017-02-22
    
  7. Use the following command to set up the stable repository:

    sudo add-apt-repository \
      "deb [arch=$(dpkg --print-architecture)] $DOCKER_EE_URL/ubuntu \
      $(lsb_release -cs) \
      stable-$DOCKER_EE_VERSION"
    

Install MCR

  1. Install the latest version of MCR and containerd:

    sudo apt-get install docker-ee docker-ee-cli containerd.io
    

    Note

    To install a specific version of MCR:

    sudo apt-get install docker-ee=<VERSION_STRING> docker-ee-cli=<VERSION_STRING> containerd.io
    
  2. Start Docker:

    sudo systemctl start docker
    
  3. Verify that you installed MCR correctly:

    sudo docker run hello-world
    

    This command downloads a test image and runs it in a container. If successful, the command prints the following informational message and exits:

    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    
    To generate this message, Docker took the following steps:
     1. The Docker client contacted the Docker daemon.
     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
        (amd64)
     3. The Docker daemon created a new container from that image which runs the
        executable that produces the output you are currently reading.
     4. The Docker daemon streamed that output to the Docker client, which sent it
        to your terminal.
    
    To try something more ambitious, you can run an Ubuntu container with:
     $ docker run -it ubuntu bash
    
    Share images, automate workflows, and more with a free Docker ID:
     https://hub.docker.com/
    
    For more examples and ideas, visit:
     https://docs.docker.com/get-started/
    

Install the license

An MCR license gives the user access to Mirantis Support. You can complete this guide and start using MCR right away, and install the license later.

To install the MCR license:

  1. Purchase an MCR subscription or contact Mirantis for more information.

  2. Follow the link to download your MCR license file found in the confirmation email you received after purchasing MCR from the Mirantis web store. If you cannot access your confirmation email, contact Mirantis.

  3. Copy the file to the data root directory and name it docker.lic. The default data root directory is /var/lib/docker.

  4. Restart MCR:

    sudo systemctl restart docker
    
  5. Verify the installation:

    sudo docker info | grep -i license
    

What’s next

QuickStart: MCR on CentOS

Use this QuickStart guide to quickly deploy Mirantis Container Runtime (MCR) to CentOS systems from the repository.

Introduction

MCR installations includes the following components:

  • MCR engine

  • MCR CLI

  • containerd

  • runc

After installing MCR, you will be able to:

The following diagram illustrates the workflow for installing MCR on CentoOS:

_images/workflow-qs.png

Set up the repository

You only need to set up the repository once, after which you can install MCR from the repository and upgrade as needed. MCR supports the latest version of CentOS 64-bit running on x86_64.

Note

MCR supports the overlay2 storage drivers on CentOS. The following limitations apply:

  • If you enable selinux, MCR supports overlay2 on CentoOS 7.4 and higher.

  • If you disable selinux, MCR supports overlay2 on CentOS 7.2 and higher, with kernel version 3.10.0-693 and higher.

  1. Remove any existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Store https://repos.mirantis.com in an environment variable:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of DOCKERURL using a yum variable in /etc/yum/vars/:

    sudo -E sh -c \
    'echo "$DOCKERURL/centos" > /etc/yum/vars/dockerurl'
    
  4. Store your operating system version string (7) in /etc/yum/vars/dockerosversion:

    sudo sh -c 'echo "7" > /etc/yum/vars/dockerosversion'
    
  5. Install the yum-utils that provides the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  6. Enable the extras RHEL repository to ensure access to the container-selinux package that docker-ee requires:

    sudo yum-config-manager --enable rhel-7-server-extras-rpms
    
    sudo yum-config-manager --enable extras
    sudo subscription-manager repos \
    --enable=rhel-7-for-power-le-extras-rpms
    sudo yum makecache fast
    sudo yum -y install container-selinux
    
  7. AWS and Azure require that you enable another repository. For AWS, refer to the official Red Hat Update Infrastructure (RHUI) documentation. For Azure, refer to the official Azure RHUI documentation.

  8. Add the stable MCR repository:

    sudo -E yum-config-manager \
    --add-repo "$DOCKERURL/centos/docker-ee.repo"
    

Install MCR

  1. Install the latest version of MCR and containerd:

    sudo yum -y install docker-ee docker-ee-cli containerd.io
    

    If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9 and accept it.

    Note

    To install a specific version of MCR:

    1. Download the three packages required for the desired MCR version from https://repos.mirantis.com/rhel/8/x86_64/stable-23.0/Packages/.

    2. Run the following command to complete the MCR installation.

      sudo yum -y install docker-ee-<version-string> \
      docker-ee-cli-<version-string> containerd.io
      
  2. Start Docker:

    sudo systemctl start docker
    
  3. Verify that you installed MCR correctly:

    sudo docker run hello-world
    

    This command downloads a test image and runs it in a container. If successful, it prints the following informational message and exits:

    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    
    To generate this message, Docker took the following steps:
     1. The Docker client contacted the Docker daemon.
     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
        (amd64)
     3. The Docker daemon created a new container from that image which runs the
        executable that produces the output you are currently reading.
     4. The Docker daemon streamed that output to the Docker client, which sent it
        to your terminal.
    
    To try something more ambitious, you can run an Ubuntu container with:
     $ docker run -it ubuntu bash
    
    Share images, automate workflows, and more with a free Docker ID:
     https://hub.docker.com/
    
    For more examples and ideas, visit:
     https://docs.docker.com/get-started/
    

Install the license

An MCR license gives the user access to Mirantis Support. You can complete this guide and start using MCR right away, and install the license later.

To install the MCR license:

  1. Purchase an MCR subscription or contact Mirantis for more information.

  2. Follow the link to download your MCR license file found in the confirmation email you received after purchasing MCR from the Mirantis web store. If you cannot access your confirmation email, contact Mirantis.

  3. Copy the file to the data root directory and name it docker.lic. The default data root directory is /var/lib/docker.

  4. Restart MCR:

    sudo systemctl restart docker
    
  5. Verify the installation:

    sudo docker info | grep -i license
    

What’s next

QuickStart: MCR on Oracle Linux

Use this QuickStart guide to quickly deploy Mirantis Container Runtime (MCR) to Oracle Linux systems from the repository.

Note

The documentation herein applies only to Oracle Linux 7. Mirantis does not support Oracle 8.

Introduction

MCR installations includes the following components:

  • MCR engine

  • MCR CLI

  • containerd

  • runc

After installing MCR, you will be able to:

The following diagram illustrates the workflow for installing MCR on Oracle Linux:

_images/workflow-qs.png

Set up the repository

Note

The documentation herein applies only to Oracle Linux 7. Mirantis does not support Oracle 8.

You only need to set up the repository once, after which you can install MCR from the repository and upgrade as needed.

MCR supports Oracle Linux 64-bit version 7.8 or later and Red Hat Compatible Kernel (RHCK) version 3.10.0-1127 or later.

Note

Mirantis recommends using fast storage, such as solid-state media.

  1. Remove any existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Store https://repos.mirantis.com in an environment variable:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of DOCKERURL using a yum variable in /etc/yum/vars/:

    sudo -E sh -c \
    'echo "$DOCKERURL/oraclelinux" > /etc/yum/vars/dockerurl'
    
  4. Install yum-utils to get the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  5. Enable the Oracle ol7_addons repository to ensure that you have access to the container-selinux package that docker-ee requires:

    sudo yum-config-manager --enable ol7_addons
    
  6. Add the stable MCR repository:

    sudo -E yum-config-manager \
    --add-repo \
    "$DOCKERURL/oraclelinux/docker-ee.repo"
    

Install MCR

Note

The documentation herein applies only to Oracle Linux 7. Mirantis does not support Oracle 8.

  1. Install the latest version of MCR and containerd:

    sudo yum -y install docker-ee docker-ee-cli containerd.io
    

    If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9 and accept it.

    Note

    To install a specific version of MCR:

    1. Download the three packages required for the desired MCR version from https://repos.mirantis.com/oraclelinux/7/x86_64/stable-23.0/Packages/.

    2. Run the following command to complete the MCR installation.

      sudo yum -y install docker-ee-<version-string> \
      docker-ee-cli-<version-string> containerd.io
      
  2. Start Docker:

    sudo systemctl start docker
    
  3. Verify that you installed MCR correctly:

    sudo docker run hello-world
    

    This command downloads a test image and runs it in a container. If successful, it prints the following informational message and exits:

    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    
    To generate this message, Docker took the following steps:
     1. The Docker client contacted the Docker daemon.
     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
        (amd64)
     3. The Docker daemon created a new container from that image which runs the
        executable that produces the output you are currently reading.
     4. The Docker daemon streamed that output to the Docker client, which sent it
        to your terminal.
    
    To try something more ambitious, you can run an Ubuntu container with:
     $ docker run -it ubuntu bash
    
    Share images, automate workflows, and more with a free Docker ID:
     https://hub.docker.com/
    
    For more examples and ideas, visit:
     https://docs.docker.com/get-started/
    

Install the license

An MCR license gives the user access to Mirantis Support. You can complete this guide and start using MCR right away, and install the license later.

To install the MCR license:

  1. Purchase an MCR subscription or contact Mirantis for more information.

  2. Follow the link to download your MCR license file found in the confirmation email you received after purchasing MCR from the Mirantis web store. If you cannot access your confirmation email, contact Mirantis.

  3. Copy the file to the data root directory and name it docker.lic. The default data root directory is /var/lib/docker.

  4. Restart MCR:

    sudo systemctl restart docker
    
  5. Verify the installation:

    sudo docker info | grep -i license
    

What’s next

QuickStart: MCR on RHEL

Use this QuickStart guide to quickly deploy Mirantis Container Runtime (MCR) to Red Hat Enterprise Linux (RHEL) systems from the repository.

Introduction

MCR installations includes the following components:

  • MCR engine

  • MCR CLI

  • containerd

  • runc

After installing MCR, you will be able to:

The following diagram illustrates the workflow for installing MCR on RHEL:

_images/workflow-qs.png

Set up the repository

You only need to set up the repository once, after which you can install MCR from the repository and upgrade as needed. MCR supports RHEL 64-bit version 7.4 and higher running on x86_64.

Note

MCR supports the overlay2 storage drivers on RHEL. The following limitations apply:

  • If you enable selinux, MCR supports overlay2 on RHEL 7.4 and higher (OverlayFS).

  • If you disable selinux, MCR supports overlay2 on RHEL 7.2 and higher, with kernel version 3.10.0-693 and higher.


Set up the repository for RHEL 7

  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Store https://repos.mirantis.com in an environment variable:

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of DOCKERURL using a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/rhel" > /etc/yum/vars/dockerurl'
    
  4. Store your OS version string in /etc/yum/vars/dockerosversion. Use 7 or include the minor version starting with 7.2:

    sudo sh -c 'echo "<version>" > /etc/yum/vars/dockerosversion'
    
  5. Install the yum-utils that provides the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  6. Enable the extras RHEL repository to ensure access to the container-selinux package that docker-ee requires:

    sudo yum-config-manager --enable rhel-7-server-extras-rpms
    
    sudo yum-config-manager --enable extras
    sudo subscription-manager repos \
    --enable=rhel-7-for-power-le-extras-rpms
    sudo yum makecache fast
    sudo yum -y install container-selinux
    
  7. Enable another repository for AWS and Azure:

    sudo yum-config-manager --enable rhel-7-server-rhui-extras-rpms
    
    sudo yum-config-manager --enable rhui-rhel-7-server-rhui-extras-rpms
    
  8. Add the stable MCR repository:

    sudo -E yum-config-manager \
    --add-repo \
    "$DOCKERURL/rhel/docker-ee.repo"
    

Set up the repository for RHEL 8

  1. Remove existing Docker repositories from /etc/yum.repos.d/:

    sudo rm /etc/yum.repos.d/docker*.repo
    
  2. Store https://repos.mirantis.com in an environment variable.

    export DOCKERURL="https://repos.mirantis.com"
    
  3. Store the value of DOCKERURL using a yum variable in /etc/yum/vars/:

    sudo -E sh -c 'echo "$DOCKERURL/rhel" > /etc/yum/vars/dockerurl'
    
  4. Store your OS version string in /etc/yum/vars/dockerosversion. Use 8:

    sudo sh -c 'echo "<version>" > /etc/yum/vars/dockerosversion'
    
  5. Install the yum-utils that provides the yum-config-manager utility:

    sudo yum install -y yum-utils
    
  6. Add the stable MCR repository:

    sudo -E yum-config-manager \
    --add-repo \
    "$DOCKERURL/rhel/docker-ee.repo"
    

Install MCR

  1. Install the latest version of MCR and containerd:

    sudo yum -y install docker-ee docker-ee-cli containerd.io
    

    If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9 and accept it.

    Note

    To install a specific version of MCR:

    1. Download the three packages required for the desired MCR version from https://repos.mirantis.com/rhel/8/x86_64/stable-23.0/Packages/.

    2. Run the following command to complete the MCR installation.

      sudo yum -y install docker-ee-<version-string> \
      docker-ee-cli-<version-string> containerd.io
      
  2. Start Docker:

    sudo systemctl start docker
    
  3. Verify that you installed MCR correctly:

    sudo docker run hello-world
    

    This command downloads a test image and runs it in a container. If successful, it prints the following informational message and exits:

    Hello from Docker!
    This message shows that your installation appears to be working correctly.
    
    To generate this message, Docker took the following steps:
     1. The Docker client contacted the Docker daemon.
     2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
        (amd64)
     3. The Docker daemon created a new container from that image which runs the
        executable that produces the output you are currently reading.
     4. The Docker daemon streamed that output to the Docker client, which sent it
        to your terminal.
    
    To try something more ambitious, you can run an Ubuntu container with:
     $ docker run -it ubuntu bash
    
    Share images, automate workflows, and more with a free Docker ID:
     https://hub.docker.com/
    
    For more examples and ideas, visit:
     https://docs.docker.com/get-started/
    

Install the license

An MCR license gives the user access to Mirantis Support. You can complete this guide and start using MCR right away, and install the license later.

To install the MCR license:

  1. Purchase an MCR subscription or contact Mirantis for more information.

  2. Follow the link to download your MCR license file found in the confirmation email you received after purchasing MCR from the Mirantis web store. If you cannot access your confirmation email, contact Mirantis.

  3. Copy the file to the data root directory and name it docker.lic. The default data root directory is /var/lib/docker.

  4. Restart MCR:

    sudo systemctl restart docker
    
  5. Verify the installation:

    sudo docker info | grep -i license
    

What’s next