0 0 Share PDF

How to convert a devicemapper thinpool volume for use with overlay2

Article ID: KB000874


Customers currently using the devicemapper storage driver who choose to migrate to overlay2 will need to modify the Docker storage on their node to make it available to overlay2. While there are various ways to reconfigure your storage the following guide shows the steps required to use the existing storage already configured as an LVM physical volume (PV) and volume group (VG) with overlay2 by removing the thinpool and creating a new logical volume which can be mounted at /var/lib/docker or your preferred Docker data directory.


Before you begin, please check the Docker Compatibility Matrix to ensure you meet the operating system and Docker engine version requirements for using overlay2. Also, check Docker's guide to Use the OverlayFS storage driver to be sure all requirements are met.

Prepare the node

Changing the underlaying storage for Docker is a destructive process for any containers or services running on the node. If there are active workloads running on the node, they should be moved to other nodes before you continue. Tasks can be offloaded by draining the node. Any important data stored in volumes should be backed up. You can use docker save to save any images you have built or push them to Docker Hub or a private registry.

After backups are complete leave the swarm, stop Docker and delete the data directory. The following commands assume the data directory is in the default location of /var/lib/docker.

$ sudo systemctl stop docker.service
$ sudo rm -rf /var/lib/docker


Recreate the data directory for use as a mount point for the logical volume.

$ sudo mkdir /var/lib/docker

Convert the devicemapper thinpool volume to a mountable volume

  1. Confirm the Logical Volume name is thinpool and the Volume Group name is docker with the following command. If the LV and VG names are different, replace them in the following commands as appropriate:

    $ sudo lvdisplay
      --- Logical volume ---
      LV Name                thinpool
      VG Name                docker
      LV UUID                2ra52i-qlfU-xaxg-SOFn-YBC6-9lFC-JzMGQV
      LV Write Access        read/write
      LV Creation host, time node7, 2018-03-15 17:48:25 -0400
      LV Pool metadata       thinpool_tmeta
      LV Pool data           thinpool_tdata
      LV Status              available
      # open                 0
      LV Size                <9.50 GiB
      Allocated pool data    58.68%
      Allocated metadata     1.56%
      Current LE             2431
      Segments               1
      Allocation             inherit
      Read ahead sectors     auto
      - currently set to     8192
      Block device           253:4
  2. Delete the logical volume:

    $ sudo lvremove /dev/docker/thinpool 
    Do you really want to remove active logical volume docker/thinpool? [y/n]: y
      Logical volume "thinpool" successfully removed
  3. Create a new logical volume which can be mounted to the filesystem. In this example, a logical device named dockerdata is created using 100% of the free space from the docker volume group:

    $ sudo lvcreate -n dockerdata -l 100%FREE docker
    WARNING: xfs signature detected on /dev/docker/dockerdata at offset 0. Wipe it? [y/n]: y
      Wiping xfs signature on /dev/docker/dockerdata.
      Logical volume "dockerdata" created.

Format and mount the volume

  1. Format the volume with your preferred filesystem. xfs is used in this example:

    $ sudo mkfs -t xfs -n ftype=1 /dev/docker/dockerdata 
    meta-data=/dev/docker/dockerdata isize=512    agcount=4, agsize=655104 blks
             =                       sectsz=512   attr=2, projid32bit=1
             =                       crc=1        finobt=0, sparse=0
    data     =                       bsize=4096   blocks=2620416, imaxpct=25
             =                       sunit=0      swidth=0 blks
    naming   =version 2              bsize=4096   ascii-ci=0 ftype=1
    log      =internal log           bsize=4096   blocks=2560, version=2
             =                       sectsz=512   sunit=0 blks, lazy-count=1
    realtime =none                   extsz=4096   blocks=0, rtextents=0
  2. Mount the volume to the empty Docker data directory:

    $ sudo mount /dev/docker/dockerdata /var/lib/docker
  3. Confirm the logical volume is mounted as expected:

    $ mount | grep dockerdata
    /dev/mapper/docker-dockerdata on /var/lib/docker type xfs (rw,relatime,seclabel,attr2,inode64,noquota)
  4. Check the output of df -h to see the extra space now available:

    $ df -h | grep dockerdata
    /dev/mapper/docker-dockerdata   10G  616M  9.4G   7% /var/lib/docker
  5. Update /etc/fstab to ensure the Logical Volume is automatically mounted at system boot. For this example, the following line would be added:

    /dev/mapper/docker-dockerdata   /var/lib/docker xfs     defaults        0 0

Configure Docker to use overlay2

At this point you have a Logical Volume mounted to your Docker data directory and you are ready to configure Docker to use overlay2. Please refer to Docker's guide on setting up OverlayFS. Steps 1-3 are already complete, so start at step 4 of the section titled "Configure Docker with the overlay or overlay2 storage driver" to complete the process.