Should I Upgrade My Docker Compose File Version From 2 to 3?

When writing docker-compose files, you’ve been starting each by specifying the version. I myself, have been using docker-compose for a while, and the yml format since fig was introduced. Until recently my docker-compose.yml files all started like this:

version: "2"

A version 3 was introduced, but all my old stuff still worked. So why bother, right? I was hesitant to put in the work, as there were no features that I wanted to use for my projects.

Before looking into the issue, the usual questions came up. Will something break when you want to update the version of your compose files to 3.x? What are the upsides? Do I risk lots of work and nasty bugs causing trouble? Will version 2 not be supported anymore, or will I need to switch up all my workflows as well?

As I have done the work, I’d like to share the results with you. Here’s everything you need to know, without having to dive into the docs. If you want to do so selectively, the most relevant links are provided :)

So What Happened?

Docker swarm happened. The new version of docker-compose files were adjusted, to work with it. Apart from this, functionality which was left to docker-compose, was added to Docker itself. Now you can work with stacks without having to install docker-compose, and do a few more fancy things. This also requires using version 3 of docker-compose.yml files, as docker stack does not support version 2.

The way handling volumes and networks was changed for the better - you can define them in their own block, which makes it easier to share both between services.

Not Much Changed

At this point, one could read through the change notes for version 3 to see what was introduced and removed for a new version. It’s easy to parse and very much to the point. In retrospect, you can also check out how the switch to version 2 looked like.

If you’re starting from scratch, just go ahead and read up on the specification of the newest version of compose files. If you’re thorough, you could go through the compose file version 2 reference and compare each point to the new one. Don’t do that :)

The most significant things you can’t use anymore: the workflow around volumes_from got replaced with handling volumes at top level of the file, and specifying which ones to use at service level.

services:
  postgres:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/db

volumes:
  data:

A bit of restructuring happened. Old keys in service blocks, which dealt with ways of limiting resources have wandered to similar keys under the deploy sub-key. Which is also more structured.

# from this
services:
  someservice:
    cpu_shares: '0.5'

# to this
services:
  someservice:
    deploy:
      limits:
        cpus: '0.5'

It’s Worth It, But Not Super Important

If you can’t spare the time, stick to the second version. You already have everything in place and it works. It might be deprecated in the future though.

When you’re going to migrate, take a look at the detailed instructions provided by Docker which will make the upgrade a breeze.

To use the new docker stack commands instead of docker-compose, you’ll need to switch to the new version. If you didn’t rely on volumes_from a lot, you won’t have to change much. Even if you did, this will improve your current setup.