Kubernetes The Hard Way en espanol

Kubernetes se entiende mejor cuando deja de ser una caja negra. kind, kubeadm, EKS, AKS y GKE son herramientas excelentes para operar rapido, pero tambien esconden decisiones importantes: certificados, kubeconfigs, etcd, control plane, kubelet, kube-proxy, runtime, CNI, DNS, autorizacion y smoke tests.

Kubernetes The Hard Way va en la direccion contraria. La idea no es tener un cluster listo lo antes posible. La idea es construirlo a mano para entender que hace cada pieza, que identidad necesita, como fluye el trafico y por que el orden de instalacion importa.

El repositorio original es de Kelsey Hightower: kelseyhightower/kubernetes-the-hard-way. Su valor no esta en reemplazar herramientas modernas, sino en formar criterio. Despues de hacerlo a mano, kubeadm, Helm, Terraform, Talos, Argo CD o un cluster gestionado dejan de sentirse magicos: empiezas a reconocer que problema resuelve cada automatizacion.

Que significa "the hard way"

"Hard way" no significa hacerlo dificil por orgullo. Significa quitar capas de abstraccion hasta ver la arquitectura real:

• Una PKI que define identidades.
• Un API server que autentica, autoriza, admite y persiste.
• Un etcd que guarda el estado del cluster.
• Un scheduler que asigna Pods a nodos.
• Un controller-manager que reconcilia estado deseado contra estado real.
• Un kubelet que materializa Pods en cada worker.
• Un runtime CRI, normalmente containerd.
• Un CNI que hace posible la red de Pods.
• Un DNS interno que vuelve usable el cluster.

Ese recorrido sirve para aprender, depurar y endurecer. No es el camino mas comodo para produccion, ni pretende serlo. En produccion normalmente conviene usar herramientas con ciclo de vida, upgrades, validaciones y automatizacion. Pero si alguna vez has visto un nodo NotReady, un Service sin endpoints, un certificado con SAN incorrecto o un etcd sin quorum, este laboratorio te da el mapa mental para no depurar a ciegas.

Referencia base: el repo oficial

Este articulo debe leerse como una guia explicativa en espanol, no como reemplazo del tutorial original. La referencia canonica es el repositorio kelseyhightower/kubernetes-the-hard-way. El propio README lo presenta como un tutorial para aprender a levantar Kubernetes sin automatizacion, tomando la ruta larga para entender cada tarea necesaria.

El repo oficial tambien deja claro el alcance: no es una receta de produccion lista para vender, sino un laboratorio de aprendizaje. La topologia actual usa cuatro maquinas ARM64 o AMD64 conectadas a la misma red: un jumpbox, un servidor/control plane y dos workers.

Versiones y alcance

El repo oficial fija el laboratorio alrededor de estas familias de componentes:

En un hard way conviene fijar explicitamente minor y patch, y mantener control plane, kubelet y kube-proxy dentro de la politica oficial de skew de versiones. Si decides modernizar versiones, documenta el cambio y valida binarios, flags y manifests antes de mezclarlo con el tutorial.

Una base de trabajo alineada al repo se ve asi:

export K8S_VERSION="v1.32.x"
export ETCD_VERSION="v3.6.x"
export CONTAINERD_VERSION="v2.1.x"
export CNI_PLUGINS_VERSION="v1.6.x"

El habito correcto es convertir esos rangos en versiones exactas en un .env, Ansible, Terraform o documentacion operativa. En un cluster montado a mano, depender de latest es una invitacion a errores dificiles de reproducir.

Esta guia asume Linux con systemd, SSH, openssl, curl, jq, kubectl y comodidad editando YAML y units de systemd. No asume una distro concreta, nube publica ni numero fijo de nodos.

Topología recomendada

Antes de tocar comandos, decide qué quieres aprender. El diseño pequeño es suficiente para entender las piezas; el diseño HA sirve cuando quieres practicar quorum, balanceo y fallos reales.

La regla corta: etcd no se escala agregando miembros para “tener más capacidad”. Agregar miembros mejora disponibilidad, pero aumenta latencia y complejidad. Para un laboratorio serio, 3 miembros suele ser el punto de equilibrio.

Inventario base

Declara el entorno antes de instalar nada. Esta claridad evita errores con SANs, kubeconfigs, rutas y rangos superpuestos.

