What do I do if I cannot install Docker by using third-party DNF repositories on an Alibaba Cloud Linux 3 instance? -

This topic describes how to resolve the following issue: Docker cannot be installed by using third-party Dandified YUM (DNF) repositories, such as Docker Community Edition (Docker-CE) and Extra Packages for Enterprise Linux (EPEL) repositories, on an Elastic Compute Service (ECS) instance that runs Alibaba Cloud Linux 3.

Problem description

You cannot install Docker by running the dnf install docker-ce command on an Alibaba Cloud Linux 3 instance that meets the following conditions, and an error message is returned.

The instance uses third-party DNF repositories that are compatible with CentOS 8.
The instance uses an image of the aliyun_3_x64_20G_alibase_20210425.vhd version or earlier.

Sample error message:

Docker CE Stable - x86_64
Failed to download metadata for repo 'docker-ce-stable'
Error: Failed to download metadata for repo 'docker-ce-stable'

Cause

Third-party DNF repositories are compatible only with CentOS 8. The $releasever value of Alibaba Cloud Linux 3 is different from that of CentOS 8. As a result, the Docker package cannot be downloaded because the resolved DNF repository addresses are invalid.

Note

When DNF installs Docker-CE, DNF obtains the version number ($releasever value) from the system and replaces the $releasever value in the baseurl of the corresponding DNF repository with the obtained version number to obtain required data. The $releasever value of CentOS 8 is 8, and the $releasever value of Alibaba Cloud Linux 3 is 3. As a result, the baseurl is resolved to a non-expected address for Alibaba Cloud Linux 3, and DNF cannot obtain the required data from the address.

Solutions

Use one of the following methods to resolve the issue:

Perform the operations described in Solution 1: Change the $releasever value to change the value of $releasever.
Perform the operations described in Solution 2: Use a plug-in to change the $releasever value to install the dnf-plugin-releasever-adapter plug-in, and then use the plug-in to change the value of $releasever.

Note

In the examples, the Docker-CE repository is used. You can perform the same operations for other DNF repositories.

Solution 1: Change the $releasever value

Log on to the Linux instance.
For more information, see Connect to a Linux instance by using a password or key.
Run the following command to open the /etc/yum.repos.d/docker-ce.repo configuration file:
```
vim /etc/yum.repos.d/docker-ce.repo
```
Press the I key to enter the edit mode. In the docker-ce.repo file, find all repositories for which enabled=1 is displayed, and change the $releasever value in the baseurls of the repositories to 8, as shown in the following figure.
Press the Esc key, enter :wq, and then press Enter to save and close the configuration file. Re-install the Docker software.

Solution 2: Use a plug-in to change the $releasever value

Install the dnf-plugin-releasever-adapter plug-in to automatically change the $releasever value from 3 to 8.

Check whether the instance supports the dnf-plugin-releasever-adapter plug-in.

The following table describes the current versions of the dnf-plugin-releasever-adapter plug-in and the third-party repositories that are supported by default.

Plug-in version

Third-party repository supported by default

Limits on the plug-in

New version: 1.0-2
Old version: 1.0-1.3

Note

The new and old versions of the plug-in are not compatible with each other. The configuration file of the new version is named releasever_adapter.conf, and the configuration file of the old version is named releasever-adapter.conf. When the plug-in is upgraded to the new version, the configuration file of the old version is deleted. After the plug-in is upgraded, if you want the plug-in to support third-party repositories other than Docker-CE and EPEL, modify the include field of the configuration file and keep the other settings unchanged.

Docker-CE and EPEL

To use the plug-in, make sure that the following requirements are met:

The operating system is Alibaba Cloud Linux 3.
Run the following command to check whether the alinux3-plus repository exists:
```
cat /etc/yum.repos.d/AliYun.repo |grep -A3 alinux3-plus
```
If a command output similar to the following one is returned, the alinux3-plus repository exists.

Log on to the Linux instance.
For more information, see Connect to a Linux instance by using a password or key.
Run the following command to install the dnf-plugin-releasever-adapter plug-in.
Note
The plug-in changes the $releasever values of the Docker-CE and EPEL repositories.
```
dnf install dnf-plugin-releasever-adapter --repo alinux3-plus
```
If you do not need to change the value of $releasever for other DNF repositories, install the Docker software after the plug-in is installed. If you need to change the value of $releasever for other DNF repositories, perform the following operations:
1. Run the following command to go to the /etc/yum/pluginconf.d/ directory:
```
cd /etc/yum/pluginconf.d/
```
2. Run the following command to modify the releasever_adapter.conf configuration file:
```
vim releasever_adapter.conf
```
  1. Press the I key to enter the edit mode. If you want to add other DNF repositories, append the .repo file names of the DNF repositories to include. Separate the file names with commas (,).
    Note
    In most cases, the .repo files of DNF repositories reside in the /etc/yum.repos.d/ directory.
    A command output that is similar to the following one is displayed:
```
[main]
enabled=1

[releasevermapping]
2.1903 = 7
3      = 8

[reposlist]
include=docker-ce.repo, epel.repo
```
    Note
    The following parameters are used in the configuration file:
    [main]: the main control part of the plug-in that is used to enable or disable the plug-in. If enabled is set to 1, the plug-in is enabled. If enabled is set to 0, the plug-in is disabled.
    [releasevermapping]: the mappings between the $releasever values that you want to change. 2.1903 is mapped to 7, and 3 is mapped to 8.
    [repolist]: the list of repositories that you want to modify. If you want to add other DNF repositories, append the .repo file names of the repositories to the include field. Separate the file names with commas (,).
    In most cases, a .repo file contains multiple repositories, and each repository has a system-wide unique name. For example, the docker-ce-stable and docker-ce-stable-debuginfo repositories exist at the same time in the docker-ce.repo file.
3. Press the Esc key, enter :wq, and then press the Enter key to save and close the configuration file.
4. Run the following command to install Docker-CE by using the Docker-CE and EPEL repositories and the other repositories that you added:
```
dnf install docker-ce
```