Un AWS simulado en la laptop: Terraform, Floci y Ansible
César Ballardini
- Lectura en 7 minutos - 1396 palabrasQuería practicar un despliegue en AWS completo, con Terraform para la infraestructura y Ansible para la aplicación, sin abrir una cuenta, sin tarjeta de crédito y sin costo. Floci1 es un emulador de AWS que corre en un solo contenedor Docker y entiende la API de AWS. Este repositorio2 es la prueba de concepto: un libro de visitas3 desplegado en ese AWS local, en una laptop con Windows 11.
El objetivo
Mi pregunta era: ¿los mismos recursos de Terraform y el mismo playbook de Ansible que uno escribiría para AWS funcionan contra el emulador?
Una respuesta práctica necesita algo que funcione:
| Herramienta | Qué hace |
|---|---|
| Terraform | Crea la infraestructura en el emulador: una instancia EC2, un PostgreSQL en RDS, un bucket S3, un rol IAM y un balanceador que atiende por HTTPS y redirige el HTTP a HTTPS |
| Ansible | Entra a la instancia por SSH, instala Python 3.14, nginx y supervisord, arma una release con lo que se construyó en la laptop y la ejecuta |
| La app | Un libro de visitas con FastAPI y HTMX: el visitante deja un mensaje, con una foto opcional. Los mensajes van a PostgreSQL y las fotos a S3 |
Cómo está armado
Todo vive en una sola red de Docker. Floci arranca un contenedor por cada instancia EC2 y otro por cada base RDS. El bucket S3 y el balanceador, en cambio, los atiende el propio proceso de Floci. Para correr Ansible usamos otro contenedor: Ansible no corre sobre MS Windows.
flowchart LR
B(["Navegador"])
T(["Terraform"])
subgraph L["Red de Docker guestbook-on-floci, en la laptop"]
subgraph F["Floci, el emulador de AWS"]
API["API de AWS<br/>:4566"]
LB["Balanceador<br/>:8443 HTTPS<br/>:8080 redirige a HTTPS"]
S3[("Bucket S3")]
end
subgraph I["Instancia EC2: un contenedor que arranca Floci"]
SV["supervisord<br/>gestor de procesos"]
N["nginx :80"] --> G["gunicorn + uvicorn<br/>el libro de visitas"]
SV -. arranca y vigila .-> N
SV -. arranca y vigila .-> G
end
R[("RDS: PostgreSQL 16")]
A["Ansible<br/>nodo de control"]
end
B --> LB --> N
G -- mensajes --> R
G -- fotos --> S3
T -- crea la infraestructura --> API
A -- "SSH: instala y arranca la app" --> I
Terraform le entrega a Ansible lo que necesita en la carpeta .generated/, que git ignora: ahí quedan la clave SSH y un inventario con la dirección de la instancia, la URL de la base y el nombre del bucket. La aplicación no guarda ninguna clave de AWS: las credenciales para S3 salen del rol de la instancia, por el servicio de metadatos, igual que en AWS.
Cómo se usa
Hace falta Docker Desktop en ejecución, Terraform 1.9 o posterior, uv y Git.
git clone https://github.com/CesarBallardini/guestbook-on-floci.git
cd guestbook-on-floci/
# arrancar el emulador y esperar a que esté operativo:
docker compose up -d --wait
# crear la infraestructura:
cd terraform/
terraform init
terraform apply
cd ..
# construir la aplicación: el wheel y sus dependencias fijadas, en app/dist/
cd app/
uv build --wheel --out-dir dist
uv export --frozen --no-dev --no-emit-project --format requirements-txt --output-file dist/requirements.txt
cd ..
# instalar la aplicación:
docker compose run --rm ansibleDespués de eso, el libro de visitas contesta en https://localhost:8443/. El navegador advierte que no confía en el certificado TLS: lo emite el Certificate Manager del emulador, un emisor que ningún navegador conoce. Con Make instalado, make all hace los cuatro pasos y make destroy elimina todo.
- Correr el playbook es idempotente.
make idempotencedespliega, vuelve a correr y falla si la segunda corrida no informachanged=0. - Cada despliegue es una release. Ansible instala el build y la configuración en una carpeta propia,
/opt/guestbook/releases/<hora UTC>, y el enlace/opt/guestbook/currentapunta a la que corre. El mismo build con la misma configuración no genera una release nueva. La instancia conserva las últimas cinco, ymake rollbackvuelve a la anterior. El rollback no deshace las migraciones: la release anterior trabaja con las tablas de la más nueva. - La instancia no tiene datos.
terraform apply -replace=aws_instance.appy otra corrida de Ansible, y los mensajes y las fotos siguen ahí, porque viven en RDS y en S3. Las releases sí se pierden: la instancia nueva no tiene a cuál volver hasta el segundo despliegue.
La aplicación
Un libro de visitas alcanza para ejercitar la infraestructura. Está armado con puertos y adaptadores4. El dominio importa sólo la biblioteca estándar, los casos de uso importan sólo el dominio; FastAPI, SQLAlchemy y boto3 quedan del lado de afuera. Esas reglas se verifican con contratos de import-linter y un test, en cada corrida de make qa. Las compuertas de calidad son las del post sobre tooling de un backend Python.
Los tests no usan mocks. Los casos de uso reciben implementaciones en memoria de los puertos. Los tests de integración hablan con un PostgreSQL y un S3 que contestan con los protocolos reales, sin costo de nube.
En números: 166 tests unitarios y de aceptación, 49 de integración (41 contra el emulador y 8 que revisan el build) y 13 de punta a punta con un navegador. Los unitarios y de aceptación cubren el 100 % del paquete de la aplicación, salvo los adaptadores de PostgreSQL y S3, que quedan para los de integración.
Algunas diferencias con respecto a AWS real
Lo que la prueba no demuestra:
- La instancia es un contenedor, no una máquina virtual. No tiene systemd, así que supervisord hace de gestor de procesos: arranca nginx y gunicorn y los reinicia si terminan. Pero a supervisord no lo arranca nadie al inicio: lo arranca Ansible. Si el contenedor se reinicia, no queda nada corriendo, ni siquiera sshd, y hay que reemplazar la instancia.
- Floci guarda su estado en memoria. Reiniciar Docker Desktop borra todos los recursos emulados y deja desactualizado el estado de Terraform.
- Los grupos de seguridad y las políticas IAM se anotan, pero no se aplican. El rol tiene la forma correcta, pero el emulador no restringe ninguna operación de la aplicación.
- Nunca lo corrí contra AWS. La hipótesis es que los mismos archivos funcionan allá, con un cambio ya identificado: la redirección de HTTP a HTTPS usa la ruta
#{path}, porque Floci le deja la barra inicial; en AWS tiene que ser/#{path}. Todavía es una hipótesis.
Contra dos listas de referencia, el resultado es este. Cumple los doce factores de The Twelve-Factor App5, uno de ellos con una nota. El factor VIII pide que un gestor de procesos arranque la aplicación; acá ese gestor es supervisord, y como la instancia emulada no tiene init, al propio supervisord lo arranca el playbook. Contra el OWASP ASVS 5.0.06 el cumplimiento es parcial. De sus 345 requisitos, 155 se aplican a una aplicación sin usuarios ni sesiones; de esos cumple 70 y 21 en parte. Las deudas más grandes están en la configuración (la aplicación entra a la base con el usuario maestro y gunicorn corre como root), en las cabeceras de seguridad del navegador y en las conexiones internas sin TLS. Estamos trabajando para que el libro de visitas cumpla con OWASP, y el avance se lleva en docs/owasp.md7, requisito por requisito.
Las decisiones de diseño
Estas son las decisiones que le dieron forma al proyecto:
- El reparto: Terraform para la infraestructura, Ansible para la aplicación.
- Ansible en un contenedor, así la laptop no necesita más que Docker y Terraform.
- Amazon Linux 2023 de junio de 2026, fijado por digest: la primera versión con Python 3.14.5.
- Puertos y adaptadores, sin mocks, con el esquema de la base en manos de Alembic.
- Nombres explicativos:
Port,UseCase,Adapter, las fechas siempre aclaran si tienen zona horaria (posted_datetime_utc).
Para aprender Terraform desde cero, el repositorio trae un tutorial breve con este proyecto como ejemplo.
Espero que te sea útil como lo fue para mi.
Referencias
-
Floci — emulador de AWS en un contenedor Docker. guestbook-on-floci fija la versión 2.5.0, por digest. ↩︎
-
CesarBallardini/guestbook-on-floci, repositorio en GitHub. El README tiene el paso a paso completo. ↩︎
-
Imagen de Magnus Hirschfeld’s Guestbook — Dominio público — Magnus Hirschfeld. Su libro de visitas, hacia 1935, conservado en el Deutsches Literaturarchiv de Marbach. Recortada a 2.5:1 para hero landscape. ↩︎
-
Alistair Cockburn, Hexagonal architecture — el artículo original sobre puertos y adaptadores. ↩︎
-
The Twelve-Factor App — doce reglas para aplicaciones que se despliegan como servicio. ↩︎
-
OWASP Application Security Verification Standard — lista de requisitos de seguridad verificables para aplicaciones web, versión 5.0.0. ↩︎
-
docs/owasp.mden guestbook-on-floci — el libro de visitas contra los 345 requisitos del ASVS 5.0.0, con el resumen por nivel y por capítulo. ↩︎