Módulo 1: Why Kubernetes And The Continuity Challenge

1. Introducción a la guía: el orquestador que faltaba

Descripción

Bienvenido a la tercera pieza de cómputo del ecosistema AWS Cloud de NIEVA. Si llegaste hasta aquí, ya completaste aws-core-services-guide (IAM de una cuenta, S3, VPC/EC2 básico, la tabla Shipments de DynamoDB) y aws-serverless-and-containers-guide (el criterio serverless-vs-contenedores, Step Functions, EventBridge, API Gateway, y —lo que más importa para esta guía— construiste con tus propias manos el Dockerfile, la imagen y el registro local de andes-cargo-status-api, un servicio HTTP de solo lectura que consulta el estado de un envío por shipmentId). Esta guía —Kubernetes y EKS en Producción— no repite nada de eso. Tampoco vuelve a explicar Docker desde cero: eso es docker-essentials-guide, un prerequisito transitivo que ya usaste sin saberlo cada vez que corriste docker build.

Lo que sí hace esta guía es resolver una frustración concreta que quedó pendiente al cerrar aws-serverless-and-containers-guide: construiste una imagen de contenedor real, la corriste local con docker run, la publicaste en un registro — y el orquestador que se supone que la iba a mantener corriendo de forma continua, escalada y saludable, nunca llegó a ejecutarse. El clúster ECS andes-cargo-cluster y el servicio status-api-service existen solo como YAML y JSON mostrados, verificados contra la documentación oficial de AWS, porque el plan gratuito de LocalStack no cubre ECS. Esta guía toma exactamente esa imagen, exactamente esos dos nombres, y les da, por primera vez, un orquestador real corriendo en tu máquina: Kubernetes, vía kind (kubernetes-in-docker), sin cuenta de AWS, sin tarjeta de crédito, sin ningún límite de plan de pago.

Conexión con el módulo

Este Módulo 1 tiene cuatro trabajos, en orden: instalar el criterio de por qué Kubernetes cuando ECS ya parecía suficiente (lección 2); resolver, con honestidad completa, el reto de continuidad del caso Andes Cargo — qué se hereda, qué se reutiliza, qué es genuinamente nuevo (lección 3); instalar el laboratorio completo, de verdad, con evidencia ejecutada (lecciones 4, 5 y 7); y entender la arquitectura de lo que acabas de crear antes de construir nada encima (lección 6). La lección 8 —el proyecto de este módulo— te deja con un clúster corriendo, la imagen cargada, y el mapa completo de los siete módulos que siguen.

Lo que esta guía asume que ya sabes (y no vuelve a explicar)

Cuatro guías anteriores del ecosistema te dejaron con el terreno preparado. Esta guía las usa sin re-enseñarlas ni una sola vez:

IAM de una cuenta, S3, VPC/EC2 básico, DynamoDB (aws-core-services-guide) — la tabla Shipments, con partition key shipmentId, ya existe y sigue siendo la fuente de datos que andes-cargo-status-api consulta.
El criterio serverless-vs-contenedores, y el Dockerfile completo de andes-cargo-status-api (aws-serverless-and-containers-guide, Módulo 6) — cinco instrucciones sobre python:3.13-slim, un servicio Flask de dos endpoints (/health y /shipments/<id>). Esta guía no vuelve a escribir ese Dockerfile, lo hereda línea por línea — lo confirmas tú mismo en la lección 7 de este módulo.
El modelo de ECS/Fargate — clusters, task definitions, services, launch types (aws-serverless-and-containers-guide, Módulo 7) — sabes qué es un desiredCount, qué hace un taskRoleArn frente a un executionRoleArn, y por qué un docker run suelto no es lo mismo que un servicio orquestado. Esta guía asume ese vocabulario instalado; lo vas a usar constantemente como punto de comparación con Kubernetes.
Dockerfile, capas, docker build/run, buenas prácticas de imágenes (docker-essentials-guide, transitivo) — si todavía no hiciste esa guía, la lección 7 de este módulo (rebuild de la imagen) se va a leer raro.
El vocabulario de GitOps push-based vs. pull-based (cicd-and-gitops-on-aws-guide, nombrado en su M7.4) — no se profundiza en este módulo, pero el Módulo 5 de esta guía lo retoma directo, sin volver a definir los términos desde cero.

