Laboratorio AWS Step Functions - EtherDev Academy

🚨 INSTRUCCIONES IMPORTANTES

ANTES DE EMPEZAR: Este laboratorio requiere seguir los pasos en orden secuencial. Cada paso debe completarse exitosamente antes de continuar al siguiente. No omitir ningún paso.

📋 Paso a Paso para la Actividad

PASO 1: Verificar Requisitos Previos ⚡

PASO 2: Configurar Entorno Local 🛠️

PASO 3: Probar Funciones Lambda Localmente 🧪

PASO 4: Desplegar Infraestructura en AWS 🚀

PASO 5: Probar API Gateway y Step Functions 🔗

PASO 6: Monitorear y Observar Ejecuciones 📊

PASO 7: Limpieza de Recursos 🧹

1. Objetivo del Laboratorio

Este laboratorio implementa un workflow de orquestación simple utilizando AWS Step Functions para procesar órdenes de compra. Aprenderás la diferencia entre coreografía y orquestación de servicios.

Arquitectura del Flujo:

HTTP Request → API Gateway → Step Functions → Lambda Validator → Choice → Lambda Processor → Response

Flujo de Estados:

Validate → Lambda valida los datos de la orden (orderId, items[], total > 0)
Route → Step Functions toma decisión basada en el resultado de validación
Process → Si es válida, Lambda procesa la orden; si no, termina con estado de falla

PASO 1: Verificar Requisitos Previos ⚡

✅ Cuenta AWS Academy

Tener una cuenta de AWS Academy Learner Lab activa
IMPORTANTE: Usar SIEMPRE el rol "LabRole" para todas las operaciones
Acceso a los servicios: Lambda, Step Functions, CloudWatch, API Gateway

✅ Herramientas Locales

Node.js 18.x o superior instalado
npm (incluido con Node.js)
AWS CLI v2 configurado
AWS CDK v2 instalado globalmente:
```
npm install -g aws-cdk
```

✅ Configuración Recomendada

Región sugerida: us-east-1 (Norte de Virginia)
Editor: VS Code con extensiones de AWS (opcional)

✅ Verificación

# Verificar Node.js
node --version
# Debería mostrar v18.x.x o superior

# Verificar npm
npm --version

# Verificar AWS CLI
aws --version

# Verificar CDK
cdk --version

PASO 2: Configurar Entorno Local 🛠️

Opción A: Desarrollo Local (Recomendado para desarrollo)

Navegar al directorio del proyecto:
```
cd ejercicio_step_functions
```
Instalar todas las dependencias:
```
npm run install-all
```
Compilar la aplicación CDK:
```
npm run build
```

Verificar configuración AWS:

aws configure list
aws sts get-caller-identity

Opción B: AWS CloudShell (Recomendado para AWS Academy)

Abrir CloudShell desde la consola AWS
Clonar/subir el proyecto y navegar:
```
cd ejercicio_step_functions
```
Instalar dependencias:
```
npm run install-all
npm run build
```

🔥 CDK Bootstrap (Importante)

Algunas cuentas de AWS Academy ya vienen bootstrappeadas. Verificar primero:

aws cloudformation describe-stacks --stack-name CDKToolkit --region us-east-1

Si NO está bootstrappeado, contactar al docente antes de ejecutar:

# SOLO si el docente lo autoriza
npx cdk bootstrap

PASO 3: Probar Funciones Lambda Localmente 🧪

CRÍTICO: Siempre probar localmente antes del deploy para evitar errores costosos.

Ejecutar Pruebas Automáticas

npm run test-local

Resultado esperado:

🧪 Iniciando pruebas locales del laboratorio Step Functions

📝 Test 1: Validando orden válida...
✅ Test 1 PASÓ: Orden válida procesada correctamente

📝 Test 2: Validando orden inválida...
✅ Test 2 PASÓ: Orden inválida rechazada correctamente

📝 Test 3: Procesando orden válida...
✅ Test 3 PASÓ: Orden procesada y aceptada correctamente

📝 Test 4: Simulando flujo completo Step Functions...
✅ Test 4 PASÓ: Flujo completo simulado correctamente

🎉 TODOS LOS TESTS PASARON EXITOSAMENTE
🚀 Siguiente paso: ejecutar npm run deploy para desplegar en AWS

