vsupalov

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.

Join the mailing list!


Subscribe to get notified about future articles and stay in touch via email.

I write about Kubernetes, Docker, automation- and deployment topics, but would also like to keep you up to date about news around the business-side of things.

Privacy and your data: You can get more information about the usage of your data, the storage of your registration, sending out mails with the US-provider ConvertKit, statistical analysis of emails sent and your possibility to unsubscribe in my Privacy Policy.

I use the US-provider ConvertKit for email automation. By clicking to submit this form, you acknowledge that the information you provide will be transferred to ConvertKit for processing in accordance with their Privacy Policy and Terms.

We won't send you spam. Unsubscribe at any time. Powered by ConvertKit