# StatefulSets

Lab de K8s 06 · Laboratorios de Kubernetes · Sistemas Operativos
Page: https://alfonsocampodonico.com/classes/operating-systems/kubernetes-06-statefulsets?lang=es
Code: https://github.com/AlfonsoCampodonico/k8s-labs/tree/main/labs/06-statefulsets (`gh repo clone AlfonsoCampodonico/k8s-labs`)

> Los Deployments tratan a sus pods como intercambiables. Eso es un desastre para bases de datos en clúster, colas o cualquier workload donde el pod web-0 es dueño del shard 0, el pod web-1 del shard 1, y los dos tienen que poder direccionarse entre sí de forma estable.

> **Tiempo estimado:** 5 horas.
> **Requisitos previos:** labs 03 y 05.

Los Deployments tratan a sus pods como intercambiables. Eso es un
desastre para bases de datos en clúster, colas o cualquier workload donde
el pod `web-0` es dueño del shard 0, el pod `web-1` del shard 1, y los
dos tienen que poder direccionarse entre sí de forma estable. Un
**StatefulSet** le da a cada pod:

- Una identidad ordinal (`mysql-0`, `mysql-1`, …).
- Un nombre DNS estable mediante un **Service headless**.
- Un PersistentVolumeClaim propio a partir de un `volumeClaimTemplates`.
- Rollout y borrado ordenados (el pod *n* recién después de que el pod
  *n-1* esté Ready).

## Objetivos de aprendizaje

1. Armar un StatefulSet respaldado por un Service headless y observar los
   registros DNS `pod-N.svc.ns.svc.cluster.local`.
2. Entender `volumeClaimTemplates` y que borrar un StatefulSet **no**
   borra sus PVCs.
3. Usar `podManagementPolicy: Parallel` cuando el orden no hace falta.
4. Hacer un rolling update y observar el rollout ordenado.
5. Escalar un StatefulSet hacia arriba y hacia abajo y razonar sobre el
   ciclo de vida de los datos.

## Contexto

El modelo mental correcto más simple: un StatefulSet es un Deployment que
además materializa un PVC por réplica, mantiene un nombre estable por
ordinal (un `db-1` reemplazado vuelve como `db-1`) y
hace el rollout de a un pod por vez, del ordinal más alto al más bajo.

Un **Service headless** (`clusterIP: None`) asociado al StatefulSet es lo
que habilita el DNS por pod — el servidor DNS devuelve un registro A por
pod (para el nombre del Service) y además publica
`{pod}.{service}.{ns}.svc.cluster.local` para cada pod.

## Recorrido guiado

### 1. Una "base de datos" de tres nodos

```bash
kubectl apply -f manifests/db-headless.yaml
kubectl apply -f manifests/db-sts.yaml
kubectl -n default rollout status statefulset/db --timeout=180s
kubectl get pods -l app=db -o wide
kubectl get pvc -l app=db
```

### 2. Identidad estable por DNS

```bash
kubectl run -it --rm shell --image=busybox:1.36 -- sh
# adentro:
nslookup db                      # headless — devuelve tres registros A
nslookup db-0.db                 # devuelve solo la IP del pod db-0
nslookup db-1.db
```

### 3. Borrá un pod, conservá los datos

```bash
kubectl delete pod db-1
kubectl get pod db-1              # se vuelve a crear con el mismo nombre + el mismo PVC
kubectl exec db-1 -- cat /data/identity
```

### 4. Escalar hacia abajo

```bash
kubectl scale statefulset db --replicas=2
kubectl get pvc -l app=db         # ¡el PVC de db-2 sigue estando!
```

Borrar el StatefulSet con `cascade=orphan` deja atrás los pods y los
PVCs — útil durante migraciones.

## Desafíos

### C1. nginx ordenado

En el namespace `lab-06`, creá:

- un Service headless `web` que apunte a `app=web` en el puerto 80
- un StatefulSet `web` con 3 réplicas de `nginx:1.27-alpine`
  - `serviceName: web`
  - `podManagementPolicy: OrderedReady`
  - `volumeClaimTemplates` que cree PVCs RWO de 500Mi llamados `html`
  - el pod monta el PVC en `/usr/share/nginx/html`
  - un init container que siembre el PVC con un archivo
    `/usr/share/nginx/html/index.html` cuyo contenido sea
    `hello from $(hostname)`

### C2. DNS estable

Desde un pod descartable, `wget -qO- http://web-0.web.lab-06` tiene que
devolver el texto que contiene `web-0`, y lo mismo para `web-1` y `web-2`.

### C3. Escalar hacia abajo sin perder datos

Escalá `web` a 1 réplica y después de vuelta a 3. Tu init container tiene
que sembrar solo si falta `index.html`; el verificador chequea que `web-1`
y `web-2` sigan respondiendo con su propio nombre después de volver a
escalar.

## Verificación

```bash
make verify LAB=06
```

## Para seguir leyendo

- Documentación de Kubernetes: [*StatefulSets*](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/).
- Janet Kuo, [*StatefulSets: deep dive*](https://www.youtube.com/watch?v=pPQKAR1pA9U).
- [*Writing a StatefulSet operator*](https://sdk.operatorframework.io/docs/building-operators/), para cuando los StatefulSets no alcanzan.


## Correrlo

Con Docker, kind y kubectl instalados, corré los targets de `make` desde la
raíz del repositorio; para los comandos del recorrido, que usan rutas
relativas al lab, primero `cd labs/06-statefulsets`:

```sh
./bin/preflight.sh
make cluster
make lab LAB=06
make verify LAB=06
```