Si hay Errores

Revisar el código de las funciones Lambda
Verificar sintaxis en archivos JSON de eventos
NO continuar al siguiente paso hasta que todos los tests pasen

PASO 4: Desplegar Infraestructura en AWS 🚀

Comando de Despliegue

npm run deploy

Proceso Esperado

Síntesis de CDK: Compilación y generación de CloudFormation
Confirmación: CDK mostrará los recursos a crear
Deploy: Creación de recursos en AWS (5-10 minutos)

Recursos que se Crearán

✅ 2 funciones Lambda (Validator y Processor) usando LabRole
✅ 1 State Machine de Step Functions
✅ 1 API Gateway REST API usando LabRole
✅ CloudWatch Log Groups para observabilidad
✅ NOTA: No se crean roles IAM nuevos, se usa LabRole existente

Outputs Importantes (Guardar)

Al finalizar verás outputs como:

Outputs:
EtherDevStepFnStack.StateMachineArn = arn:aws:states:us-east-1:123456789012:stateMachine:OrderWorkflowStateMachine
EtherDevStepFnStack.ApiGatewayUrl = https://abc123def4.execute-api.us-east-1.amazonaws.com/prod/
EtherDevStepFnStack.ApiGatewayOrdersEndpoint = https://abc123def4.execute-api.us-east-1.amazonaws.com/prod/orders/process
EtherDevStepFnStack.ValidatorFunctionArn = arn:aws:lambda:us-east-1:123456789012:function:EtherDevStepFnStack-ValidatorFunction
EtherDevStepFnStack.ProcessorFunctionArn = arn:aws:lambda:us-east-1:123456789012:function:EtherDevStepFnStack-ProcessorFunction
EtherDevStepFnStack.LogGroupName = /aws/stepfunctions/EtherDevOrderWorkflow

🔥 IMPORTANTE: Copiar y guardar estos valores para las pruebas.

PASO 5: Probar API Gateway y Step Functions 🔗

5.1. Pruebas con API Gateway (Recomendado)

Usar el endpoint del output: ApiGatewayOrdersEndpoint

Caso 1: Orden Válida via curl

curl -X POST \
  https://TU-API-ID.execute-api.us-east-1.amazonaws.com/prod/orders/process \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-1001",
    "items": [
      {
        "sku": "SKU-LAPTOP-001",
        "qty": 1
      },
      {
        "sku": "SKU-MOUSE-002", 
        "qty": 2
      }
    ],
    "total": 1299.99
  }'

Respuesta esperada:

{
  "message": "Order processing started successfully",
  "executionArn": "arn:aws:states:us-east-1:123456789012:execution:OrderWorkflowStateMachine:uuid",
  "timestamp": "Wed, 03 Nov 2025 10:30:00 GMT"
}

Caso 2: Orden Inválida via curl

curl -X POST \
  https://TU-API-ID.execute-api.us-east-1.amazonaws.com/prod/orders/process \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "",
    "items": [],
    "total": -50.00
  }'

Usando Postman (Alternativa)

Método: POST
URL: Tu endpoint del output
Headers: Content-Type: application/json
Body: Cualquiera de los JSONs de arriba

Usando AWS Console para API Gateway

API Gateway console → tu API → Resources
Seleccionar /orders/process → POST
Hacer clic en "TEST"
Pegar JSON en Request Body
Hacer clic en "Test"

5.2. Pruebas Directas con Step Functions Console

Abrir Step Functions console → tu state machine
Hacer clic en "Start execution"
Usar estos eventos de prueba:

Orden Válida:

{
  "orderId": "ORD-1001",
  "items": [
    {
      "sku": "SKU-LAPTOP-001",
      "qty": 1
    },
    {
      "sku": "SKU-MOUSE-002", 
      "qty": 2
    }
  ],
  "total": 1299.99
}

Orden Inválida:

{
  "orderId": "",
  "items": [],
  "total": -50.00
}

5.3. Verificación de Resultados

Copiar executionArn de la respuesta de API Gateway
Ir a Step Functions console → tu state machine → Executions
Buscar la ejecución por ARN o timestamp
Ver el diagrama visual:
- Caso válido: Validate → Route → Process → Done (Verde)
- Caso inválido: Validate → Route → Rejected (Rojo)

