Módulo 1: Why Kubernetes And The Continuity Challenge

8. Proyecto: el clúster de Andes Cargo, listo

Descripción

Este proyecto no agrega ningún concepto nuevo — reutiliza, en un solo recorrido de verificación, todo lo que construiste en las lecciones 4, 5 y 7: las herramientas instaladas, el clúster andes-cargo-cluster corriendo, y la imagen andes-cargo-status-api disponible dentro de él. La diferencia con las lecciones anteriores es la disciplina: en vez de verificar cada pieza por separado, a medida que la construías, este proyecto la audita completa, de punta a punta, con un checklist explícito. Al terminar, tienes exactamente lo que el Módulo 2 necesita para empezar: un clúster real, con la imagen correcta ya adentro, listo para correr un Pod de verdad.

Conexión con el módulo

Cada lección de este módulo construyó una pieza: el criterio de mercado (lección 2), el reto de continuidad resuelto (lección 3), las herramientas instaladas (lección 4), el clúster creado (lección 5), su arquitectura entendida (lección 6), y la imagen cargada (lección 7). Este proyecto es la primera vez que ves las tres piezas ejecutables confirmadas en un solo recorrido, justo antes de que el Módulo 2 tome este mismo clúster y despliegue en él la primera carga de trabajo real.

El checklist final: tres verificaciones, un laboratorio completo

Verificación 1 — Las herramientas, con la versión correcta

kind version
kubectl version --client

Qué esperar (v0.32.0 es la versión mínima que esta guía verificó — la tuya puede ser igual o más reciente; go1.26.3 darwin/arm64 es tu plataforma específica, variable; v1.36.1 es la versión de kubectl que corresponde a la versión de Kubernetes que corre kind v0.32.0 por defecto):

kind v0.32.0 go1.26.3 darwin/arm64
Client Version: v1.36.1
Kustomize Version: v5.8.1

Si cualquiera de las dos versiones sale muy por debajo de lo esperado, vuelve a la lección 4 antes de seguir — el resto de este checklist asume que ambas herramientas están al día.

Verificación 2 — El clúster existe, y sus tres nodos están sanos

kind get clusters

Qué esperar:

andes-cargo-cluster

kubectl get nodes

Qué esperar (AGE es tu valor variable — depende de cuánto tiempo lleva corriendo tu clúster; el resto es literal para esta arquitectura de tres nodos):

NAME                                STATUS   ROLES           AGE     VERSION
andes-cargo-cluster-control-plane   Ready    control-plane   5m41s   v1.36.1
andes-cargo-cluster-worker          Ready    <none>          5m26s   v1.36.1
andes-cargo-cluster-worker2         Ready    <none>          5m26s   v1.36.1

Tres nodos, los tres en Ready. Si alguno muestra NotReady y ya pasó más de un minuto desde que creaste el clúster, revisa docker ps para confirmar que los tres contenedores del nodo siguen corriendo antes de continuar.

Verificación 3 — La imagen está disponible, en los tres nodos

for node in andes-cargo-cluster-control-plane andes-cargo-cluster-worker andes-cargo-cluster-worker2; do
  echo "--- $node ---"
  docker exec "$node" crictl images | grep andes-cargo-status-api
done

Qué esperar (IMAGE ID truncado es tu valor variable, generado a partir del contenido exacto de tu build; idéntico en los tres nodos porque es la misma imagen cargada tres veces):

--- andes-cargo-cluster-control-plane ---
docker.io/library/andes-cargo-status-api        latest               d07c069076658       186MB
--- andes-cargo-cluster-worker ---
docker.io/library/andes-cargo-status-api        latest               d07c069076658       186MB
--- andes-cargo-cluster-worker2 ---
docker.io/library/andes-cargo-status-api        latest               d07c069076658       186MB

Si algún nodo no muestra la imagen, vuelve a la lección 7 y repite kind load docker-image andes-cargo-status-api:latest --name andes-cargo-cluster — no cuesta nada volver a correrlo, y kind simplemente confirma que la imagen ya está presente en los nodos que la tengan.

