2.1 Upgrading Oracle Container Runtime for Docker

Upgrading the Docker Engine is easily handled during a standard yum update or by doing a yum install docker-engine. Before simply upgrading it is worth checking that you meet the requirements for the most current version of the Docker Engine. If not, you may need to perform some additional steps. See the following sections to determine which steps may apply to your existing environment.

Change of package name

The supported Docker package is docker-engine, which conflicts with the docker package.

Stop the docker service.

# systemctl stop docker

If the older docker package is installed, swap it for the docker-engine package:

# yum swap -- remove docker -- install docker-engine

Requirement for Unbreakable Enterprise Kernel

Configure the system to use the Unbreakable Enterprise Kernel Release 4 (UEK R4) or later and boot the system with this kernel. If you are using either UEK R3 or the Red Hat Compatible Kernel (RHCK), you must upgrade the kernel.

  1. If your system is registered with ULN, disable access to the ol7_x86_64_UEKR3 channel and enable access to either the ol7_x86_64_UEKR4 or ol7_x86_64_UEKR5 channels. 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 repository and enable either the ol7_UEKR4 or ol7_UEKR5 repository. You can do this easily using yum-config-manager:

    # yum-config-manager --disable ol7_UEKR3
    # yum-config-manager --enable ol7_UEKR5
  2. Run the following command to upgrade the system to the selected UEK release:

    # yum update

    For information on how to make UEK the default boot kernel, see the Oracle Linux Administrator's Guide for Release 7 at https://docs.oracle.com/cd/E52668_01/E54669/html/ol7-grub2_bootloader.html.

  3. Reboot the system, selecting the UEK kernel if this is not the default boot kernel.

    # systemctl reboot

Content Addressability

Docker has introduced content addressability to the way in which image data is stored on disk. This functionality provides better security and helps to ensure data integrity for Docker images and layers. Since the way in which files are stored on disk and are referenced within Docker has changed, any existing Docker images created using a prior version of Docker must be migrated to the new format. This new feature and the migration process are described in more detail at https://github.com/moby/moby/wiki/Engine-v1.10.0-content-addressability-migration.

Migration of Docker images is performed automatically after the upgrade when the Docker Engine is first restarted. The upgrade process requires that all Docker containers are offline during the process and might take a significant period of time to complete. If you cannot afford the downtime required for the migration, you might use the migration utility referenced in the link provided above. However, you should note that Oracle does not package or support this utility.

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:

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

A brief summary of migration steps follows:

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

  2. Format the block device with the XFS file system, for example to format a partition /dev/sdb1:

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

  3. Temporarily mount the new file system, so that you can copy the contents from the existing Docker root directory:

    # mount -t xfs /dev/sdb1 /mnt
  4. Stop the Docker Engine, if it is running:

    # systemctl stop docker
  5. Move the existing Docker data to the new file system:

    # mv /var/lib/docker/* /mnt
  6. Unmount the new file system and remount it onto the Docker root directory:

    # umount /mnt
    # mount -t xfs /dev/sdb1 /var/lib/docker
  7. 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:

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

To temporarily mount this file, you can enter:

# 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 Section 2.5, “Configuring Docker Storage” for more information on setting up and configuring storage for Docker.