Lo que vas a construir: de una imagen huérfana a una plataforma completa

                    ANDES CARGO — DE "IMAGEN CONSTRUIDA, NUNCA ORQUESTADA"
                    A UNA PLATAFORMA KUBERNETES COMPLETA EN PRODUCCIÓN

  aws-serverless-and-containers-guide te dejó esto:

    andes-cargo-status-api:1.0 (imagen, EJECUTADA)
              │
              │  docker push a registry:2 (EJECUTADO, $0)
              ▼
    localhost:5000/andes-cargo-status-api:1.0
              │
              │  ¿quién la corre de forma continua?
              ▼
    andes-cargo-cluster (ECS) ──── REPRESENTATIVO, nunca ejecutado
    status-api-service (ECS) ──── (LocalStack Hobby no cubre ECS)

  Esta guía lo convierte en esto:

    andes-cargo-status-api (mismo Dockerfile, sin cambios)
              │
              │  kind load docker-image (M1, EJECUTADO)
              ▼
    andes-cargo-cluster (kind — Kubernetes real, EJECUTADO)
              │
    ┌─────────┴──────────────────────────────────────────────────┐
    │  Deployment + Service + ConfigMap/Secret + probes + HPA (M2-M3)│
    │  Ingress + NetworkPolicy (M4)                                    │
    │  ArgoCD sincronizando desde Git (M5)                              │
    │  Gatekeeper + Kyverno + trivy image (M6)                          │
    │  EKS real: lo que cambia (M7, representativo, con honestidad)     │
    └────────────────────────────────────────────────────────────────┘

El nombre andes-cargo-cluster no es casualidad — es el mismo nombre que la guía anterior dejó documentado, nunca corrido. Cuando en la lección 5 de este módulo lo veas aparecer en un kubectl get nodes real, vas a estar viendo el clúster que aws-serverless-and-containers-guide prometió y no pudo entregar.

El mapa completo: los 8 módulos de esta guía

#	Módulo	Qué instala	Pieza de Andes Cargo que construye
1	Por qué Kubernetes y el reto de continuidad	El criterio K8s-vs-ECS, `kind`, `kubectl`, el clúster	`andes-cargo-cluster` corriendo, imagen cargada
2	Pods, Deployments y Services	Las tres primitivas de carga de trabajo	`andes-cargo-status-api` con N réplicas, expuesto por `status-api-service`
3	Configuración, secretos, salud y autoscaling	`ConfigMap`/`Secret`, `probes`, `HorizontalPodAutoscaler`	El mismo Deployment, ahora listo para producción
4	Red, `Ingress` y `NetworkPolicy`	El modelo de red de Kubernetes, `ingress-nginx`	`status-api-service` expuesto por HTTP y protegido
5	GitOps con ArgoCD	Operador pull-based, Gitea, `Application`	Un cambio en Git que se refleja solo, sin `kubectl apply`
6	Seguridad de runtime: admission control y escaneo	OPA Gatekeeper, Kyverno, `trivy image`	Guardrails reales sobre `andes-cargo`
7	Lo específico de EKS	Plano gestionado, node groups, IRSA, ALB Controller	El plan de migración de `kind` a EKS real
8	Capstone: Andes Cargo en Kubernetes	Recorrido end-to-end, un cambio que pasa y uno que el gate detiene	El sistema completo, documentado

El mapa de este módulo: las 8 lecciones

#	Lección	Qué practicas
1	Introducción (esta)	El mapa completo, qué se hereda, qué es nuevo
2	Por qué Kubernetes cuando ECS ya alcanzaba	El criterio de mercado, qué gana y qué cuesta
3	El reto de continuidad: recogiendo `andes-cargo-status-api`	Recap honesto de aws-serverless M6/M7
4	Manos a la obra: instalando `kind` y `kubectl`	Ejecutado: versiones confirmadas en tu máquina
5	Manos a la obra: tu primer clúster	Ejecutado: `andes-cargo-cluster` corriendo
6	Arquitectura de un clúster	`kube-apiserver`, `etcd`, `scheduler`, `kubelet`
7	Manos a la obra: cargando la imagen en el clúster	Ejecutado: la imagen de `status-api` dentro de `kind`
8	Proyecto: el clúster de Andes Cargo, listo	Ejecutado: checklist final + roadmap del resto de la guía

