Diagrama de arquitectura serverless en AWS: API Gateway, Lambda, DynamoDB y eventos

En un sistema serverless los servidores desaparecen, y con ellos la forma habitual de un diagrama de arquitectura. Lo que importa en su lugar es cómo se dispara cada función, qué pasa cuando falla y qué eventos conectan una parte del sistema con la siguiente. Un diagrama con veinte cajas de Lambda y ningún disparador parece completo y no explica nada.

Esta guía muestra cómo dibujar un diagrama de arquitectura serverless en AWS que alguien nuevo en el equipo pueda seguir: un ejemplo completo, una notación para los tipos de invocación y las rutas de fallo, y los errores que vuelven engañosos estos diagramas.

Empieza por cómo se invoca cada función

Algo pone en marcha cada función Lambda del diagrama, y AWS tiene tres modelos de invocación que se comportan de forma distinta ante un fallo. Es lo más útil que puede mostrar un diagrama serverless.

Modelo de invocación	Orígenes típicos	Quién reintenta si falla	Dónde acaban los fallos
Síncrono	API Gateway, una URL de función, una llamada del SDK	Decide quien llama	Una respuesta de error para quien llama
Asíncrono	EventBridge, notificaciones de S3, SNS	Lambda reintenta dos veces por defecto	Un destino en caso de fallo o una cola de mensajes fallidos (DLQ), si configuras uno
Asignación de origen de eventos (Lambda sondea)	SQS, DynamoDB Streams, Kinesis	Lambda sigue reintentando el lote	SQS: la cola de mensajes fallidos de la cola. Streams: un destino en caso de fallo, o los registros caducan

Etiqueta la conexión de cada disparador con su origen y su modelo: sync, async o poll, batch 10. Cuando un incidente empieza con "se están acumulando mensajes", esa es la línea que todos buscan.

El ejemplo: una API de pedidos serverless

Un pequeño servicio de pedidos construido por completo sobre servicios gestionados:

1. Los clientes llaman a una API HTTP de API Gateway. Un autorizador JWT comprueba los tokens emitidos por un grupo de usuarios de Amazon Cognito.
2. API Gateway invoca createOrder de forma síncrona. La función valida la petición y escribe el pedido en la tabla de DynamoDB orders.
3. Un stream de DynamoDB sobre la tabla dispara publishOrderEvents, que envía OrderPlaced a un bus personalizado de EventBridge. Como el evento sale del stream, solo se publica para las escrituras que tuvieron éxito.
4. Una regla de EventBridge captura OrderPlaced y lo envía a la cola SQS receipts.
5. Lambda sondea la cola e invoca sendReceipt con lotes de hasta diez mensajes; la función envía un correo al cliente a través de Amazon SES.
6. Un mensaje que falla cinco veces pasa a receipts-dlq, donde una alarma avisa al equipo.

La ruta de la petición termina en el paso 2: el cliente recibe su respuesta en cuanto se guarda el pedido. Todo lo que viene después es asíncrono, y el diagrama dibuja esos disparadores con conexiones discontinuas.

Reglas para diagramas serverless

Dibuja los disparadores como conexiones etiquetadas

La conexión que entra en una función dice qué la inicia: POST /orders, DynamoDB stream, rule: OrderPlaced, SQS, batch 10. Una función sin conexión entrante es código muerto o una línea que falta en tu diagrama.

Separa la ruta de la petición del trabajo asíncrono

Usa conexiones continuas para las llamadas síncronas y discontinuas para todo lo que ocurre después. Quien lea el diagrama debe poder seguir la ruta que añade latencia para el usuario sin leer cada etiqueta.

Dibuja la ruta de fallo a propósito

Para cada conexión asíncrona, decide adónde van los fallos y dibújalo: una cola de mensajes fallidos, un destino en caso de fallo o una nota que diga "los registros caducan a las 24 horas". DynamoDB Streams conserva los registros durante 24 horas, así que un consumidor que sigue fallando pierde eventos en cuanto caducan. Un destino en caso de fallo en S3 guarda una copia de los registros fallidos; un destino SQS o SNS solo recibe metadatos, así que algo tiene que volver a leer los registros del stream dentro de esas 24 horas.

