Skip to main content

Toward Docker 17.xx in Container Linux

As a modern, minimal, container-focused operating system, Container Linux by CoreOS strives to deliver the most recent stable versions of the key software needed to run containers: the Docker and rkt container engines, the Linux kernel, systemd, and etcd.

In recent months, however, the version of one of these components has remained unchanged: Container Linux beta and stable releases have included version 1.12.6 of the Docker Engine since January of this year. We've been sticking with Docker 1.12 to support users who require that version due to the support matrices of Kubernetes, Mesos, and other tools. In contrast, some users prefer to run the latest versions of Docker, and until now we haven't had a way to address both needs.

In the coming months, Container Linux will return to shipping current versions of Docker Community Edition (CE) Stable, while continuing to assist those users who need older versions of Docker. The migration will be implemented in three steps, beginning today with an interim solution and continuing through July 2018.

First, in recent releases of Container Linux (1548.0.0 and above, plus stable releases 1520.5.0 and above), we've added support for a configuration file — /etc/coreos/docker-1.12 — enabling users to choose between Docker 1.12 and the current version of Docker CE Stable (17.09 at this writing). With this file, you can begin testing and deploying Docker 17.09 right away.

Second, we'll be changing the default version of Docker in Container Linux to the current Docker CE Stable release. The beta channel will switch on November 8, and the stable channel will follow on December 6. If you'd like to continue running Docker 1.12 after those dates, you can do so via the same config file, /etc/coreos/docker-1.12.

Finally, we're working on Torcx, a generic system enabling Container Linux users to select the versions of container runtimes and other key components that are most compatible with their environments. Once the full Torcx functionality is ready, and before May 23, 2018, we'll document a migration path from /etc/coreos/docker-1.12 to the Torcx infrastructure. Then, on June 6, 2018, the Container Linux alpha channel will no longer use /etc/coreos/docker-1.12 to select a Docker version. The beta channel will follow on June 20, and the stable channel on July 18.

Choosing a Docker version

Starting today, the Docker version in all three Container Linux channels can be configured using the file /etc/coreos/docker-1.12.

If /etc/coreos/docker-1.12 is absent, Container Linux will select a default version of Docker according to the timeline below. To select current Docker before it becomes the default, write no (with or without a trailing newline) to /etc/coreos/docker-1.12 and reboot. To select Docker 1.12, even after the default version changes, write yes (with or without a trailing newline) to /etc/coreos/docker-1.12, stop all containers and the Docker daemon, delete /var/lib/docker, and reboot. Note that this will remove all of Docker’s data, including all containers and images.

/etc/coreos/docker-1.12 can be written when a Container Linux machine is provisioned, using a Container Linux Config or Ignition config. On existing machines, it can be configured via configuration management tools or SSH. Example configs and additional details are available at the end of this post.

As mentioned above, this mechanism is temporary. By May 23, 2018, we will document a migration path to a long-term mechanism for selecting the Docker version in Container Linux. The Container Linux alpha release of June 6, 2018, will ignore the /etc/coreos/docker-1.12 file and will update to the latest version of the Docker Engine unless otherwise configured. As that release is promoted to beta and stable (on June 20 and July 18, respectively), those channels will do the same.

If you encounter any issues with the migration process, please let us know via the coreos-user mailing list.

Timeline

  • October 27, 2017: The alpha channel defaults to Docker 17.09.0. Beta and stable continue to default to Docker 1.12.6, but users can set /etc/coreos/docker-1.12 to no for an earlier switch to Docker 17.09.
  • November 8, 2017: The beta channel defaults to Docker 17.09 unless /etc/coreos/docker-1.12 is set to yes.
  • December 6, 2017: The stable channel defaults to Docker 17.09 unless /etc/coreos/docker-1.12 is set to yes.
  • May 23, 2018: Docker version selection via Torcx is documented and available in all channels.
  • June 6, 2018: /etc/coreos/docker-1.12 is ignored in the alpha channel.
  • June 20, 2018: /etc/coreos/docker-1.12 is ignored in the beta channel.
  • July 18, 2018: /etc/coreos/docker-1.12 is ignored in the stable channel.