Qué va a existir al final de esta guía: el capstone (adelanto)

El Módulo 8, el capstone completo, es a donde apunta cada pieza que construyes desde este primer módulo. Vale la pena verlo ahora, aunque falten siete módulos, porque cambia cómo lees todo lo que sigue: al final, andes-cargo-status-api va a estar corriendo dentro de andes-cargo-cluster, con un repositorio Git (andes-cargo-k8s/) como única fuente de verdad que un operador (ArgoCD) sincroniza solo, sin que nadie corra kubectl apply a mano; cada objeto que intente entrar al clúster va a pasar primero por un admission controller que puede rechazarlo antes de que exista; y la imagen que ese Deployment corre va a estar escaneada por Trivy. Un cambio inocuo —una etiqueta nueva— va a cruzar todo ese camino sin fricción; un cambio que viola una política de seguridad va a ser rechazado, con el mensaje de error real, antes de tocar un solo Pod.

Esa es la diferencia de fondo entre lo que dejó aws-serverless-and-containers-guide (una imagen construida, un orquestador solo documentado) y lo que entrega esta guía: el mismo componente, ahora con un sistema completo de producción alrededor.

Lo que esta guía NO enseña (y dónde sí)

Para que sepas desde ya la frontera: esta guía construye Kubernetes de punta a punta, pero no es donde termina el camino de todo lo que toca de refilón.

Terraform/IaC en sí (HCL, módulos, state) → terraform-and-iac-guide. El único YAML de infraestructura que aparece aquí es el necesario para lo que esta guía enseña (manifiestos Kubernetes, un kind-config.yaml), nunca un recurso de negocio nuevo declarado en Terraform.
CI/CD push-based sobre AWS (pipelines de GitHub Actions, plan/apply automatizado) → cicd-and-gitops-on-aws-guide, prerequisito. Esta guía es el otro polo del mismo principio GitOps: pull, no push.
Seguridad de infraestructura y cadena de suministro de IaC (OIDC de punta a punta contra AWS real, SBOM, firma con cosign, escaneo de HCL) → cloud-security-and-guardrails-guide. Esta guía construye el admission control en clúster y el escaneo de imagen de contenedor que esa guía delegó — dos capas distintas.
FinOps de Kubernetes (costo por Pod, right-sizing de nodos, Spot) → finops-and-cost-guardrails-guide. Un guardrail de esta guía nunca es "esto es caro" — es "esto viola una política".
SRE e incident response (SLI/SLO, on-call, postmortem) → sre-and-incident-response-guide (no diseñada aún). Se construye el sistema que previene el incidente, no la disciplina de responder cuando falla igual.
GenAI sobre EKS (GPU en nodos, inferencia) → genai-on-aws-production-guide (no diseñada aún).
Observabilidad de clúster a fondo (Prometheus, Grafana) → monitoring-observability-guide. Esta guía usa kubectl logs/describe/top como herramienta mínima de depuración, no como tema aparte.
Docker desde cero → docker-essentials-guide, prerequisito.

La analogía que va a acompañarte toda esta guía: el director de orquesta

Vas a desarrollar esto a fondo en la lección 2, pero vale la pena que lo tengas presente desde ya: un orquestador de contenedores es, literalmente, un director de orquesta. Cada músico (contenedor) sabe tocar su instrumento, pero sin alguien que marque el tempo, decida cuándo entra cada sección, y reaccione en tiempo real si un violinista se desconcentra, la "orquesta" —tu sistema— se desarma en cualquier momento imprevisto. docker run a mano es un músico solo, tocando sin nadie que lo escuche ni lo corrija. ECS es un director capaz de dirigir un cuarteto — suficiente para una sala pequeña, con un repertorio limitado de instrumentos disponibles. Kubernetes es un director capaz de dirigir una orquesta sinfónica completa —decenas de músicos, secciones enteras, instrumentos que otros compositores (la comunidad) siguen agregando— pero ese poder viene con una contrapartida real: dirigir una sinfónica exige mucha más preparación que dirigir un cuarteto. Esa contrapartida, con nombre y evidencia, es exactamente el tema de la lección 2.

Errores comunes

Asumir que esta guía va a repasar Docker, IAM, ECS o el criterio serverless-vs-contenedores antes de avanzar (de expectativa). Qué pasa: alguien llega de aws-serverless-and-containers-guide esperando un repaso de esos temas antes de tocar Kubernetes, y se sorprende cuando la lección 2 salta directo a comparar Kubernetes contra un modelo de ECS que da por conocido. Por qué pasa: es el patrón natural de cualquier guía escalonada — pero esta, deliberadamente, no lo sigue: aws-serverless-and-containers-guide Módulo 7 ya cubrió ECS/Fargate a fondo, y repetirlo aquí sería el mismo contenido dos veces. Cómo detectarlo: si en algún punto de este módulo te preguntas "¿y qué era un taskRoleArn?", no es que esta guía lo dé por saltado por accidente — es una decisión de diseño explícita. Cómo corregirlo: vuelve a aws-serverless-and-containers-guide, Módulo 7, puntualmente para ese concepto específico; no esperes que esta guía te lo repita en el camino.

Confundir "esta guía usa el mismo caso" con "esta guía reconstruye el mismo trabajo" (conceptual, el error central que la lección 3 corrige de raíz). Qué pasa: alguien asume que va a reescribir el Dockerfile de andes-cargo-status-api, o a inventar un componente nuevo para tener "algo propio" en esta guía. Por qué pasa: es intuitivo pensar que una guía nueva necesita construir algo desde cero para justificar su existencia. Cómo detectarlo: si en la lección 7 de este módulo te encuentras editando app.py o el Dockerfile en vez de solo reconstruir la imagen tal cual está. Cómo corregirlo: la decisión de diseño de esta guía, explicada a fondo en la lección 3, es exactamente la opuesta — reutilizar la imagen sin tocarla es el punto, no un atajo. Cualquier cambio de comportamiento del servicio se hace, desde el Módulo 3 en adelante, vía ConfigMap/Secret, nunca reconstruyendo la imagen.

Saltarse la lección 4 (instalación) porque "ya tengo kind o kubectl instalados de otro proyecto" (de flujo). Qué pasa: alguien con experiencia previa en Kubernetes asume que su instalación existente ya sirve, sin confirmar la versión, y llega a la lección 5 con un kind desactualizado que se comporta distinto a lo que la guía describe. Por qué pasa: kind/kubectl son herramientas comunes, y es fácil asumir que "instalado" es suficiente sin verificar la versión exacta. Cómo detectarlo: si tu kind version reporta algo anterior a v0.32.0 o tu kubectl version --client reporta algo muy distinto a v1.36.1. Cómo corregirlo: corre igual los dos comandos de verificación de la lección 4 — toma 10 segundos, y evita que una versión vieja te dé un comportamiento distinto al que documenta esta guía sin que sepas por qué.

Ejercicios

Ejercicio 1 — Traza la frontera de continuidad. Sin mirar de nuevo la sección "Lo que esta guía asume que ya sabes", escribe de memoria las cuatro guías (o partes de guías) que esta guía hereda sin repetir, y para cada una, la pieza concreta de Andes Cargo que retoma.

Ver solución

aws-core-services-guide → la tabla Shipments de DynamoDB, que andes-cargo-status-api sigue consultando sin ningún cambio.
aws-serverless-and-containers-guide, Módulo 6 → el Dockerfile exacto de andes-cargo-status-api, reutilizado sin reescribir ni una línea.
aws-serverless-and-containers-guide, Módulo 7 → los nombres andes-cargo-cluster y status-api-service, reutilizados a propósito como el hilo narrativo de esta guía — el clúster que solo existió en YAML ahora existe de verdad.
docker-essentials-guide (transitivo) → el vocabulario de capas y docker build/run, que la lección 7 de este módulo usa sin volver a explicarlo.