cat > inventory.env <<'EOF'
CLUSTER_NAME="kthw-lab"
CLUSTER_DOMAIN="cluster.local"

API_ENDPOINT_FQDN="k8s-api.lab.local"
API_ENDPOINT_PORT="6443"
API_ENDPOINT="${API_ENDPOINT_FQDN}:${API_ENDPOINT_PORT}"

POD_CIDR="10.200.0.0/16"
SERVICE_CIDR="10.32.0.0/24"
DNS_SERVICE_IP="10.32.0.10"

CP1_NAME="cp1"
CP1_IP="10.0.0.11"

WK1_NAME="wk1"
WK1_IP="10.0.0.21"
WK2_NAME="wk2"
WK2_IP="10.0.0.22"

CP2_NAME="cp2"
CP2_IP="10.0.0.12"
CP3_NAME="cp3"
CP3_IP="10.0.0.13"
EOF

source inventory.env

Los rangos de Nodes, Pods y Services no deben solaparse. En este ejemplo, 10.200.0.0/16 identifica Pods y 10.32.0.0/24 identifica Services. Lo importante no es copiar esos CIDRs exactos, sino mantenerlos separados y usarlos de forma coherente en API server, controller-manager, kube-proxy y CNI.

Orden de trabajo

El orden importa. Esta tabla sigue el mapa oficial del repo y agrega que debes observar en cada laboratorio:

Los workers necesitan un API estable. El API necesita etcd. CoreDNS necesita red. kubelet y kube-proxy necesitan kubeconfigs y certificados. Si te saltas ese orden, los errores empiezan a mezclarse.

PKI: la identidad del cluster

La parte mas importante de un hard way moderno no es el YAML: es la identidad. Kubernetes autentica componentes con certificados cliente, tokens bearer o proxys autenticantes. En este laboratorio, la ruta principal usa certificados.

Principios basicos:

• No uses system:masters para usuarios humanos normales. Ese grupo evita restricciones de autorizacion.
• Para administracion cotidiana, crea un grupo propio y ligalo a cluster-admin con RBAC.
• Para kubelets, respeta el formato CN=system:node:<nodeName> y O=system:nodes.
• El nodeName del certificado debe coincidir con el nombre que registra kubelet.
• El API server debe verificar al kubelet con --kubelet-certificate-authority.

Artefactos minimos:

Genera las CAs y claves de ServiceAccount:

mkdir -p ~/kthw/{pki,kubeconfigs,configs,units}
cd ~/kthw/pki

openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 \
  -subj "/CN=kubernetes-ca" \
  -out ca.crt

openssl genrsa -out etcd-ca.key 4096
openssl req -x509 -new -nodes -key etcd-ca.key -sha256 -days 3650 \
  -subj "/CN=etcd-ca" \
  -out etcd-ca.crt

openssl genrsa -out sa.key 4096
openssl rsa -in sa.key -pubout -out sa.pub

Para un usuario admin, evita system:masters:

openssl genrsa -out admin.key 4096
openssl req -new -key admin.key \
  -subj "/CN=kubernetes-admin/O=kthw:admins" \
  -out admin.csr

Para un kubelet:

NODE_NAME="wk1"

openssl genrsa -out ${NODE_NAME}-kubelet.key 4096
openssl req -new -key ${NODE_NAME}-kubelet.key \
  -subj "/CN=system:node:${NODE_NAME}/O=system:nodes" \
  -out ${NODE_NAME}-kubelet.csr

cat > ${NODE_NAME}-kubelet.ext <<'EOF'
basicConstraints=critical,CA:FALSE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=clientAuth,serverAuth
EOF

openssl x509 -req -in ${NODE_NAME}-kubelet.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out ${NODE_NAME}-kubelet.crt -days 365 -sha256 \
  -extfile ${NODE_NAME}-kubelet.ext

El certificado del API server es el que mas falla en laboratorios. Debe incluir el endpoint real, los nombres internos del Service kubernetes y la primera IP del rango de Services:

cat > apiserver.ext <<EOF
basicConstraints=critical,CA:FALSE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
subjectAltName=@alt_names

