etcd Documentation

Ideas you will meet

Consensus

Raft, Paxos and how replicas agree on one order.

Kubernetes

Container orchestration, scheduling and service discovery.

What we already know about this

Our own lessons on these ideas. Read them here before you start, so it makes sense.

• Advanced Distributed Systems · 12 minConsensus: Raft and PaxosHow a group of machines agrees on one order of operations even when some crash or messages are delayed, and why a majority is the magic number.Read hereClose

  The problem consensus solves

  Several machines must agree on one sequence of operations (who is the leader, what is the next log entry, who owns a lock) even though machines crash and messages are delayed or lost. Without a protocol, replicas drift apart and two nodes may both believe they are the leader.

  Systems that rely on consensus include coordination services (etcd, ZooKeeper), many databases for their metadata or their data, and Kubernetes (through etcd).

  Why a majority

  A decision is valid when a majority (quorum) of nodes accepts it. Any two majorities share at least one node, so a later decision always meets someone who remembers the earlier one. A cluster of n nodes tolerates floor((n-1)/2) failures: 3 nodes tolerate 1, 5 nodes tolerate 2. That is why clusters have an odd number of nodes; a 4th node adds cost but no extra fault tolerance over 3.

  Raft in three parts

  Raft splits the problem so it can be understood:

  100%

  Figure SDA-ADS-01-1 · Raft roles and elections · © forcsguy.com

  1. Leader election. Time is divided into numbered terms. A node that hears nothing becomes a candidate and requests votes. A node votes at most once per term, and only for a candidate whose log is at least as up to date as its own. Randomised timeouts make split votes rare.
  2. Log replication. The leader appends a client command to its log and sends it to followers. When a majority has stored the entry, it is committed; the leader applies it and replies to the client. Followers apply committed entries in order, so every replica runs the same sequence.
  3. Safety. The vote rule guarantees that any new leader already has every committed entry, so committed entries are never lost or reordered.

  100%

  Figure SDA-ADS-01-2 · Replicating one write · © forcsguy.com

  Paxos, briefly

  Paxos reaches the same guarantee with two phases (prepare/promise, then accept/accepted) over a majority. It is famous for being hard to implement and explain, and for being the basis of many systems. Multi-Paxos repeats it for a log of decisions. Raft is essentially a clearer arrangement of the same ideas with a strong leader, which is why most new systems choose it.

  What consensus costs and what it does not give

  • Latency: every committed write waits for a majority round trip, so cross-region clusters are slow. Keep consensus groups within a region or use few, small groups for metadata.
  • Throughput: one leader handles all writes in a group. Large databases run many small groups (one per data range) to spread load.
  • Availability under partition: the minority side cannot make progress. This is the CAP trade-off made concrete: consensus systems are consistent first.
  • It does not remove all problems: slow nodes, clock assumptions, and reconfiguration (adding or removing nodes safely) need care.

  Where you will meet it

  Leader election for databases and queues, distributed locks and configuration stores, metadata for storage systems, and cluster state in Kubernetes. When a design needs "exactly one leader" or "all replicas agree on this order", you are describing consensus. See also the distributed-locks lesson in the core-concepts course.

  Real-world reading

  Related reading

  • In Search of an Understandable Consensus Algorithm (Raft paper)Ongaro and Ousterhout · Stanford UniversityPapers
  • The Raft Consensus Algorithm (site and visualisation)Diego Ongaro and community · raft.github.ioDocumentation
  • ZippyDB: Facebook's key-value storeMeta Engineering · MetaCase Studies
  • How Ringpop from Uber Engineering Helps Distribute Your ApplicationUber Engineering · UberCase Studies

  Show 6 moreShow fewer

  • etcd Raft libraryetcd · CNCF / etcdGitHub
  • Google SRE Book: Managing Critical State (Distributed Consensus)Google SRE team · GoogleBlogs
  • Paxos Made Simple (paper)Leslie Lamport · Microsoft ResearchPapers
  • HashiCorp RaftHashiCorp · GitHubGitHub
  • Distributed Systems (4th edition)Maarten van Steen and Andrew Tanenbaum · distributed-systems.netBooks
  • Scaling Hadoop YARN cluster beyond 10,000 nodes at LinkedInLinkedIn engineers · LinkedInCase Studies

  Open this lesson with its quiz and exercise

• Advanced Distributed Systems · 13 minKubernetes essentialsPods, deployments, services, ingress and operators: the building blocks of the most common container platform and how a request reaches a pod.Read hereClose

  What Kubernetes does

  Kubernetes (K8s) runs containers across a cluster of machines. You describe the desired state (for example "three copies of this image, reachable at this address") and controllers continuously make reality match it: restarting failed containers, replacing lost nodes and rolling out new versions. (Containers themselves are introduced in the cloud models lesson.)

  The cluster

  • Control plane: the API server (everything talks to it), etcd (the consistent store of cluster state, built on Raft; see the consensus lesson), the scheduler (decides which node runs a pod) and controllers (reconcile desired and actual state).
  • Nodes: machines that run pods, each with a node agent (kubelet), a container runtime and a networking component.

  The core objects

  100%

  Figure SDA-ADS-07-1 · From request to pod · © forcsguy.com

  Object	Purpose
  Pod	Smallest unit: one or more containers sharing network and volumes
  ReplicaSet / Deployment	Keep N pods running; roll out updates and roll back
  Service	Stable virtual IP and DNS name that load balances to matching pods
  Ingress	HTTP routing from outside to services (host, path, TLS), handled by an ingress controller
  ConfigMap / Secret	Configuration and sensitive values injected as environment variables or files
  StatefulSet	Pods with stable identity and storage, for databases and brokers
  DaemonSet	One pod per node (log shippers, agents)
  Job / CronJob	Run to completion, once or on a schedule
  Namespace	Logical separation of resources and quotas
  PersistentVolume(Claim)	Durable storage requested by pods

  Networking in one paragraph

  Every pod gets its own IP and can reach every other pod without NAT. Because pods are short-lived, clients use Services (found through cluster DNS such as orders.shop.svc). Network policies restrict which pods may talk to which. An Ingress (or the newer Gateway API) handles external HTTP(S) traffic.

  A deployment and a rolling update

  apiVersion: apps/v1
  kind: Deployment
  metadata: { name: web }
  spec:
    replicas: 3
    selector: { matchLabels: { app: web } }
    strategy: { type: RollingUpdate, rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } }
    template:
      metadata: { labels: { app: web } }
      spec:
        containers:
          - name: web
            image: example/web:1.4.2
            resources: { requests: { cpu: 200m, memory: 256Mi }, limits: { memory: 512Mi } }
            readinessProbe: { httpGet: { path: /healthz, port: 8080 } }
  

  100%

  Figure SDA-ADS-07-2 · Rolling update · © forcsguy.com

  Probes: readiness decides if a pod receives traffic; liveness decides if it should be restarted; startup gives slow starters time. Requests and limits tell the scheduler how much CPU and memory a pod needs and cap what it can use.

  Autoscaling

  A Horizontal Pod Autoscaler adds or removes pods by metrics such as CPU or request rate; a cluster autoscaler adds or removes nodes when pods cannot be placed. Scaling is useless without correct resource requests.

  Extending Kubernetes: operators and CRDs

  A Custom Resource Definition (CRD) adds a new object type (for example PostgresCluster). An operator is a controller that watches those objects and does the operational work (create replicas, take backups, fail over), encoding human runbooks as code. Many databases and brokers ship operators.

  Things that often go wrong

  Missing readiness probes (traffic to pods not ready), no resource requests (noisy neighbours, evictions), latest image tags (unrepeatable deploys), secrets in plain config, a single replica for a critical service, and running stateful systems without understanding storage and failure behaviour.

  Real-world reading

  Related reading

  • TechWorld with Nana: Docker & KubernetesNana Janashia · TechWorld with NanaYouTube
  • AWS Containers BlogAmazon Web Services engineers · Amazon Web ServicesBlogs
  • Awesome KubernetesRamit Surana · ramitsuranaGitHub
  • Kubernetes ConceptsKubernetes Authors · CNCF / KubernetesDocumentation

  Show 6 moreShow fewer

  • Kubernetes: IngressKubernetes · CNCF / KubernetesDocumentation
  • Docker BlogDocker engineers · DockerBlogs
  • DevOps Roadmaproadmap.sh community · roadmap.shCourses
  • Kubernetes BlogKubernetes community · CNCF / KubernetesBlogs
  • From bare-metal to Kubernetes at BetabrandBetabrand engineers · BetabrandCase Studies
  • Large-scale cluster management at Google with Borg (paper)Verma et al. · GooglePapers

  Open this lesson with its quiz and exercise