StackPractices
intermediate Por Mathias Paulenko

Patrón de Elección de Líder

Coordina una única instancia activa entre múltiples nodos distribuidos para evitar conflictos y escenarios de split-brain.

Visión General

El Patrón de Elección de Líder garantiza que exactamente una instancia en un sistema distribuido actúe como líder activo en cada momento. El resto permanece como seguidoras y toman el control solo cuando el líder deja de renovar su reclamo. Sin él, dos nodos que creen estar al mando producen split-brain: trabajos duplicados, escrituras en conflicto y estado compartido corrupto.

El patrón aparece dondequiera que un clúster necesite un único coordinador: kube-scheduler y kube-controller-manager eligen líder mediante objetos Lease de Kubernetes, Kafka elige un controlador por clúster, y planificadores como Quartz o ejecutores de cron lo usan para que un trabajo se dispare una vez y no N veces. En el fondo es una especialización del patrón de bloqueo distribuido: el “bloqueo” es un lease con TTL que el ganador debe renovar continuamente.

Cuándo Usar

Usa este patrón cuando:

  • Varias réplicas podrían ejecutar el mismo trabajo programado, migración o informe, pero el trabajo debe ejecutarse exactamente una vez por intervalo.
  • Un servicio necesita un único escritor para un recurso compartido: una cola, un espacio de configuración, una asignación de shards.
  • Construyes un gestor de clúster o un plano de control donde un único coordinador simplifica las decisiones.
  • Puedes aceptar un hueco de conmutación por error de unos segundos mientras las seguidoras detectan al líder caído y eligen uno nuevo.

No lo uses cuando:

  • Una sola réplica detrás de un balanceador con health checks ya te da la disponibilidad que necesitas: la elección añade modos de fallo que aún no tienes.
  • El trabajo tolera la duplicación mediante idempotencia o semántica de al-menos-una-vez; un grupo de consumidores de una cola es más simple.
  • Todos los nodos deben seguir trabajando en paralelo: eso es un problema de distribución de trabajo, no de coordinación.

Solución

Toda implementación correcta se reduce al mismo contrato: los candidatos compiten por escribir atómicamente su identidad en una clave compartida con expiración (el lease), el ganador lo renueva con un heartbeat, y el almacén devuelve un fencing token — un número estrictamente creciente — que los servicios downstream verifican para rechazar líderes obsoletos.

# Elección de líder sobre un almacén atómico con CAS y fencing tokens.
# Funciona igual sobre etcd Txn, ZooKeeper o SQL `UPDATE ... WHERE`.
import threading
import time
import uuid


class AtomicStore:
    """Sustituto mínimo de etcd/ZooKeeper: solo operaciones atómicas."""

    def __init__(self):
        self._data, self._fence, self._lock = {}, 0, threading.Lock()

    def get(self, key):
        return self._data.get(key)

    def cas(self, key, expected, value):
        """Escribe solo si el valor actual == expected. Devuelve un fencing token."""
        with self._lock:
            if self._data.get(key) != expected:
                return None
            self._fence += 1
            value["fence"] = self._fence
            self._data[key] = value
            return self._fence


class LeaderElection:
    def __init__(self, store, lease_seconds=10):
        self.store = store
        self.lease_seconds = lease_seconds
        self.node_id = uuid.uuid4().hex[:8]

    def campaign(self):
        """Devuelve un fencing token cuando este nodo gana el lease."""
        now = time.monotonic()  # tiempo transcurrido, inmune a saltos de reloj
        current = self.store.get("leader")
        if current and current["expires"] > now:
            return None  # otro nodo tiene un lease vigente
        return self.store.cas(
            "leader", current,
            {"node": self.node_id, "expires": now + self.lease_seconds},
        )

    def renew(self, token):
        now = time.monotonic()
        current = self.store.get("leader")
        if not current or current["fence"] != token:
            return False  # liderazgo perdido
        current["expires"] = now + self.lease_seconds
        return True

