Módulo 4: LocalStack — AWS Local Development

1. Introducción: LocalStack — AWS Local Development

Descripción

Esta es la primera cápsula del Módulo 4 de la Guía de Deployment & Cloud Infrastructure. Aquí vas a entender qué es LocalStack, por qué existe, y por qué cambia completamente tu forma de aprender y desarrollar contra AWS. Te acabo de quitar la excusa de que AWS es caro para aprender. Con LocalStack, corres S3, Lambda, y otros servicios AWS en tu propia máquina — gratis, sin cuenta AWS, sin tarjeta de crédito, sin facturas sorpresa.

Por qué importa: La barrera #1 para aprender AWS no es la complejidad técnica — es el miedo a la factura. "¿Y si dejo un servicio corriendo?" "¿Y si algo escala sin control?" LocalStack elimina esa barrera por completo. Desarrollas, pruebas, rompes, y vuelves a probar — sin consecuencias económicas. Y lo mejor: tu código usa las mismas APIs de AWS (boto3), así que cuando migres a AWS real, solo cambias un endpoint URL.

En los módulos anteriores construiste un framework de decisión (M1), un Docker Compose multi-container (M2), y un Lambda AI Endpoint (M3). Ahora vas a tomar ese Lambda del M3 y ejecutarlo localmente en LocalStack, añadir S3 para almacenamiento, y construir un pipeline AI completo — todo corriendo en tu laptop.

¿Dónde Estamos en la Guía?

Contexto

Phase 1: Deployment Strategies (Módulos 1-3)
├── Módulo 1: Understanding Deployment Options    ✅ COMPLETADO
├── Módulo 2: Local & Container Deployment        ✅ COMPLETADO
└── Módulo 3: Serverless & Lambda for AI          ✅ COMPLETADO

Phase 2: Cloud Infrastructure & Migration (Módulos 4-6)
├── Módulo 4: LocalStack — AWS Local Development  ← ESTÁS AQUÍ
├── Módulo 5: AWS Services for AI (S3, Lambda, SageMaker Basics)
└── Módulo 6: Cloud Migration Patterns

Phase 3: Alternatives & Production (Módulos 7-8)
├── Módulo 7: Alternative Platforms (Render, Railway, Fly.io)
└── Módulo 8: Proyecto Integrador — Deployed AI System

Duración total estimada de la guía: 10-12 horas (self-paced).

Transición desde Phase 1

En la Phase 1 aprendiste las estrategias de deployment. Ahora entras a la Phase 2: infraestructura cloud real. Pero "real" no significa "costosa." LocalStack es el puente entre aprender conceptos y operar servicios cloud — sin gastar un centavo.

La progresión es deliberada:

Módulo 1: Decidiste qué estrategia de deployment usar
Módulo 2: Construiste infraestructura local con Docker Compose
Módulo 3: Creaste un Lambda AI Endpoint funcional
Módulo 4 (aquí): Ejecutas servicios AWS localmente con LocalStack — zero cost
Módulo 5: Profundizas en AWS real (S3, Lambda, SageMaker)
Módulo 6: Migras de LocalStack a AWS con confianza

Tu Docker Compose del M2 va a crecer: le agregas LocalStack como un servicio más, al lado de Redis y FastAPI. Tu Lambda del M3 va a correr en LocalStack con mínimos cambios. Todo conectado.

Qué Es LocalStack

Definición

LocalStack es un emulador de servicios AWS que corre en tu máquina dentro de un container Docker. Replica las APIs de AWS — S3, Lambda, SQS, DynamoDB, y 70+ servicios más — para que puedas desarrollar y testear código cloud sin conectarte a AWS real.