El diagrama de cierre: qué existe hoy, y qué falta

              ANDES CARGO — EL LABORATORIO COMPLETO, LISTO PARA EL MÓDULO 2

  ┌──────────────────────────────────────────────────────────────────────┐
  │  andes-cargo-cluster (kind v0.32.0, Kubernetes v1.36.1)                   │
  │                                                                          │
  │  ┌────────────────────────────────────────────────────────────────┐ │
  │  │  NODO: andes-cargo-cluster-control-plane                            │ │
  │  │    kube-apiserver · etcd · kube-scheduler · kube-controller-manager │ │
  │  │    kubelet · kube-proxy                                             │ │
  │  │    imagen andes-cargo-status-api:latest ── CARGADA (lección 7)        │ │
  │  └────────────────────────────────────────────────────────────────┘ │
  │                                                                          │
  │  ┌──────────────────────────┐  ┌──────────────────────────┐        │
  │  │  NODO: ...-worker            │  │  NODO: ...-worker2          │        │
  │  │    kubelet · kube-proxy        │  │    kubelet · kube-proxy        │        │
  │  │    imagen CARGADA               │  │    imagen CARGADA               │        │
  │  └──────────────────────────┘  └──────────────────────────┘        │
  └──────────────────────────────────────────────────────────────────────┘

  Lo que existe hoy: un clúster de Kubernetes real, sano, con la imagen
  heredada de aws-serverless-and-containers-guide disponible en los tres
  nodos — sin cuenta de AWS, sin ningún límite de plan de pago.

  Lo que falta: ningún Pod está corriendo todavía. La imagen está
  disponible, pero nadie le pidió al clúster que la ejecute.

El mapa del resto de la guía, sobre este mismo diagrama

  M2  Pods, Deployments, Services       ── el primer Pod real, con réplicas
                    │                       y un Service que lo expone dentro
                    ▼                       del clúster
  M3  Configuración, salud, autoscaling ── ConfigMap/Secret externalizados,
                    │                       probes, HorizontalPodAutoscaler
                    ▼
  M4  Red, Ingress, NetworkPolicy       ── el servicio, expuesto por HTTP
                    │                       real, y protegido con deny-by-default
                    ▼
  M5  GitOps con ArgoCD                 ── un cambio en Git, reflejado solo,
                    │                       sin kubectl apply manual
                    ▼
  M6  Admission control, escaneo         ── Gatekeeper + Kyverno + trivy image,
                    │                       el portero antes de etcd
                    ▼
  M7  Lo específico de EKS               ── qué cambia con un plano de control
                    │                       gestionado real (representativo)
                    ▼
  M8  Capstone                          ── el sistema completo, un cambio que
                                            pasa y uno que el gate detiene

Cada módulo de esta lista construye directamente sobre el clúster que acabas de confirmar sano en este proyecto — ninguno empieza de cero, ninguno requiere que vuelvas a este módulo salvo que algo se rompa.

Qué llevar al Módulo 2

Tres piezas concretas, ninguna hipotética, todas confirmadas por este proyecto:

El clúster andes-cargo-cluster, con un plano de control y dos nodos de trabajo, corriendo Kubernetes v1.36.1 de verdad — no una versión reducida, no un simulador.
La imagen andes-cargo-status-api:latest, disponible en el containerd interno de los tres nodos, lista para que cualquier manifiesto la referencie sin depender de ningún registro externo.
El contexto activo de kubectl (kind-andes-cargo-cluster), ya configurado, sin necesidad de ninguna bandera adicional para hablar con este clúster desde el Módulo 2 en adelante.

Errores comunes

