Skip to main content

Toward etcd v3 in CoreOS Container Linux

CoreOS etcd’s first commits happened some three and a half years ago, and a lot has changed since that initial version 0 of the etcd API. etcd version 3, introduced last summer, offers a streamlined, gRPC-based API and dramatic performance improvements over both competitive solutions and its own prior versions, while maintaining the distributed reliability and rolling upgrade capabilities that make etcd manageable in production.

With adoption coalescing around etcd v3, today we are announcing deprecation plans for older versions of etcd in CoreOS Container Linux (formerly known as CoreOS Linux). The current schedule for end of support for each version in Container Linux is:

  • etcd v0: May 7, 2017
  • etcd v2: February 1, 2018

etcd v3 API is the current etcd API

As applications and systems software scale for the cloud, a distributed key-value store like etcd has become an essential component of many architectures. The Kubernetes cluster orchestrator, for example, relies on etcd for cluster metadata storage and retrieval. Kubernetes version 1.6, scheduled for release soon, will be built with etcd v3 by default, to take advantage of the scalability and performance improvements of the latest edition.

If you’re writing new applications that leverage the etcd distributed key-value store, you should be targeting the v3 API. If you have existing applications that use the v2 API, etcd v3 provides compatibility while offering improved performance and scalability. You’ll want to read on to find out how to upgrade to etcd v3, and what to expect in the eventual deprecation of etcd v2 binaries in CoreOS Container Linux. An upgrade to etcd v3 maintains the same rolling update capability as the v2 series, preserving data while transitioning between etcd versions.

If you have legacy code that targets the v0 etcd API, this is a reminder of the notice provided last autumn that all support for and packaging of the etcd v0.4 binary in CoreOS Container Linux will cease after May 7, 2017.

etcd v0 scheduled for removal from Container Linux in May, 2017

While etcd v0 has been de-facto deprecated in the tradition of “version zero” software for some time, CoreOS Container Linux has continued to deliver an etcd v0.4 binary alongside current etcd versions. On May 7, 2017, the etc v0.4 binary will be removed from the Alpha channel CoreOS Container Linux image. As that version is promoted through the Beta and Stable channels, etcd v0 will be removed from them as well.

Those still using etcd v0 should immediately consult the documentation of major changes in the API, beginning with those introduced between versions 0 and 2, and convert applications to use the etcd v3 API.

etcd v2 series in maintenance: No new feature development

etcd v2.3.x continues to be supported and included in CoreOS Container Linux. However, the etcd 2.x series is strictly in maintenance, receiving only critical bug fixes and security updates after January, 2017. No new feature development will occur in the etcd v2.x series after this date.

Users are advised to begin testing and plan to migrate etcd v2.x deployments to etcd v3. Upgrading a deployment from etcd v2 to v3 does not require changes to API client application source code, since etcd v3 exposes a v2 compatibility API.

etcd v2 scheduled for removal from Container Linux in February, 2018

Etcd v2 will be removed from the CoreOS Container Linux Alpha channel on February 1, 2018, and will not be supported after that time. As that version of Container Linux is promoted through the Beta and Stable channels, etcd v2 will be removed from them as well.

The future of etcd v3 on Container Linux: etcd in a container

CoreOS Container Linux already includes lightweight scaffolding for running etcd v3 in a container executed by the rkt container engine. Briefly, running etcd in a container involves selecting an etcd version and enabling the containerized etcd v3 systemd unit. A wrapper knows how to fetch the etcd container image from the CoreOS Quay registry and works with the systemd unit to execute etcd. The result is an even slimmer base OS, but with simple facilities for adding key infrastructure like etcd by taking advantage of container distribution and execution. After February, 2018, this will be the standard and supported method for running etcd on CoreOS Container Linux.

Frequently Asked Questions

My app uses etcd v0.4 on CoreOS Container Linux. What should I do?

You should immediately consult the differences between v0 and later etcd editions, and update your application to use the etcd v3 API. Since etcd v2 is also scheduled for eventual deprecation, it makes sense to avoid updating your code twice.

My app uses etcd v2.3.7, or another etcd v2.x. What should I do?

You should begin testing your deployments with etcd v3 binaries, according to the instructions in the upgrade guide. Source code changes to client applications are not required; etcd v3 offers compatibility with the v2 API.

How do I run etcd v3 on Container Linux?

For evaluation purposes in preparation for the eventual deprecation of etcd v2, advanced users might consult the unit file and wrapper scripts that fetch and execute an etcd v3 container.

It’s simple to use this framework to bring up a single-node etcd v3 “cluster” on any recent CoreOS Container Linux version:

$ systemctl enable /usr/lib/systemd/system/etcd-member.service
$ systemctl start etcd-member
$ rkt list
4d566696 etcd running 6 minutes ago 6 minutes ago
$ etcdctl set fname Regis
$ etcdctl get fname

Check out the etcd documentation for more information and next steps with etcd v3.