[alt_names]
DNS.1=${API_ENDPOINT_FQDN}
DNS.2=kubernetes
DNS.3=kubernetes.default
DNS.4=kubernetes.default.svc
DNS.5=kubernetes.default.svc.${CLUSTER_DOMAIN}
IP.1=${CP1_IP}
IP.2=10.32.0.1
EOF

En HA, agrega el VIP o balanceador y las IPs de cada control plane.

Kubeconfigs

Un kubeconfig contiene endpoints, CAs e identidad. Tratalo como secreto. Para generar kubeconfigs repetibles:

cd ~/kthw

make_kubeconfig() {
  local NAME="$1"
  local USER="$2"
  local CRT="$3"
  local KEY="$4"

  kubectl config set-cluster "${CLUSTER_NAME}" \
    --certificate-authority="${HOME}/kthw/pki/ca.crt" \
    --embed-certs=true \
    --server="https://${API_ENDPOINT}" \
    --kubeconfig="${HOME}/kthw/kubeconfigs/${NAME}.kubeconfig"

  kubectl config set-credentials "${USER}" \
    --client-certificate="${CRT}" \
    --client-key="${KEY}" \
    --embed-certs=true \
    --kubeconfig="${HOME}/kthw/kubeconfigs/${NAME}.kubeconfig"

  kubectl config set-context default \
    --cluster="${CLUSTER_NAME}" \
    --user="${USER}" \
    --kubeconfig="${HOME}/kthw/kubeconfigs/${NAME}.kubeconfig"

  kubectl config use-context default \
    --kubeconfig="${HOME}/kthw/kubeconfigs/${NAME}.kubeconfig"
}

Ejemplos:

make_kubeconfig admin kubernetes-admin \
  ~/kthw/pki/admin.crt \
  ~/kthw/pki/admin.key

make_kubeconfig scheduler system:kube-scheduler \
  ~/kthw/pki/scheduler.crt \
  ~/kthw/pki/scheduler.key

make_kubeconfig kube-proxy system:kube-proxy \
  ~/kthw/pki/kube-proxy.crt \
  ~/kthw/pki/kube-proxy.key

make_kubeconfig wk1 system:node:wk1 \
  ~/kthw/pki/wk1-kubelet.crt \
  ~/kthw/pki/wk1-kubelet.key

RBAC minimo

Un arranque limpio necesita permisos explicitos:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kthw-admins
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: Group
  name: kthw:admins
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: system-kube-proxy
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:node-proxier
subjects:
- kind: User
  name: system:kube-proxy
  apiGroup: rbac.authorization.k8s.io

Ese primer binding da poder administrativo a tu grupo, no a un usuario metido en system:masters. El segundo permite que kube-proxy observe Services y Endpoints para programar reglas de red.

Cifrado en reposo

TLS protege los datos mientras viajan por la red. El cifrado en reposo protege los Secrets antes de persistirlos en etcd. En Kubernetes The Hard Way esta decisión aparece como un archivo de configuración que el API server carga con --encryption-provider-config.

La parte importante no es copiar el YAML de memoria, sino entender el orden de lectura: Kubernetes intenta cifrar con el primer proveedor compatible y deja identity como fallback para objetos ya existentes o para migraciones controladas. En un entorno real también debes pensar en rotación de llaves, respaldo de la llave activa y reescritura de Secrets después de cambiar el proveedor.

Código oficial para leerlo completo: configs/encryption-config.yaml y el laboratorio 06-data-encryption-keys.md.

etcd: la memoria del cluster

etcd es la fuente de verdad persistente. Si etcd se pierde, Kubernetes pierde memoria operacional: Deployments, Secrets, Services, objetos de estado y mucho más.

Cuando leas la unidad oficial de etcd, fíjate en cuatro grupos de decisiones:

• identidad del miembro: nombre del nodo, token de cluster y lista inicial de miembros;
• URLs de cliente y peer: una cosa es cómo habla el API server con etcd y otra cómo se replican los miembros entre sí;
• TLS obligatorio: certificados separados para cliente y peer, con autenticación mutua;
• directorio de datos: /var/lib/etcd es estado crítico, por eso debe tener permisos estrictos y política clara de backup.

Código oficial: units/etcd.service. Para el flujo completo, lee 07-bootstrapping-etcd.md.

La verificación debe confirmar dos cosas distintas: salud del endpoint y estado del miembro. endpoint health responde si etcd puede atender operaciones; endpoint status te enseña liderazgo, versión, base de datos y consistencia general. Si hay más de un miembro, mira quorum antes de tocar el API server.

Control plane

El control plane mínimo tiene tres componentes:

• kube-apiserver: frontal REST, autenticación, autorización, admisión y persistencia.
• kube-controller-manager: control loops que reconcilian estado.
• kube-scheduler: asignación de Pods pendientes a nodos.

El kube-apiserver es la puerta principal. Ahí convergen autenticación, autorización, admisión, conexión a etcd, certificados de kubelet, ServiceAccounts y cifrado en reposo. Al leer su unidad, no memorices cada bandera: agrúpalas por responsabilidad.

Código oficial: units/kube-apiserver.service.

El kube-controller-manager corre los loops de reconciliación. Sus decisiones más importantes son el cluster-cidr para asignación de PodCIDRs, el rango de Services, la CA usada para firmar certificados si habilitas rotación y la llave privada usada por ServiceAccounts. Código oficial: units/kube-controller-manager.service.

El kube-scheduler es más pequeño, pero igual necesita identidad propia. Su archivo de configuración apunta al kubeconfig del scheduler y habilita leader election para que el patrón funcione también cuando tienes más de un control plane. Código oficial: configs/kube-scheduler.yaml y units/kube-scheduler.service.

Si el control plane no queda sano, no sigas con workers. Revisa primero:

journalctl -u etcd -xe --no-pager
journalctl -u kube-apiserver -xe --no-pager
journalctl -u kube-controller-manager -xe --no-pager
journalctl -u kube-scheduler -xe --no-pager

Workers: runtime, kubelet y kube-proxy

Cada worker necesita runtime CRI, kubelet, kube-proxy y CNI. En el repo oficial, containerd aparece como runtime porque es común, directo y encaja bien con Kubernetes moderno.

Lee la configuración de containerd buscando tres ideas: overlayfs como snapshotter, runc como runtime OCI y SystemdCgroup = true para alinear cgroups con kubelet en hosts systemd. Código oficial: configs/containerd-config.toml y units/containerd.service.

El kubelet es el agente del nodo. Su configuración debe desactivar acceso anónimo, usar autorización webhook, apuntar al socket de containerd, registrar el nodo con una identidad coherente y usar el DNS interno del cluster. Código oficial: configs/kubelet-config.yaml y units/kubelet.service.

kube-proxy programa la conectividad de Services en cada nodo. El punto que debes revisar es que su clusterCIDR y su kubeconfig coincidan con el resto del cluster. Código oficial: configs/kube-proxy-config.yaml y units/kube-proxy.service.

CNI: Calico o Flannel

Un cluster sin CNI no está completo. kubelet puede registrar nodos, pero los Pods no tendrán red funcional.

Con Calico:

curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.31.4/manifests/calico.yaml

# Si tu POD_CIDR no coincide con el default del manifest, ajusta CALICO_IPV4POOL_CIDR.
kubectl apply -f calico.yaml

Con Flannel:

curl -LO https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml
sed -i 's#10.244.0.0/16#10.200.0.0/16#g' kube-flannel.yml
kubectl apply -f kube-flannel.yml

El punto didáctico es entender POD_CIDR, SERVICE_CIDR, rutas, encapsulación y políticas. En un hard way histórico se hacían rutas a mano; en un hard way moderno, el CNI suele tomar esa responsabilidad.

DNS con CoreDNS

Kubernetes usa DNS para que los Services sean usables. El Service se llama kube-dns por compatibilidad, aunque el componente recomendado sea CoreDNS.

Si tu SERVICE_CIDR es 10.32.0.0/24, una IP común para DNS es 10.32.0.10. Lo importante es que kubelet use esa misma IP en clusterDNS, que el Service kube-dns apunte a los Pods de CoreDNS y que kube-proxy pueda programar las reglas del Service.

Para el manifiesto completo, usa el ejemplo oficial de Kubernetes: dnsutils.yaml para probar resolución y la documentación de debugging DNS resolution para el flujo de revisión.

Después de aplicar CoreDNS, valida con:

kubectl apply -f https://k8s.io/examples/admin/dns/dnsutils.yaml
kubectl get pod dnsutils
kubectl exec -it dnsutils -- nslookup kubernetes.default