Q & A

What version of Docker will Container Linux ship in the future?

Container Linux beta and stable releases will typically default to the most recent version of Docker CE Stable as of the corresponding Container Linux alpha release. Container Linux alpha releases will typically default to the most recent release of either Docker CE Stable or Docker CE Edge.

What about Docker 17.03?

Kubernetes 1.8 is officially validated for Docker versions through 17.03. If you want to run a Docker version validated by Kubernetes, we recommend staying on Docker 1.12 for now. The full Torcx functionality, once available, will enable you to select the version of Docker most appropriate for your environment.

How will this affect Tectonic?

Starting with Tectonic 1.7.5, Tectonic automatically manages the container runtime used on the nodes within the cluster. Newly-provisioned clusters and clusters that are updated from a previous Tectonic release will begin to automatically manage the container runtime. On older clusters that do not update to a newer version of Tectonic, Container Linux will automatically detect Tectonic and create /etc/coreos/docker-1.12. In all cases, no manual intervention is required.

Looking ahead

We hope this version-selection mechanism helps to ease the transition from Docker 1.12.6. If anything changes, or if we learn of additional issues you might encounter during the transition, we'll update this blog post. If you'd like to share your use cases or to participate in Torcx design or implementation, you can get involved on GitHub, the coreos-dev mailing list, or IRC. And as always, if you have questions or concerns, feel free to get in touch.


Example configurations

Container Linux Config

CoreOS recommends provisioning Container Linux using Container Linux Configs. The following Container Linux Config fragment configures a system to continue using Docker 1.12:

storage:
  files:
    - filesystem: root
      path: /etc/coreos/docker-1.12
      contents:
        inline: yes

Pass this config to the Config Transpiler to produce an Ignition config.

To configure the system to use the current version of Docker before it becomes the default, change yes to no.

Ignition config

For systems using hand-crafted Ignition configs, the following fragment configures a system to continue using Docker 1.12:

{
  "ignition": {
    "version": "2.1.0"
  },
  "storage": {
    "files": [
      {
        "filesystem": "root",
        "path": "/etc/coreos/docker-1.12",
        "contents": {
          "source": "data:,yes"
        }
      }
    ]
  }
}

To configure the system to use the current version of Docker before it becomes the default, change yes to no.

cloud-config

Container Linux executes cloud-configs late in the boot process, after /etc/coreos/docker-1.12 has already been processed, and potentially after the Docker daemon has started. Therefore, we do not recommend creating or modifying /etc/coreos/docker-1.12 using a cloud-config. Instead, modify /etc/coreos/docker-1.12 after the system has booted, using the instructions in the next section, or migrate to Container Linux Configs.

Configuring existing systems

To upgrade to the current version of Docker on a running system, write no to /etc/coreos/docker-1.12 and reboot. For example, using SSH:

ssh core@node01 'sudo sh -c "mkdir -p /etc/coreos && echo no > /etc/coreos/docker-1.12 && systemctl reboot"'

Reverting to Docker 1.12 requires an additional step, due to changes in the format of the Docker runtime directory between 1.12 and 17.09. To downgrade Docker, write yes to /etc/coreos/docker-1.12, stop all containers and the Docker daemon, delete /var/lib/docker, and reboot. Be aware that this will remove all of Docker’s data, including all containers and images.

For example, using SSH:

ssh core@node01 'sudo sh -c "mkdir -p /etc/coreos && echo yes > /etc/coreos/docker-1.12 && docker ps -aq | xargs -r docker stop && systemctl stop docker.service && rm -rf /var/lib/docker && systemctl reboot"'

To return to the default Docker version, delete /etc/coreos/docker-1.12 and reboot. If downgrading to Docker 1.12, stop all containers and the Docker daemon and remove /var/lib/docker before rebooting. For example, using SSH:

ssh core@node01 'sudo sh -c "rm /etc/coreos/docker-1.12 && docker ps -aq | xargs -r docker stop && systemctl stop docker.service && rm -rf /var/lib/docker && systemctl reboot"'