PASO 6: Monitorear y Observar Ejecuciones 📊

CloudWatch Logs

Logs de Lambda Functions

Ubicación: CloudWatch → Log groups → /aws/lambda/<function-name>

Funciones a revisar:

/aws/lambda/EtherDevStepFnStack-ValidatorFunction-<random>
/aws/lambda/EtherDevStepFnStack-ProcessorFunction-<random>

Qué buscar:

Input recibido por cada Lambda
Proceso de validación (Validator)
Tiempo de procesamiento simulado (Processor)
Errores o excepciones

Logs de Step Functions

Ubicación: CloudWatch → Log groups → /aws/stepfunctions/EtherDevOrderWorkflow

Información disponible:

Inicio y fin de cada estado
Transiciones entre estados
Input y output de cada estado
Decisiones tomadas por el Choice state

Logs de API Gateway

Ubicación: CloudWatch → Log groups → API-Gateway-Execution-Logs_<api-id>/prod

Información disponible:

Requests HTTP recibidos
Tiempos de respuesta
Errores de integración
Request/Response mapping

Métricas en Step Functions Console

Ir a Step Functions → tu state machine
Pestaña "Executions" → Ver historial completo
Pestaña "Metrics" → Ver métricas de rendimiento
Hacer clic en una ejecución → Ver detalles paso a paso

PASO 7: Limpieza de Recursos 🧹

Comando de Destrucción

npm run destroy

Confirmación

Are you sure you want to delete: EtherDevStepFnStack (y/n)? y

Recursos Eliminados

API Gateway REST API
State Machine de Step Functions
Funciones Lambda
CloudWatch Log Groups
Cualquier otro recurso creado por el stack

🔥 IMPORTANTE: Ejecutar SIEMPRE la limpieza al terminar para evitar costos.

🔧 Troubleshooting y Problemas Comunes

Error: "CDK bootstrap requerido"

Problema: This stack uses assets, so the toolkit stack must be deployed to the environment

Solución:

Contactar al docente
NO crear recursos IAM manualmente si está restringido

Error: "LabRole no tiene permisos suficientes"

Posibles errores:

User: arn:aws:sts::123456789012:assumed-role/LabRole/user is not authorized to perform: lambda:InvokeFunction
An error occurred (AccessDenied) when calling the StartExecution operation

Solución:

Verificar con el instructor que LabRole tiene permisos necesarios
Revisar la política de LabRole en IAM console
Contactar AWS Academy Support si faltan permisos

Error: "API Gateway endpoint not responding"

Problema: 403, 500 o timeout

Solución:

Verificar URL del endpoint en outputs
Confirmar método POST con Content-Type: application/json
Revisar CloudWatch logs de API Gateway
Alternativa: Usar Step Functions console directamente

Error: "Tests locales fallan"

Problema: npm run test-local no pasa

Solución:

NO continuar con el deploy
Revisar código de funciones Lambda
Verificar sintaxis JSON en eventos
Corregir errores antes de deploy

Error: "Región incorrecta"

Solución:

Verificar región: aws configure get region
Cambiar región en consola AWS
O especificar: CDK_DEFAULT_REGION=us-east-1 npm run deploy

📋 Información Técnica del Proyecto

Arquitectura

ejercicio_step_functions/
├── README.md                 # Este archivo
├── package.json              # Scripts del workspace  
├── test-local.js             # Script de pruebas locales
├── .gitignore               # Archivos a ignorar
├── .editorconfig            # Configuración del editor
├── cdk/                     # Infraestructura CDK
│   ├── package.json         # Dependencias CDK
│   ├── cdk.json             # Configuración CDK
│   ├── tsconfig.json        # Config TypeScript
│   ├── bin/app.ts           # Punto de entrada CDK
│   └── lib/etherdev-stepfn-stack.ts  # Definición del stack
└── src/                     # Código fuente
    ├── validator/index.js   # Lambda validador
    ├── processor/index.js   # Lambda procesador
    └── events/              # Eventos de prueba
        ├── valid-order.json
        └── invalid-order.json

Scripts Disponibles

npm run install-all - Instala todas las dependencias
npm run build - Compila la aplicación CDK
npm run test-local - Prueba funciones Lambda localmente
npm run deploy - Despliega toda la infraestructura
npm run destroy - Elimina todos los recursos