Smoke tests que importan

No basta con ver nodos Ready. Prueba control plane, red, Services, DNS, logs y exec:

export KUBECONFIG=~/kthw/kubeconfigs/admin.kubeconfig

kubectl version
kubectl get nodes -o wide
kubectl get pods -A -o wide
kubectl cluster-info

kubectl create namespace smoke
kubectl -n smoke create deployment nginx --image=registry.k8s.io/nginx:stable
kubectl -n smoke expose deployment nginx --port=80 --target-port=80
kubectl -n smoke get pods,svc -o wide

Si esto funciona, el cluster no solo arrancó: las piezas cooperan.

Backup y restore de etcd

No dejes los backups para "después". etcd documenta snapshots con etcdctl snapshot save y validación con etcdutl snapshot status.

export ETCDCTL_API=3
BACKUP_FILE="/var/backups/etcd-$(date +%F-%H%M%S).db"

etcdctl \
  --endpoints="https://10.0.0.11:2379" \
  --cacert=/etc/etcd/pki/etcd-ca.crt \
  --cert=/etc/etcd/pki/healthcheck-client.crt \
  --key=/etc/etcd/pki/healthcheck-client.key \
  snapshot save "${BACKUP_FILE}"

etcdutl snapshot status "${BACKUP_FILE}" -w table

Para restaurar single-node:

systemctl stop etcd
mv /var/lib/etcd /var/lib/etcd.broken.$(date +%s)

etcdutl snapshot restore /var/backups/etcd-2026-04-25-120000.db \
  --name cp1 \
  --initial-cluster cp1=https://10.0.0.11:2380 \
  --initial-cluster-token etcd-cluster-restore-01 \
  --initial-advertise-peer-urls https://10.0.0.11:2380 \
  --data-dir /var/lib/etcd

chown -R etcd:etcd /var/lib/etcd
systemctl start etcd

En un cluster de 3 miembros, restaura los tres desde el mismo snapshot con nombres, peer URLs y initial-cluster coherentes. No mezcles un miembro restaurado con dos miembros viejos esperando consistencia.

Troubleshooting por plano

La forma correcta de depurar es preguntar que plano se rompio: identidad, persistencia, networking o servicios.

Comandos que conviene memorizar:

journalctl -u etcd -xe --no-pager
journalctl -u kube-apiserver -xe --no-pager
journalctl -u kube-controller-manager -xe --no-pager
journalctl -u kube-scheduler -xe --no-pager
journalctl -u containerd -xe --no-pager
journalctl -u kubelet -xe --no-pager
journalctl -u kube-proxy -xe --no-pager

kubectl get nodes -o wide
kubectl get pods -A -o wide
kubectl describe node wk1
kubectl get events -A --sort-by=.lastTimestamp
kubectl get svc,endpoints,endpointslice -A

Como lo usaria para aprender

Yo lo haria en tres vueltas:

1. Completar la guia sin optimizar nada.
2. Repetirla documentando cada comando con mis propias palabras.
3. Automatizar pequenas partes solo despues de poder explicarlas sin mirar la receta.

Ese orden evita aprender herramientas antes que fundamentos. Kubernetes The Hard Way no compite con la automatizacion. La vuelve mas comprensible.

Checklist final

• Entender que certificado usa cada componente.
• Saber que guarda etcd y como se respalda.
• Poder explicar por que el API server es la frontera del sistema.
• Reconocer que hace scheduler y que hace controller-manager.
• Entender el papel de kubelet, containerd y kube-proxy.
• Instalar un CNI y explicar que problema resuelve.
• Probar DNS, Services, logs, exec y Secrets.
• Depurar fallos separando identidad, persistencia, red y servicios.

El resultado mas valioso no es el cluster. Es la capacidad de diagnosticarlo.

Fuentes y lectura recomendada

• Kubernetes The Hard Way, Kelsey Hightower
• README oficial del repo
• Laboratorios oficiales en docs/
• Plantillas oficiales en configs/
• Units oficiales en units/
• ca.conf oficial
• downloads-amd64.txt
• downloads-arm64.txt
• Kubernetes components
• Kubernetes PKI certificates and requirements
• Kubernetes version skew policy
• etcd disaster recovery