TP 0 — Prerrequisitos

Instalación de k3s y primeros pasos con Kubernetes

Requisito obligatorio para entregar la Parte 2 del TP 1 (entrega 02/05/2026)

Esta guía es prerrequisito obligatorio de la Parte 2 del TP 1. Sin haber completado el TP 0 (cluster k3s/k3d funcional + checklist de validación al final), no se acepta la entrega del Hit #7.

¿Por qué Kubernetes y por qué k3s?

Kubernetes (k8s) es el orquestador de contenedores estándar de la industria. Te permite declarar “quiero que esto corra cada hora”, “esto necesita 2 réplicas”, “este job tiene que reintentarse hasta 3 veces si falla”, y el cluster se encarga.

k3s es una distribución liviana de Kubernetes (~70 MB de binario) creada por Rancher y donada al CNCF. Es Kubernetes real (certificado), no una versión recortada. Lo eligieron porque es lo más simple de levantar localmente sin depender de snap (microk8s) ni de máquinas virtuales (minikube).

Para este TP vamos a usar k3s en dos sabores según el sistema operativo:

Los manifiestos YAML son idénticos entre ambos. Solo cambia cómo levantás el cluster y cómo cargás imágenes Docker.

Aviso importante: cómo va a vivir este cluster en tu máquina

Lo que vamos a montar acá es la forma más simple posible de tener Kubernetes corriendo. Es perfecto para aprender, pero tiene implicaciones que conviene entender antes de empezar:

• Tu máquina cumple los dos roles a la vez:

  • Control plane — el cerebro del cluster: API server, scheduler, controllers, etcd. Es el que recibe tus kubectl apply, decide dónde corre cada pod, y mantiene el “estado deseado” del sistema.
  • Worker node — donde efectivamente corren los containers de tus pods.

  En un cluster de producción estos roles están separados en máquinas distintas, con varios nodos cada uno, para tener tolerancia a fallos y poder escalar. Acá los junta uno solo: tu laptop.

• El cluster se muere si apagás la máquina. k3s queda registrado como servicio systemd y arranca solo al boot, pero si suspendés el equipo, hibernás, o reiniciás bruscamente, los pods se pierden hasta que vuelva el servicio. Los Jobs/CronJobs se reanudan recién cuando el cluster vuelva a estar arriba. Esto NO es una limitación de Kubernetes — es la limitación de correrlo sobre un solo nodo, en tu máquina, sin alta disponibilidad.

• No es producción, pero es Kubernetes real. Los manifiestos que vas a escribir (Deployment, Service, Job, CronJob, ConfigMap, PVC) son idénticos a los que usarías en GKE / EKS / AKS o en un k3s multi-nodo desplegado en VPSs. La única diferencia es que en producción ese mismo kubectl apply -f lo recibe un cluster distribuido y replicado, en lugar de tu notebook.

Por qué este TP exige esto y no un docker-compose

El objetivo no es “que el scraper corra en algún lado”. Es que empiecen a pensar en términos de Kubernetes, que es donde la industria está parada hoy. Eso significa entender la diferencia entre:

Cuando en el Hit #7 conviertan el docker run de la Infra base en un Job + CronJob + ConfigMap + PVC, ese ejercicio mental es el verdadero aprendizaje del TP — más que los YAMLs en sí. Pasar de “tengo un Dockerfile y un compose” a “tengo manifiestos declarativos que cualquier cluster Kubernetes puede ejecutar” es el salto profesional que se les pide.

Requisitos previos

• Tener Docker instalado y funcionando (lo necesitan para la Infra base igual).
  • Verificá con: docker version y docker ps.
• Tener kubectl instalado (CLI oficial de Kubernetes).
  • macOS: brew install kubectl
  • Linux: curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && chmod +x kubectl && sudo mv kubectl /usr/local/bin/
  • Windows: choco install kubernetes-cli o scoop install kubectl
  • Verificá: kubectl version --client
• 4 GB de RAM libres. 2 GB de disco libres.

Camino A — Linux nativo o WSL2 (instalación de k3s)

Paso 1: Instalar k3s