En Kubernetes no escribes esto a mano: el API server almacena objetos Lease y el paquete leaderelection de client-go ejecuta la campaña:

apiVersion: coordination.k8s.io/v1
kind: Lease
metadata:
  name: app-leader
  namespace: default
spec:
  holderIdentity: pod-1
  leaseDurationSeconds: 15
kubectl apply -f lease.yaml
kubectl get lease app-leader -o yaml   # inspeccionar titular + renewTime

Explicación

El ciclo de vida tiene cuatro piezas móviles:

  1. Campaña: cada candidato intenta un único compare-and-swap atómico sobre la clave del lease. Solo una escritura puede ganar — eso es lo que hace la elección segura incluso bajo una partición, siempre que el almacén sea consistente.
  2. Heartbeat: el ganador renueva el lease bastante antes de su TTL (normalmente a TTL/2 o TTL/3). Perder una renovación no es fatal; perderlas todas hasta la expiración sí.
  3. Expiración: cuando las renovaciones se detienen — caída, pausa de GC, partición de red — el lease simplemente vence. Nadie tiene que “detectar” el fallo; lo hace el tiempo.
  4. Conmutación: una seguidora gana la siguiente campaña y se convierte en líder con un fencing token mayor.
Ciclo de vida del lease — los candidatos compiten por la clave del lease; el ganador envía heartbeats hasta que se detiene, el lease expira en su TTL y una seguidora gana la siguiente ronda.

Dos detalles separan una implementación de juguete de una segura:

Fencing tokens. Un líder que pierde su lease no se entera al instante: puede quedar pausado por el GC o aislado por una partición mientras sigue creyéndose al mando. Si entonces escribe en un recurso compartido, tienes dos escritores. El almacén devuelve un token monótono en cada elección exitosa; el líder lo adjunta a cada escritura y downstream rechaza cualquier token menor que el más alto visto. Raft lo llama term; etcd lo expone como la revisión de la clave. Omitir el fencing es la forma más común de que el código de elección de líder corrompa datos en silencio.

Supuestos de reloj. La lógica del lease debe usar tiempo transcurrido (time.monotonic, System.nanoTime), no hora de pared: una corrección de NTP puede “expirar” todos los leases a la vez o extender uno para siempre. El propio TTL del almacén (TTL del lease de etcd, leaseDurationSeconds de K8s, PX de Redis) es aún mejor, porque la expiración la decide un solo reloj, no el de cada nodo.

Elegir la duración del lease es el principal compromiso operativo: un TTL corto (5-15 s) conmuta rápido pero oscila bajo picos de carga o pausas de GC; un TTL largo es estable pero deja el clúster sin cabeza más tiempo. La mayoría de sistemas quedan en 15-30 s con renovaciones a TTL/3.

Variantes

VarianteAlmacén de coordinaciónCompromiso
Lease en base de datosPostgreSQL, MySQLSimple — un UPDATE ... WHERE expires < now() — pero ata la conmutación a la disponibilidad de la BD
Bloqueo distribuidoRedis SET NX PXRápido y barato, pero vulnerable a la deriva del reloj y exige verificar el fencing del lado del cliente
Algoritmo de consensoetcd, ZooKeeperEscrituras linealizables y watchers integrados; a cambio operas (o pagas) un clúster de consenso
Lease de KubernetesAPI server de K8sNativo para cargas ya en K8s; el paquete leaderelection maneja el bucle

Elige el almacén en el que tu clúster ya confía. Si usas etcd, aprovecha su primitiva concurrency.Election (documentada en la API de concurrencia de etcd): ordena a los candidatos por revisión de creación, así hay una línea de sucesión limpia en lugar de una estampida al expirar. En Kubernetes, el objeto Lease junto al leaderelection de client-go es el camino pavimentado. Redis sirve para coordinación blanda donde un doble líder ocasional es tolerable, pero lee el debate sobre Redlock antes de apostar la corrección: el análisis de Martin Kleppmann sobre fencing y relojes aplica directamente a la elección.