Cuando tu código usa boto3 (el SDK de AWS para Python) para crear un bucket S3 o invocar una Lambda, lo hace contra el endpoint de LocalStack (http://localhost:4566) en lugar de contra https://s3.amazonaws.com. La API es la misma. Los parámetros son los mismos. La respuesta tiene el mismo formato. Solo cambia la URL.

La analogía

Piensa en LocalStack como un simulador de vuelo. Los pilotos entrenan miles de horas en simuladores antes de volar un avión real. El simulador replica los controles, las respuestas, los escenarios — pero no estás en el aire. No hay riesgo. Cuando subes al avión real, ya conoces los controles porque son los mismos.

LocalStack es tu simulador de AWS. Aprendes los controles (boto3, CLI, CloudFormation) sin riesgo económico. Cuando migras a AWS real, ya conoces las APIs porque son las mismas.

LocalStack vs alternativas

LocalStack:
├── Emula 70+ servicios AWS localmente
├── Mismo CLI (aws), mismo SDK (boto3)
├── Corre en Docker — un container, un puerto (4566)
├── Community Edition: gratis, suficiente para S3/Lambda
└── Pro: servicios avanzados (IAM enforcement, SQS FIFO)

Alternativas que NO hacen esto:
├── SAM CLI local: solo Lambda + API Gateway, no S3 ni otros servicios
├── Moto (Python mock): mocks en tests, no un servicio corriendo
├── MinIO: solo S3, no Lambda ni otros servicios
└── Docker Compose solo: corres TUS servicios, no emulas AWS

Qué incluye la Community Edition (gratis)

Para esta guía, usamos la Community Edition. Incluye todo lo que necesitas:

✅ S3 — Buckets, objetos, presigned URLs
✅ Lambda — Funciones, invocación, layers
✅ API Gateway — HTTP endpoints para Lambda
✅ CloudFormation / SAM — Deploy via templates
✅ CloudWatch Logs — Logs de Lambda
❌ IAM enforcement (Pro) — en Community, todo tiene acceso a todo
❌ Persistence (Pro) — en Community, los datos se borran al reiniciar

La limitación de persistence significa que cuando reinicies LocalStack, pierdes buckets y funciones. Para desarrollo esto es aceptable — recreas con un script. Para datos importantes, usas volúmenes Docker.

Por Qué Zero Cost Importa

La barrera económica real

Habla con cualquier developer que quiere aprender AWS y escucharás variaciones de:

"Dejé un EC2 corriendo y me llegó una factura de $50"
"No sé si estoy en free tier o no"
"Tengo miedo de experimentar porque no sé cuánto va a costar"
"Mi empresa no me da cuenta AWS para experimentar"

Estas no son excusas — son barreras reales. AWS es poderoso pero intimidante cuando cada click puede tener coste.

Lo que LocalStack elimina

Con AWS real:
├── Necesitas cuenta AWS (tarjeta de crédito obligatoria)
├── Free tier tiene límites confusos
├── Un error puede generar costes inesperados
├── Experimentar da miedo
└── Aprender tiene coste económico

Con LocalStack:
├── No necesitas cuenta AWS
├── No necesitas tarjeta de crédito
├── No vas a recibir facturas sorpresa
├── Experimentar es gratis — rompe todo, recrea
└── Aprender tiene coste CERO

Para sistemas AI, el impacto es mayor

Los pipelines AI son intensivos en recursos: almacenas embeddings en S3, ejecutas inferencia en Lambda, procesas documentos en batch. En AWS real, un pipeline de pruebas puede costar $5-20 al día. Con LocalStack, cuesta $0 — siempre.

Esto significa que puedes:

Iterar tu pipeline 50 veces al día sin pensar en costes
Probar configuraciones de Lambda (memory, timeout) sin impacto económico
Subir y bajar archivos a S3 sin límites
Romper cosas a propósito para aprender troubleshooting

Objetivo del Módulo

Al terminar este módulo serás capaz de:

✅ Instalar y configurar LocalStack via Docker Compose, integrado con tu infraestructura del M2
✅ Crear y operar buckets S3 locales: crear, subir, descargar, listar, presigned URLs — todo con boto3
✅ Desplegar y ejecutar funciones Lambda en LocalStack: deploy, invoke, leer logs
✅ Construir un pipeline S3 + Lambda local: Lambda lee de S3, procesa con LLM, escribe resultado a S3
✅ Configurar environment switching: el mismo código apunta a LocalStack o AWS cambiando una variable de entorno
✅ Debuggear problemas de LocalStack: leer logs, diagnosticar errores, verificar disponibilidad de servicios
✅ Articular el valor de LocalStack: zero cost, iteración rápida, testing sin infraestructura cloud

Objetivo profesional

Cuando alguien en tu equipo diga "necesitamos una cuenta AWS para cada developer," tú vas a proponer: "usemos LocalStack para desarrollo. Mismo código, mismas APIs, zero cost. La cuenta AWS solo la necesitamos para staging y producción." Esa propuesta ahorra miles de dólares al año en un equipo de 5 developers.

Roadmap del Módulo

Mapa de cápsulas

#	Cápsula	Qué aprenderás	Tipo
01	Introducción (esta)	Qué es LocalStack, zero cost, setup, roadmap	Intro
02	LocalStack Setup y Configuración	Docker Compose, CLI, awslocal, verificación	Técnica
03	S3 Local para AI	Buckets, upload/download, presigned URLs, boto3	Técnica
04	Lambda Local con LocalStack	Deploy Lambda del M3, invoke, logs	Técnica
05	Pipeline S3 + Lambda Local	Lambda lee de S3, procesa, escribe a S3	Técnica
06	Environment Switching	Mismo código → LocalStack o AWS con env vars	Técnica
07	Debugging LocalStack	Errores comunes, logs, troubleshooting	Técnica
08	Proyecto: LocalStack AI Pipeline	Pipeline AI completo en LocalStack + Docker Compose	Proyecto

Flujo de aprendizaje

Primero configuras LocalStack en tu Docker Compose (cápsula 02). Luego aprendes S3 local para almacenar assets AI (cápsula 03). Después despliegas tu Lambda del M3 en LocalStack (cápsula 04). Conectas ambos en un pipeline S3 + Lambda (cápsula 05). Aprendes la skill clave: environment switching para usar el mismo código contra LocalStack o AWS (cápsula 06). Sabes debuggear cuando algo falla (cápsula 07). Y finalmente integras todo en un proyecto funcional (cápsula 08).

La progresión es: setup → S3 → Lambda → pipeline → switching → debugging → proyecto.

Duración estimada del módulo: 1.25-1.5 horas.

Conexión con el Proyecto

Proyecto de este módulo: LocalStack AI Pipeline

El LocalStack AI Pipeline es un sistema funcional que:

Corre enteramente en LocalStack dentro de Docker Compose
Usa S3 para almacenar documentos de entrada y resultados
Usa Lambda para procesar documentos con un LLM
Integra todo en un flujo: upload → process → result

Upload documento a S3 (bucket: ai-input)
    ↓
Lambda se invoca
    ↓
Lambda lee documento de S3
    ↓
Lambda procesa con GPT-4o-mini
    ↓
Lambda escribe resultado a S3 (bucket: ai-output)
    ↓
Descargas resultado de S3

Conexión con módulos posteriores

Módulo 4: LocalStack AI Pipeline → pipeline funcional, local, gratis
    ↓
Módulo 5: AWS Services → mismo pipeline, ahora en AWS real
    ↓
Módulo 6: Migration → el código ya funciona en ambos (solo cambia endpoint)
    ↓
Módulo 8: Proyecto Integrador → LocalStack es tu entorno de desarrollo

Prerequisitos

Lo que ya sabes

✅ Docker y Docker Compose — Sabes levantar servicios con docker compose up (Módulo 2)
✅ Lambda fundamentals — Entiendes handler, event, context, packaging (Módulo 3)
✅ boto3 básico — Has visto el SDK de AWS en el módulo anterior
✅ Python intermedio — Funciones, clases, requests, JSON
✅ Apps AI — Has construido endpoints que invocan LLMs

Lo que aprenderás aquí (nuevo)

LocalStack: instalación, configuración, operación
S3 local: buckets, objetos, presigned URLs
Lambda local: deploy y ejecución en LocalStack
Environment switching: mismo código, diferentes targets
Debugging de servicios AWS emulados

Si te falta algo

Te falta	Recurso recomendado
Docker Compose	Módulo 2 de esta guía
Lambda fundamentals	Módulo 3 de esta guía
Docker básico	Docker Essentials Guide (#15) — NIEVA
Python + FastAPI	Python REST APIs for AI Guide — NIEVA

Setup Técnico

Herramientas necesarias

# Docker (ya lo tienes del M2)
docker --version
# Docker version 24.0+ esperado

# Docker Compose (ya lo tienes del M2)
docker compose version
# Docker Compose version v2.x.x esperado

# Python 3.10+ (ya lo tienes)
python --version

# AWS CLI v2 (ya lo tienes del M3)
aws --version

Instalar herramientas nuevas

# LocalStack CLI (opcional pero útil)
pip install localstack

# awslocal — wrapper que agrega --endpoint-url automáticamente
pip install awscli-local

# Verificar instalación
localstack --version
awslocal --version

awslocal vs aws --endpoint-url

Hay dos formas de hablar con LocalStack desde el CLI:

# Opción 1: aws CLI con --endpoint-url (verbose)
aws --endpoint-url=http://localhost:4566 s3 ls

# Opción 2: awslocal (wrapper que hace lo mismo, menos typing)
awslocal s3 ls

# Ambos hacen EXACTAMENTE lo mismo
# awslocal es azúcar sintáctica: internamente agrega --endpoint-url

En esta guía usamos awslocal para brevedad. Si prefieres aws --endpoint-url, funciona igual.

Verificación rápida

# Levanta LocalStack (lo harás bien en la cápsula 02)
docker run -d --name localstack-test \
  -p 4566:4566 \
  localstack/localstack

# Espera a que arranque (~10 segundos)
sleep 10

# Verifica que responde
curl http://localhost:4566/_localstack/health

# Respuesta esperada (JSON con status de servicios):
# {"services": {"s3": "available", "lambda": "available", ...}}

# Prueba rápida de S3
awslocal s3 mb s3://test-bucket
awslocal s3 ls
# Debe mostrar: test-bucket

# Limpia
docker stop localstack-test && docker rm localstack-test

Si ves el bucket listado, tu setup está listo.

Estructura de archivos del módulo

module-04/
├── docker-compose.yml          # Compose con LocalStack (extiende M2)
├── scripts/
│   ├── setup-localstack.sh     # Crea buckets y funciones
│   └── test-pipeline.sh        # Prueba el pipeline completo
├── lambda/
│   ├── handler.py              # Lambda del M3 adaptada
│   ├── requirements.txt        # Dependencias
│   └── handler.zip             # Package para deploy
├── data/
│   ├── input/                  # Documentos de prueba
│   └── output/                 # Resultados procesados
└── .env                        # Variables (OPENAI_API_KEY)

Límites: Qué NO Cubre Este Módulo

❌ Todos los servicios de LocalStack — Nos enfocamos en S3 y Lambda. No cubrimos SQS, DynamoDB, SNS — serían scope creep para los objetivos de esta guía.
❌ LocalStack Pro — Usamos la Community Edition (gratis). Pro tiene IAM enforcement, persistence, y más, pero no lo necesitas para aprender.
❌ Deploy a AWS real — Eso es el Módulo 5. Aquí todo corre localmente.
❌ Testing automatizado con LocalStack — Integrar LocalStack en CI/CD es valioso pero es un tema de la guía de CI/CD (#16).
❌ Servicios de ML en LocalStack — SageMaker en LocalStack es Pro y limitado. Lambda + OpenAI API es nuestra estrategia.

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ LocalStack corre como servicio en tu Docker Compose, junto a FastAPI y Redis del M2
✅ Puedes crear buckets S3, subir archivos, y descargarlos — todo contra LocalStack
✅ Tu Lambda del M3 corre en LocalStack con mínimos cambios
✅ Un pipeline S3 → Lambda → S3 funciona de principio a fin localmente
✅ El mismo código Python (boto3) funciona contra LocalStack y contra AWS cambiando solo un endpoint URL
✅ Puedes diagnosticar un error de LocalStack leyendo logs del container
✅ Puedes explicar a un colega por qué LocalStack ahorra dinero y acelera el desarrollo

Test rápido de autoevaluación

Si puedes responder estas preguntas, vas por buen camino:

¿Qué puerto expone LocalStack y por qué solo necesitas uno?
¿Cuál es la diferencia entre aws s3 ls y awslocal s3 ls?
¿Por qué tu código boto3 funciona igual contra LocalStack y AWS?
¿Qué pasa con tus datos en LocalStack cuando reinicias el container?

Resumen

LocalStack emula servicios AWS en tu máquina dentro de un container Docker. Mismas APIs, zero cost.
Elimina la barrera económica #1 para aprender AWS: no necesitas cuenta, tarjeta, ni presupuesto.
En este módulo trabajas con S3 y Lambda — los servicios relevantes para pipelines AI.
Tu Docker Compose del M2 crece: LocalStack es un servicio más al lado de FastAPI y Redis.
Tu Lambda del M3 corre en LocalStack con mínimos cambios — solo cambia el endpoint URL.
La skill clave es environment switching: el mismo código boto3 apunta a LocalStack o AWS según una variable de entorno.
LocalStack es tu entorno de desarrollo para el resto de la guía: desarrollas local, despliegas a cloud.

Recursos Adicionales

LocalStack Documentation — Documentación oficial completa
LocalStack GitHub — Código fuente y issues
LocalStack Docker Setup — Guía de instalación con Docker Compose
awscli-local (awslocal) — CLI wrapper para LocalStack
boto3 Documentation — SDK de AWS para Python
LocalStack Coverage — Qué servicios emula y con qué fidelidad
LocalStack + SAM Integration — Usar SAM con LocalStack

← Anterior8. Proyecto: Lambda AI Endpoint Siguiente →2. LocalStack Setup y Configuración