curl -sfL https://get.k3s.io | sh -

Esto te baja el binario, lo deja en /usr/local/bin/k3s, lo registra como servicio systemd, y lo arranca. Duración: ~30 segundos.

Paso 2: Verificar que el cluster está vivo

sudo k3s kubectl get nodes

Tenés que ver algo así:

NAME            STATUS   ROLES                  AGE   VERSION
mi-laptop       Ready    control-plane,master   12s   v1.32.x+k3s1

Paso 3: Configurar kubectl para no necesitar sudo

k3s deja el kubeconfig en /etc/rancher/k3s/k3s.yaml con permisos restrictivos. Para usar kubectl sin sudo:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
chmod 600 ~/.kube/config

Verificá:

kubectl get nodes

Si te devuelve el nodo sin pedir sudo, ya está.

Paso 4: Cómo cargar una imagen Docker en k3s

k3s no usa Docker como runtime — usa containerd. Por eso, una imagen que construiste con docker build no la “ve” k3s automáticamente. Hay que importarla:

docker save mi-imagen:latest -o mi-imagen.tar
sudo k3s ctr images import mi-imagen.tar
rm mi-imagen.tar

Para verificar que la imagen está cargada:

sudo k3s ctr images list | grep mi-imagen

Paso 5: Tirar abajo k3s cuando termines el TP

sudo /usr/local/bin/k3s-uninstall.sh

Limpia todo: binario, servicio systemd, datos del cluster, redes. Limpio.

Camino B — macOS o Windows (k3d)

Paso 1: Instalar k3d

macOS:

brew install k3d

Windows (con Chocolatey):

choco install k3d

Windows (con Scoop):

scoop install k3d

Verificá:

k3d version

Paso 2: Crear un cluster k3s adentro de Docker

k3d cluster create scraper

Esto levanta:

• Un container Docker llamado k3d-scraper-server-0 corriendo k3s.
• Te configura ~/.kube/config automáticamente para apuntar a este cluster.

Duración: ~30 segundos.

Paso 3: Verificar el cluster

kubectl get nodes

Debería mostrar k3d-scraper-server-0 en estado Ready.

Paso 4: Cargar una imagen Docker en k3d

docker build -t mi-imagen:latest .
k3d image import mi-imagen:latest -c scraper

k3d image import se encarga de empaquetar la imagen y enviarla al cluster. Mucho más cómodo que el flujo de k3s nativo.

Paso 5: Tirar abajo el cluster cuando termines

k3d cluster delete scraper

Camino C — Cargar la imagen vía registry público (recomendado para entrega)

Los Pasos 4 de los Caminos A y B (k3s ctr import / k3d image import) sirven para vos en tu máquina. Pero para que los profesores puedan correr tu Hit #7 sin tener tu imagen local, necesitás que la imagen esté en algún lugar público que cualquiera pueda hacer docker pull.

Para este TP usamos GitHub Container Registry (ghcr.io): es gratis para imágenes públicas, no tiene rate limit de pulls (al contrario de Docker Hub free tier que limita a 100-200/6h y se siente en CI), y la autenticación reusa el GITHUB_TOKEN que ya viene con cualquier repo en GitHub.

⚠️ Esto es solo para la demo / entrega del TP. En producción real las imágenes nunca van a un registry público — van a uno privado / interno del equipo (control de seguridad, control de quién hace pull/push, no exponer el código vía las layers, evitar dependencia de un servicio externo). Más abajo hay una tabla con las opciones de registry profesional 2026.

Push manual a ghcr.io (la primera vez)

# 1. Generá un Personal Access Token (PAT) con scope write:packages:
#    GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token
#    Tildá: write:packages, read:packages, delete:packages
#    Copiá el token (lo vas a ver una sola vez).

# 2. Login a ghcr.io con el PAT
export GHCR_PAT=<pegá-el-token>
echo $GHCR_PAT | docker login ghcr.io -u <tu-usuario-github> --password-stdin

# 3. Tagear la imagen con el path completo
docker tag ml-scraper:latest ghcr.io/<tu-usuario>/ml-scraper:latest