Un apunte sobre el alcance: la elección es por responsabilidad, no por clúster. Elegir un líder por partición, shard o tipo de trabajo escala la coordinación y es como Kafka (un controlador más líderes por partición) y Vitess (primarios por shard) aguantan fallos parciales.

Lo que Funciona

  • Mantén el lease corto y renúevalo bien antes de la expiración: renovaciones a TTL/3 absorben un latido perdido sin disparar conmutación.
  • Emite un fencing token por periodo y verifícalo en cada escritura downstream; sin él, un ex-líder particionado aún puede corromper estado.
  • Renuncia limpiamente al apagarte: resigna el lease o déjalo expirar en lugar de retener a las seguidoras un TTL entero.
  • Observa la clave del lease desde las seguidoras (etcd Watch, watch de K8s, watcher exists de ZooKeeper) en lugar de sondear: obtienes latencia de conmutación sin carga de consultas.
  • Mantén las tareas del líder idempotentes cuando sea posible, de modo que una acción duplicada durante la conmutación sea un reintento y no una corrupción.
  • Registra cada campaña, adquisición y pérdida con el fencing token: el liderazgo oscilante es invisible sin eso.

Errores Comunes

  • Sin verificación de fencing en las escrituras: el fallo clásico — un líder antiguo despierta de una pausa de GC y escribe sobre el trabajo del nuevo. El lease solo no lo evita; solo el token puede.
  • Lease más largo que la caída que temes: un TTL de 60 s significa hasta un minuto de clúster sin cabeza en cada caída del líder.
  • Comparaciones con hora de pared: datetime.utcnow() entre nodos invita al split-brain con deriva de reloj; usa el TTL del almacén o relojes de tiempo transcurrido.
  • Check-then-set no atómico: leer la clave y escribirla en dos llamadas permite que dos candidatas “ganen” a la vez. La elección debe ser un único CAS/transacción.
  • Renovar en el mismo hilo que hace el trabajo: si el trabajo del líder se bloquea (GC largo, E/S síncrona), el lease expira a mitad de mandato. Renueva en su propio planificador.
  • Tratar la elección como consenso: elegir un líder coordina una decisión; no hace que las seguidoras acuerden estado. Si necesitas eso, necesitas Raft o Paxos — la guía de patrones de concurrencia explica cómo se componen.

Soluciones Avanzadas

Elección de líder con la API de transacciones de etcd

El cliente Python etcd3 es síncrono; la primitiva segura es client.transaction — un compare-then-put atómico protegido por un lease, no un check-then-set:

import time
import etcd3

client = etcd3.client(host="localhost", port=2379)
ELECTION_KEY = "/app/leader"
NODE_ID = "node-42"

# El lease muere automáticamente si este nodo deja de refrescarlo.
lease = client.lease(ttl=10)

# Operación atómica única: escribe nuestro ID solo si la clave no existe
# (version == 0). El equivalente al fencing es el mod_revision de la clave.
won = client.transaction(
    compare=[client.transactions.version(ELECTION_KEY) == 0],
    success=[client.transactions.put(ELECTION_KEY, NODE_ID, lease=lease)],
    failure=[],
)

if won:
    try:
        while True:
            lease.refresh()          # mantener el lease vivo
            time.sleep(3)            # renovar bien antes del TTL
    finally:
        lease.revoke()               # renunciar limpiamente al salir
else:
    # Camino de seguidora: observar la clave; cuando se borre o se
    # vuelva a crear, reintentar la transacción de arriba.
    events, cancel = client.watch(ELECTION_KEY)

Para un orden más fuerte (sucesión en cola en lugar de carrera al expirar), etcd expone concurrency.Election, que asigna a cada candidata una clave ordenada por revisión de creación — el equivalente en etcd a los nodos efímeros secuenciales de ZooKeeper.