Dar por cerrado el módulo sin correr las tres verificaciones, porque "ya vi que cada pieza funcionaba en su lección" (de flujo, el más fácil de saltarse). Qué pasa: alguien confirma mentalmente que cada lección salió bien en su momento, y asume que el proyecto es solo un resumen, sin correr los comandos reales de este checklist. Por qué pasa: cada verificación individual ya se sintió "hecha" cuando se ejecutó por primera vez, en su propia lección. Cómo detectarlo: si no puedes pegar, ahora mismo, la salida real de las tres verificaciones de este proyecto. Cómo corregirlo: el propósito de este checklist no es repetir lo obvio — es confirmar que el estado actual de tu laboratorio (no el de hace unas horas, cuando quizás cerraste la terminal o reiniciaste tu máquina) sigue siendo el esperado. Es la misma disciplina que ya viste en el proyecto del Módulo 6 de aws-serverless-and-containers-guide.

Apagar Docker Desktop (o detener el servicio docker) entre este módulo y el siguiente, sin darse cuenta de que eso apaga también el clúster (operativo, con consecuencias reales al retomar la guía). Qué pasa: alguien cierra su máquina o Docker Desktop al terminar este módulo, y al retomar la guía para el Módulo 2, kubectl get nodes falla con un error de conexión, como si el clúster hubiera desaparecido. Por qué pasa: cada nodo de andes-cargo-cluster es un contenedor Docker (lección 6) — si Docker se detiene, los tres contenedores se detienen con él. Cómo detectarlo: docker ps -a --filter "name=andes-cargo-cluster" muestra los tres contenedores en estado Exited, no Up. Cómo corregirlo: a diferencia de LocalStack en las guías anteriores (donde perder el contenedor significaba perder todo el estado), los contenedores de kind sobreviven un reinicio de Docker si no se eliminaron explícitamente — basta con arrancar Docker Desktop de nuevo, y los tres contenedores (y el clúster completo) vuelven a estar disponibles, sin necesidad de kind create cluster otra vez. Confírmalo con kind get clusters.

Asumir que "el clúster está listo" significa "el servicio de Andes Cargo ya está corriendo" (conceptual, el error que el diagrama de esta lección corrige de forma explícita). Qué pasa: alguien, después de completar este proyecto con las tres verificaciones en verde, espera poder hacer curl contra andes-cargo-status-api de alguna forma, y se sorprende de que no hay ningún puerto ni ninguna dirección a la cual conectarse todavía. Por qué pasa: "la imagen está cargada" suena, por el nombre, a "el servicio está corriendo". Cómo detectarlo: si intentas correr kubectl get pods esperando ver algo relacionado con andes-cargo-status-api, y el resultado viene vacío (fuera del namespace kube-system). Cómo corregirlo: revisa el diagrama de cierre de esta lección — "cargada" significa que la imagen está disponible para que un Pod la use, no que algún Pod ya la esté usando. Nadie le pidió todavía al clúster que ejecute nada con esa imagen; eso es, exactamente, lo que arranca el Módulo 2.

Ejercicios

Ejercicio 1 — Reconstruye el checklist de memoria. Sin volver a la sección "El checklist final", escribe los tres comandos (o grupos de comandos) que verificarían, contra cualquier laboratorio con estas mismas características, cada una de las tres piezas que este proyecto confirmó.

Ver solución

kind version y kubectl version --client — confirman que las herramientas están instaladas, con la versión esperada.
kind get clusters y kubectl get nodes — confirman que el clúster existe y que sus nodos están en estado Ready.
docker exec <nombre-del-nodo> crictl images | grep <nombre-de-la-imagen>, repetido en cada nodo — confirma que la imagen está disponible dentro del containerd interno de cada uno, no solo en el Docker del host.

Si reconstruiste los tres sin mirar, tienes internalizado el patrón completo de auditoría de un laboratorio de Kubernetes listo para producción de carga de trabajo.

Ejercicio 2 — Explica por qué el clúster sobrevive un reinicio de Docker, pero LocalStack (guías anteriores) no. Con lo que sabes de esta lección y de las guías anteriores del ecosistema, explica en dos o tres frases la diferencia de fondo.

Ver solución