# 4. Push
docker push ghcr.io/<tu-usuario>/ml-scraper:latest

# 5. En GitHub: ir a la pestaña "Packages" del repo → click en el package →
#    "Package settings" → "Change visibility" → Public.
#    (las imágenes son privadas por default; sin esto, kubectl no podrá pull desde el cluster)

En el manifest del Hit #7, cambiás:

containers:
  - name: scraper
    image: ghcr.io/<tu-usuario>/ml-scraper:latest
    imagePullPolicy: Always   # importante: ahora sí queremos que k8s vaya al registry

Y eliminás el paso de k3s ctr import / k3d image import — k8s va a bajar la imagen directo del registry.

CI auto-push de la imagen al registry (recomendado)

En lugar de pushear a mano, el workflow de la Infra base puede empujar la imagen en cada merge a main:

# .github/workflows/scrape.yml — extracto
- name: Login to ghcr.io
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}   # provisto por GH Actions, sin setup

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
    tags: |
      ghcr.io/${{ github.repository_owner }}/ml-scraper:latest
      ghcr.io/${{ github.repository_owner }}/ml-scraper:${{ github.sha }}

Después de merguear a main, la imagen está disponible automáticamente para kubectl apply.

Container registries — el panorama 2026

Para que tengan idea de cómo se hace esto en la industria, no solo en el TP:

Reglas de decisión rápidas (2026):

• ¿Imagen pública para que cualquiera la use? → ghcr.io (si es OSS en GitHub) o Docker Hub (si querés discoverability máxima).
• ¿Workload en una sola nube? → el registry nativo de esa nube (ECR / GAR / ACR). Ahorra latencia y a veces dinero en transferencia.
• ¿On-prem / multi-nube / requisitos de soberanía? → Harbor es la respuesta más común. Es CNCF graduated, tiene replicación, escaneo de vulnerabilidades (Trivy / Clair), RBAC, GC, signing.
• ¿Stack monorepo Maven + npm + Docker + Helm? → Artifactory o Nexus.

Lecturas útiles:

• The 2024 State of Container Registries — CNCF (la edición 2026 sale a fin de año)
• Harbor docs — para entender qué hace un registry de producción que un public hub no
• OCI Distribution Spec — el protocolo HTTP estándar que hablan todos los registries OCI-compliant (saber esto te abre el mercado entero)
• Sigstore / cosign — firma criptográfica de imágenes (lo que viene como estándar 2026 para supply chain security; ya es parte de SLSA Level 3)

Comandos básicos de kubectl que vas a usar todo el tiempo

Hello world: deployar nginx para validar que todo funciona

Creá un archivo nginx-test.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: nginx-test
  labels:
    app: nginx-test
spec:
  containers:
  - name: nginx
    image: nginx:alpine
    ports:
    - containerPort: 80

Aplicalo:

kubectl apply -f nginx-test.yaml

Esperá a que esté corriendo:

kubectl get pod nginx-test --watch
# salí con Ctrl+C cuando veas STATUS=Running

Hacé port-forward para probarlo:

kubectl port-forward pod/nginx-test 8080:80

En otra terminal:

curl http://localhost:8080

Tenés que ver el HTML de bienvenida de nginx. Si lo ves, felicitaciones — tu cluster funciona.

Limpieza:

kubectl delete -f nginx-test.yaml

Conceptos mínimos que vas a usar en el Hit #7

No hace falta entender todo de Kubernetes. Para el Hit #7 alcanza con saber qué hace cada uno de estos 6.

Troubleshooting frecuente

“El pod queda en Pending y no arranca”

Casi siempre es porque la imagen no está disponible. En k3s tenés que importar la imagen con sudo k3s ctr images import. En k3d con k3d image import. Después en el manifiesto del pod usá imagePullPolicy: IfNotPresent para que no intente bajarla de Docker Hub.

kubectl describe pod <nombre>
# leé la sección "Events" — ahí dice qué está fallando

“El pod arranca pero falla con CrashLoopBackOff”

Es un error del proceso adentro del container. Mirá los logs:

kubectl logs <pod>
kubectl logs <pod> --previous   # logs de la corrida anterior si ya reinició

