Skip to content

Upgrade etcd

This page explains how the etcd version is tied to a KX Sensors release, why the installer leaves etcd untouched on existing deployments, and how to upgrade etcd separately.

KX Sensors uses etcd as the data store behind discovery. For background on how it fits into the architecture, see Key processes.

The etcd version is pinned per release

Each KX Sensors release pins the etcd version that the installer deploys. The ETCD_VER variable in the installer's scripts/remote/install-etcd.sh defines this version. When the version changes between releases, KX announces it in the release notes.

A new installation gets the pinned version. An existing deployment keeps the etcd version it was installed with, even after you upgrade KX Sensors itself.

Note

In an air-gapped environment, the installer looks for the etcd tarball in the deps directory of your deployment, matching the pinned version exactly (for example, etcd-v3.5.2-linux-amd64.tar.gz). When ETCD_VER changes, place the matching tarball in deps before installing a new deployment, otherwise the installer attempts to download it and fails.

The installer does not upgrade etcd

When you stage an upgrade by using the installer's -U flag, the installer copies the packages and applies the new directory list. It doesn't run the etcd installation step. As a result:

  • The etcd binaries in ETCD_DIR are unchanged.
  • The etcd data directory ETCD_DATA_DIR is untouched.
  • The running kxs-etcd service continues to use the installed version.

This behavior is intentional. etcd is treated as a modular component that can be upgraded independently of KX Sensors. A KX Sensors upgrade doesn't change the etcd version used by a running cluster.

Warning

Don't use the installer to upgrade etcd on an existing deployment. The installer's etcd step reinstalls etcd from scratch: it removes and re-extracts ETCD_DIR without first stopping the kxs-etcd service, so the service keeps running on the previous version and the cluster reports healthy even though nothing was upgraded. The installer steps that reset or reinstall a deployment (-a, -e, and -P) are for initial installation and full resets, not for etcd version changes. The full reset path also deletes all etcd data.

Upgrade etcd separately

You can upgrade etcd independently of KX Sensors, on its own schedule, by following the standard rolling upgrade procedure:

  • Upgrade one minor version at a time. etcd does not support skipping minor versions. For example, to upgrade from 3.5 to 3.7, first upgrade to 3.6.
  • Upgrade one cluster member at a time. Wait for each member to rejoin and verify that the cluster is healthy before upgrading the next member. Mixed versions across members are expected during the rollout.
  • Keep quorum throughout. With a three-member cluster you can take one member offline at a time. A single-member etcd deployment can't be upgraded without downtime.
  • Back up the etcd data directory before you start.

For the authoritative procedure, including per-version notes and any version-specific migration steps, follow the etcd upgrade documentation for your target version.

Note

Upgrading etcd restarts each kxs-etcd service in turn. Check the health of your KX Sensors system afterwards, as described in Look up the status of feeds and nodes.

Next steps