Si tu respuesta reconoció que nada se reescribe, todo se reutiliza, entendiste el espíritu de esta guía.

Ejercicio 2 — Predicción: qué va a cambiar y qué no. Con el diagrama de "Lo que vas a construir" de esta lección, predice: ¿el nombre andes-cargo-status-api (la imagen) va a cambiar en algún módulo de esta guía? ¿Y el nombre andes-cargo-cluster? Justifica cada respuesta en una frase.

Ver solución

Ninguno de los dos cambia. La imagen andes-cargo-status-api se reconstruye tal cual en la lección 7 de este módulo (mismo Dockerfile, sin cambios) y nunca se vuelve a tocar salvo que un módulo específico lo pida de forma explícita (regla dura de esta guía: cualquier cambio de comportamiento va vía ConfigMap/Secret, no reconstruyendo la imagen). El nombre andes-cargo-cluster tampoco cambia — es, literalmente, el mismo nombre que aws-serverless-and-containers-guide usó para el clúster ECS documentado-nunca-ejecutado; esta guía lo retoma a propósito para que quede claro que es el mismo clúster prometido, ahora corriendo de verdad.

Ejercicio 3 — Explica la continuidad a un colega. Un colega que hizo aws-serverless-and-containers-guide pero no esta guía te pregunta: "¿por qué el clúster de Kubernetes se llama igual que el clúster de ECS que nunca llegamos a correr?". Respóndele en dos o tres frases.

Ver solución

Una respuesta completa suena, más o menos, así: "No es casualidad ni un error — es intencional. aws-serverless-and-containers-guide diseñó un clúster ECS llamado andes-cargo-cluster con un servicio status-api-service, pero el plan gratuito de LocalStack no incluye ECS, así que ese clúster nunca corrió de verdad, solo quedó documentado. Esta guía retoma exactamente esos dos nombres para el clúster de Kubernetes que sí corre en tu máquina — es la misma promesa de infraestructura, cumplida con otro orquestador."

Resumen y siguiente paso

En esta lección conociste el mapa completo de la tercera guía de cómputo del ecosistema AWS Cloud de NIEVA: ocho módulos que van del criterio de diseño (aquí) a las primitivas de Kubernetes, configuración y autoscaling, red, GitOps con ArgoCD, seguridad de runtime, y lo específico de EKS. Confirmaste qué hereda esta guía sin repetirlo —IAM/S3/VPC/DynamoDB, el Dockerfile de andes-cargo-status-api, el modelo de ECS/Fargate, Docker básico— y recibiste el primer adelanto de la analogía central de la guía: un orquestador de contenedores es un director de orquesta, y la diferencia entre ECS y Kubernetes es la diferencia entre dirigir un cuarteto y dirigir una sinfónica completa.

Antes de avanzar deberías poder: nombrar los ocho módulos de esta guía y qué pieza de Andes Cargo construye cada uno; explicar por qué el nombre andes-cargo-cluster se reutiliza a propósito; y describir, con tus propias palabras, la diferencia entre "reutilizar" y "reconstruir" el caso de Andes Cargo.

La lección 2 formaliza la analogía del director de orquesta con el criterio real de mercado: cuándo Kubernetes le gana a ECS, y qué cuesta esa ganancia.

Recursos

aws-core-services-guide (NIEVA) — la primera guía del ecosistema, prerequisito completo de esta.
aws-serverless-and-containers-guide (NIEVA), Módulos 6 y 7 — el origen exacto de andes-cargo-status-api, andes-cargo-cluster y status-api-service que esta guía retoma.
docker-essentials-guide (NIEVA) — prerequisito transitivo, Dockerfile y capas desde cero.
Kubernetes — What is Kubernetes? — la definición oficial del proyecto, punto de partida de la lección 2.
kind — Quick Start — la documentación oficial de la herramienta que instalas en la lección 4 de este módulo.

Siguiente →2. Por qué Kubernetes cuando ECS ya alcanzaba