“kubectl no encuentra el cluster (The connection to the server localhost:8080 was refused)”

Tu ~/.kube/config no apunta al cluster correcto. En k3s seguí el Paso 3 del Camino A. En k3d corré k3d kubeconfig merge scraper --kubeconfig-switch-context.

“k3s consume mucha RAM”

k3s idle anda en ~400-500 MB. Si tenés problemas, asegurate de no tener microk8s, minikube ni Docker Desktop con su Kubernetes activo en paralelo.

Lectura recomendada y referencias

No es lectura obligatoria, pero si van en serio con esto, las primeras 4-5 referencias les van a ahorrar meses.

Documentación oficial (lo que conviene tener bookmarkeado)

• Kubernetes — sitio oficial — https://kubernetes.io/
• Conceptos de Kubernetes — https://kubernetes.io/docs/concepts/ (Pod, Deployment, Service, Job, CronJob, ConfigMap, PVC explicados por la fuente)
• API Reference — https://kubernetes.io/docs/reference/kubernetes-api/ (todos los campos de cada manifiesto)
• kubectl cheatsheet — https://kubernetes.io/docs/reference/kubectl/quick-reference/
• k3s docs — https://docs.k3s.io/
• k3d docs — https://k3d.io/
• CNCF Landscape — https://landscape.cncf.io/ (mapa de ~1500 proyectos del ecosistema cloud-native — útil para ubicar herramientas en contexto)
• KEPs (Kubernetes Enhancement Proposals) — https://github.com/kubernetes/enhancements/tree/master/keps (cómo evoluciona Kubernetes — útil cuando quieren entender por qué algo funciona como funciona)

Libros — ordenados de “primer contacto” a “producción/avanzado”

Papers fundacionales — el ADN intelectual de Kubernetes

Los conceptos de Job, CronJob, scheduling, PVC, etc. no salieron de la nada — vienen de 15 años de investigación y operación a escala en Google con sus sistemas Borg y Omega. Estos 4 papers son lectura obligatoria conceptual para cualquiera que quiera entender el “por qué” detrás de Kubernetes:

• Burns, Grant, Oppenheimer, Brewer, Wilkes (2016). “Borg, Omega, and Kubernetes: Lessons learned from three container-management systems over a decade”. ACM Queue / Communications of the ACM. — https://queue.acm.org/detail.cfm?id=2898444

  El paper que conecta los puntos: por qué Kubernetes es como es. Léanlo aunque sea uno solo.

• Verma, Pedrosa, Korupolu, Oppenheimer, Tune, Wilkes (2015). “Large-scale cluster management at Google with Borg”. EuroSys 2015. — https://research.google.com/pubs/archive/43438.pdf

  El paper original de Borg, el sistema interno de Google que inspiró Kubernetes. Estructura de control plane, scheduling, admission control.

• Schwarzkopf, Konwinski, Abd-El-Malek, Wilkes (2013). “Omega: flexible, scalable schedulers for large compute clusters”. EuroSys 2013. — https://research.google/pubs/omega-flexible-scalable-schedulers-for-large-compute-clusters/

  Schedulers paralelos optimistic — la base conceptual del scheduler de Kubernetes.

• Tirmazi, Barker, Deng, Haque, Qin, Hand, Harchol-Balter, Wilkes (2020). “Borg: the Next Generation”. EuroSys 2020. — https://dl.acm.org/doi/10.1145/3342195.3387517

  Análisis empírico de cómo evolucionó Borg después de 5 años más de operación. Datos de utilización, mix de workloads, lecciones aprendidas.

Recursos comunitarios

• Kubernetes the Hard Way — Kelsey Hightower — https://github.com/kelsey-hightower/kubernetes-the-hard-way

  Tutorial canónico para construir un cluster Kubernetes “desde cero” sin instaladores. No lo necesitan para el TP, pero si después quieren entender qué hace k3s por debajo, este es el camino.

• Awesome Kubernetes — https://github.com/ramitsurana/awesome-kubernetes (lista curada de herramientas, charlas, libros)

• CNCF YouTube — https://www.youtube.com/@cncf (KubeCon talks gratis — buscá “Job”, “CronJob”, “k3s” para charlas específicas)

• Learnk8s blog — https://learnk8s.io/blog (artículos técnicos profundos, gratuitos)

• Killercoda — https://killercoda.com/playgrounds/scenario/kubernetes (sandbox interactivo en el navegador para practicar kubectl sin instalar nada)

Glosario — términos densos en una línea cada uno

• WebDriver (W3C protocol): estándar W3C que define cómo un programa controla un browser real (clicks, navegación, lectura del DOM) por HTTP.
• Headless browsing: ejecutar un browser sin interfaz gráfica visible, controlado solo por código. Necesario en CI y servidores.
• Browser Factory (patrón): función o clase que centraliza la creación del WebDriver con su config (browser, headless, timeouts) para no repetir código.
• Explicit wait vs implicit wait: explicit espera una condición concreta (un elemento visible); implicit aplica un timeout global a cada find_element. Preferí explicit.
• Selector CSS vs XPath: CSS es más rápido y legible para selectores simples; XPath permite navegar relaciones complejas (padres, hermanos, texto).
• Backoff exponencial: estrategia de reintentos donde la espera entre intentos crece (1s, 2s, 4s, 8s) para no saturar al servicio caído.
• Coverage / cobertura de código: porcentaje de líneas/ramas ejecutadas por los tests. Métrica útil pero no garantiza calidad de los tests.
• Multi-stage Docker build: Dockerfile con varios FROM; el final copia solo los artefactos del stage de build, achicando la imagen y reduciendo superficie.
• Image registry: servidor que almacena imágenes Docker/OCI versionadas (ej: ghcr.io, ECR). Ver Camino C de TP 0 y la tabla “Container registries”.
• CI/CD pipeline: pipeline automático que compila, testea y publica el código en cada push (Continuous Integration / Continuous Delivery).
• Pre-commit hook: script que corre antes de cada git commit para validar formato, lint o tests rápidos y bloquear commits que no pasan.
• ADR (Architecture Decision Record): documento corto en el repo que registra una decisión arquitectónica, su contexto y consecuencias.
• Pod (Kubernetes): unidad mínima desplegable en k8s: uno o más containers que comparten red y storage. Ver “Conceptos mínimos” del TP 0.
• Job vs CronJob (Kubernetes): Job corre una tarea hasta completarse una vez; CronJob lanza Jobs según una expresión cron (ej: cada 5 min).
• ConfigMap (Kubernetes): objeto que guarda configuración no-secreta (env vars, archivos) y la inyecta a los pods sin tocar la imagen.
• PVC — PersistentVolumeClaim: pedido de almacenamiento persistente que un pod hace al cluster; sobrevive a reinicios del pod.
• StatefulSet: controlador de k8s para apps con identidad estable (DBs, colas) — pods con nombre fijo y storage propio por réplica.
• Secret (Kubernetes): objeto similar a ConfigMap pero para datos sensibles (passwords, tokens), codificado en base64 y con RBAC más estricto.
• Schema migration (DB): cambios versionados al esquema de la base (crear tablas, columnas) aplicados en orden con herramientas tipo Alembic o Flyway.
• Supply chain security (Sigstore/cosign): firma criptográfica de imágenes para verificar quién las construyó y que no fueron alteradas. Estándar 2026 (SLSA L3).

Validación obligatoria previa al Hit #7

Para que la entrega de la Parte 2 sea aceptada, tienen que poder responder afirmativamente a las 4 preguntas. Documenten en el README de la Parte 2 (sección “Prerrequisitos cumplidos”) la evidencia de cada checkpoint (output del comando o screenshot).

• kubectl get nodes me devuelve un nodo en Ready.
• Pude correr el nginx-test y abrirlo con curl localhost:8080.
• Sé importar una imagen Docker al cluster (k3s ctr images import / k3d image import).
• Entiendo qué es un Pod, un Job, un CronJob, un ConfigMap y un PVC (al menos a nivel “para qué sirve”).

Si las 4 son sí, están listos para el Hit #7.