Elección de líder en Kubernetes con client-go

Dentro de un clúster, usa el recurso Lease y el bucle de actualización de client-go. El campo holderIdentity es el reclamo; renewTime gobierna la conmutación:

package main

import (
	"context"
	"fmt"
	"time"

	coordinationv1 "k8s.io/api/coordination/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/rest"
)

type LeaseLeaderElection struct {
	clientset      *kubernetes.Clientset
	leaseName      string
	leaseNamespace string
	holderIdentity string
	leaseDuration  time.Duration
}

func NewLeaseLeaderElection(leaseName, namespace, holderIdentity string, duration time.Duration) (*LeaseLeaderElection, error) {
	config, err := rest.InClusterConfig()
	if err != nil {
		return nil, err
	}

	clientset, err := kubernetes.NewForConfig(config)
	if err != nil {
		return nil, err
	}

	return &LeaseLeaderElection{
		clientset:      clientset,
		leaseName:      leaseName,
		leaseNamespace: namespace,
		holderIdentity: holderIdentity,
		leaseDuration:  duration,
	}, nil
}

func (l *LeaseLeaderElection) Acquire(ctx context.Context) error {
	lease := &coordinationv1.Lease{
		ObjectMeta: metav1.ObjectMeta{
			Name:      l.leaseName,
			Namespace: l.leaseNamespace,
		},
		Spec: coordinationv1.LeaseSpec{
			HolderIdentity:       &l.holderIdentity,
			LeaseDurationSeconds: pointerToInt32(int32(l.leaseDuration.Seconds())),
			AcquireTime:          &metav1.Time{Time: time.Now()},
			RenewTime:            &metav1.Time{Time: time.Now()},
		},
	}

	for {
		current, err := l.clientset.CoordinationV1().Leases(l.leaseNamespace).Get(ctx, l.leaseName, metav1.GetOptions{})
		if err != nil {
			// El lease no existe, intentar crearlo
			_, err = l.clientset.CoordinationV1().Leases(l.leaseNamespace).Create(ctx, lease, metav1.CreateOptions{})
			if err == nil {
				return nil // Liderazgo adquirido
			}
			time.Sleep(time.Second)
			continue
		}

		// Comprobar si el lease expiró o somos el titular
		if current.Spec.HolderIdentity == nil || *current.Spec.HolderIdentity == l.holderIdentity {
			// Renovar el lease
			current.Spec.HolderIdentity = &l.holderIdentity
			current.Spec.RenewTime = &metav1.Time{Time: time.Now()}
			_, err = l.clientset.CoordinationV1().Leases(l.leaseNamespace).Update(ctx, current, metav1.UpdateOptions{})
			if err == nil {
				return nil // Liderazgo mantenido
			}
		}

		time.Sleep(time.Second)
	}
}

func (l *LeaseLeaderElection) Renew(ctx context.Context) error {
	ticker := time.NewTicker(l.leaseDuration / 2)
	defer ticker.Stop()

	for {
		select {
		case <-ticker.C:
			lease, err := l.clientset.CoordinationV1().Leases(l.leaseNamespace).Get(ctx, l.leaseName, metav1.GetOptions{})
			if err != nil {
				return fmt.Errorf("fallo al obtener el lease: %w", err)
			}

			if lease.Spec.HolderIdentity == nil || *lease.Spec.HolderIdentity != l.holderIdentity {
				return fmt.Errorf("liderazgo perdido")
			}

			lease.Spec.RenewTime = &metav1.Time{Time: time.Now()}
			_, err = l.clientset.CoordinationV1().Leases(l.leaseNamespace).Update(ctx, lease, metav1.UpdateOptions{})
			if err != nil {
				return fmt.Errorf("fallo al renovar el lease: %w", err)
			}

		case <-ctx.Done():
			return nil
		}
	}
}

func pointerToInt32(i int32) *int32 {
	return &i
}

