Upgrading Oracle Container Runtime for Docker

3 Upgrading Oracle Container Runtime for Docker

This chapter describes the steps required to perform an upgrade of Oracle Container Runtime for Docker on an Oracle Linux 7 host.

Note:

Docker requires that you configure the system to use the Unbreakable Enterprise Kernel Release 4 (UEK R4) or later and boot the system with this kernel.

Using the Docker configuration files in /etc/sysconfig is deprecated. Instead, you should use the /etc/docker/daemon.json configuration file and systemd drop-in configuration files in /etc/systemd/system/docker.service.d as required.

After adding or modifying a drop-in file while the docker service is running, run the command systemctl daemon-reload to tell systemd to reload the configuration for the service.

Upgrade Preqrequisites

Before upgrading, make sure you meet the requirements for the most current version of the Docker Engine. See the following sections to determine which steps may apply to your existing environment.

Updating the Unbreakable Enterprise Kernel

Configure the system to use the Unbreakable Enterprise Kernel Release 5 (UEK R5) or later and boot the system with this kernel. If you are using an earlier Unbreakable Enterprise Kernel (UEK) release, or the Red Hat Compatible Kernel (RHCK), you must upgrade the kernel.

To install or update UEK:

If your system is registered with ULN, disable access to the ol7_x86_64_UEKR3 and ol7_x86_64_UEKR4 channels, and enable access to the ol7_x86_64_UEKR5 channel.

Log into https://linux.oracle.com with your ULN user name and password and click on the Systems tab to select the system where you installing Oracle Container Runtime for Docker. Go to the Manage Subscriptions page and update the channel subscriptions for the system. Click on Save Subscriptions to save your changes.
If you use the Oracle Linux yum server, disable the ol7_UEKR3 and ol7_UEKR4 repositories and enable the ol7_UEKR5 repository. You can do this easily using yum-config-manager:
```
sudo yum-config-manager --disable ol7_UEKR3 ol7_UEKR4
sudo yum-config-manager --enable ol7_UEKR5                     
```
Run the following command to upgrade the system to the selected UEK release:
```
sudo yum update                     
```
Reboot the system, selecting UEK if this is not the default boot kernel.
```
sudo systemctl reboot                     
```

Checking the Storage Driver

The Docker Engine uses overlay2 as the default storage driver to manage Docker containers. The overlay2 storage driver can run into issues on systems using an XFS formatted file system that is not created with the -n ftype=1 option enabled. This is because overlay file systems depend on dtype support to handle metadata such as white outs for file deletion.

The root partition on Oracle Linux 7 is automatically formatted with -n ftype=0 where XFS is selected as the file system, disabling dtype support. On new installations of Docker, the package installer checks the file system format options to ensure that dtype support is available. If dtype support is not enabled, the installer overrides the default storage driver to use devicemapper to ensure that Docker is ready-to-use on newly installed systems. However, upgraded versions of Docker continue to use the storage driver that was configured in the previous release. This means that if you have configured Docker to use overlay2 on an underlying XFS-formatted file system, you may need to migrate the data to dedicated storage that has been formatted correctly.

Oracle recommends using Btrfs as a more stable and mature technology than overlayfs.

To check which storage driver and backing file system are configured on a running Docker Engine and to determine the path to the root Docker storage, run:

sudo docker info |grep 'Storage\|Filesystem\|Root'

If the storage driver is set to overlay2 and the backing file system is set to xfs, check that the XFS file system is formatted correctly:

xfs_info /var/lib/docker |grep ftype

If necessary, replace /var/lib/docker with the path to the root Docker storage returned in the previous command. If the information returned by this command includes ftype=0, you must migrate the data held in this directory to storage that is formatted with support for overlay filesystems.

To migrate the storage:

Attach a block storage device to the system where you are running Docker. Use the lsblk command to identify the device name and UUID. For example:
```
lsblk -o 'NAME,TYPE,UUID,MOUNTPOINT'                        
```
If necessary, you may need to partition the device using a partitioning tool such as fdisk or parted.
Format the block device with the XFS file system, for example to format a partition /dev/sdb1:
```
sudo mkfs -t xfs -n ftype=1 /dev/sdb1
```
It is essential that you use the -n ftype=1 option when you create the file system or you will not be able to use overlayfs.
Temporarily mount the new file system, so that you can copy the contents from the existing Docker root directory:
```
sudo mount -t xfs /dev/sdb1 /mnt
```

Stop the Docker Engine, if it is running:

sudo systemctl stop docker

Move the existing Docker data to the new file system:
```
sudo mv /var/lib/docker/* /mnt
```

Unmount the new file system and remount it onto the Docker root directory:

sudo umount /mnt                           
sudo mount -t xfs /dev/sdb1 /var/lib/docker

Create an entry in your fstab to ensure that the file system is mounted at boot. Open /etc/fstab in an editor and add a line similar to the following:
```
UUID=UUID_value /var/lib/docker   xfs     defaults        0 0
```
Replace UUID_value with the UUID value for the partition that you created. Use the lsblk or blkid command if you need to check the value.

Tip:

If you do not have additional storage available for this purpose, it is possible to create an XFS file system image and loopback mount this. For example, to create a 25 GB image file in the root directory, you could use the following command:

sudo mkfs.xfs -d file=1,name=/DockerStorage,size=25g -n ftype=1

To temporarily mount this file, you can enter:

sudo mount -o loop -t xfs /DockerStorage /mnt

An entry in /etc/fstab, to make a permanent mount for Docker storage, may look similar to the following:

/DockerStorage    /var/lib/docker        xfs     loop            0 0

This configuration can help as a temporary solution to solve upgrade issues. However, using a loopback mounted file system image as a form of permanent storage for Docker is not recommended for production environments.

See Configuring Docker Storage for more information on setting up and configuring storage for Docker.

Upgrading the Docker Engine

To upgrade the Docker Engine:

Stop the docker service if it is running:
```
sudo systemctl stop docker
```

Update the docker-engine and docker-cli packages:

sudo yum update docker-engine docker-cli

Start the docker service:

sudo systemctl start docker