La diferencia no está en Docker —el mismo motor de contenedores en ambos casos— sino en qué contenedor se detiene y qué contenía. Un contenedor de Docker detenido (docker stop, o el propio Docker Desktop cerrándose) conserva su sistema de archivos interno hasta que alguien lo elimina explícitamente (docker rm); al volver a arrancarlo, todo lo que había adentro sigue ahí, incluido el estado de etcd del clúster. LocalStack, en las guías anteriores, perdía su estado con un simple reinicio porque, sin el flag PERSISTENCE=1 (una configuración explícita que esas guías nunca activaron por defecto), el contenedor guardaba todo en memoria, no en disco — un reinicio del contenedor, no solo de Docker, ya bastaba para perderlo todo. El clúster de kind, en cambio, si el contenedor nunca se elimina, conserva su estado en el sistema de archivos interno del propio contenedor.

Ejercicio 3 — Diseña tu propia verificación de "clúster listo" para un caso nuevo. Imagina que, en vez de una sola imagen, necesitaras verificar que dos imágenes distintas están disponibles en un clúster de kind de cuatro nodos. Describe, sin ejecutarlo, cómo adaptarías el patrón de la Verificación 3 de este proyecto a ese caso.

Ver solución

El patrón se extiende de forma directa: en vez de un solo grep por nodo, correrías el mismo bucle for sobre los cuatro nombres de nodo, y dentro de cada iteración, correrías crictl images una vez y usarías grep -E "imagen-uno|imagen-dos" (o dos líneas de grep separadas) para confirmar ambas imágenes en la misma pasada. La estructura de fondo no cambia: por cada nodo, confirmas explícitamente qué imágenes tiene su containerd interno — nunca asumes que, porque una imagen está en un nodo, las demás también lo están, ni que porque está en un nodo, está en todos.

Resumen y siguiente paso

En este proyecto verificaste, con tres comandos de auditoría, que el laboratorio completo de este módulo está sano: kind v0.32.0 y kubectl v1.36.1 instalados y confirmados; el clúster andes-cargo-cluster corriendo, con sus tres nodos en Ready; y la imagen andes-cargo-status-api:latest disponible en el containerd interno de los tres nodos. El diagrama de cierre te dejó el estado exacto de hoy —un clúster sano, sin ningún Pod corriendo todavía— y el mapa completo de los siete módulos que quedan, cada uno construyendo directamente sobre este mismo clúster.

Antes de avanzar deberías poder: ejecutar el checklist completo de memoria; explicar por qué el clúster de kind sobrevive un reinicio de Docker; y describir, con el diagrama de esta lección, la diferencia exacta entre "la imagen está cargada" y "el servicio está corriendo".

Siguiente módulo: Pods, Deployments y Services. El Módulo 2 toma exactamente este clúster —sano, con la imagen ya disponible— y crea el primer Pod real de esta guía: andes-cargo-status-api, corriendo de verdad dentro de Kubernetes, con réplicas administradas por un Deployment y expuesto por un Service con el mismo nombre, status-api-service, que la guía anterior dejó documentado y nunca corrió. Con la misma profundidad que la arquitectura del clúster tuvo en este módulo.

Recursos

aws-serverless-and-containers-guide (NIEVA), Módulo 7, lecciones 4 y 8 — el clúster ECS y el servicio status-api-service documentados-nunca-ejecutados que este módulo empieza a reemplazar con un orquestador real.
Kubernetes — Workloads — la puerta de entrada oficial al Módulo 2: Pods, Deployments, y el resto de las primitivas de carga de trabajo.
kind — User Guide — referencia completa de kind, útil como consulta general durante el resto de esta guía.
Kubernetes — kubectl Reference Docs — referencia oficial completa de comandos, la herramienta que vas a usar en cada lección "manos a la obra" del resto de la guía.

← Anterior7. Manos a la obra: cargando la imagen de `andes-cargo-status-api` en el clúster Siguiente →1. Introducción: de un contenedor a una carga de trabajo administrada