Why ETCDCTL_API=3 is Required for etcdctl Snapshot Commands
An admin attempts to restore an etcd snapshot using 'etcdctl snapshot restore' but encounters an error. Which environment variable must be set for etcdctl to work with v3 API?
Quick Answer
The answer is ETCDCTL_API=3. This environment variable is required because etcdctl defaults to the v2 API, but snapshot restore commands like `etcdctl snapshot restore` rely entirely on the v3 API’s data model and command structure; without setting ETCDCTL_API=3, the tool cannot interpret the snapshot file or execute the restore, resulting in an error. On the Certified Kubernetes Administrator CKA exam, this is a classic trap—candidates often forget that etcdctl must be explicitly told to use the v3 API, especially when working with etcd v3.x clusters in Kubernetes control plane recovery scenarios. The exam tests your ability to troubleshoot snapshot operations, and this environment variable is the most common missing piece. A simple memory tip: think “v3 for restore”—if you’re restoring a snapshot, you’re working with v3 data, so set the API to match.
⚠ Common exam trap
Watch out — candidates often confuse the variable name (`ETCDCTL_API` vs `ETCD_API`) or the value format (`3` vs `v3`), leading them to pick a syntactically similar but incorrect option.
Answer choices
Why each option matters
Answer the question above first, then reveal the full breakdown to understand why each option is right or wrong.
Correct answer & explanation
✓
ETCDCTL_API=3
Etcdctl uses the etcd v2 API by default, and to interact with the v3 API (which is the standard for etcd v3.x clusters), the environment variable `ETCDCTL_API=3` must be set. Without this variable, `etcdctl snapshot restore` will fail as it relies on v3-specific commands and data model.
Answer analysis
Option-by-option breakdown
For each option: why learners choose it and why it is or isn't the right answer here.
- ✗
ETCD_API=3
Why it's wrong here
ETCD_API is not a recognised etcdctl variable, so setting it changes nothing and the client still defaults to the v2 API. The variable etcdctl actually reads is ETCDCTL_API. ETCD_API resembles the ETCD_* naming used for endpoints and certificates, which is why it appears plausible.
- ✗
ETCDCTL_API=v3
Why it's wrong here
ETCDCTL_API=v3 is the correct variable, so this option would not be the wrong answer. It forces etcdctl to use the v3 API, which snapshot restore requires. Older etcdctl builds default to v2, hence the explicit setting. The other options name variables etcdctl never reads.
- ✓
ETCDCTL_API=3
Why this is correct
etcdctl defaults to the v2 API unless told otherwise, so snapshot restore against a v3 data directory fails. Setting ETCDCTL_API=3 forces etcdctl to speak the v3 API, matching the cluster's etcd version and allowing the restore to proceed.
- ✗
ETCDCTL_VERSION=3
Why it's wrong here
ETCDCTL_VERSION is not read by etcdctl, so it leaves the client on its default API version and restore still fails. The variable that selects the API is ETCDCTL_API. The name is tempting because etcdctl does expose a --version flag, but that reports the binary version rather than choosing an API.
Go deeper
Related to this question
About these practice questions
This CKA question is part of Courseiva's 726-question bank — original exam-style content with full explanations and wrong-answer analysis, never real exam questions or exam dumps. Learn why practice questions differ from exam dumps →
Same concept, more angles
1 more way this is tested on CKA
These questions test the same concept from different angles. Work through them to make sure you can recognise it however the exam phrases it.
Variation 1. A cluster is running etcd without TLS. The admin wants to take a snapshot backup. Which command is correct?
medium- A.etcdctl backup --data-dir /var/lib/etcd
- ✓ B.ETCDCTL_API=3 etcdctl snapshot save /backup/snapshot.db
- C.etcdctl export --data-dir /var/lib/etcd
- D.etcdctl snapshot save --endpoints=http://127.0.0.1:2379 /backup/snapshot.db
Why B: `ETCDCTL_API=3 etcdctl snapshot save` is the proper command to take a snapshot backup of an etcd cluster using the v3 API. Since the cluster is running without TLS, the command does not require additional flags like `--cacert` or `--cert`, but the default endpoint is `http://127.0.0.1:2379`, which is used implicitly. The v3 API is required because etcd v3 stores data in a different format than v2, and `snapshot save` captures the full key-value store for disaster recovery.
JA
Written by Johnson Ajibi, MSc IT Security
Senior Network & Security Engineer · founder of Courseiva
This CKA practice question is part of Courseiva's free CNCF certification practice question bank. Courseiva provides original exam-style practice questions with explanations, topic-based practice, mock exams, readiness tracking, and study analytics to help learners prepare for the CKA exam.