Skip to content

🗄️ ETCD for Beginners

🎯 Objectives

  1. What is etcd?
  2. What is a Key-Value Store?
  3. How to get started quickly?
  4. How to operate etcd?
  5. Distributed system
  6. How etcd works
  7. RAFT Protocol
  8. Best practices on number of nodes

📖 What is ETCD?

ETCD is a distributed, reliable key-value store that is simple, secure, and fast.

🗃️ What is a Key-Value Store?

Relational Databases (Tabular Format)

Traditionally, databases have been in tabular format — relational databases store data in rows and columns. For example, here is a table that stores information about a few individuals:

Name Age Location
John Doe 45 New York
Dave Smith 34 New York
Aryan Kumar 10 New York
Lauren Rob 13 Bangalore
Lily Oliver 15 Bangalore

The rows represent each person and the columns represent the type of information stored. Now say we want to add additional details — for example, salary — so we add an additional column. Doing so impacts the entire table and all individuals in it.

Name Age Location Salary
John Doe 45 New York 5000
Dave Smith 34 New York 4000
Aryan Kumar 10 New York
Lauren Rob 13 Bangalore
Lily Oliver 15 Bangalore

We are then required to store grade information, so we add a new column and update the students with their respective grades. Again, only students have grades, so the corresponding fields for adults are empty. Every time new information needs to be added, the entire table is affected and leads to many empty cells.

[!warning] In relational databases, adding a new attribute (column) affects every row in the table — even when most rows don't need that field.

Document / Key-Value Store

A key-value store stores information in the form of documents or pages. Each individual gets a document, and all information about that individual is stored within that file. These files can be in any format or structure, and changes to one file do not affect others.

The working individuals can have files with salary fields, and the students can have pages with grades only:

Key Value
Name John Doe
Age 45
Location New York
Salary 5000
Key Value
Name Dave Smith
Age 34
Location New York
Salary 4000
Organization Active
Key Value
Name Aryan Kumar
Age 10
Location New York
Grade A
Key Value
Name Lauren Rob
Age 13
Location Bangalore
Grade C
Key Value
Name Lily Oliver
Age 15
Location Bangalore
Grade B

Document stores typically use data formats like JSON or YAML.

📊 Relational DB vs Document Store vs Key-Value Store

Feature Relational DB Document Store Key-Value Store
Schema Yes No No
Complex Queries Yes (SQL) Limited (No Joins) No
Performance Good Good ⚡ Superfast
Flexibility Rigid Flexible Very Flexible
Best For Structured Data Semi-Structured Simple Fast Lookup

[!tip] ETCD is one such tool — a distributed, reliable key-value store optimised for speed and consistency.

🔑 Key-Value Store — Examples

Here's how simple key-value pairs look in practice:

Key: name          →  Value: John Doe
Key: location      →  Value: New York
Key: salary        →  Value: 5000

A single record combining multiple fields:

Key:   user:john_doe
Value: name=John Doe, age=45, location=New York, salary=5000

Or stored as a JSON document:

Key:   user.john_doe
Value: {"name": "John Doe", "age": 45, "location": "New York", "salary": 5000}

⚙️ Install ETCD

Step 1 — Download Binaries

curl -L https://github.com/etcd-io/etcd/releases/download/v3.x.xx/etcd-v3.x.xx-linux-amd64.tar.xz \
  -o etcd-v3.x.xx-linux-amd64.tar.gz

Step 2 — Extract

tar xzvf etcd-v3.x.xx-linux-amd64.tar.xz

Step 3 — Run the Service

./etcd

🛠️ Operating ETCD with ETCDCTL

ETCDCTL is the CLI tool used to interact with ETCD. ETCDCTL can communicate with the ETCD server using two API versions — Version 2 and Version 3. By default it is set to use Version 2. Each version has a different set of commands.

API Version 2 Commands

etcdctl backup
etcdctl cluster-health
etcdctl mk
etcdctl mkdir
etcdctl set

API Version 3 Commands

etcdctl snapshot save
etcdctl endpoint health
etcdctl get
etcdctl put

Setting the API Version

To use Version 3, set the environment variable:

export ETCDCTL_API=3

[!important] When the API version is not set, it defaults to Version 2 — Version 3 commands will not work. When the API version is set to 3, Version 2 commands will not work.

🔐 Authenticating ETCDCTL

You must also specify the path to certificate files so that ETCDCTL can authenticate to the ETCD API Server. The certificate files are available on the etcd-master at the following paths:

--cacert /etc/kubernetes/pki/etcd/ca.crt
--cert   /etc/kubernetes/pki/etcd/server.crt
--key    /etc/kubernetes/pki/etcd/server.key

Full Command Example

For the commands to work correctly, you must specify both the ETCDCTL API version and the path to the certificate files:

kubectl exec etcd-controlplane -n kube-system -- sh -c "ETCDCTL_API=3 etcdctl get / \
  --prefix --keys-only --limit=10 \
  --cacert /etc/kubernetes/pki/etcd/ca.crt \
  --cert   /etc/kubernetes/pki/etcd/server.crt \
  --key    /etc/kubernetes/pki/etcd/server.key"

[!note] We discuss certificates in detail in the Security section of this course. Don't worry if this looks complex right now!

📝 Summary

Concept Detail
ETCD Distributed, reliable key-value store
Key-Value Store Stores data as document pairs — flexible, schema-free
ETCDCTL CLI tool to interact with ETCD
Default API Version 2 (set ETCDCTL_API=3 for Version 3)
Certificates Required for authenticating ETCDCTL to ETCD API Server