Una función por nodo

Un único nodo "Lambda" para treinta funciones oculta los disparadores, y los disparadores son la arquitectura. Si hay demasiadas funciones, divide el diagrama por servicio en lugar de fusionar cajas.

Enmarca por unidad de despliegue

Agrupa en un marco los recursos que se despliegan juntos, como un stack de SAM, CDK o Terraform. Así se ve quién es responsable de qué y qué cambia a la vez.

Deja los permisos y los límites en notas

Cada función tiene un rol de ejecución de IAM, y algunas tienen simultaneidad reservada o tiempos de espera largos. No dibujes un rol por función. Añade una nota con lo que importa en una revisión: "solo createOrder puede escribir en orders", "disparador SQS de sendReceipt con simultaneidad máxima de 5 para proteger los límites de SES".

Errores comunes

• API Gateway dibujado como un balanceador de carga. También autentica, limita el tráfico y transforma las peticiones, y el autorizador debe aparecer en el diagrama.
• Faltan colas de mensajes fallidos, o hay colas de mensajes fallidos que nadie vigila. Dibuja también la alarma.
• Buses de eventos sin reglas. Un bus de EventBridge reparte los eventos por regla; etiqueta la conexión con la regla, no solo con el bus.
• Sin distinción entre sync y async. Es la diferencia entre una API lenta y un correo lento.
• Ruido de infraestructura. Los grupos de registros, las capas y cada política de IAM van en la plantilla, no en la vista general.

Constrúyelo en Archboard

Los nodos del pack Nube de Archboard son neutrales respecto al proveedor y tienen puertos, así que etiquetas cada nodo con el nombre del servicio de AWS:

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Añade nodos Caja del pack Básico para los clientes y para Amazon SES, una Puerta de enlace de API del pack Nube y un Proveedor de identidad del pack Seguridad con la etiqueta Amazon Cognito.
3. Añade una Función del pack Nube por cada función Lambda, con exactamente el mismo nombre que en tu plantilla.
4. Añade una Base de datos administrada del pack Nube con la etiqueta DynamoDB: orders, un Tema del pack Datos con la etiqueta EventBridge bus, nodos Cola del pack Nube para la cola y su cola de mensajes fallidos, y una Alerta del pack DevOps para la alarma.
5. Conecta los puertos. Mantén la ruta de la petición con línea continua, cambia las conexiones asíncronas a discontinuas y etiqueta cada disparador con su origen y su modelo de invocación.
6. Pon el stack en un Marco del pack Básico, añade notas sobre permisos y límites, y luego comparte el enlace en vivo con el equipo.

El ejemplo usa 13 nodos de diagrama, así que cabe en el plan Free. Para la red que rodea una carga de trabajo serverless o de contenedores, consulta la guía del diagrama de VPC de AWS, y para más patrones cloud, la página de casos de uso de cloud.

Preguntas frecuentes

¿Debo dibujar cada función Lambda? En el diagrama del servicio, sí, porque cada una tiene su propio disparador y su propio comportamiento ante fallos. En una vista general del sistema, muestra el servicio como un solo nodo y enlaza a su diagrama.

¿Puedo usar los iconos oficiales de AWS? Archboard no tiene un pack específico de AWS: construye el diagrama con nodos tipados y con puertos de los packs Nube, Red y Seguridad, y etiqueta cada uno con el nombre del servicio, como Amazon SES o DynamoDB: orders. Si además quieres logotipos, Buscar e insertar tiene iconos de marca para servicios de AWS, como AWS Lambda, que puedes colocar como nodos de icono.

¿Cómo represento Step Functions? Como un solo nodo en el diagrama de arquitectura, etiquetado con el nombre de la máquina de estado, y el flujo de trabajo en sí como un diagrama de flujo o un diagrama BPMN aparte.

¿Dónde van los arranques en frío y la simultaneidad? En notas junto a las funciones en las que importan, por ejemplo la simultaneidad aprovisionada en un endpoint sensible a la latencia.

¿Tengo que mostrar los roles de IAM? No como nodos. Anota los permisos que dan forma al diseño y deja las políticas completas en tu código de infraestructura.

Empieza gratis — un puesto, sin tarjeta de crédito.