An etcd upgrade check should prove more than that a daemon starts. Operators need to know that the version of etcdctl in the release can commit a request to the endpoint and that the backup procedure still produces an inspectable snapshot. Those are separate checks. A listener can answer a TCP connection while a client request fails, and a snapshot file can exist without the tool used to examine it being present where the runbook expects it.
This guide creates a disposable single-member etcd 3.7.1 node, checks endpoint health, writes and reads a harmless key, saves a snapshot, and inspects that snapshot with etcdutl. The successful result is concrete: endpoint health reports a committed proposal, the key round trip returns its expected value, snapshot save completes, and etcdutl snapshot status reports one key at revision 2. The lab uses a temporary data directory and loopback-only URLs; do not apply its unauthenticated listener settings to a cluster.
etcd 3.7.1 was released on 23 July 2026. Treat a release as a reason to rehearse the operational commands that surround an upgrade, not as evidence that an existing cluster should be changed immediately. Read the release notes and the version-specific upgrade guidance, then test the exact release and authentication model planned for the environment.
Make the test disposable
A single-member node cannot validate quorum behavior, member replacement, certificates, or a production backup destination. It can validate the client and snapshot commands before they are introduced into a maintenance procedure. Use a private working directory and an unused loopback client and peer port. The names below are placeholders deliberately separated from any real cluster.
Download the release archive and checksum manifest from the same release. Validate the one archive for the platform before extracting it:
set -eu
version=3.7.1
archive="etcd-v${version}-linux-amd64.tar.gz"
base="https://github.com/etcd-io/etcd/releases/download/v${version}"
curl -fsSLO "$base/$archive"
curl -fsSLO "$base/SHA256SUMS"
grep " $archive$" SHA256SUMS | sha256sum -c -
tar -xzf "$archive"
The checksum command should print OK for the selected archive. Do not extract or execute a file that fails this check. The release directory contains etcd, etcdctl, and etcdutl; keep the three binaries from the same archive so the client and utility versions are unambiguous.
Record what was tested before starting the service:
bin="$PWD/etcd-v${version}-linux-amd64"
"$bin/etcd" --version
"$bin/etcdctl" version
"$bin/etcdutl" version
In the isolated Linux amd64 validation run, all three commands reported version 3.7.1. The server reported Git SHA 5e7fd0d, and both utilities reported API version 3.7. Preserve equivalent version output with the upgrade ticket. A package supplied by an operating-system repository may use a different build or patch level even when its package name looks similar.
Start one local member
The following command creates a new data directory and binds only to loopback placeholder URLs. Run it in a terminal that can be stopped after the test. The data directory must not point at a member directory copied from a cluster.
"$bin/etcd" \
--name evidence-node \
--data-dir "<temporary-data-directory>" \
--listen-client-urls "<loopback-client-url>" \
--advertise-client-urls "<loopback-client-url>" \
--listen-peer-urls "<loopback-peer-url>" \
--initial-advertise-peer-urls "<loopback-peer-url>" \
--initial-cluster "evidence-node=<loopback-peer-url>" \
--initial-cluster-state new
--initial-cluster-state new is appropriate only because this is a newly created single-member lab. A real member needs the cluster’s established initial-cluster configuration and its documented upgrade sequence. Likewise, a production endpoint normally requires TLS and authentication. The intentionally simple local listener removes certificate and identity setup from this narrow compatibility check; it is not a secure etcd configuration.
Wait until the client endpoint is ready, then ask etcdctl to perform a real proposal rather than only listing a process:
"$bin/etcdctl" --endpoints="<loopback-client-url>" endpoint health
"$bin/etcdctl" --endpoints="<loopback-client-url>" put upgrade-check passed
"$bin/etcdctl" --endpoints="<loopback-client-url>" get upgrade-check
A healthy result resembles this:
<loopback-client-url> is healthy: successfully committed proposal: took = <duration>
OK
upgrade-check
passed
The put and get are intentionally harmless, but they make the health test meaningful. endpoint health reports whether the endpoint can commit a proposal; it is stronger than a port probe because it exercises the client request path and the member’s ability to apply it. The read-back confirms that the proposal became visible through the same endpoint.
For a real cluster, supply every endpoint and the same --cacert, --cert, --key, authentication, and timeout options used by the backup or upgrade automation. A one-member lab cannot tell you whether all production members agree on revision, whether a follower is behind, or whether a load balancer routes the request as expected. Use endpoint status across the authorized cluster endpoints to review member IDs, leader state, revision, database size, and any reported errors before changing a member.
Save a snapshot, then inspect it with etcdutl
Capture the snapshot to a temporary file while the test member is still running:
"$bin/etcdctl" --endpoints="<loopback-client-url>" \
snapshot save "<temporary-snapshot-file>"
A save result should say that the snapshot was fetched and saved. Treat a successful file creation alone as insufficient. Check the saved content using the release’s etcdutl binary:
"$bin/etcdutl" snapshot status "<temporary-snapshot-file>" --write-out=table
The 3.7.1 lab produced a table with one key, revision 2, and a 29 kB snapshot. The exact hash and size will differ on every run, but a valid status contains the hash, revision, total key count, total size, and stored version. These values give an operator a compact record to compare with the deliberate test write.
This distinction between the two utilities is worth making explicit in a runbook. In the tested 3.7.1 archive, etcdctl snapshot save created the snapshot, but etcdctl snapshot status was not an available subcommand: it printed the snapshot command help. etcdutl snapshot status successfully inspected the same file. A procedure copied from an older environment that calls the former status command therefore needs correction before an upgrade window, even though the backup itself may still have succeeded.
Do not over-interpret the laboratory revision. It reflects the synthetic put, not a measure of a production cluster’s health. On the real backup path, save the snapshot to the approved protected destination, restrict the file permissions, record its checksum according to the backup policy, and test restoration in a separate authorized environment. A snapshot report is useful evidence that a file is structurally readable; a restore exercise is the evidence that the recovery procedure meets the service objective.
Leave no member behind
Stop the temporary process and remove its data directory, snapshot, archive, and extracted binaries when the validation record has been captured. The isolated 3.7.1 run stopped its member after snapshot inspection and confirmed that no test etcd process remained. Do not remove a production data directory as part of an upgrade check.
The useful pre-upgrade result is a short chain of evidence: the exact release passed checksum verification, the matching client committed and read a test value, the snapshot was saved, and the matching etcdutl inspected it. That chain caught a tool-boundary change before it could become a failed runbook command during maintenance.