En producción normalmente llamarías a leaderelection.RunOrDie de k8s.io/client-go/tools/leaderelection en lugar de escribir este bucle a mano — el código de arriba muestra lo que ese paquete hace internamente.

Elección basada en Redis con SET NX PX

Redis te da la primitiva atómica directamente. Las dos reglas: adquirir con SET clave token NX PX ttl (un solo comando, atómico) y liberar/renovar solo mediante Lua para que el compare-and-delete no compita con otro líder:

import redis
import time
import uuid

RELEASE_LUA = """
if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("del", KEYS[1])
end
return 0
"""

RENEW_LUA = """
if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("pexpire", KEYS[1], ARGV[2])
end
return 0
"""


class RedisLeaderElection:
    def __init__(self, redis_client, lock_key="leader_lock", ttl_ms=10000):
        self.redis = redis_client
        self.lock_key = lock_key
        self.ttl_ms = ttl_ms
        self.node_id = uuid.uuid4().hex
        self.token = None

    def acquire(self):
        # Un único comando atómico — sin carrera check-then-set.
        self.token = f"{self.node_id}:{int(time.time() * 1000)}"
        return self.redis.set(
            self.lock_key, self.token, nx=True, px=self.ttl_ms
        ) is not None

    def renew(self):
        # Lua: extender solo si aún lo tenemos.
        return self.redis.eval(
            RENEW_LUA, 1, self.lock_key, self.token, self.ttl_ms
        ) == 1

    def release(self):
        # Lua: borrar solo nuestro token — nunca el lease de otro.
        self.redis.eval(RELEASE_LUA, 1, self.lock_key, self.token)

Redis en una sola instancia cubre bien la coordinación blanda. Para garantías bajo conmutación de Redis, Redlock reparte el lease entre N maestros independientes — pero sigue sin poder cercar escrituras, así que acompáñalo de verificación de token dondequiera que el líder escriba estado.

Las versiones ejecutables de estas implementaciones (más una demo de caída y conmutación que no necesita servicios) están en el repositorio complementario.

Preguntas frecuentes

¿Cuál es la diferencia entre elección de líder y bloqueo distribuido?

La elección de líder es un bloqueo especializado mantenido durante un periodo largo que elige a un coordinador; el bloqueo distribuido protege secciones críticas arbitrarias y cortas. La elección añade semántica de mandato, heartbeats y normalmente fencing tokens — el patrón de bloqueo distribuido describe la forma general.

¿Puede cada subsistema tener su propio líder?

Sí — y normalmente debería. Elige un líder por shard, partición o tipo de trabajo: la coordinación sigue simple mientras el trabajo escala. El riesgo es que un fallo correlacionado elija líderes que acaben todos en un mismo nodo.

¿Es la elección de líder suficiente para el consenso?

No. La elección elige un coordinador, pero no replica decisiones a las seguidoras ni garantiza que acuerden. Los algoritmos de consenso como Raft o Paxos incluyen elección de líder y estado replicado; la elección sola es solo el primer tercio de Raft.

¿Qué es un fencing token y por qué lo necesito?

Un número monótono que el almacén emite cada vez que un nuevo líder gana. Los servicios downstream recuerdan el token más alto visto y rechazan escrituras con tokens anteriores, la única forma fiable de impedir que un ex-líder pausado o particionado siga actuando como tal.

¿Cuánto debe durar el lease?

Lo bastante para sobrevivir tu peor pausa de GC o microcorte de red, lo bastante corto para cumplir tu presupuesto de conmutación. 15-30 segundos con renovación a TTL/3 cubre la mayoría de despliegues; baja solo si tu almacén soporta heartbeats de sub-segundo baratos.

¿Qué pasa con el líder antiguo tras perder el lease?

Debería descubrir la pérdida en su siguiente intento de renovación (el CAS falla o la verificación de fencing lo rechaza), dejar de actuar como líder y reincorporarse como seguidor. Si sigue escribiendo, es exactamente el fallo para el que existen los fencing tokens.