Recursos AWS Creados

AWS::ApiGateway::RestApi × 1
AWS::Lambda::Function × 2 (usando LabRole)
AWS::StepFunctions::StateMachine × 1
AWS::Logs::LogGroup × 4

Consideraciones de AWS Academy

Uso de LabRole:

✅ Funciones Lambda usan LabRole como execution role
✅ API Gateway usa LabRole para invocar Step Functions
✅ No se crean roles IAM adicionales
⚠️ Posibles limitaciones con trust policies

Si hay problemas con LabRole:

Verificar permisos con instructor
Usar Step Functions console directamente (evita API Gateway)
Contactar AWS Academy Support

🎯 Objetivos de Aprendizaje Completados

Al finalizar este laboratorio habrás aprendido:

✅ Orquestación vs Coreografía de servicios
✅ AWS Step Functions para workflows
✅ Integración Lambda con Step Functions
✅ API Gateway como punto de entrada HTTP
✅ Infrastructure as Code con AWS CDK
✅ Observabilidad con CloudWatch
✅ Debugging y troubleshooting distribuido

Siguiente Pasos Sugeridos

Modificar validaciones en Lambda Validator
Agregar más estados al workflow (ej: notificaciones)
Implementar persistencia con DynamoDB
Agregar autenticación a API Gateway
Implementar tests unitarios completos

¡Felicitaciones! Has completado exitosamente el laboratorio de AWS Step Functions. 🎉

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
cdk		cdk
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
test-local.js		test-local.js

utn-frc-iaew/etherdev_step_functions

Folders and files

Latest commit

History

Repository files navigation

Laboratorio AWS Step Functions - EtherDev Academy

🚨 INSTRUCCIONES IMPORTANTES

📋 Paso a Paso para la Actividad

PASO 1: Verificar Requisitos Previos ⚡

PASO 2: Configurar Entorno Local 🛠️

PASO 3: Probar Funciones Lambda Localmente 🧪

PASO 4: Desplegar Infraestructura en AWS 🚀

PASO 5: Probar API Gateway y Step Functions 🔗

PASO 6: Monitorear y Observar Ejecuciones 📊

PASO 7: Limpieza de Recursos 🧹

1. Objetivo del Laboratorio

PASO 1: Verificar Requisitos Previos ⚡

✅ Cuenta AWS Academy

✅ Herramientas Locales

✅ Configuración Recomendada

✅ Verificación

PASO 2: Configurar Entorno Local 🛠️

Opción A: Desarrollo Local (Recomendado para desarrollo)

Opción B: AWS CloudShell (Recomendado para AWS Academy)

🔥 CDK Bootstrap (Importante)

PASO 3: Probar Funciones Lambda Localmente 🧪

Ejecutar Pruebas Automáticas

Si hay Errores

PASO 4: Desplegar Infraestructura en AWS 🚀

Comando de Despliegue

Proceso Esperado

Recursos que se Crearán

Outputs Importantes (Guardar)

PASO 5: Probar API Gateway y Step Functions 🔗

5.1. Pruebas con API Gateway (Recomendado)

Caso 1: Orden Válida via curl

Caso 2: Orden Inválida via curl

Usando Postman (Alternativa)

Usando AWS Console para API Gateway

5.2. Pruebas Directas con Step Functions Console

5.3. Verificación de Resultados

PASO 6: Monitorear y Observar Ejecuciones 📊

CloudWatch Logs

Logs de Lambda Functions

Logs de Step Functions

Logs de API Gateway

Métricas en Step Functions Console

PASO 7: Limpieza de Recursos 🧹

Comando de Destrucción

Confirmación

Recursos Eliminados

🔧 Troubleshooting y Problemas Comunes

Error: "CDK bootstrap requerido"

Error: "LabRole no tiene permisos suficientes"

Error: "API Gateway endpoint not responding"

Error: "Tests locales fallan"

Error: "Región incorrecta"

📋 Información Técnica del Proyecto

Arquitectura

Scripts Disponibles

Recursos AWS Creados

Consideraciones de AWS Academy

🎯 Objetivos de Aprendizaje Completados

Siguiente Pasos Sugeridos

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages