DEV Community: AWS Community Builders

Workflow en Strands: un DAG de tareas ejecutado como herramienta única

Laura Bolaños — Wed, 19 Aug 2026 21:31:31 +0000

En estas notas te explico cómo orquestar agentes con la arquitectura Workflow de Strands Agents utilizando paralelismo y join points, ejemplificado con la construcción de un entregable para preparar y gestionar reuniones como Solutions Architect. Testado de dos maneras: con Gemma4 + Ollama (local) y con la API de Gemini.

Introducción

La idea principal es experimentar con el patrón de orquestación workflow sin gastar en suscripciones pagas de tokens, dejando el deploy en AWS para otra instancia. Durante el desarrollo y testing me encontré con algunos inconvenientes de features no implementadas y descubrí proveedores de modelos soportados al día de hoy.

🗒 El caso de uso que elegí para representar el patrón de orquestación Workflow es un copiloto para Solutions Architects que prepara y cierra discovery meetings con clientes: investiga la empresa, mapea a los stakeholders, genera preguntas de discovery fundamentadas en ese contexto, resume la reunión una vez ocurrida, y sintetiza todo en un entregable de seguimiento (email + próximos pasos + gaps a resolver).

La idea del diseño se sacó del playground de PartyRock de Jeff Escott

En las secciones siguientes cubro los conceptos claves del patrón, el diseño e implementación del caso de uso, los hallazgos reales de ejecución con ambos modelos, y las evaluaciones con strands-agents-evals.

Conceptos Claves

➡ Workflow de Agentes es un patrón de orquestación coordinado en una secuencia definida.

Cada Agente realiza una serie de tareas definidas. El desarrollador puede descomponer tareas complejas en componentes manejables y distribuirlos entre agentes especializados. Cada workflow tiene un control explícito del orden de ejecución de las tareas, las dependencias y el flujo de información entre tareas.

Workflow es apropiado:

Cuando se tiene un proceso complejo pero repetible que se desea encapsular en una herramienta única, confiable y reutilizable, un Workflowes un grafo de tareas definido por el desarrollador que un agente puede ejecutar como una acción única y potente.
Si tenemos complejidad en los procesos con múltiples pasos, resolución de tareas con distintas etapas secuenciales.
Procesos que requieren subagentes especializados en cada etapa o un seguimiento detallado en cada paso
Ejecutar tareas independientes en paralelo, mientras hay gestión de independencias. De esta manera optimizamos recursos.
Si tenemos que reintentar pasos por error tareas especificas sin reiniciar todo el flujo.

Para clarificar las diferencias entre patrones de orquestación, te muestro una comparativa entre workflow, graph y swarm. La mayor diferencia a considerar es cómo se determina la ruta de ejecución :

	Workflow	Graph	Swarm
Concepto fundamental	Un grafo de tareas predefinido (DAG) ejecutado como una herramienta única y no conversacional.	Un flowchart estructurado y definido por el desarrollador, donde un agente decide qué camino tomar.	Un equipo dinámico y colaborativo de agentes que se pasan las tareas de forma autónoma.
Estructura	Un desarrollador define todas las tareas y sus dependencias en el código.	Un desarrollador define todos los nodos (agentes) y aristas (transiciones) con antelación.	Un desarrollador proporciona un pool de agentes. Los propios agentes deciden el camino.
Flujo de ejecución	Determinista y paralelo. El flujo está determinado por el grafo de dependencias. Las tareas independientes se ejecutan en paralelo.	Controlado pero dinámico. El flujo sigue los bordes del grafo, pero la decisión de un LLM en cada nodo determina el camino (path).	Secuencial y autónomo. Un agente ejecuta una tarea y luego cede el control a otro agente adecuado en el enjambre.
¿Permite ciclo?	NO.	SÍ.	SÍ.
Mecanismos de compartir estados	La herramienta captura automáticamente los outputs de las tareas y los pasa como inputs a las tareas dependientes.	Se pasa un objeto de estado compartido a todos los agentes, quienes pueden leerlo y modificarlo libremente.	Todos los agentes disponen de un contexto compartido o memoria de trabajo, que contiene la solicitud original, el historial de tareas y el conocimiento de los agentes anteriores.
Historial de conversaciones	Contexto específico de la tarea. Una tarea recibe un resumen curado de los resultados relevantes de sus dependencias, no el historial completo.	Transcripción completa. Todo el historial de diálogo forma parte del estado compartido, lo que proporciona a cada agente un contexto completo y abierto.	Transcripción compartida. El contexto compartido proporciona un historial completo de los handoffs de agentes y el conocimiento aportado por agentes anteriores, disponible para el agente actual.
Control del comportamiento	La solicitud del usuario puede activar un workflow predefinido, pero no puede alterar su estructura interna.	La información que introduce el usuario en cada paso puede influir directamente en la ruta que seguirá el grafo a continuación.	La indicación inicial del usuario define el objetivo, pero a partir de ahí el Swarm corre de forma autónoma.
Escalabilidad	Escala bien en operaciones repetibles y complejas.	Escala bien en procesos complejos(muchas ramificaciones, condiciones).	Escala en función del número de agentes especializados en el equipo y de la complejidad de la tarea colaborativa.
Manejo de errores	Sistémico. Un fallo en una tarea detendrá todas las tareas dependientes posteriores. Es probable que todo el workflow entre en estado `failed`.	Controlable. Un desarrollador puede definir aristas de "error" explícitas para dirigir el flow a un nodo de error-handling si falla un paso.	Agent-driven. Un agente puede decidir transferir la tarea a un especialista en manejo de errores. El sistema se basa en tiempos de espera y límites de transferencia para evitar bucles infinitos.

➡ Conceptos genéricos de Workflow agénticos

Para la implementación del caso de uso, solo usé la workflow tool, una de las ~45 tools nativas disponibles en strands-agents-tools.

Componentes claves en la arquitectura:

⭐Definición y distribución de tareas. Cada tarea necesita una descripción especifica de qué debe lograr el agente, una asignación que haga matching con el agente adecuado según sus capacidades, y un nivel de prioridad que determine qué se ejecuta primero cuando hay margen de elección.

⭐Gestión de dependencias. Algunas tareas deben ejecutarse en un orden específico (dependencias secuenciales), mientras que las tareas independientes pueden correr en simultáneo (ejecución paralela). En la ejecución paralela tener en cuenta que el modelo de IA que se utilice debe permitirlo.
Los join points son los puntos donde varios caminos paralelos convergen antes de continuar. En el caso de uso elegido, los dos join points son discovery_questions (espera a company_research + stakeholder_mapping) y follow_up_actions (espera a discovery_questions + meeting_summary).

⭐Flujo de información. El mapeo de input/output conecta la salida de un agente con la entrada de otro, la preservación de contexto mantiene la información relevante a lo largo de todo el workflow, y la gestión de estado permite trackear el progreso general del workflow.

Parámetros básicos del workflow:

action → create, start, status (indica si hubo error o no), list, delete.

workflow_id → identificador único del workflow.

tasks → lista de tareas con sus correspondientes propiedades

Algunas propiedades dentro de cada task:
task_id : Obligatorio. Identificador o nombre de la tarea.

description: Obligatorio. se completa con un resumen de lo que hace la tarea, es un pequeño prompt.

dependencies: Opcional. Encadenas una tarea con la otra para que no se ejecute si las dependencias aún no culminaron.

system_prompt: Obligatorio.

priority: Propiedad numérica que indica prioridad en la ejecución por el modelo.

tools: Opcional. Pero si no lo especificás puede que en la inferencia el modelo decida usar cualquier tool nativa y entre en un loop infinito.
Si no querés que la tarea ejecute ninguna tool se puede especificar cómo "tools": NO_TOOLS, esto no es un valor oficial del SDK, es un workaround verificado empíricamente: se pasa un nombre de tool que no existe en el registry, forzando al sub-agente a correr sin tools. Pasar "tools": [] no funciona porque es falsy en Python y el workflow lo ignora heredando todo el toolset del agente padre.

➡ Topologías de Secuencias y Workflow

En Strands Agents, "Workflow" puede referirse a dos cosas distintas: una arquitectura secuencial que se implementa manualmente encadenando agentes en código Python, o la Workflow Tool (strands-agents-tools), que gestiona dependencias, paralelismo y pasaje de contexto automáticamente.

Workflow Secuencial

En la topología secuencial, cada agente es un objeto Python independiente y el desarrollador conecta las salidas manualmente. Es la forma más simple de encadenar agentes, pero no hay gestión automática de dependencias ni paralelismo.

from strands import Agent
# Create specialized agents
agent1 = Agent(system_prompt="You are Agent 1. Perform the first step.", callback_handler=None)
agent2 = Agent(system_prompt="You are Agent 2. Perform the second step.", callback_handler=None)
agent3 = Agent(system_prompt="You are Agent 3. Perform the final step.")

# Sequential workflow processing
def process_workflow(input_data):
    step1_result = agent1(f"Process: {input_data}")
    step2_result = agent2(f"Process: {step1_result}")
    final_result = agent3(f"Process: {step2_result}")
    return final_result

Workflow Tool

La Workflow Tool gestiona dependencias, paralelismo y pasaje de contexto automáticamente. El desarrollador define la estructura (tasks + dependencies) y la tool se encarga del resto: qué corre en paralelo, qué espera, y qué contexto inyecta a cada tarea dependiente.

from strands import Agent
from strands_tools import workflow

# Create an agent with workflow capability
agent = Agent(tools=[workflow])

# Create a multi-agent workflow
agent.tool.workflow(
    action="create",
    workflow_id="generic_workflow",
    tasks=[
        {
            "task_id": "task1",
            "description": "Description of the first task",
            "system_prompt": "You perform the first task.",
            "priority": 5
        },
        {
            "task_id": "task2",
            "description": "Description of the second task",
            "dependencies": ["task1"],
            "system_prompt": "You perform the second task.",
            "priority": 3
        },
        {
            "task_id": "task3",
            "description": "Description of the third task",
            "dependencies": ["task2"],
            "system_prompt": "You perform the third task.",
            "priority": 2
        }
    ]
)

# Execute workflow (parallel processing where possible)
agent.tool.workflow(action="start", workflow_id="generic_workflow")
# Check results
status = agent.tool.workflow(action="status", workflow_id="generic_workflow")

➡ Evaluaciones (Evals)

Strands cuenta con una marco oficial para realizar evaluaciones de resultados simples hasta el análisis de interacciones de multiagentes complejos.

Para evaluar el workflow usé strands-agents-evals con el mismo provider configurado en .env (Gemini u Ollama) como juez. En producción la práctica estándar es usar un modelo más capaz como judge (ej. el workflow corre con gemini-2.0-flash y el judge usa gemini-2.5-pro), pero para este proyecto educativo se unifica por simplicidad.

Combiné dos tipos de evaluación:

LLM-as-a-judge — el modelo evalúa la calidad del output final:

Evaluador	¿Qué evalúa?	Escala
`OutputEvaluator`	Verifica que `follow_up_actions` tenga las 3 secciones obligatorias (email, next steps, gaps) y que el contenido esté fundamentado en los datos reales de la reunión.	0 / 0.5 / 1
`HelpfulnessEvaluator`(1)	Evalúa si el entregable final es útil para un Solutions Architect — no solo si tiene el formato correcto. (Es una instancia de OutputEvaluator con rubric propio, no una clase separada del SDK!)	0 / 0.5 / 1

(1)HelpfulnessEvaluator del SDK requiere trazas OpenTelemetry que la Workflow Tool no provee. Se reemplazó por un segundo OutputEvaluator con rubric de helpfulness.
Cuando usé HelpfulnessEvaluator del SDK, el score devolvió 0.0 con el error: "Trace parsing requires actual_trajectory to be a Session object, got NoneType". El evaluador espera un objeto Session de Strands (que debe contener trazas OpenTelemetry de la ejecución del agente), no solo el texto del output.

Métricas deterministas — evalúan propiedades estructurales del patrón, sin llamadas a LLM:

Métrica	¿Qué mide?
`task_completion_rate`	Fracción de tasks que completaron con `status="completed"` en el JSON persistido.
`join_point_coverage`	Verifica que ambos join points produjeron output no vacío, confirma que la inyección de contexto funcionó.
`required_sections`	Check determinista de las 3 secciones del entregable (email, next steps, gaps).
`stakeholder_coverage`	Verifica que cada stakeholder del input aparece en `discovery_questions`, confirma que el contexto de `stakeholder_mapping` llegó al join point #1.
`keyword_presence`	Presencia de keywords de dominio (con soporte de sinónimos via `\

Descripción de la solución

📦 Repositorio GitHub: github.com/reinalau/strands-workflow

Para la prueba de concepto utilicé dos opciones locales de ejecución que permitió analizar sus resultados, pero se puede utilizar solo una:
a. Ollama + el pequeño modelo gemma4:e2b-it-qat (que pesa poco mas de 4gb) ejecutando en Docker.
En caso que quieras ejecutar realmente las task que son independientes en paralelo, hay que indicarselo a ollama (sino el comportamiento por default es secuencial) :
{% raw %}

# Start the Ollama server with a persistent volume
docker run -d --name ollama -p 11434:11434 -v ollama_data:/root/.ollama ollama/ollama

# Start the Ollama server en parallel
# docker run -d --name ollama -p 11434:11434 -v ollama_data:/root/.ollama -e OLLAMA_NUM_PARALLEL=3  ollama/ollama

# Download the model
docker exec -it ollama ollama pull gemma4:e2b-it-qat

# Test that the model responds
# If the container has already been created and 
# is currently stopped, simply use: docker start ollama
docker exec -it ollama ollama run gemma4:e2b-it-qat

# Verify that the model is running
docker exec -it ollama ollama ps

b. Api de gemini. La api key se puede generar de manera gratuita desde aquí y utilizar algunos de estos modelos (experimentar con los que te permita):

gemini-2.5-flash-lite
gemini-2.5-flash
gemini-3.5-flash
gemini-3.5-flash-lite

El código está en Python y la estructura del proyecto se diseñó de manera que sea más explicativo su lógica, todo el detalle lo encontrás en el Readme.md del proyecto:

strands-workflow/
├── README.md
├── requirements.txt                  # strands-agents[litellm,ollama], strands-agents-tools, pydantic, pytest
├── .env.example                      # MODEL_PROVIDER, GEMINI_API_KEY, OLLAMA_MODEL_ID
├── .gitignore
├── pytest.ini                        # pythonpath=. so tests/ and evals/ resolve src./config imports
│
├── src/
│   ├── __init__.py
│   ├── config.py                     # get_model_config(): single global provider (Gemini or Ollama) via MODEL_PROVIDER env var
│   ├── main.py                       # Entry point: builds tasks, creates+starts the workflow, assembles the final .md
│   │
│   ├── agents/
│   │   ├── __init__.py
│   │   └── prompts.py                # System prompts per task_id (company_research, stakeholder_mapping, etc.)
│   │
│   ├── workflow/
│   │   ├── __init__.py
│   │   ├── builder.py                # build_tasks(): builds the task list — task_id, dependencies, priority
│   │   ├── deliverable.py            # Reads the persisted workflow JSON and assembles the final .md
│   │   └── instrumentation.py        # Timing hook: logs START/END + duration per task
│   │
│   ├── models/
│   │   └── schemas.py                # Pydantic: DiscoveryMeetingInput
│   │
│   └── utils/
│       ├── logging_config.py         # Tees stdout+stderr to logs/, optional DEBUG level
│       └── report_export.py          # Writes the final .md to outputs/
│
├── tests/
│   ├── __init__.py
│   ├── test_config.py                # get_model_config(): provider resolution + error if API key is missing
│   ├── test_workflow_structure.py    # Validates the workflow is well-formed: no cycles, existing dependencies, correct join points
│   ├── test_schemas.py               # Pydantic validation of DiscoveryMeetingInput
│   ├── test_report_export.py         # Generates the .md from a mocked workflow JSON
│   └── test_instrumentation.py       # Verifies install_task_timing_hooks() logs START/END with duration, without calling a real LLM
│
├── examples/
│   └── sample_input.json             # Sample input to run the workflow quickly
│
├── evals/
│   ├── __init__.py
│   ├── evaluate_workflow.py          # strands-evals runner: OutputEvaluator + HelpfulnessEvaluator + deterministic metrics
│   ├── metrics.py                    # Domain metrics: task completion rate, join point coverage, required sections, stakeholder coverage, keyword presence
│   └── test_cases/
│       └── workflow_eval_cases.json  # Input + expected properties per eval case
│
├── logs/
│   └── .gitkeep                      # logs/run_<timestamp>.log, gitignored otherwise
│
└── outputs/
    └── .gitkeep                      # .md generated per run, gitignored otherwise

Ejecución Local

Una vez que tengas el repositorio del código fuente clonado y el docker de ollama con el modelo gemma 4 o la api key de gemini generada, pasamos armar el ambiente.

Los requerimientos que vas a encontrar en requirements.txt :

strands-agents[litellm,ollama]==1.52.0
strands-agents-tools==0.8.6
ollama==0.5.1
pydantic==2.13.4
pytest==8.3.4
strands-agents-evals>=1.0.0
python-dotenv==1.0.1

pip install -r requirements.txt

En .env se necesitan estos valores. Notar que depende el modelo que elegimos podemos intercambiar el MODEL_PROVIDER:

# Select ONE provider: "ollama" or "gemini"
MODEL_PROVIDER=ollama

# --- Gemini (only required if MODEL_PROVIDER=gemini) ---
# Free tier key: https://aistudio.google.com/apikey
GEMINI_API_KEY=YourApiKey
GEMINI_MODEL_ID=gemini-3.5-flash-lite

# --- Ollama (only used if MODEL_PROVIDER=ollama) ---
# Must have the Ollama daemon running locally: https://ollama.com
# Pull the model first: ollama pull gemma4:e2b-it-qat
OLLAMA_MODEL_ID=gemma4:e2b-it-qat
OLLAMA_HOST=http://localhost:11434

# --- Workflow persistence ---
# Redirects strands_tools' internal workflow state JSON into logs/ instead of
# the default ~/.strands/workflows/ — keeps everything from one run together.
STRANDS_WORKFLOW_DIR=logs/workflows

cp .env.example .env

En src/config.py está la configuración de ejecución, en este caso de uso utilicé parámetros como la temperature y max_tokens (limita los tokens que pueden gastar los agentes).
→ Si optas por ejecutar con el provider ollama hay que tener en cuenta el valor de la ventana de contexto: num_ctx.
→ Si optas por ejecutar con la apikey de Gemini, en el SDK de Strands, el dispatcher create_model que usa workflowinternamente soporta estos modelos solo vía litellm ("model_provider": "litellm")

Las pruebas están organizadas en tests/ en un solo nivel: ejecución rápida y determinista. Validan la estructura del workflow (sin ciclos, dependencias existentes, join points correctos), el schema del input con Pydantic, la exportación del .md desde un JSON mockeado, y los hooks de timing (sin llamadas al LLM).

python -m pytest

Ejecución del Workflow principal. En examples/sample_input.txtestá el input de ejemplo en un formato json:

{
"company_name": "...",
"known_challenges": "...",
"stakeholders": "...",
"raw_meeting_notes": "..."
}

Se puede ejecutar contra el modelo ollama local o vía api de gemini comentado más arriba.

python -m src.main

🎯 Un bug real: durante las pruebas descubrí que usando Gemini con paralelismo real puede hacer crashear el proceso de forma intermitente (y no es un problema de Windows, ocurre también en Linux). La causa es un bug conocido y abierto en LiteLLM: el cliente HTTP que usa para el streaming de Gemini es un singleton global que no distingue entre los distintos event loops que crea cada tarea del workflow al correr en paralelo.
Solución aplicada: limitar la ejecución a un hilo por vez cuando el proveedor es Gemini, vía la env var STRANDS_WORKFLOW_MAX_THREADS=1 de Strands.

El log de las llamadas del workflow está en logs/. Contiene la data cruda que permite verificar si hubo paralelismo, cuanto tiempo tarda cada task, etc.

El resultado final
Es un documento markdown con diferentes secciones como:
Company Research - Stakeholder Mapping - Meeting Summary - Discovery Questions - Follow-up Deliverable and Gap
Se guarda en outputs/discovery_meeting_yyyymmdd_hhmmss.md.

Por último, hice una evaluación de pruebas sobre el workflow multiagente real con el concepto de "Evals". Ejecuta el workflow completo contra el modelo configurado, corre los evaluadores LLM-as-judge y las métricas deterministas, muestra los resultados en consola y guarda el reporte completo en outputs/eval_report_<timestamp>.json.

python  -m  evals.evaluate_workflow

📝 Nota: La explicación del código fuente y paso a paso de la ejecución se encuentra detallado en el README.md en github .

Conclusiones y lecciones aprendidas

El patrón Workflow en Strands resuelve en lineas generales lo que indica su documentación. Dependency resolution, paralelismo real y context passing automático entre join points funcionaron correctamente y sin código extra de orquestación. El DAG se ejecuta en el orden correcto y los join points reciben el contexto inyectado de sus dependencias sin intervención manual.
La Workflow Tool de Strands está en maduración activa. pause/resume están documentados como Advanced Features pero no implementados — al ejecutarlos devuelven "🚧 Action '...' is not yet implemented", verificado contra el código fuente instalado. El workflow puede quedar colgado indefinidamente si una task termina en error (el loop interno gira para siempre esperando dependientes que nunca se vuelven "ready"). El resultado de cada task no se expone via API... hay que leer el JSON persistido directamente.
Algunos comportamientos requieren workarounds no oficiales. La herencia de tools en sub-agentes no está documentada. Por defecto cada sub-agente hereda todo el toolset del padre, incluida la workflow tool, lo que con modelos agénticos lleva a llamadas recursivas reales. "tools": [] (lista vacía) no funciona como restricción porque es falsy en Python — la solución es NO_TOOLS (["__no_tools__"]), un placeholder que fuerza filtered_tools a quedar vacío. No encontré hooks públicos para observar timing por task, se requiere monkeypatch sobre WorkflowManager.execute_task.
Los hooks de Strands tienen un mecanismo LimitToolCounts (via BeforeToolCallEvent) que permite cancelar una tool cuando se invoca más veces de lo permitido, útil como guardrail contra loops. Sin embargo, no aplica al bug de herencia de la Workflow Tool, ese mecanismo actúa sobre el agente padre, pero los sub-agentes creados internamente por el framework son instancias separadas sobre las que no hay control para registrar hooks desde afuera. Por eso "tools": NO_TOOLS sigue siendo la solución correcta.
Concurrencia del workflow tool con Gemini. Cuando hay tasks en paralelo + LiteLLM/aiohttp, se produce un RuntimeError: loop is not the running loop intermitente. Cada task corre en su propio thread con su propio asyncio.run(), y el cierre del connector de aiohttp cae en el loop equivocado. Se solucionó colocando una variables de entorno de Strands STRANDS_WORKFLOW_MAX_THREADS=1, limitando la concurrencia. (esto no sucede con Ollama-Gemma4 via Docker).

Recursos

Curso Fundamentos (hacelos!)
Building AI Agent Harnesses with Strands Agents
Building AI Agent Harnesses – Video Course
Documentación Strands Agents
Agent Workflows
Evals
Otros
5 Multi-Agent Patterns in Strands

SnapStart for Python Lambda

Sabarish Sathasivan — Wed, 19 Aug 2026 18:17:49 +0000

Recently we built an analytical API on Lambda using Python 3.12, FastAPI and DuckDB to query Parquet files in S3. The functionality worked fine, but we ran into cold start issues, mainly from initializing DuckDB and FastAPI at startup. This article explains how we used Lambda SnapStart to reduce that cold start, and what we learned from the experience.

Why DuckDB?

DuckDB is an open-source, in-process analytical (OLAP) database engine. The simplest mental model is: it is SQLite, but optimized for analytics.

Because it runs in-process inside the Lambda, there is no database server or cluster to manage, and no database credentials to handle, as S3 is read through the Lambda execution role. It also queries Parquet directly, including Parquet objects in S3:

SELECT
    count(*) AS request_count,
    median(response_time_ms) AS median_ms,
    quantile_cont(response_time_ms, 0.95) AS p95_ms
FROM read_parquet(
    's3://example-bucket/website-requests/*.parquet'
);

What is Lambda SnapStart?

Every time Lambda spins up a new environment, it runs your initialization code again. SnapStart changes when that happens: the init runs when you publish a version. Lambda takes a snapshot of the environment after it is initialized, encrypts it, and caches it. From then on, Lambda restores new environments from that snapshot instead of starting from scratch.

Here is what that looks like on a cold request:

Without SnapStart
  start the runtime
  -> run the initialization code
  -> handle the request

With SnapStart
  restore the snapshot
  -> handle the request

SnapStart is currently available on three runtimes, but it is not free everywhere:

Runtime	Extra SnapStart charge
Java 11 and later	None
Python 3.12 and later	Snapshot caching and restoration
.NET 8 and later	Snapshot caching and restoration

Sample project

Let's try to explain SnapStart with a website-performance API. This API queries the performance of a website, with the data stored in S3. Built with FastAPI, it takes a date range and an optional page, then uses DuckDB to scan the Parquet files for request count, median and p95 response time, error count and error rate, overall and per page.

The complete source is available in the python_lambda_with_snapshot_support repository.

The CDK project in the repository deploys the following resources:

Implementation

The CDK stack deploys two Lambda functions:

web-perf-without-snapstart runs app.lambda_handler
web-perf-with-snapstart runs app_snapstart.lambda_handler and has SnapStart enabled

Everything else is identical: Python 3.12, x86_64, 1024 MB, a 30 second timeout, and the same ZIP.

The shared code sits in src/app.py, which holds the DuckDB query class, the FastAPI app and the Mangum handler. src/app_snapstart.py is a thin wrapper that imports it, registers the after-restore hook and re-exports the handler.

The sections below cover the code changes SnapStart needed.

Keep expensive initialization at module level

The DuckDB connection, the FastAPI app and the route registration all happen at module level in src/app.py, so web-perf-with-snapstart captures them in its snapshot.

analytics = DuckDBWebsiteAnalytics(
    dataset_uri=os.getenv(
        "WEBSITE_DATASET_URI",
        "data/website-requests/*.parquet",
    ),
    aws_region=os.getenv("AWS_REGION") or os.getenv("AWS_DEFAULT_REGION"),
)
app = FastAPI(
    title="Website performance analytics API",
    version="2.0.0",
    docs_url=None,
    redoc_url=None,
)

Refreshing S3 Connection

DuckDB creates its S3 secret during init, so whatever credentials it resolved are part of the snapshot. One snapshot can then be restored many times over several hours.

So src/app_snapstart.py recreates that secret after every restore:

"""SnapStart entry point."""

from snapshot_restore_py import register_after_restore

import app


@register_after_restore
def refresh_credentials_after_restore() -> None:
    app.analytics.refresh_s3_credentials()


lambda_handler = app.lambda_handler

Most functions don't need a hook. When SnapStart is on, the runtime switches to container credentials rather than the access-key environment variables, specifically so they don't expire before a restore, and SDK connections usually resume on their own. We rebuild the secret anyway: it's one cheap call, and AWS advises refreshing ephemeral data like temporary credentials in the handler even without SnapStart.

Keep hooks quick. Runtime load and all after-restore hooks share a 10-second budget before SnapStartTimeoutException.

Wiring it up in CDK

SnapStart is a function-level setting, and it applies to every version published from it:

with_snapstart = lambda_.Function(
    # identical configuration omitted
    snap_start=lambda_.SnapStartConf.ON_PUBLISHED_VERSIONS,
)

with_snapstart_alias = lambda_.Alias(
    self,
    "WithSnapStartLiveAlias",
    alias_name="live",
    version=with_snapstart.current_version,
)

Ensure that API Gateway points to the alias. Pointing it at the function's unqualified ARN invokes $LATEST, which cannot use SnapStart, so cold starts stay slow.

Performance

Both functions ran with the same configuration:

Memory: 1024 MB
Region: us-east-1
Architecture: x86_64
Package type: ZIP

Test strategy: we built a harness that forces cold starts by publishing a fresh version, then firing 30 concurrent requests at each API. That gives 30 cold starts per function per endpoint, confirmed by Init Duration in the REPORT lines of the function without SnapStart, and Restore Duration in the REPORT lines of the SnapStart function. A SnapStart function's REPORT has no Init Duration field at all, because it initialized at publish time; that value lands in a separate INIT_REPORT record.

Client-side through API Gateway:

Endpoint	Metric	Without SnapStart	With SnapStart	Improvement
`/health`	median	5478.9 ms	1189.0 ms	78.3%
`/health`	p95	6136.9 ms	1349.6 ms	78.0%
`/analytics/website`	median	7589.8 ms	4057.7 ms	46.5%
`/analytics/website`	p95	8381.3 ms	4217.9 ms	49.7%

Improvement is (without - with) / without * 100.

Approximate monthly cost

The following cost is calculated for a SnapStart-enabled Lambda running a single published version in us-east-1 at 1024 MB. Lambda bills per GB-second, so 1024 MB appears as 1 GB in the calculations.

Assumptions:

100,000 requests a month
500 ms average billed duration
the version is active all month
1% of invocations restore a snapshot

Component	Calculation	Monthly cost
Requests	100,000 ÷ 1,000,000 × $0.20	$0.02
Duration	100,000 × 0.5 s × 1 GB × $0.0000166667	$0.83
SnapStart cache	2,592,000 s (30 days) × 1 GB × $0.0000015046	$3.90
SnapStart restores	1,000 × 1 GB × $0.0001397998	$0.14
Total		$4.89

The cache is the largest item, and it is billed on memory and uptime rather than traffic. Restores scale with how often Lambda creates environments, which invocation count alone cannot tell you:

Restore rate	Restores	Restore cost	Total
1%	1,000	$0.14	$4.89
10%	10,000	$1.40	$6.15
100%	100,000	$13.98	$18.73

Gotchas

Every published version keeps its own cached snapshot, billed for at least three hours and for as long as the version exists. Delete the ones you don't need.
Lambda re-runs your init code when it patches snapshots, and bills you for it, so "runs once at publish" is not quite true.
Enabling SnapStart isn't enough. If API Gateway hits the unqualified ARN it gets $LATEST and no SnapStart.
Don't trust a connection opened during init.
One snapshot seeds many environments, so anything unique from init gets duplicated. Generate per-request values in the request.
Publishing is slower. The version sits in Pending until the snapshot is built, so wait for Active before moving the alias.
SnapStart can't be combined with provisioned concurrency. They solve the same problem in different ways, so pick one.
No Amazon EFS, no Amazon S3 Files, and no ephemeral storage above 512 MB. The last one matters for DuckDB, since large joins and sorts spill to /tmp.

Conclusion

SnapStart brought our initialization down from seconds to under a second, which is a real gain on a cold request. It does nothing for query time, and the snapshot cache costs money whether the function is called or not.

Worth trying, but measure it on your own workload before you commit to it.

References

Zero-Downtime Releases with Docker Compose on One EC2 Instance

Yusuf Adeyemo — Wed, 19 Aug 2026 17:11:13 +0000

Imagine this scenario. You have one EC2 instance. It runs seven containers: a web application, two background workers, a database, a cache, a RADIUS server, and a reverse proxy. You push a change. Your pipeline connects to the instance and runs this command:

docker compose up -d --build backend

Docker builds the image. Docker then stops the old container and starts the new one. The build takes 90 seconds. The application takes 20 more seconds to open its database connections. For almost two minutes, your users get a 502 error.

For Our WiFi Hotsopt platform, those two minutes have a direct cost. A customer at a hotel front desk pays for a data plan on a phone. If the API is down at that moment, the payment provider sends a webhook to a server that cannot answer it. The customer pays, and the customer gets no internet access.

The usual advice is to move to Amazon ECS or Amazon EKS. That advice is correct at a certain size. It was not correct for me. This article shows the method I use instead: a blue/green release on one EC2 instance, with Docker Compose, a container health check, and an atomic proxy reload.

Why I did not move to ECS

I want to be honest about this decision, because the cost is not only money.

A move to ECS adds an Application Load Balancer, an ECR repository, task definitions, and a service definition. It also adds a new failure surface that I must learn before my first outage, not during it. My platform serves one region and a small number of tenants. One t3 instance holds the full stack, and it has spare capacity.

There is also a technical constraint. My gateways dial into a WireGuard hub. That hub must run on the host, because it needs kernel and network interface access. A FreeRADIUS container answers UDP on the same box, over that tunnel. A move to Fargate would divide this stack between two networks with no advantage.

So the question became simple. Can one EC2 instance do a zero-downtime release? It can. The pattern is older than the container orchestrators, and the orchestrators did not invent it.

The four parts of the design

A blue/green release needs four things. Each one maps to a small piece of code.

Two identical slots. Only one slot takes traffic at a time.
A health check. The new slot must prove that it works.
A switch. One action moves all traffic from the old slot to the new slot.
A record of the active slot. The next release must know where to go.

Here is the flow:

  release starts
       │
       ├─ build the image, tag it as the idle slot (green)
       ├─ run the database migration one time
       ├─ start green, and wait for its health check
       │ └─ green is unhealthy? stop green, keep blue live, exit
       ├─ tell the proxy to send traffic to green ← the switch
       ├─ write "green" to the active-slot file
       ├─ wait 30 seconds for in-flight requests
       └─ stop blue

Note the order. The proxy switches only after the health check passes. Every failure before the switch leaves the old version live.

Two slots with Compose profiles

Docker Compose supports YAML anchors and profiles. An anchor removes the duplication between the two slots. A profile keeps the idle slot out of a normal docker compose up.

x-backend-common: &backend-common
  restart: unless-stopped
  env_file: .env.prod
  stop_grace_period: 45s
  depends_on:
    postgres:
      condition: service_healthy
  healthcheck:
    test: ["CMD", "python", "-c",
      "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/internal/health/ready', timeout=2)"]
    interval: 3s
    timeout: 3s
    retries: 20
    start_period: 60s

services:
  backend_blue:
    <<: *backend-common
    image: app-backend-blue
    profiles: ["deployment"]

  backend_green:
    <<: *backend-common
    image: app-backend-green
    profiles: ["deployment"]

Two settings in this block prevent common release errors.

start_period: 60s gives the container time to start before Docker counts a failed check. Without it, a slow start looks like a broken release.

stop_grace_period: 45s sets the time between the graceful stop signal and the forced stop signal. My web server has a 30-second graceful timeout. The grace period must be longer than that timeout. If it is shorter, Docker stops a process by force during a request.

The health check must query the database

A health check that only proves that the process is alive is not sufficient. My readiness endpoint makes one query:

@require_GET
@never_cache
def ready(request):
    """The process is ready for traffic only when its database is reachable."""
    try:
        with connection.cursor() as cursor:
            cursor.execute("SELECT 1")
            cursor.fetchone()
    except Exception:
        return JsonResponse({"status": "unavailable"}, status=503)
    return JsonResponse({"status": "ok"})

This endpoint answers the only question the release script asks: can this container serve a real request? A liveness probe cannot answer that question. I keep both endpoints, and I use only the readiness endpoint for the cutover.

Migrations are a release action, not a start command

Many teams put the database migration in the container start command. Do not do this in a blue/green release.

During the release, the old version and the new version are both live. If the new container changes the schema as it starts, the old container can fail immediately. The migration must run one time, as its own step:

docker compose run --rm --no-deps backend_green python manage.py migrate --noinput

This rule has a consequence. Every schema change must use the expand/contract method. First you add the new column, and you keep the old column. You release the code that writes to both. Only in a later release do you remove the old column. The old version must continue to operate against the new schema for the length of the cutover.

The switch

My reverse proxy is Caddy, in a container. The configuration file names the upstream by its Compose service name. A template holds the name backend:8000, and one command writes the file for the correct slot:

sed "s/backend:8000/${upstream}:8000/g" caddy/Caddyfile.template > caddy/Caddyfile.next

The next step is the part I recommend most. The script does not send the new file to the live proxy. It first validates the file in a disposable container:

docker compose run --rm --no-deps caddy \
  caddy adapt --config /etc/caddy/Caddyfile.next \
  --adapter caddyfile --pretty --validate > caddy/Caddyfile.next.json

A bad configuration file now fails in a container that serves no traffic. Only a valid file becomes the live file:

mv -f caddy/Caddyfile.next caddy/Caddyfile
docker compose exec -T caddy caddy reload --config /etc/caddy/Caddyfile.json --force

mv on the same filesystem is atomic. No process can read a file that is half written. The proxy reload is also atomic: the proxy loads the new configuration into memory, and it applies the change in one action. If the load fails, the previous configuration continues to serve traffic. The script then puts the previous file back on disk, so a later restart cannot start the rejected configuration.

The failure paths

A release with no error is the easy part. These are the failures that the script must also handle.

The new slot never becomes healthy. An error trap stops the new slot and prints its last 200 log lines. The old slot never stopped, so there is no outage.

The proxy rejects the new configuration. The reload fails, the old configuration stays live, and the script exits. The trap then stops the new slot.

The disk write of the active-slot file fails. This one is easy to miss. At this point the proxy already sends traffic to the new slot. If the script exits here, the trap stops the slot that now serves all traffic. So the script switches the proxy back to the old slot first:

if ! { printf '%s\n' "$target" > .backend-active.next && mv -f .backend-active.next .backend-active; }; then
  ./scripts/reload-caddy.sh "$active" || true
  exit 1
fi

Requests arrive during the switch. The proxy accepts a request one microsecond before the reload. The old container must answer it. This is why the script waits 30 seconds before it stops the old slot.

What this method does not give you

I must be clear about the limits of this method. Do not use it in a system that has different requirements.

This method gives you zero-downtime releases. It does not give you high availability. The instance is one point of failure. A hardware event, a full disk, or a kernel panic stops everything.

It does not give you horizontal scale. When one instance is not sufficient, you need a load balancer and more than one host. At that point the orchestrator is worth its complexity, and ECS is the shorter path.

This method also keeps state on the instance. My database runs in a container with a volume, so my backup procedure, not my instance, is my recovery plan.

Use this method when one instance holds your load, and your releases still cause downtime. Move to ECS when one instance is no longer sufficient. Do not move earlier only because the release procedure is the problem. The release procedure has a smaller answer.

From Panic to Peace: Mastering Zero-Downtime ECS Deployments

N Chandra Prakash Reddy — Wed, 19 Aug 2026 16:28:37 +0000

Friday afternoon. The code is merged, the pipeline is green and the release is ready. But instead of pressing the deploy button and heading out for the weekend, your team is haggling who needs to stick around "just in case" everything catches fire.

Let’s be real. Deploying new code to production is like placing a bet on the roulette table.

You start the app, watch the server logs like a hawk, and hope the customer service channel is silent. If an alert is triggered, there is panic. You hustle to determine what broke, patch it live, or execute a nasty manual rollback while users are down.

Does this sound familiar? This is a stressful routine and is very typical in software engineering. But it doesn’t have to be this way. Modern traffic-shifting tactics on Amazon Elastic Container Service (ECS) can turn stressful releases into repetitive, automated processes.

Now you can take control of your deployments with Blue-Green and Canary tactics.

The Vicious Cycle of Deployment Dread

Here is the point … when delivering software is hard, teams naturally want to do it less often.

If releasing code takes downtime, late night coordination and significant risk, you start batching your changes. You don't deploy a single minor feature on a Tuesday, you combine three weeks of updates into one enormous weekend release.

And that’s a huge problem. Larger batches of code have more variables, more possible conflicts and a much greater danger of breaking something vital. The pain when that huge discharge inevitably bombs strengthens your fear of deploying.

To break this loop you need to be able to test in a true production environment without impacting the users and you also need to be able to roll back changes immediately if something goes wrong.

The Two-House Strategy: Blue-Green Deployments

Imagine that you are moving into a new residence. You simply build an exact replica of your house next door instead of loading all your stuff into a truck, selling your old house and praying the new one has functional plumbing.

You bring your furniture in, check the water pressure, sleep on the bed for a night, and make sure it’s perfect. Then when you are happy you just move your mailing address to the new house. If the roof starts leaking the next day, you just change your address back and move next door to your previous, perfectly functional home.

This is called a Blue-Green deployment in the cloud world.

How the Dual Environment Works

You have the same infrastructural settings. We can call the existing live environment “Blue” and the freshly updated environment “Green”.

Step 1: The Shadow Launch. Your ECS pipeline distributes the new container image to the Green environment. At this stage 100% of your live client traffic is still going to the Blue environment.
Step 2: Private Validation. Your team does testing against the green environment. It is a totally accurate testing ground because it is connected to the same production databases and employs the same networking rules.
Step 3: The Swap. When the Green environment has passed all of the checks, you adjust your Application Load Balancer (ALB) to send traffic to the Green environment.
Step 4: The Safety Net. The old Blue environment is still running for a pre-determined cool down period.

You’re probably wondering… what if a little bug snuck through our testing? You just flip the load balancer back to Blue. The rollback is seconds, not hours.

Defining Blue-Green Infrastructure

To get this working within AWS using Terraform you need to create two target groups and let ECS manage the traffic moving.

# The target group for our current live traffic
resource "aws_lb_target_group" "primary_tg" {
  name        = "app-primary-tg"
  port        = 80
  protocol    = "HTTP"
  vpc_id      = aws_vpc.main_network.id
  target_type = "ip"

  health_check {
    path                = "/api/health"
    interval            = 15
    healthy_threshold   = 2
  }
}

# The target group for our incoming new releases
resource "aws_lb_target_group" "secondary_tg" {
  name        = "app-secondary-tg"
  port        = 80
  protocol    = "HTTP"
  vpc_id      = aws_vpc.main_network.id
  target_type = "ip"

  health_check {
    path                = "/api/health"
    interval            = 15
    healthy_threshold   = 2
  }
}

You set up your ECS service to use the CODE_DEPLOY controller (or native ECS deployment tools) to handle the transition between the two target groups.

resource "aws_ecs_service" "web_api" {
  name            = "core-web-api"
  cluster         = aws_ecs_cluster.production.id
  task_definition = aws_ecs_task_definition.api_def.arn
  desired_count   = 4

  deployment_controller {
    type = "ECS"
  }

  # Instructing ECS to keep the old tasks around for a safety buffer
  blue_green_deployment_config {
    deployment_ready_wait_time_in_minutes = 10
    terminate_blue_tasks_on_deployment_success {
      enabled               = true
      termination_wait_time = 30
    }
  }
}

The Taste Test: Canary Releases

While Blue-Green provides a good safety net, it still requires all your users to move to the new version at the same time.

And here’s where it gets interesting...what if you only exposed a very small fraction of your consumers to the new code?

Think of it as making a big pot of soup for a banquet. You taste one spoonful, then serve it to 500 visitors. You put sugar instead of salt in the soup; by accident, you only spoiled one spoonful, not the whole dinner party.

Canary deployments slowly transfer traffic to the new version in small increments.

The Phased Rollout Process

Instead of a hard swap, ECS’s canary deployment uses the weighted routing features of an AWS Application Load Balancer.

Phase 1: The Initial Dip. You push the new version out, but only send 5% of your live traffic to it. The other 95% continue with the stable version.
Phase 2: Metric Monitoring. You keep a careful eye on your dashboards. Is that 5% seeing error rate spikes? Seeing database slowness growing up?
Phase 3: The Ramp-Up. If the system seems healthy after a period of time, you bump the weight up to 20%, then 50% and finally 100%.

If the new version faults out at any stage, you immediately set the ALB weights for the new version back to 0%. The bug’s blast radius is tightly controlled to a small subset of users.

Configuring Weighted Traffic

To do this, you create a listener rule on your AWS load balancer to route traffic based on the supplied weights.

resource "aws_lb_listener_rule" "canary_traffic_split" {
  listener_arn = aws_lb_listener.https_listener.arn
  priority     = 50

  action {
    type = "forward"
    forward {
      target_group {
        arn    = aws_lb_target_group.stable_version.arn
        weight = 90
      }
      target_group {
        arn    = aws_lb_target_group.new_release.arn
        weight = 10
      }
      # Critical: Ensure users don't bounce between versions
      stickiness {
        enabled  = true
        duration = 3600 
      }
    }
  }

  condition {
    path_pattern {
      values = ["/api/*"]
    }
  }
}

See the stickiness configuration in the codeblock. This ensures that a user who lands on the updated version of your app stays on that version for the length of their session. Randomly bouncing a user between two separate codebases every click will be a poor user experience.

Choosing Your Deployment Weapon

Fair enough... neither is always "better" than the other. They encounter quite different operating challenges.

Opt for Blue-Green when:

You are installing internal tools or APIs where a harsh cutover is tolerable.
You want to be able to conduct intensive integration tests on the exact production infrastructure before any real traffic actually hits the servers.
You want your deployment pipeline to be simple and speedy.

Opt for Canary when:

You are deploying really critical functionality (like payment gateway) where even 1 minute outage is fatal.
You need to validate business metrics (e.g. conversion rates or user engagement) and technical data before a full launch.
If the traffic volumes are high, then you will have enough data even with a small 2% slice of traffic to identify anomalies.

Rules for Safe Deployments

Whichever approach you pick, dynamically rerouting traffic adds layers of complication. You can't just lay down in these infrastructure models and expect miracles if you disregard the rest of the ecosystem.

1. The Database Schema Trap

Simply said, your database is not rollback-able, but your code is.

If you change a database column name in your new deployment and direct traffic to the new version, the previous version will immediately crash because it is expecting the old column name. If you ever have to roll back, your application is now broken forever.

If you want zero-downtime deployments then database modifications must be fully backward-compatible. You have to follow a pattern of “expand and contract”:

Deploy 1: Add the new database column (both code versions still function).
Deploy 2: Update the application code to read/write to the new column.
Deploy 3: Remove the old column days later, long after the rollback window has closed.

2. You Must Have Excellent Metrics

Driving blindfolded is like moving traffic without visibility.

How do you know a Canary release is working when you route 10% of your traffic to it? You can’t depend on users to file support tickets. You want automatic dashboards on HTTP 500s, response times, and CPU utilization.

3. Automate the Rollback

Humans panic. Systems do not.

Don’t have a stressed engineer manually modify load balancer weights when anything goes sideways. Use automatic lifecycle hooks. You can use AWS to trigger Lambda functions on ECS deploys. Your Lambda can automatically abort the deployment and roll back traffic if it finds that the new target group is failing health checks.

Key Takeaways

Blue-Green deployments enable an easy escape route by keeping two similar settings that offer a suitable testing ground before going live.
Canary releases minimize the damage of uncovered bugs by first exposing new code to a small subset of users and growing up gradually.
It must be able to work with databases backward. If your database updates break your previous code, you don't have your safety net of rollback anymore.
Observability is a must. If you don't have analytics to see how your application is functioning in real-time, you can't securely move traffic.

Conclusion

Software deployments should be dull, at the end of the day.

By using Blue-Green cutovers for a speedy escape route, or Canary rollouts to reduce the blast radius of issues, you safeguard your users from your mistakes. When engineers are no longer afraid to break the system, they code with more confidence. They merge pull more quickly. They provide little, digestible updates rather than terrifyingly large monoliths.

Long story short...investing time in your ECS deployment architecture is more than simply focusing on server health. It’s about maintaining the mental health of your engineering staff, keeping your weekends intact, and delivering uninterrupted value to your users.

About the Author

As an AWS Community Builder, I enjoy sharing the things I've learned through my own experiences and events, and I like to help others on their path. If you found this helpful or have any questions, don't hesitate to get in touch! 🚀

🔗 Connect with me on LinkedIn

Also Published On

AWS Builder Center

Hashnode

AWS Transit Gateway Policy-Based Routing : le routage intelligent arrive !

sylvainbruas — Wed, 19 Aug 2026 08:59:39 +0000

Le routage réseau sur AWS a longtemps été contraint par une logique simple : le trafic est acheminé en fonction de l'adresse IP de destination. Point final. Pour les architectes réseau habitués aux fonctionnalités avancées des équipements on-premise (Cisco, Juniper, Palo Alto), cette limitation était frustrante. AWS vient de combler ce gap avec l'annonce de la disponibilité générale du Policy-Based Routing (PBR) sur AWS Transit Gateway.

Cette fonctionnalité, annoncée le 30 juillet 2026, permet désormais de prendre des décisions de routage basées sur une combinaison d'attributs : adresse IP source, adresse IP destination, ports, et protocole. C'est un changement fondamental dans la manière dont nous concevons les architectures réseau sur AWS.

Qu'est-ce que le Policy-Based Routing ?

Le Policy-Based Routing est un mécanisme qui permet de diriger le trafic réseau en fonction de politiques définies par l'administrateur, plutôt que de s'appuyer uniquement sur la table de routage classique basée sur la destination. En d'autres termes, vous pouvez désormais dire : « tout le trafic HTTPS provenant du subnet applicatif à destination du port 443 doit passer par mon appliance d'inspection, tandis que le trafic SSH de l'équipe opérations peut prendre un chemin direct ».

Sur AWS Transit Gateway, le PBR fonctionne avec un concept de policy table que vous associez à un attachement Transit Gateway. Dans cette table, vous définissez un ensemble ordonné de règles. Chaque règle classifie le trafic selon les critères suivants :

Adresse IP source : d'où vient le trafic
Adresse IP destination : où va le trafic
Port source et destination : quel service est utilisé
Protocole : TCP, UDP, ICMP, etc.

Les règles sont évaluées dans l'ordre avec une logique first-match-wins : la première règle qui correspond au trafic détermine vers quelle route table le paquet sera dirigé. Si aucune règle ne correspond, le trafic est silencieusement supprimé (implicit deny). Ce comportement, similaire à celui des Security Groups, impose de toujours prévoir une règle catch-all si vous souhaitez éviter les drops involontaires.

Pourquoi c'est un game-changer ?

Avant le PBR : la complexité architecturale

Avant cette annonce, les architectes réseau qui avaient besoin de diriger le trafic de manière granulaire devaient construire des architectures multi-VPC complexes avec des sauts de routage supplémentaires. Concrètement, cela signifiait :

Multiplier les VPC d'inspection : un VPC dédié pour chaque type de trafic à inspecter différemment
Ajouter des Gateway Load Balancers : pour distribuer le trafic vers des appliances tierces
Créer des chaînes de routage : avec plusieurs Transit Gateway route tables interconnectées
Gérer des coûts croissants : chaque saut supplémentaire génère des frais de traitement de données

Cette complexité se traduisait par une surcharge opérationnelle importante, des latences accrues, et un risque d'erreur de configuration élevé.

Avec le PBR : la simplicité retrouvée

Le PBR élimine une grande partie de cette complexité en étendant les capacités natives de routage du Transit Gateway. Plus besoin d'ajouter des couches intermédiaires : vous classifiez et dirigez le trafic directement au niveau du Transit Gateway, en une seule étape.

Cas d'usage concrets

Le PBR ouvre la porte à de nombreux scénarios que les équipes réseau et sécurité attendaient depuis longtemps.

Inspection sélective du trafic

C'est probablement le cas d'usage le plus demandé. Plutôt que de faire passer tout le trafic par AWS Network Firewall ou une appliance tierce (ce qui génère des coûts et de la latence), vous pouvez désormais ne router que le trafic sensible vers l'inspection. Par exemple :

Le trafic à destination des bases de données (port 3306, 5432) passe par l'inspection
Le trafic interne entre microservices sur des ports applicatifs connus peut contourner l'inspection
Le trafic vers des destinations externes spécifiques est systématiquement inspecté

Routage basé sur la source pour la connectivité hybride

Pour les entreprises utilisant AWS Direct Connect et AWS VPN en parallèle, le PBR permet de diriger le trafic vers le bon chemin en fonction de sa source ou de son protocole :

Le trafic critique (bases de données, ERP) emprunte le Direct Connect pour bénéficier de la latence faible et de la bande passante garantie
Le trafic moins sensible (mises à jour, synchronisation) peut utiliser le VPN comme chemin secondaire
Le basculement peut être géré de manière plus fine en fonction des applications

Isolation des environnements

Le PBR permet d'isoler les environnements de production et de développement dans des domaines de routage séparés, limitant ainsi les mouvements latéraux. Même si deux environnements partagent des plages IP similaires ou des attachements communs, les règles PBR garantissent que le trafic de développement ne peut jamais atteindre les ressources de production, et inversement.

Configuration et mise en place

Contrainte fondamentale : policy table OU route table, jamais les deux

C'est le point le plus important à comprendre avant de se lancer : un attachement Transit Gateway ne peut être associé qu'à une policy table OU à une route table, jamais aux deux simultanément. Il n'existe aucun mode hybride. Concrètement :

Si votre attachement VPC est actuellement associé à une route table classique, vous devez d'abord dissocier cette route table avant de pouvoir associer une policy table
Pendant la fenêtre de dissociation/association, le trafic de cet attachement sera interrompu
Une policy table vide (sans aucune règle) entraîne le drop de tout le trafic entrant sur cet attachement — c'est l'implicit deny

Cette exclusivité signifie que le PBR remplace complètement la logique de routage classique pour un attachement donné. C'est un choix architectural binaire par attachement.

Les étapes de mise en place

La configuration du PBR se fait en quatre étapes :

Créer les route tables cibles : chaque règle PBR pointe vers une route table TGW qui contient les routes effectives
Créer une policy table : vous définissez une table de politiques associée à votre Transit Gateway
Définir les règles : vous créez un ensemble ordonné de règles (numérotées de 1 à 50 000) avec les critères de classification et la route table cible
Dissocier la route table existante puis associer la policy table à l'attachement

Le PBR est configurable via la Console AWS, l'AWS CLI, et les SDK AWS. Les commandes CLI dédiées (create-transit-gateway-policy-table, create-transit-gateway-policy-table-entry, associate-transit-gateway-policy-table) sont disponibles dès maintenant.

Exemple concret : filtrage HTTP/HTTPS et SSH

Voici un exemple complet de mise en place via AWS CLI, qui implémente le scénario décrit en introduction : le trafic HTTPS est inspecté, le trafic SSH prend un chemin direct.

# 1. Créer la policy table
aws ec2 create-transit-gateway-policy-table \
  --transit-gateway-id tgw-0bc994abffEXAMPLE \
  --tag-specifications 'ResourceType=transit-gateway-policy-table,Tags=[{Key=Name,Value=app-security-policy}]'
# Retourne : tgw-ptb-0ca78a549EXAMPLE

# 2. Règle 100 : trafic HTTPS (port 443) du subnet applicatif → inspection firewall
aws ec2 create-transit-gateway-policy-table-entry \
  --transit-gateway-policy-table-id tgw-ptb-0ca78a549EXAMPLE \
  --policy-rule-number 100 \
  --policy-rule '{"SourceCidrBlock":"10.1.10.0/24","Protocol":"6","DestinationPortRange":"443"}' \
  --target-route-table-id tgw-rtb-0a823edbdeEXAMPLE

# 3. Règle 200 : trafic HTTP (port 80) → même inspection
aws ec2 create-transit-gateway-policy-table-entry \
  --transit-gateway-policy-table-id tgw-ptb-0ca78a549EXAMPLE \
  --policy-rule-number 200 \
  --policy-rule '{"SourceCidrBlock":"10.1.10.0/24","Protocol":"6","DestinationPortRange":"80"}' \
  --target-route-table-id tgw-rtb-0a823edbdeEXAMPLE

# 4. Règle 300 : trafic SSH (port 22) de l'équipe ops → routage direct (pas d'inspection)
#    Ne matche que si ce trafic entre bien par l'attachement associé à la policy table
aws ec2 create-transit-gateway-policy-table-entry \
  --transit-gateway-policy-table-id tgw-ptb-0ca78a549EXAMPLE \
  --policy-rule-number 300 \
  --policy-rule '{"SourceCidrBlock":"10.1.50.0/24","Protocol":"6","DestinationPortRange":"22"}' \
  --target-route-table-id tgw-rtb-0b91f2c3d4EXAMPLE

# 5. Règle 40000 : catch-all → routage par défaut (évite l'implicit deny)
#    Un policy-rule vide matche tout : toutes les conditions valent * par défaut
aws ec2 create-transit-gateway-policy-table-entry \
  --transit-gateway-policy-table-id tgw-ptb-0ca78a549EXAMPLE \
  --policy-rule-number 40000 \
  --policy-rule '{}' \
  --target-route-table-id tgw-rtb-0f5e4d3c2bEXAMPLE

# 6. Vérifier les entries avant de basculer l'attachement
aws ec2 get-transit-gateway-policy-table-entries \
  --transit-gateway-policy-table-id tgw-ptb-0ca78a549EXAMPLE

# 7. Dissocier la route table existante de l'attachement source
#    Un attachement ne peut être associé qu'à une route table OU une policy table
aws ec2 disassociate-transit-gateway-route-table \
  --transit-gateway-attachment-id tgw-attach-0def6EXAMPLE \
  --transit-gateway-route-table-id tgw-rtb-0c7d8e9f01EXAMPLE

# 8. Attendre la fin de la dissociation : associer trop tôt fait échouer la requête
while :; do
  STATE=$(aws ec2 get-transit-gateway-route-table-associations \
    --transit-gateway-route-table-id tgw-rtb-0c7d8e9f01EXAMPLE \
    --filters "Name=transit-gateway-attachment-id,Values=tgw-attach-0def6EXAMPLE" \
    --query 'Associations[0].State' --output text)
  # "None" : l'association a disparu de la liste
  if [ "$STATE" = "None" ] || [ "$STATE" = "disassociated" ]; then
    break
  fi
  sleep 5
done

# 9. Associer la policy table à l'attachement
aws ec2 associate-transit-gateway-policy-table \
  --transit-gateway-policy-table-id tgw-ptb-0ca78a549EXAMPLE \
  --transit-gateway-attachment-id tgw-attach-0def6EXAMPLE

# 10. Confirmer l'association
aws ec2 get-transit-gateway-policy-table-associations \
  --transit-gateway-policy-table-id tgw-ptb-0ca78a549EXAMPLE

Avec cette configuration, le trafic est traité comme suit :

Paquet TCP:443 depuis 10.1.10.x → inspecté par le firewall (règle 100)
Paquet TCP:80 depuis 10.1.10.x → inspecté par le firewall (règle 200)
Paquet TCP:22 depuis 10.1.50.x → routage direct sans inspection (règle 300)
Tout autre trafic → routage par défaut (règle 40000 catch-all)

Considérations et bonnes pratiques

Comme toute fonctionnalité réseau avancée, le PBR nécessite une approche structurée :

Commencez simple : déployez d'abord une ou deux règles sur un attachement non-critique pour valider le comportement
Documentez vos politiques : la logique first-match-wins peut devenir complexe avec de nombreuses règles. Maintenez une documentation claire de l'ordre et de l'intention de chaque règle
Surveillez les métriques : utilisez Amazon CloudWatch pour monitorer les hits sur chaque règle et identifier les règles inutilisées. La métrique PacketDropCountNoPolicy vous alerte quand du trafic est droppé faute de règle correspondante
Prévoyez toujours une règle catch-all : sauf si vous souhaitez explicitement un comportement Zero Trust (deny-all), ajoutez une règle à numéro élevé (ex: 40000) qui capture le trafic restant
Laissez des gaps entre les numéros de règle : utilisez 100, 200, 300… pour pouvoir insérer de nouvelles règles sans tout renuméroter
Testez les scénarios de basculement : validez que vos règles PBR se comportent correctement en cas de panne d'un attachement cible
Attention au BGP : associer une policy table à un attachement VPN (Site-to-Site) ou Connect stoppe les advertisements BGP vers le peer. Direct Connect n'est pas affecté (utilise la liste allowed-prefixes)

Impact sur la latence réseau

Une question légitime : le PBR ajoute-t-il de la latence au transit du trafic ?

La réponse est non. L'évaluation des règles PBR s'effectue au niveau du plan de données du Transit Gateway, au même point de décision que la table de routage classique. Il n'y a pas de saut réseau supplémentaire, pas de composant intermédiaire ajouté dans le chemin. La décision est prise « en ligne » lors du transit du paquet.

En réalité, le PBR peut même réduire la latence globale de votre architecture :

Avant le PBR : pour inspecter sélectivement le trafic, il fallait tout envoyer vers un VPC d'inspection (un saut supplémentaire) puis filtrer au niveau de l'appliance. Même le trafic « propre » subissait la traversée.
Avec le PBR : seul le trafic qui nécessite effectivement une inspection est dirigé vers l'appliance. Le reste prend le chemin direct, économisant un ou plusieurs sauts réseau.

Les quotas de bande passante ne sont pas impactés non plus : chaque attachement VPC conserve sa capacité de 100 Gbps par Availability Zone dans chaque direction.

Limites et quotas

Comme tout service AWS, le PBR a ses limites qu'il faut connaître avant de concevoir votre architecture :

Ressource	Limite	Ajustable
Policy tables par Transit Gateway	20	Non
Policy entries (customer-managed) par TGW, toutes tables confondues	200	Oui
Numéros de règle	1 à 50 000	—
Types d'attachement supportés	VPC, VPN, Direct Connect, Connect, Peering (sauf Cloud WAN)	—

Autres contraintes importantes :

Exclusivité absolue : un attachement est associé à une policy table OU une route table, jamais les deux
Pas de PBR sur les peering Cloud WAN : seules les entries system-managed (gérées par Cloud WAN) s'appliquent sur ces attachements
Ports limités à TCP/UDP : le filtrage par port ne fonctionne que pour les protocoles TCP (6) et UDP (17). Pour ICMP, GRE ou « Any », les ports sont automatiquement à *
Policy table vide = blackhole : associer une policy table sans aucune règle à un attachement provoque le drop silencieux de tout le trafic
Route table référencée non supprimable : une route table utilisée comme cible par une policy entry ne peut pas être supprimée tant que la référence existe

Migration : passer d'une route table au PBR sans coupure

La migration vers le PBR est la question qui préoccupe le plus les équipes réseau en production. Soyons clairs : il existe une micro-interruption inévitable lors du basculement, car la dissociation de la route table et l'association de la policy table ne sont pas atomiques.

Voici la stratégie recommandée pour minimiser l'impact :

Approche progressive (recommandée)

Préparez tout en amont : créez la policy table, définissez toutes les règles, et créez les route tables cibles avec les routes nécessaires — tout cela sans aucun impact sur le trafic existant
Commencez par un attachement non-critique : choisissez un VPC de développement ou de test pour valider le comportement
Incluez une règle catch-all qui réplique le comportement actuel : votre règle à numéro élevé doit pointer vers une route table qui reproduit exactement le routage actuel. Ainsi, même si vos règles spécifiques ont un bug, le trafic continue de transiter
Planifiez une fenêtre de maintenance : la dissociation de la route table suivie de l'association de la policy table prend généralement quelques secondes, mais prévoyez 30 à 60 secondes de micro-coupure potentielle
Basculez : dissociez la route table, puis associez immédiatement la policy table
Validez : vérifiez les flux avec GetTransitGatewayPolicyTableEntries et surveillez la métrique PacketDropCountNoPolicy
Itérez : une fois validé, répétez sur les attachements de production

Ce qui se passe pendant la bascule

[Route table associée] ──dissociation──▶ [Aucune association] ──association──▶ [Policy table associée]
                                              │
                                    Trafic droppé pendant
                                    cette fenêtre (secondes)

Pendant la fenêtre où l'attachement n'a ni route table ni policy table, le trafic entrant est droppé. Les connexions TCP établies seront coupées et devront être ré-établies. Pour les protocoles stateless (UDP, ICMP), la reprise est transparente dès que la policy table est active.

Stratégies de mitigation

Applications tolérantes : la plupart des applications avec des mécanismes de retry (HTTP, gRPC) survivent à une interruption de quelques secondes sans impact utilisateur visible
Trafic critique : pour les flux qui ne tolèrent aucune perte, envisagez un schéma de migration par duplication d'attachement — créez un second attachement VPC (dans un subnet dédié), migrez-le vers PBR, puis basculez le trafic applicatif vers ce nouveau subnet
DNS failover : si vous avez un mécanisme de failover DNS (Route 53 health checks), vous pouvez basculer le trafic temporairement vers un chemin alternatif le temps de la migration
Coordination multi-AZ : migrez un AZ à la fois si votre architecture le permet (attachements distincts par AZ)

Rollback

En cas de problème, le rollback est simple : dissociez la policy table et réassociez l'ancienne route table. La même micro-interruption s'applique dans l'autre sens. C'est pourquoi il est essentiel de ne pas supprimer l'ancienne route table tant que la migration n'est pas validée en production.

Disponibilité et tarification

Le Policy-Based Routing pour AWS Transit Gateway est disponible dans toutes les régions commerciales AWS où Transit Gateway est disponible. Point important : le PBR n'engendre aucun coût supplémentaire au-delà des frais standard de Transit Gateway (frais par attachement + frais de traitement de données). Il n'y a pas de tarification par règle ni par évaluation. C'est une excellente nouvelle car cela signifie que l'adoption ne sera pas freinée par des considérations budgétaires.

Conclusion

Pour les architectes réseau et les équipes sécurité, c'est une fonctionnalité qui va simplifier considérablement les architectures existantes tout en ouvrant de nouvelles possibilités.

Mon conseil : si vous avez aujourd'hui des architectures multi-VPC complexes uniquement pour gérer du routage conditionnel, c'est le moment de revoir votre design. Le PBR peut potentiellement vous permettre de réduire le nombre de composants intermédiaires, diminuer la latence, et simplifier vos opérations quotidiennes.

Commencez par identifier vos flux de trafic les plus critiques qui nécessitent un traitement différencié, puis testez le PBR sur un périmètre restreint avant de l'étendre à l'ensemble de votre organisation.

How I Run ML Inference at $0 Idle Compute with SageMaker Async Inference (CDK Included)

Matia Rašetina — Wed, 19 Aug 2026 08:55:44 +0000

A few months ago, I wrote an article “Stop Using Lambda for ML at This Scale”, where I’ve taken a deeper dive into packing a ML model into a Lambda and tested out at what scale does that approach cost more than using a more conventional approach, like using Sagemaker. And that post is great if you are approaching it as a startup which needs to save as much money as possible.

However, in this post, we are going to take a closer look at the architecture which I’ve actually shipped in one of my startups called HeartSense.

HeartSense is a serverless platform which gives a suggestion to the user if they should go and visit a cardiologist, based on a recording of their heartbeats by using their phone’s microphone. The system simply categorizes the sounds by either healthy or unhealthy , by using a ResNet18 model in the background. This product is not meant to be a medical one, and any result of the project should not be taken as medical advice.

In this blog post, I’m giving you my ML pipeline playbook with AWS CDK in Python — every snippet below is from the real-world application. All code, for training the model and CDK infrastructure code, can be found by clicking on the link here.

The first version: one Lambda doing too much

The first version was a single fat Lambda. It downloaded the WAV, generated a spectrogram, ran the ONNX model, and wrote the result — all in one invocation.

It worked in a demo. In practice it had three problems:

Coupling. Preprocessing (CPU, fast, cheap) and inference (heavy, slow) shared one timeout, one memory setting, and one failure domain. A slow inference would hold the whole invocation hostage.
Cold starts. Loading the model into the Lambda runtime on every cold start added seconds to user-facing latency.
No back-pressure. A burst of uploads meant a burst of concurrent heavy Lambdas, with nothing to smooth the spikes.

The fix to all of these problems is to decouple preprocessing code from inference and put a buffer between them.

The architecture

The flow:

User requests a presigned URL to upload the WAV file, the API creates an AnalysisRecord in DynamoDB and sets the status to PENDING , and returns the URL for WAV file upload
The user uploads a WAV straight to S3
S3 creates an ObjectCreated event under the recordings/ prefix, which lands on an SQS queue
A preprocessing Lambda (which is configured to use a Docker image, because the scientific Python deps are too big for a zip) pulls the information about the uploaded WAV file, validates the audio, renders a 224×224 spectrogram, uploads it to S3, and calls the async SageMaker endpoint.
SageMaker runs inference on its own schedule and drops the JSON which contains results into S3 under results/.
That write triggers a tiny result-processor Lambda that parses the prediction and updates DynamoDB.

Nothing here runs unless there’s work to do. The SageMaker endpoint scales to zero instances when idle. Let’s build it.

Step 1 — Buffer uploads with SQS + S3 events

The SQS queue used in this architecture is the shock absorber and gives us batching abilities, partial failure handling and a DLQ — things you don’t get out of the box when using a direct S3-to-Lambda trigger.

When the user uploads the recording of their heartbeat, a S3 event gets created and goes straight to the queue, instead to the Lambda. The reason is to reduce the number of Lambda invocations and to use batching to lower Lambda provisioning and usage cost. One Lambda can handle multiple S3 events and process everything in one or multiple batches, depending on the load on the system.

A very important detail is to know how to handle bad and malicious files too, that’s why this architecture has a DLQ set up, so the data doesn’t get lost anywhere in the system. A platform administrator can take a look into the failing data any time.

The CDK is straightforward — note the dead-letter queue wired in from the start, and the prefix filter so only recordings/ objects trigger the pipeline:

# infra/stacks/queue_stack.py

# Dead Letter Queue — captures messages that fail 3 times (14-day retention)
self.dlq = sqs.Queue(
    self,
    "DeadLetterQueue",
    queue_name=f"heartsense-dlq-{stage}",
    retention_period=Duration.days(SQS_RETENTION_DAYS),
)

# Processing Queue — buffers S3 upload events for the Preprocessing Lambda
self.processing_queue = sqs.Queue(
    self,
    "ProcessingQueue",
    queue_name=f"heartsense-processing-queue-{stage}",
    retention_period=Duration.days(SQS_RETENTION_DAYS),
    visibility_timeout=Duration.seconds(SQS_VISIBILITY_TIMEOUT_SECONDS),
    dead_letter_queue=sqs.DeadLetterQueue(
        max_receive_count=SQS_MAX_RECEIVE_COUNT,  # 3 attempts, then DLQ
        queue=self.dlq,
    ),
)

# S3 → SQS: only ObjectCreated events under recordings/
audio_bucket.add_event_notification(
    s3.EventType.OBJECT_CREATED,
    s3n.SqsDestination(self.processing_queue),
    s3.NotificationKeyFilter(prefix="recordings/"),
)

Two settings matter more than they look:

visibility_timeout - AWS recommends setting the SQS visibility timeout to at least six times the value of the Lambda function timeout + the number of seconds of the SQS queue batching window. This configuration give the Lambda enough time to handle any throttling and/or retry attempts which could happen - you can read more about this configuration on official AWS documentation web page - https://docs.aws.amazon.com/lambda/latest/dg/services-sqs-configure.html
max_receive_count = 3 - after three failed attempts a message lands in the DLQ instead of being retried forever. That DLQ is also where your CloudWatch alarm should point (more on failure handling later).

One gotcha worth mentioning: adding an S3 notification that targets a resource in another CDK stack creates a circular dependency. I import the audio bucket by name inside this stack to break the cycle, rather than passing the L2 bucket construct across stacks.

Step 2 — The preprocessing Lambda (Docker)

For spectrogram generation, the Python code needs libraries like scipy , Pillow and others, which inflate the Lambda ZIP way above the limit. That’s why, in this architecture, I’ve made the preprocessing Lambda be a container image Lambda. CDK builds the image from the project root and pushes it to ECR for you:

# infra/stacks/preprocessing_stack.py

self.preprocessing_function = _lambda.DockerImageFunction(
    self,
    "PreprocessingFunction",
    function_name=f"heartsense-preprocessing-{stage}",
    code=_lambda.DockerImageCode.from_image_asset(
        directory=project_root,
        file="src/services/preprocessing/Dockerfile",
        platform=ecr_assets.Platform.LINUX_AMD64,
        exclude=["infra/cdk.out", ".git", "node_modules", "ai/data", "..."],
    ),
    timeout=Duration.seconds(PREPROCESSING_LAMBDA_TIMEOUT_SECONDS),  # 300s
    memory_size=PREPROCESSING_LAMBDA_MEMORY_MB,                      # 1024 MB
    environment={
        "AUDIO_BUCKET_NAME": audio_bucket.bucket_name,
        "SPECTROGRAM_BUCKET_NAME": spectrogram_bucket.bucket_name,
        "SAGEMAKER_ENDPOINT_NAME": sagemaker_endpoint_name,
        "IDEMPOTENCY_TABLE_NAME": self.idempotency_table.table_name,
        # ...
    },
    tracing=_lambda.Tracing.ACTIVE,
)

# SQS trigger with partial batch failure reporting
self.preprocessing_function.add_event_source(
    lambda_event_sources.SqsEventSource(
        processing_queue,
        batch_size=SQS_BATCH_SIZE,               # 10 as default, but can be adjusted
        max_batching_window=Duration.seconds(SQS_BATCH_WINDOW_SECONDS),
        report_batch_item_failures=True,                            # <-- important
    )
)

report_batch_item_failures=True is the unsung hero in the configuration. Without it, one bad message in a batch of 10 fails the entire batch and re-drives all 10. With it, the handler can return just the IDs that failed, and SQS only retries those.

The intermediate artifacts which the model sees: a 224×224 mel-spectrogram generated from the uploaded WAV file.

Inside the handler, the batch loop classifies every error as transient (retry via SQS) or permanent (don’t retry, mark the record failed):

# src/services/preprocessing/handler.py

def handler(event: dict, context: LambdaContext) -> dict:
    records = event.get("Records", [])
    batch_item_failures: list[dict[str, str]] = []

    for record in records:
        message_id = record["messageId"]
        try:
            _process_record(record)
        except TransientError:
            # report as failure so SQS retries just this message
            batch_item_failures.append({"itemIdentifier": message_id})
        except PermanentError:
            # already marked FAILED in DynamoDB; consume the message
            pass
        except Exception:
            # unknown errors are treated as transient (safer to retry)
            batch_item_failures.append({"itemIdentifier": message_id})

    return {"batchItemFailures": batch_item_failures}

That transient-vs-permanent distinction is the difference between a self-healing pipeline and one that hammers a dead endpoint forever.

For example, a throttle or a 5xx is transient, while on the other hand, a corrupt WAV is permanent — even if we try and process the audio file a million times, it will still be corrupted.

Step 3 — Make it idempotent

S3-to-SQS delivery is at-least-once — which means that some point of time, the same upload event will delivered twice. Hence, we need to protect our system from processing the same information twice, saving processing time and space.

I use Lambda Powertools idempotency, keyed on the analysis_id, backed by a small DynamoDB table with TTL:

# src/services/preprocessing/handler.py

persistence_layer = DynamoDBPersistenceLayer(table_name=IDEMPOTENCY_TABLE_NAME)
idempotency_config = IdempotencyConfig(
    event_key_jmespath="analysis_id",
    expires_after_seconds=3600,  # 1 hour
)

@idempotent_function(
    data_keyword_argument="data",
    config=idempotency_config,
    persistence_store=persistence_layer,
)
def _process_audio_idempotent(data: dict[str, str]) -> dict[str, Any]:
    _process_audio(**data)
    return {"status": "success", "analysis_id": data["analysis_id"]}

The idempotency table is defined right next to the function, with PAY_PER_REQUEST billing and a TTL attribute so old records expire on their own:

# infra/stacks/preprocessing_stack.py
self.idempotency_table = dynamodb.Table(
    self, "IdempotencyTable",
    partition_key=dynamodb.Attribute(name="id", type=dynamodb.AttributeType.STRING),
    billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
    time_to_live_attribute="expiration",
)

In addition, another layer of idempotency was added too: every DynamoDB status update is a conditional write. The record only moves PENDING → PROCESSING → INFERRING if it’s currently in the expected state. A duplicate invocation simply fails the condition check and no-ops — no exceptions, no double processing.

# src/shared/constants.py — the state machine these conditions enforce
VALID_STATUS_TRANSITIONS = {
    AnalysisStatus.PENDING:    {AnalysisStatus.PROCESSING, AnalysisStatus.FAILED},
    AnalysisStatus.PROCESSING: {AnalysisStatus.INFERRING,  AnalysisStatus.FAILED},
    AnalysisStatus.INFERRING:  {AnalysisStatus.COMPLETED,  AnalysisStatus.FAILED},
    AnalysisStatus.COMPLETED:  set(),  # terminal
    AnalysisStatus.FAILED:     set(),  # terminal
}

Here is the state machine diagram which explains this in a more simple way:

Step 4 — Invoke SageMaker asynchronously

This is one of the crucial parts of this ML processing pipeline — instead of calling the Sagemaker endpoint synchronously and waiting for the result, we are using invoke_endpoint_async to call the endpoint asynchronously, so we don’t have additional Lambda usage for no reason. After sending the processing request to the SageMaker endpoint, Lambda’s job is done, it doesn’t have to wait for the result.

What I’ve learned here is that the ways of calling the SageMaker endpoint changes, based on the way you are calling it — with a synchronous endpoint, you would usually send the payload / request body to it and wait for the response. On the other hand, with SageMaker Async Inference, the approach to processing data is different:

you upload the input to S3
retrieve the S3 file URI and pass it into the invoke_endpoint_async method as the InputLocation argument
let SageMaker write the result back to S3

# src/services/preprocessing/handler.py

response = sagemaker_runtime_client.invoke_endpoint_async(
    EndpointName=SAGEMAKER_ENDPOINT_NAME,
    InputLocation=input_s3_uri,            # s3://.../spectrograms/<user>/<id>.jpg
    ContentType="image/jpeg",
    InferenceId=analysis_id,
    Filename=f"{analysis_id}.out",         # forces a deterministic output key
    InvocationTimeoutSeconds=900,
)

Hard-won detail: set Filename explicitly. If you don’t, SageMaker writes the async output under a random UUID that won’t match the InferenceId you passed. By forcing Filename={analysis_id}.out, the result lands at a deterministic key (results/{analysis_id}.out) and the downstream Lambda can map it straight back to the DynamoDB record — no lookup table, no scan.

The invocation is wrapped in manual exponential backoff (1s, 2s) for transient SageMaker errors, and disables boto3’s built-in retries so the two retry mechanisms don’t fight each other.

Step 5 — The scale-to-zero endpoint (the money shot)

Here’s the part that makes idle cost disappear. The async endpoint is configured with an AsyncInferenceConfig (output + failure S3 paths, one concurrent invocation per instance):

# infra/stacks/inference_stack.py

endpoint_config = sagemaker.CfnEndpointConfig(
    self, "InferenceEndpointConfig",
    production_variants=[
        sagemaker.CfnEndpointConfig.ProductionVariantProperty(
            variant_name="AllTraffic",
            model_name=model.model_name,
            initial_instance_count=1,
            instance_type="ml.t3.medium",
        )
    ],
    async_inference_config=sagemaker.CfnEndpointConfig.AsyncInferenceConfigProperty(
        output_config=sagemaker.CfnEndpointConfig.AsyncInferenceOutputConfigProperty(
            s3_output_path=async_output_s3_uri,    # results/
            s3_failure_path=async_failure_s3_uri,  # failures/
        ),
        client_config=sagemaker.CfnEndpointConfig.AsyncInferenceClientConfigProperty(
            max_concurrent_invocations_per_instance=SAGEMAKER_MAX_CONCURRENT_INVOCATIONS,
        ),
    ),
)

Then Application Auto Scaling with min_capacity=0 lets the endpoint drop to zero instances when there’s nothing in the queue. Async endpoints are the only SageMaker endpoint type that can do this:

def _create_autoscaling(
    self, endpoint_name: str, stage: str, endpoint: sagemaker.CfnEndpoint
) -> None:
    from aws_cdk import aws_applicationautoscaling as appscaling
    from aws_cdk import aws_cloudwatch as cloudwatch
    from aws_cdk import aws_cloudwatch_actions as cw_actions

    # Scale between 0 and 1 instances for this low-cost async endpoint.
    scalable_target = appscaling.ScalableTarget(
        self,
        "EndpointScalableTarget",
        service_namespace=appscaling.ServiceNamespace.SAGEMAKER,
        resource_id=f"endpoint/{endpoint_name}/variant/AllTraffic",
        scalable_dimension="sagemaker:variant:DesiredInstanceCount",
        min_capacity=0,
        max_capacity=1,
    )

    # Wait until the endpoint exists before attaching autoscaling.
    scalable_target.node.add_dependency(endpoint)

    endpoint_dimensions = {"EndpointName": endpoint_name}

    # Target tracking should follow queued async work, not invocation rate.
    backlog_per_instance_metric = cloudwatch.Metric(
        namespace="AWS/SageMaker",
        metric_name="ApproximateBacklogSizePerInstance",
        dimensions_map=endpoint_dimensions,
        statistic="Average",
        period=Duration.minutes(1),
    )

    scalable_target.scale_to_track_metric(
        "BacklogPerInstancePolicy",
        policy_name=f"heartsense-backlog-per-instance-{stage}",
        target_value=float(SAGEMAKER_BACKLOG_TARGET_PER_INSTANCE),
        custom_metric=backlog_per_instance_metric,
        scale_in_cooldown=Duration.minutes(SAGEMAKER_IDLE_TIMEOUT_MINUTES),
        scale_out_cooldown=Duration.seconds(SAGEMAKER_SCALE_OUT_COOLDOWN_SECONDS),
    )

    # Target tracking alone cannot wake a zero-instance endpoint.
    # HasBacklogWithoutCapacity becomes 1 when backlog > 0 and capacity == 0.
    scale_from_zero_action = appscaling.StepScalingAction(
        self,
        "ScaleFromZeroAction",
        scaling_target=scalable_target,
        policy_name=f"heartsense-scale-from-zero-{stage}",
        adjustment_type=appscaling.AdjustmentType.CHANGE_IN_CAPACITY,
        metric_aggregation_type=appscaling.MetricAggregationType.MAXIMUM,
        cooldown=Duration.seconds(SAGEMAKER_SCALE_OUT_COOLDOWN_SECONDS),
    )
    # +1 instance; max_capacity=1 keeps the endpoint at a single instance.
    scale_from_zero_action.add_adjustment(adjustment=1, lower_bound=0)

    has_backlog_without_capacity_alarm = cloudwatch.Alarm(
        self,
        "HasBacklogWithoutCapacityAlarm",
        alarm_name=f"heartsense-has-backlog-without-capacity-{stage}",
        alarm_description=(
            "SageMaker async inference has queued requests but zero instances — "
            "triggers the scale-from-zero step scaling policy."
        ),
        metric=cloudwatch.Metric(
            namespace="AWS/SageMaker",
            metric_name="HasBacklogWithoutCapacity",
            dimensions_map=endpoint_dimensions,
            statistic="Maximum",
            period=Duration.minutes(1),
        ),
        threshold=1,
        comparison_operator=cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
        evaluation_periods=SAGEMAKER_SCALE_FROM_ZERO_EVALUATION_PERIODS,
        datapoints_to_alarm=SAGEMAKER_SCALE_FROM_ZERO_EVALUATION_PERIODS,
        treat_missing_data=cloudwatch.TreatMissingData.MISSING,
    )
    # Alarm fires → step scaling policy → endpoint scales from 0 to 1.
    has_backlog_without_capacity_alarm.add_alarm_action(
        cw_actions.ApplicationScalingAction(scale_from_zero_action)
    )

    return scalable_target

There is one very useful metric in CloudWatch for Sagemaker instances for target-tracking called ApproximateBacklogSizePerInstance , which represents the queued requests relative to the available endpoint capacity, and AWS recommends the usage for this metric for all autoscaling asynchronous endpoints. You can read about it in more detail by clicking on the link here.

There is one important scale-to-zero edge case when using this configuration. When the endpoint already has zero instances, a small backlog may not be enough for normal target-tracking policy to scale it out right away, and for that reason, I used already available metric HasBacklogWithoutCapacity which is a second scaling signal. The value of the metric becomes 1 when the requests are waiting, but there is no compute instances available to process the information, which triggers a step-scaling policy and it starts the endpoint from zero instances to one.

It’s important to mention that in this stack, the max number of provisioned SageMaker endpoints is going to be 1 — just to cut down on cost and have a POC ready.

When an upload arrives after a quiet period, SageMaker spins an instance back up, processes the queued request, and scales back to zero ~15 minutes after the last invocation. The async queue in front of the endpoint means callers never get a “no capacity” error — requests just wait for the instance to warm up.

The interesting part was not that the model saturated the instance. It did the opposite. During this test, CPU utilization stayed under ~2%, and memory utilization stayed around ~2.3%. It was surprising to me, as the ml.t3.medium instance is not a very strong instance and it’s only CPU dependent, so I expected a bigger impact on it’s hardware.

That is exactly why idle cost matters. If the endpoint is lightly used, the waste does not come from a single expensive inference. The waste comes from keeping model-serving compute warm while there are no requests. For this workload, scale-to-zero mattered more than squeezing every last percent out of the instance.

Another interesting metric which is available to see inside the console is the model latency metric and it looks like this:

The actual model execution was not the slow part. SageMaker model latency stayed roughly in the 30–37 ms range during this run.

That is an important distinction: model latency is not the same as user-visible pipeline latency. The end-to-end path also includes S3 upload, S3 event delivery, SQS batching, preprocessing, async endpoint queueing, result writing, result processing, and frontend polling.

Step 6 — Close the loop with an S3 event

When SageMaker finishes, it writes the result JSON to results/. Same as for WAV file upload, that is considered a S3 event, and the information about that event is put inside the SQS queue. When the queue gets some data, it triggers a small, plain-zip Lambda (no Docker needed here) that parses the prediction and finishes the record:

# infra/stacks/inference_stack.py
# Buffer SageMaker result objects so the Lambda can process them in batches.
self.result_processor_queue = sqs.Queue(
    self,
    "ResultProcessorQueue",
    queue_name=f"heartsense-result-processor-queue-{stage}",
    retention_period=Duration.days(SQS_RETENTION_DAYS),
    visibility_timeout=Duration.seconds(
        RESULT_QUEUE_VISIBILITY_TIMEOUT_SECONDS
    ),
    dead_letter_queue=sqs.DeadLetterQueue(
        max_receive_count=SQS_MAX_RECEIVE_COUNT,
        queue=self.result_processor_dlq,
    ),
)

# SageMaker writes to results/ → S3 notifies the result-processing SQS queue.
local_inference_output_bucket.add_event_notification(
    s3.EventType.OBJECT_CREATED,
    s3n.SqsDestination(self.result_processor_queue),
    s3.NotificationKeyFilter(prefix=RESULTS_PREFIX),
)

# Result Processor Lambda consumes the queue with partial batch failure reporting.
self.result_processor_function.add_event_source(
    lambda_event_sources.SqsEventSource(
        self.result_processor_queue,
        batch_size=SQS_BATCH_SIZE,
        max_batching_window=Duration.seconds(SQS_BATCH_WINDOW_SECONDS),
        report_batch_item_failures=True,
    )

Before the ResultProcessor Lambda, which has a SQS queue in-front of it - the primary objective of this queue is to absorb the burst of completed SageMaker predictions.

The result processor validates the payload and writes the final COMPLETED state — again with a conditional update, so a fast inference that beats preprocessing’s INFERRING write (or a duplicate S3 event) can never clobber the record:

# src/services/inference/result_processor.py

table.update_item(
    Key={"analysis_id": analysis_id},
    UpdateExpression=(
        "SET #status = :completed, #prediction = :prediction, "
        "#confidence = :confidence, #model_version = :model_version, "
        "#completed_at = :completed_at"
    ),
    ExpressionAttributeValues={
        ":completed": AnalysisStatus.COMPLETED.value,
        ":prediction": prediction,
        ":confidence": Decimal(str(confidence)),
        # ...
        ":inferring": AnalysisStatus.INFERRING.value,
        ":processing": AnalysisStatus.PROCESSING.value,
    },
    # only complete if we're mid-flight — idempotent against duplicates
    ConditionExpression="#status IN (:inferring, :processing)",
)

Here are the invocation statistics of the Results Processor Lambda:

This image shows the result processor is tiny:

145 invocations
average duration ~257 ms
max ~586 ms
min ~44 ms

This Lambda is intentionally boring — it doesn’t generate audio features, load a model or do any heavy computation. It simply reads the SageMaker output JSON, validates that everything is alright with the payload and updates the DynamoDB table containing the results.

During multiple test runs, it handled ~140 invocations with an average duration ~260ms and a max duration of just under 600ms. That kind of work for a Lambda is excellent and excels at: short, event-driven glue code around managed services.

The frontend polls GET /analyses/{id} and flips from a spinner to the result the moment the record hits COMPLETED.

Failure handling, in one place

Because every stage is decoupled, failures are isolated instead of cascading:

Failure	What happens
Corrupt / invalid WAV	`PermanentError` → record marked `FAILED`, message consumed (no retry)
S3 throttle / 5xx	`TransientError` → SQS redelivers, up to 3×
SageMaker throttle	manual backoff (1s, 2s); if exhausted → `FAILED`
Poison message	after 3 receives → DLQ → CloudWatch alarm
Duplicate S3 event	idempotency table + conditional writes → no-op

What the metrics showed

After running a small batch through the pipeline, the metrics matched the architecture:

Preprocessing was the heavier Lambda stage, averaging ~8.9s and peaking around ~27.6s.
Result processing was tiny, averaging ~257ms.
SageMaker model latency stayed around 30–37ms.
Endpoint CPU and memory utilization stayed low, which made scale-to-zero more important than raw instance utilization.

That confirmed the main design decision: this was not one workload. It was several smaller workloads with different scaling profiles.

What this buys you

The expensive model-serving compute scales to zero.
Independent tuning. Preprocessing is 1 GB / 300s; inference has its own instance type and timeout. Neither blocks the other.
Burst tolerance. SQS flattens spikes; the async queue means callers never see capacity errors.
Self-healing. Transient errors retry, permanent errors fail fast, duplicates are absorbed, and poison messages park in a DLQ you can replay.

The whole thing is a few hundred lines of CDK. If you’ve been forcing ML into a single Lambda and watching it strain, this is the shape I’d reach for instead.

AWS AppSync: The Easiest Way to Build Real-Time Apps

Tanseer — Wed, 19 Aug 2026 05:30:00 +0000

Build APIs that fetch exactly the data an app needs and push live updates as things change. Stop five in the AWS Hidden Gems series.

About this series

Most AWS learning stops after EC2, S3, IAM, and Lambda. But AWS has over two hundred services, and many of the most useful ones rarely appear in tutorials.

AWS Hidden Gems covers those underrated services you shouldn't ignore. Each article picks one, then explains why it exists, what it does, where it fits, and how to set it up from the console. Know the four basics above and you can follow along. Everything else gets explained as it comes up.

Today's service: AWS AppSync

Modern apps often need two things that are awkward to build: letting the client ask for exactly the data it wants in one request, and pushing live updates to the screen the moment data changes. AppSync gives you both. It is a managed service for building GraphQL APIs, with real time updates included.

Why does this service exist?

Two common API headaches led to AppSync. First, with traditional REST APIs, the client often calls several endpoints and gets back more data than it needs, which is slow on mobile. GraphQL fixes this by letting the client ask for precisely the fields it wants in a single request, but running a GraphQL server yourself means managing servers, connecting data sources, and writing a lot of glue.

Second, live updates. Showing new messages or a changing dashboard in real time usually means managing WebSocket connections, which are long lived two way connections between client and server. Doing that at scale is fiddly.

AppSync handles both. It runs the GraphQL API for you, connects it to your data with little code, and manages the real time connections so updates just arrive.

What is AWS AppSync?

AppSync is a managed GraphQL service. GraphQL is a query language for APIs where the client describes the exact data it wants, and the server returns just that, in one round trip.

You define a schema, which is the shape of your data and the operations allowed on it. You connect each part of the schema to a data source, which AppSync can talk to directly:

DynamoDB for fast NoSQL storage
Lambda for any custom logic
Relational databases, HTTP endpoints, and others AppSync supports three kinds of operations: queries to read data, mutations to change data, and subscriptions to receive live updates. When someone changes data through a mutation, AppSync automatically pushes that change to every client subscribed to it. Authentication is built in, with options including API keys and Amazon Cognito, the AWS user sign in service.

A real world problem

A team is building a shared task board, like a simple Trello. When one person moves a card, everyone else looking at the board should see it move immediately.

Building this the usual way means a REST API for the data plus a separate WebSocket layer to broadcast changes, with code to track who is connected and who cares about which board. That is a lot of plumbing for a small team.

With AppSync, they define the board and card types once, back them with DynamoDB, and add a subscription. Now a mutation to move a card is pushed to every open board automatically. The real time behavior comes almost for free.

Real world use cases

Chat and messaging apps deliver new messages instantly to everyone in a conversation
Collaborative tools like shared boards and documents sync changes across users live
Live dashboards update metrics on screen as new data arrives
Multiplayer game features share state like scores and moves between players
Mobile apps fetch lean, exact payloads to stay fast on slow connections
Apps that work offline sync their changes when the connection returns The pattern is flexible data access plus live updates, without building the real time layer yourself.

Where it fits in AWS

The client app talks to a single AppSync endpoint. AppSync routes each request to the right data source, most often DynamoDB for storage or Lambda for custom logic. Cognito handles who is allowed to do what. For live updates, clients hold a subscription connection to AppSync, and AppSync pushes changes to them.

flowchart LR
    A[Client app] -->|GraphQL query or mutation| B[AppSync API]
    B --> C[DynamoDB]
    B --> D[Lambda]
    B -->|Auth check| E[Cognito]
    B -->|Live updates| A

AppSync sits between your app and your data, giving one flexible endpoint and handling the real time push.

How the workflow runs

You define a GraphQL schema with your types and operations. You attach data sources and connect each field to an action, such as read this item from DynamoDB. The client sends a query or mutation, and AppSync runs the connected action and returns exactly the requested fields. When a mutation changes data, AppSync notifies every client subscribed to that change over their live connection.

flowchart TD
    A[Define GraphQL schema] --> B[Connect fields to data sources]
    B --> C[Client sends query or mutation]
    C --> D[AppSync runs it against the data source]
    D --> E[Return exactly the requested fields]
    D --> F[Push updates to subscribed clients]

Setting it up in the AWS Console

You will create a GraphQL API, let AppSync build a DynamoDB backed type, and test it live.

Sign in to the AWS Console, search for AppSync, and open it. Check the region in the top right corner.
Click Create API, choose GraphQL APIs, and pick the option to design from scratch. Give the API a name and create it.
Open the Schema page. Define a simple type and the operations for it, for example a Task type with an id and a title, and queries and mutations to create and list tasks.
Use the Create Resources shortcut on the schema. AppSync can generate a DynamoDB table and the resolvers, which are the small pieces that connect each GraphQL field to a table action, so you do not write them by hand.
Go to the Queries page, a built in tool for running operations against your API. Run a mutation to create a task, then a query to list tasks, and confirm your data comes back.
To see real time updates, open a subscription in the Queries page in one browser tab, then run a create mutation in another. The new task appears in the subscription tab immediately.
For your app to call the API, note the API URL and set an authorization mode under Settings. An API key is fine for testing, while Cognito is the usual choice for real users. Confirm a call works from your code using the URL and key. Common mistakes: an unauthorized error usually means the request is missing the API key or Cognito token the API expects, so check the authorization mode and that your client sends the right credential. If a field returns null, its resolver is probably not connected to a data source yet.

Using it from code

With AppSync, the code is your GraphQL schema and the operations clients run against it. Here is a small schema and the three operation types.

type Task {
  id: ID!
  title: String!
  done: Boolean!
}

type Query {
  listTasks: [Task]
}

type Mutation {
  addTask(title: String!): Task
}

type Subscription {
  onAddTask: Task
  @aws_subscribe(mutations: ["addTask"])
}

A client adds a task and, thanks to the subscription, every other client is notified without polling:

mutation {
  addTask(title: "Write the AppSync post") {
    id
    title
    done
  }
}

The @aws_subscribe line is what wires the subscription to the mutation, so any addTask pushes the new task to subscribers automatically.

Pricing

Item	Detail
Queries and mutations	Per million operations
Query and mutation rate	About $4.00 per million operations (US)
Real time updates	Per million updates pushed to clients
Connection time	Per million minutes clients stay connected
Free tier	250,000 operations and 250,000 real time updates per month for 12 months

The AWS API and app services family

AWS API and App Services
├── AppSync       managed GraphQL with real time updates
├── API Gateway   REST and WebSocket APIs you route yourself
├── Amplify       front end hosting and app building tools
└── Lambda        serverless functions behind your APIs

The main choice is AppSync versus API Gateway. AppSync is built around GraphQL and real time updates, and connects to data sources with little code. API Gateway is built around REST and WebSocket routing, giving you more manual control. For live, data driven apps, AppSync usually gets you there faster.

Wrapping up

AppSync gives you a flexible GraphQL API and real time updates without running a server or building a WebSocket layer. Define a schema, point it at your data, and changes flow to every client live. Next time an app needs live, precise data access, you know the service that skips the plumbing.

Series progress

You are on stop five of AWS Hidden Gems.

AWS Elemental MediaConvert
Amazon IVS
Amazon Rekognition
Amazon Personalize
AWS AppSync (you are here)
Amazon Timestream
Amazon Textract
Amazon Kendra
AWS DataSync
AWS IoT Core Next up is Amazon Timestream, a database built specifically for time series data like sensor readings and metrics.

Let's connect

Questions, corrections, or want to talk through where this fits in your own project? Reach me at khantanseer43@gmail.com.

Cómo mantener siempre disponibles las sesiones de tu agente de código remoto (parte 2)

Franchesco Romero — Wed, 19 Aug 2026 00:53:33 +0000

La Parte 1 construyó una caja siempre encendida para una sesión de remote-control de Claude Code y terminó con una alarma que convierte seis días de silencio en quince minutos. Esa alarma atrapa una caja muerta. Esta es la secuela, y la caja de aquí nunca estuvo muerta. Estaba active, su token estaba fresco, y en cada reinicio imprimía:

Take this session with you and pick up right where you left off on any device.
Open the Code tab in the Claude mobile app, or visit claude.ai/code in a browser.

y la sesión no estaba en claude.ai/code. Nunca se había registrado. El banner de arriba se imprime al arrancar, antes de que haya pasado lo que anuncia, así que le mintió al monitoreo, me mintió a mí cuando lo "arreglé", y casi se mintió hasta meterse en este blog post como el arreglo. Este post es sobre la diferencia entre un proceso que dice que está listo y una sesión que de verdad lo está.

TL;DR

	Lo que creía	Lo que era cierto
Causa raíz	el registro se puso viejo a lo largo de ~6 días de uptime	nunca se registró, el CLI se colgó en un prompt interactivo sin TTY
El "arreglo"	reinicia el servicio; el banner regresa; el heartbeat en verde	el reinicio imprimió el banner otra vez y aun así no se registró
La señal de salud que construí	grep del journal por `claude.ai/code`	ese string es el banner de pre-registro, verde para un proceso colgado
La señal real		la URL registrada (`claude.ai/code/session_…`), que solo se imprime después del registro

Placeholders, como en la parte 1: myapp, appuser, acme/myapp.

El síntoma

La sesión simplemente no estaba en la lista de claude.ai/code, mientras que todo en la caja decía que debería estar:

$ systemctl is-active claude-remote-control
active
$ stat -c %y ~/.claude/.credentials.json
2026-07-28 02:54:11          # token refrescado hace horas, la auth está bien
$ aws cloudwatch describe-alarms --alarm-names myapp-agent-box-down \
    --query 'MetricAlarms[].StateValue' --output text
OK

Así que hice lo obvio: reinicié el servicio. Imprimió el banner, el proceso subió, el heartbeat se puso verde, y la sesión seguía sin estar ahí. Ese es el momento en el que vale la pena detenerse. Cada señal que tenía decía sano, y el producto real (una sesión que puedo abrir desde un navegador) no existía.
Un reinicio que produce un banner no es un reinicio que produce una
sesión.

Conseguir una señal que no puede mentir

systemctl is-active reporta que el proceso existe. El banner reporta que el proceso arrancó. Ninguno reporta que la caja se registró con el punto de encuentro hospedado, lo único que mete la sesión en la lista. Para ver eso, pídele al CLI que escriba su propio log de debug y lee lo que de verdad pasa:

claude remote-control --name myapp-cloud --continue --debug-file /tmp/rc.log --verbose

Dos fallas cayeron de inmediato, y ninguna era "vieja":

Take this session with you and pick up right where you left off on any device.
Open the Code tab in the Claude mobile app, or visit claude.ai/code in a browser.
The session keeps running on this machine. ... Press Ctrl+C to stop.

Enable Remote Control? (y/n)

El proceso imprime el banner y luego se bloquea en un prompt interactivo.
Bajo systemd no hay TTY que lo conteste, así que espera ahí para siempre: active, banner emitido, registro ni siquiera intentado. Los CLI recientes agregaron esta confirmación; la caja de la parte 1 es anterior a ella.

Y cuando le di una y, la segunda falla:

Error: No recent session found in this directory or its worktrees.
Run `claude remote-control` to start a new one.

--continue, la bandera de la parte 1 que mantiene el marcador estable reanudando la misma sesión, da error duro cuando no hay sesión que reanudar. En una caja cuyo historial de sesión local se había borrado en una reconstrucción, --continue no era una optimización; era un arranque que solo podía fallar.

El arreglo real: contesta el prompt, y no dependas de que una sesión exista

Las dos fallas viven en una línea, así que el arreglo es una línea, un wrapper en ExecStart:

ExecStart=/bin/bash -c 'cd /home/appuser/myapp; \
  echo y | /home/appuser/.local/bin/claude remote-control --name myapp-cloud --continue || \
  echo y | /home/appuser/.local/bin/claude remote-control --name myapp-cloud'

Tres cosas se ganan su lugar:

echo y contesta el prompt. Importa que el proceso siga corriendo después de que su stdin se cierra (verificado, sí lo hace), así que un echo de una sola vez basta; sin yes inundando el pipe, sin sleep infinity manteniéndolo abierto.
--continue || <nuevo> trata de reanudar (marcador estable) y cae de vuelta a una sesión nueva cuando no hay nada que reanudar. Como echo y cierra limpio, un --continue fallido de verdad regresa y corre el fallback; un sleep infinity aquí colgaría el pipeline en el camino de falla y reintroduciría el atoro silencioso exacto.
Sin $@ ni $VAR en ExecStart. systemd expande ${} y $VAR pelón él mismo, y mutila $@; la jugada segura es repetir la ruta en lugar de factorizarla en una variable.

Ahora el log de debug muestra lo que el banner solo fingía:

[bridge:init] Resuming session session_01Pp8… on environment env_01Vp…
[bridge:init] Registered, server environmentId=env_01Vp…
[bridge:title] server title: myapp-cloud

Registered. Ese es el recibo. El banner era el menú.

Defensa en profundidad, todavía vale la pena conservarla

El wrapper arregla el outage. Dos guardas del primer borrador de este trabajo se quedan, porque endurecen la caja contra otras maneras en que la sesión puede caducar:

Reciclado diario. RuntimeMaxSec=86400 rebota la unidad cada 24h; Restart=always la trae de vuelta y --continue reanuda la misma sesión, así que el marcador aguanta. Si un registro alguna vez se pone viejo en un uptime largo, esto le pone tope al radio de impacto en un día en lugar de confiar en
que viva para siempre. TimeoutStopSec=20 mantiene cada reciclado rápido, ya que el CLI ignora SIGTERM por ~90s.

Escritura de vuelta de credenciales. La parte 1 señaló que el CLI rota su refresh token y la captura del secreto se pudre. Un helper chico empuja el token vivo de vuelta a Secrets Manager en cada corrida del watchdog, protegiendo con fuerza contra escribir un archivo local malformado encima de un secreto bueno, para que una instancia reemplazada ya no arranque sin autenticar.

El health check al que engañó el mismo banner

Aquí está la parte que arde. La primera versión del chequeo de readiness, la que se suponía atrapaba justo este estado de "arriba pero sin registrar", hacía esto:

# MAL: hace match al banner de pre-registro, así que está verde para un proceso colgado
journalctl -u claude-remote-control --since "${AGE}s ago" | grep -q "claude.ai/code"

claude.ai/code está en el banner que se imprime antes del prompt en el que el proceso estaba colgado. El chequeo que construí para detectar la falla quedaba satisfecho por la falla. Es el bug original vestido con el disfraz de su propio arreglo.

La sesión registrada imprime una línea distinta, una URL con un id de sesión o de environment:

Continue coding in the Claude mobile app or https://claude.ai/code/session_01Pp8…

El discriminador entre "anunciada" y "registrada" es un solo carácter: lo que sigue a code. El banner dice code in a browser; la cosa real dice code/session_… o code?environment=…. Así que haz match a eso:

# solo una sesión REGISTRADA imprime una URL con '/' o '?' después de 'code'
journalctl -u claude-remote-control --since "${AGE}s ago" | grep -qE 'claude\.ai/code[/?]'

Con el chequeo corregido el heartbeat significa lo que dice: active, lo bastante joven para haberse registrado, y una URL de registro en su propio log.
Cualquier otra cosa degrada el latido a DEGRADED y reinicia, y DEGRADED no hace match al filtro OK de la parte 1, así que un estado que no se va a auto-sanar de todos modos le suena a la alarma existente.

Callejones sin salida (los dos el mismo error)

Checar por una conexión de red abierta. La sonda de readiness intuitiva: seguramente una sesión registrada sostiene un socket al punto de encuentro. Medido en la caja sana: cero sockets establecidos. Una sesión registrada inactiva no mantiene ninguno. El chequeo reiniciaría una caja funcionando en cada tick.
Grep del banner de arranque. Cubierto arriba. Verde antes de que el trabajo esté hecho.

Los dos fallan de la misma manera: afirman sobre algo que es cierto antes de
que pase la cosa real. Un socket que quizá todavía no esté ahí; un banner que
está ahí demasiado pronto. El arreglo en los dos casos es afirmar sobre el
artefacto que existe solo después del éxito: la línea Registered, la URL
con un id.

Lecciones

Un banner es un menú, no un recibo. Cualquier mensaje de "ya puedes hacer X" impreso al arrancar es una intención, no una confirmación. Los health checks tienen que indexarse en el artefacto que existe solo una vez que X de verdad pasó.
Reiniciar hasta que reaparezca el mensaje feliz no es verificación. Vi el banner, vi el heartbeat ponerse verde, y seguí adelante, dos veces. El mensaje era el mismo las dos veces porque nunca dependió del éxito.
Los prompts interactivos son minas en cajas sin atender. Una sola compuerta (y/n) nueva, incontestable sin un TTY, convierte en silencio un servicio que funciona en uno colgado. Dale la respuesta explícitamente; no asumas que un servicio hereda la de tu terminal.
Las banderas de conveniencia tienen modos de falla. --continue mantiene un marcador estable y falla duro cuando no hay nada que continuar. En una caja que se puede reconstruir desde nada, "reanudar" necesita un "o arranca de nuevo" al lado.
Cuando no hay API de estado, afirma sobre el log de éxito, el específico. No el banner optimista. La línea que solo el camino exitoso puede producir.

RDS High Availability and credential rotation without downtime

Carlos Filho — Tue, 18 Aug 2026 18:54:22 +0000

I got an AWS question and implemented it to make sure that the option is correct.

A critical financial application runs on RDS for PostgreSQL. The requirements are tight: 1-second RPO, 60-second RTO, and database credentials rotated every 30 days without taking the application offline.

Two independent problems. Two independent solutions.

Prerequisites

Check these before running terraform apply:

RDS Proxy availability
RDS Proxy is not available on all instance types. It requires instances with at least 2 vCPUs. db.t3.micro is not supported. db.t3.medium and above work.

Terraform executor permissions
The IAM principal running Terraform needs, at minimum:

rds:CreateDBInstance
rds:CreateDBProxy
rds:CreateDBProxyTargetGroup
rds:RegisterDBProxyTargets
rds:ModifyDBInstance
iam:CreateRole
iam:AttachRolePolicy
iam:PutRolePolicy
iam:PassRole
secretsmanager:CreateSecret
secretsmanager:PutSecretValue
secretsmanager:RotateSecret
lambda:CreateFunction
lambda:AddPermission
ec2:CreateSecurityGroup
ec2:AuthorizeSecurityGroupIngress
ec2:CreateDBSubnetGroup

AdministratorAccess on the account covers all of these. Lock it down after the initial setup.

VPC requirements
RDS Proxy runs inside your VPC. You need at least two private subnets in different Availability Zones. The rotation Lambda also runs inside the VPC so it can reach the RDS instance directly during the credential update step.

The problem

Database failure recovery

RPO of 1 second means almost no data loss is acceptable. RTO of 60 seconds means the application must resume within a minute of a failure. A standard single-instance RDS setup fails both requirements: there is no automatic failover, and restoring from a backup takes far longer than 60 seconds.

Credential rotation

Rotating credentials on a schedule sounds simple until you factor in application downtime. If you update a password and the application still holds connections authenticated with the old one, those connections fail. The rotation mechanism needs to handle the transition without the application noticing.

The solutions

Multi-AZ + RDS Proxy

RDS Multi-AZ keeps a synchronous standby replica in a second Availability Zone. Every write to the primary is committed to the standby before the transaction is acknowledged. This gives you RPO close to zero, typically under 1 second for PostgreSQL.

When the primary fails, RDS automatically promotes the standby. The DNS record for the cluster endpoint is updated to point to the new primary. Failover typically completes in 60 seconds or less, which meets the RTO requirement.

The problem is what happens to application connections during that DNS update. Existing database connections are dropped. If your application has a connection pool, it will spend time re-establishing connections and waiting for DNS propagation. Under load, this causes errors.

RDS Proxy sits between the application and the database. The application connects to the Proxy endpoint, not the RDS endpoint directly. The Proxy maintains a warm pool of connections to the database. During a Multi-AZ failover, the Proxy detects the new primary and reroutes connections internally. The application connection to the Proxy stays alive. From the application's perspective, the failover is nearly invisible.

Without the Proxy, Multi-AZ alone may technically meet 60-second RTO on paper but cause application-level errors during the DNS transition. With the Proxy, the application keeps working through the failover.

Secrets Manager with automatic rotation

Secrets Manager stores the database credentials and handles rotation through a managed Lambda function. AWS provides a built-in rotation Lambda for RDS PostgreSQL that handles the full rotation cycle: generate a new password, update it in RDS, update the secret, verify the new credentials work.

The rotation Lambda follows a four-step process using staging labels (AWSPENDING, AWSCURRENT, AWSPREVIOUS). The new password is set in the database before it becomes AWSCURRENT. This means both the old and new passwords are valid during the transition window. Applications retrieving credentials from Secrets Manager at runtime always get the current valid credentials without any downtime.

RDS Proxy reads credentials from Secrets Manager directly. The application connects to the Proxy endpoint and never touches credentials directly. When Secrets Manager rotates the password, the Proxy picks up the new credentials on its next refresh cycle. The application connection to the Proxy stays alive throughout.

Terraform

File structure

├── variables.tf
├── networking.tf
├── iam.tf
├── rds.tf
├── secrets.tf
└── outputs.tf

`variables.tf`

variable "aws_region" {
  description = "AWS region to deploy resources"
  type        = string
  default     = "us-east-1"
}

variable "vpc_id" {
  description = "ID of the VPC where RDS and RDS Proxy will run"
  type        = string
}

variable "private_subnet_ids" {
  description = "List of private subnet IDs in at least two AZs"
  type        = list(string)
}

variable "app_security_group_id" {
  description = "Security group ID of the application servers that connect to RDS Proxy"
  type        = string
}

variable "db_password" {
  description = "Initial database password (Secrets Manager takes over after first rotation)"
  type        = string
  sensitive   = true
}

`networking.tf`: security groups

# Security group for the RDS instance
# Accepts connections from RDS Proxy and the rotation Lambda only
resource "aws_security_group" "rds" {
  name        = "financial-app-rds"
  description = "Allow PostgreSQL access from RDS Proxy and rotation Lambda"
  vpc_id      = var.vpc_id

  ingress {
    description     = "PostgreSQL from RDS Proxy"
    from_port       = 5432
    to_port         = 5432
    protocol        = "tcp"
    security_groups = [aws_security_group.rds_proxy.id, aws_security_group.rotation_lambda.id]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# Security group for RDS Proxy
# Accepts connections from the application tier
resource "aws_security_group" "rds_proxy" {
  name        = "financial-app-rds-proxy"
  description = "Allow PostgreSQL access from application servers"
  vpc_id      = var.vpc_id

  ingress {
    description     = "PostgreSQL from application"
    from_port       = 5432
    to_port         = 5432
    protocol        = "tcp"
    security_groups = [var.app_security_group_id]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# Security group for the rotation Lambda
# Needs outbound access to RDS and to the Secrets Manager VPC endpoint (or internet)
resource "aws_security_group" "rotation_lambda" {
  name        = "financial-app-rotation-lambda"
  description = "Allow rotation Lambda to reach RDS and Secrets Manager"
  vpc_id      = var.vpc_id

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# DB subnet group: RDS requires subnets in at least two AZs
resource "aws_db_subnet_group" "main" {
  name       = "financial-app-db-subnet-group"
  subnet_ids = var.private_subnet_ids

  tags = {
    Name = "financial-app-db-subnet-group"
  }
}

`iam.tf`: roles for RDS Proxy and rotation Lambda

# Role for RDS Proxy to read credentials from Secrets Manager
resource "aws_iam_role" "rds_proxy_role" {
  name = "RDSProxySecretsManagerRole"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "rds.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })
}

resource "aws_iam_role_policy" "rds_proxy_secrets" {
  name = "RDSProxySecretsManagerPolicy"
  role = aws_iam_role.rds_proxy_role.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ]
      Resource = aws_secretsmanager_secret.db_credentials.arn
    }]
  })
}

`rds.tf`: RDS instance and Proxy

resource "aws_db_instance" "primary" {
  identifier              = "financial-app-db"
  engine                  = "postgres"
  engine_version          = "15.4"
  instance_class          = "db.t3.medium"
  allocated_storage       = 100
  db_name                 = "financialdb"
  username                = "dbadmin"
  password                = var.db_password
  multi_az                = true
  storage_encrypted       = true
  backup_retention_period = 7
  skip_final_snapshot     = false

  vpc_security_group_ids = [aws_security_group.rds.id]
  db_subnet_group_name   = aws_db_subnet_group.main.name

  tags = {
    Name = "financial-app-db"
  }
}

resource "aws_db_proxy" "main" {
  name                   = "financial-app-proxy"
  debug_logging          = false
  engine_family          = "POSTGRESQL"
  idle_client_timeout    = 1800
  require_tls            = true
  role_arn               = aws_iam_role.rds_proxy_role.arn
  vpc_security_group_ids = [aws_security_group.rds_proxy.id]
  vpc_subnet_ids         = var.private_subnet_ids

  auth {
    auth_scheme = "SECRETS"
    iam_auth    = "DISABLED"
    secret_arn  = aws_secretsmanager_secret.db_credentials.arn
  }

  tags = {
    Name = "financial-app-proxy"
  }
}

resource "aws_db_proxy_default_target_group" "main" {
  db_proxy_name = aws_db_proxy.main.name

  connection_pool_config {
    connection_borrow_timeout    = 120
    max_connections_percent      = 100
    max_idle_connections_percent = 50
  }
}

resource "aws_db_proxy_target" "main" {
  db_instance_identifier = aws_db_instance.primary.identifier
  db_proxy_name          = aws_db_proxy.main.name
  target_group_name      = aws_db_proxy_default_target_group.main.name
}

The application connects to aws_db_proxy.main.endpoint, not to the RDS instance endpoint directly.

`secrets.tf`: Secrets Manager and rotation

The rotation Lambda comes from the AWS Serverless Application Repository. AWS maintains it. You do not write or host any rotation code.

resource "aws_secretsmanager_secret" "db_credentials" {
  name                    = "financial-app/db-credentials"
  recovery_window_in_days = 7

  tags = {
    Name = "financial-app-db-credentials"
  }
}

resource "aws_secretsmanager_secret_version" "db_credentials" {
  secret_id = aws_secretsmanager_secret.db_credentials.id

  secret_string = jsonencode({
    username             = "dbadmin"
    password             = var.db_password
    engine               = "postgres"
    host                 = aws_db_instance.primary.address
    port                 = 5432
    dbname               = "financialdb"
    dbInstanceIdentifier = aws_db_instance.primary.identifier
  })
}

# Deploy the AWS-managed rotation Lambda from the Serverless Application Repository
resource "aws_serverlessapplicationrepository_cloudformation_stack" "rotation_lambda" {
  name             = "SecretsManagerRDSPostgreSQLRotationSingleUser"
  application_id   = "arn:aws:serverlessrepo:us-east-1:297356227824:applications/SecretsManagerRDSPostgreSQLRotationSingleUser"
  semantic_version = "1.1.387"

  capabilities = [
    "CAPABILITY_IAM",
    "CAPABILITY_RESOURCE_POLICY"
  ]

  parameters = {
    endpoint            = "https://secretsmanager.${var.aws_region}.amazonaws.com"
    functionName        = "SecretsManagerRDSPostgreSQLRotation"
    vpcSubnetIds        = join(",", var.private_subnet_ids)
    vpcSecurityGroupIds = aws_security_group.rotation_lambda.id
  }
}

data "aws_lambda_function" "rotation" {
  function_name = "SecretsManagerRDSPostgreSQLRotation"
  depends_on    = [aws_serverlessapplicationrepository_cloudformation_stack.rotation_lambda]
}

resource "aws_lambda_permission" "secrets_manager" {
  statement_id  = "AllowSecretsManagerInvocation"
  action        = "lambda:InvokeFunction"
  function_name = data.aws_lambda_function.rotation.function_name
  principal     = "secretsmanager.amazonaws.com"
}

resource "aws_secretsmanager_secret_rotation" "db_credentials" {
  secret_id           = aws_secretsmanager_secret.db_credentials.id
  rotation_lambda_arn = data.aws_lambda_function.rotation.arn

  rotation_rules {
    automatically_after_days = 30
  }

  depends_on = [aws_lambda_permission.secrets_manager]
}

`outputs.tf`

output "proxy_endpoint" {
  description = "Connect the application to this endpoint, not to the RDS instance directly"
  value       = aws_db_proxy.main.endpoint
}

output "secret_arn" {
  description = "ARN of the Secrets Manager secret storing database credentials"
  value       = aws_secretsmanager_secret.db_credentials.arn
}

output "rds_instance_id" {
  description = "RDS instance identifier"
  value       = aws_db_instance.primary.identifier
}

Validating the deployment

Check 1: Multi-AZ is active

aws rds describe-db-instances \
  --db-instance-identifier financial-app-db \
  --query 'DBInstances[0].MultiAZ'
# Expected: true

Check 2: RDS Proxy is available and connected to the instance

aws rds describe-db-proxies \
  --db-proxy-name financial-app-proxy \
  --query 'DBProxies[0].Status'
# Expected: "available"

aws rds describe-db-proxy-targets \
  --db-proxy-name financial-app-proxy \
  --query 'Targets[*].{Endpoint:Endpoint,State:TargetHealth.State}'
# Expected: State "AVAILABLE"

Check 3: rotation is configured and working

aws secretsmanager describe-secret \
  --secret-id financial-app/db-credentials \
  --query '{RotationEnabled:RotationEnabled,LastRotatedDate:LastRotatedDate,NextRotationDate:NextRotationDate}'

To trigger a manual rotation immediately and confirm the Lambda executes without errors:

aws secretsmanager rotate-secret \
  --secret-id financial-app/db-credentials

Then check the rotation status:

aws secretsmanager describe-secret \
  --secret-id financial-app/db-credentials \
  --query 'RotationRules'

Check 4: simulate a failover

RDS provides a reboot-with-failover option that forces the standby to become primary. This lets you observe the actual failover behavior before a real incident:

aws rds reboot-db-instance \
  --db-instance-identifier financial-app-db \
  --force-failover

Monitor the event log during the failover:

aws rds describe-events \
  --source-identifier financial-app-db \
  --source-type db-instance \
  --duration 10 \
  --query 'Events[*].{Time:Date,Message:Message}'

The application should continue serving requests through the Proxy during this window. Check your application logs for connection errors. If the Proxy is working correctly, you should see none.

Why the other options do not work?

Option: automated backups with PITR

PITR restores to a point in time by replaying transaction logs onto a snapshot. This creates a new RDS instance. Provisioning a new instance, restoring data, and updating connection strings takes 15 to 30 minutes at minimum. The 60-second RTO is not achievable with this approach.

Option: Parameter Store with EventBridge rotation

Parameter Store does not have native RDS credential rotation. You write the rotation logic yourself in Lambda, manage the staging window yourself, and handle the transition between old and new credentials yourself. This is exactly what Secrets Manager already does, with managed Lambda functions and staging label support built in. Option D reimplements a subset of Secrets Manager without the reliability guarantees.

Option: read replica with manual promotion

A read replica provides an asynchronous copy of the data. Promotion requires manual steps: stopping replication, promoting the replica, updating the application connection string. The process takes several minutes and requires human intervention. Neither the RTO nor the automation requirement is met.

What the architecture looks like end to end

Application
    |
    v
RDS Proxy endpoint
    |
    |-- Normal operation --> RDS Primary (AZ-a)
    |                             |
    |                         Synchronous replication
    |                             |
    |                        RDS Standby (AZ-b)
    |
    |-- During failover --> Proxy detects new primary
                            Proxy reroutes internally
                            Application connection stays alive

Secrets Manager (30-day rotation schedule)
    |
    v
Rotation Lambda (inside VPC)
    |-- Updates password in RDS
    |-- Updates AWSCURRENT in Secrets Manager
    |
RDS Proxy reads new credentials on next refresh
Application never sees the credential change

Cost to keep in mind

Multi-AZ doubles the instance cost because the standby runs continuously. RDS Proxy charges per vCPU of the underlying RDS instance per hour. Secrets Manager charges $0.40 per secret per month plus $0.05 per 10,000 API calls.

For a financial application with a 1-second RPO and 60-second RTO requirement, the alternative to this setup is manual failover, potential data loss, and credential management code you have to maintain and test yourself.

DynamoDB Now Does Vector Search

Marcelo Acosta Cavalero — Tue, 18 Aug 2026 16:57:51 +0000

Originally published on Build With AWS. Subscribe for weekly AWS builds.

On August 5, 2026, AWS made vector search generally available in Amazon DynamoDB.

The headline promises single-digit millisecond searches, 99%+ recall, and a design that reaches trillions of vectors.

The reaction across engineering forums split in two within hours.

One group read it as the end of a product category, with variations on “so I don’t need S3 Vector buckets anymore?” and “MongoDB is finished.”

Another group opened the service quotas page and came back with a much narrower reading, pointing out that the documented way to hold latency down and scale search throughput as your index grows is to keep each query scoped to a manageable partition.

Both readings are defensible from the announcement alone.

The documentation settles it, and it also contains three things the announcement never mentions: a hard requirement that rules out many existing tables, a security warning that matters enormously for multi-tenant applications, and a pricing example where vector writes cost far more than searches.

Before any of that makes sense, we need to talk about what a vector actually is, because the rest follows from it.

What a Vector Actually Is

Imagine you run a bookstore and you want to arrange books so that similar ones sit near each other.

You could sort alphabetically, but then a cookbook lands beside a book on cosmology. Instead, suppose you give every book a set of coordinates, the way a city gives every building a street address.

One coordinate might loosely capture “how technical is this,” another “how much does this concern food,” another “how narrative is this.”

Books about pasta end up clustered in one corner of the room. Books about black holes end up in a different corner.

An embedding is exactly that: a list of numbers that acts as an address describing the meaning of a piece of text.

A machine learning model reads your text and produces the address.

Two pieces of text that mean similar things get addresses that sit close together.

That closeness is the whole trick, and it is why the technique works for search: you convert the shopper’s phrase “lightweight running shoes for summer” into an address, then look for products whose addresses are nearby.

You never match keywords. You match meaning.

That is why people call it semantic search, and it is why a search for “footwear for hot weather” can surface a product whose description never uses either word.

The number of coordinates is called the number of dimensions. Our bookstore used three. Real models use hundreds or thousands, because meaning is complicated and three numbers cannot capture it. DynamoDB accepts up to 4,096 dimensions.

Because there are many ways to measure “near,” you have to pick one, called the distance function.

Picture each address as an arrow drawn from the middle of the room out to that point. You now have two arrows, one for the shopper’s query and one for a product, and three sensible ways to compare them.

Cosine distance only cares about the angle between the arrows, ignoring their length. It asks “are these pointing the same way,” which for text means “are these about the same thing,” while ignoring how emphatically each one says it.

Euclidean distance is the tape-measure answer: how far apart are the two arrowheads in a straight line. Length matters here, so a long arrow and a short arrow pointing identically still count as far apart.

Dot product is the one worth slowing down for, because everyone repeats the phrase “it considers direction and magnitude” without saying what it does.

Think of two people pushing a shopping cart. If both push in the same direction, the work they get done depends on the direction and on how hard each pushes: two people shoving hard in agreement moves the cart much further than two people nudging it gently.

If one pushes sideways, their effort barely contributes. If one pushes backwards, they actively subtract. The dot product is that number, agreement scaled by effort, which is precisely why dot product scores can come out negative when the two arrows point opposite ways.

AWS calls Cosine the safe default when you are unsure, and otherwise recommends matching whatever measure your embedding model’s own documentation specifies.

Dot product then comes with a choice worth understanding rather than following blindly.

AWS recommends normalizing your embeddings to unit length, which means rescaling every arrow to exactly the same length so only direction can differ. Do that and dot product ranks results identically to Cosine, because you have removed the “how hard each person pushes” part and left only “do they agree.”

Skip normalization only when you want length to carry meaning. The documentation’s example is a recommendation system that stretches each product’s arrow in proportion to its popularity score, so popular products push harder and rank higher.

One trap here has caught people in every vector database that offers a choice.

For Cosine and Euclidean, a lower score means a closer match, with zero meaning identical. For Dot product, higher means closer. The comparison flips depending on a setting you chose weeks earlier, and nothing stops you from sorting the wrong way.

Two related details are easy to get wrong: Cosine distance here runs from 0 for identical direction up to 2 for opposite directions, not 0 to 1, and Dot product scores can be negative for vectors pointing the opposite way.

If you write a relevance threshold assuming scores never go below zero, it will behave strangely on exactly the results you meant to exclude.

What DynamoDB shipped is not a new data type for any of this.

You store the embedding in the ordinary List type, where each element is a Number holding one coordinate, and you write it with a normal PutItem or UpdateItem call. No new data type and no change to your item schema is required, though as the next section covers, you may still need to change one setting on the table itself.

What is new is a new kind of index. An index is a second, reorganized copy of your data that DynamoDB maintains for you, kept in a shape that makes one particular question fast, the way a library keeps a card catalog sorted by author alongside shelves sorted by subject.

You declare a vector index on the attribute holding your embeddings, then query it through a new SearchVectors call that takes a query address, a count of how many neighbors you want (up to 100, called top-K), and optional filters.

Two words from that setup will recur, so here they are up front.

The SearchSchema is simply the bundle of settings you declare when creating the index, holding the grouping attribute and the attributes you want to filter on. It is the form you fill in when you order the card catalog.

The projection is your choice of which of the item’s other attributes get copied onto the index entry alongside the vector, the way a catalog card carries the title and author but not the book’s full text.

Copy little and the card is cheap but you have to go fetch the book to read anything else.

Copy everything and the card is self-sufficient but expensive, in ways the pricing section gets specific about.

Almost every design choice about that index is fixed the moment you create it.

You cannot change the number of dimensions or the distance function.

The SearchSchema is fixed at creation, and the documentation is explicit that you cannot add, remove, or change the partition key afterward.

Projection choices are fixed too: with an INCLUDE projection you cannot later change which attributes are included.

Changing any of these means creating a second index and migrating to it, which AWS documents as a four-step dance: create the new index under a different name, wait for it to finish backfilling, cut your application over, then delete the old one to stop paying for its storage.

Backfilling is what happens when you point an index at a table that already holds data: DynamoDB walks every existing item and builds the index entry for it, because an index created today knows nothing about items written last year.

It is the clerk who has to sit down and type up a catalog card for every book already on the shelves before the catalog is any use to anyone.

Your base table is never affected, because DynamoDB re-derives the index from your items. But it does mean the design work happens up front, and this is the reason the rest of this post exists.

Finally, the 99%+ recall figure in the announcement is the most informative number in it.

Recall means: of the genuinely closest neighbors, what fraction did the search actually find? A figure below 100% tells you this is approximate nearest neighbor search, and AWS documents it as such.

Rather than comparing your query against every stored vector, which would be like reading every book in the building, the system uses a structure that walks it quickly to the right neighborhood and looks around there.

It usually finds the true nearest neighbors and occasionally misses one.

At large scale, production vector systems generally work this way, because the exact version does not survive contact with a billion items.

What matters practically is that AWS states a recall figure and gives you no knob to tune it. You get 99%+ or you use something else.

Two Requirements That Decide Whether You Can Use This At All

Before evaluating anything else, check two facts about your table, because either one can end the conversation.

The first is not mentioned in the announcement at all.

DynamoDB bills capacity in two modes.

Provisioned mode means you tell AWS in advance how much traffic to reserve, like booking a fixed number of restaurant tables for the evening.

On-demand mode means you pay per request and AWS handles the scaling, like walking in and being seated.

Vector indexes are supported only on tables using on-demand capacity mode, and are not supported on provisioned capacity tables.

If your production table runs provisioned capacity, which many cost-optimized tables do precisely because it is cheaper for steady predictable traffic, you must switch it to on-demand before you can add a vector index.

That is a real change to your cost profile, and it needs to be part of the evaluation rather than a surprise during implementation.

The second is a self-service threshold rather than a true ceiling.

You can create a vector index on a base table up to 600 GB without asking anyone. Above that, the quota is adjustable, but you have to go through AWS Support to raise it.

AWS does not publish a reason for the threshold, so I will not invent one.

The practical consequence is simply that the largest existing DynamoDB tables cannot self-serve their way into this feature and need a conversation first.

The Partition Key Is the One Decision You Cannot Change Your Mind About

DynamoDB’s default quotas are 1 GBps of vector search and 10 MBps of vector writes, per partition key value. Both are adjustable through AWS Support, so treat them as the shape of the system rather than a wall.

A partition key is the label DynamoDB uses to decide which group your data belongs to. In our bookstore, it is which branch of the shop a book lives in.

Every SearchVectors call must name exactly one partition key value, so every search happens inside one branch. You cannot search two branches in one call.

That constraint is what makes the whole thing fast.

A partition key restricts each search to the portion of the index belonging to a single value, and the call does not search the entire index.

Searching less data lowers cost, can improve latency and recall, and scales throughput sideways as you add more values.

Fifty branches give you roughly fifty times the total search and write capacity of one, because each branch gets its own 1 GBps allowance.

This is why the trillion-vector claim and the per-partition quota are both true at once, and it is worth being precise rather than dramatic about it.

AWS documents no storage limit for vector indexes, so the system as a whole genuinely has no size ceiling. Throughput, meanwhile, stays governed by those per-partition-key quotas.

Horizontal partitioning is the primary way to scale out, adding branches rather than enlarging one, and the per-partition quotas can also be raised through Support if a single branch genuinely needs more.

AWS’s own worked example makes the tradeoff concrete: a 768-dimension embedding plus 1 KB of other item data comes to roughly 4 KB per item, which works out to about 250,000 vectors examined per second and about 2,500 vector writes per second, per partition key value. As the number of vectors in a partition grows, each search examines more data and you approach the limit sooner.

So the partition key is your central design decision, and the guidance is more subtle than “pick something with lots of distinct values.” AWS says to avoid extremes in both directions.

The word for this is cardinality, which just means how many different values an attribute actually takes across your data. A yes-or-no flag has a cardinality of two.

A country field has around two hundred. An order ID has as many values as you have orders, one apiece. Both ends of that scale hurt you here, for opposite reasons.

Too few distinct values fails the obvious way. A boolean gives you two branches, most items land in one of them, and you get almost no throughput scaling and little of the latency or cost benefit.

Too many distinct values fails in a way that is easy to miss, and it is the more interesting failure. If you partition by something nearly unique, like an item ID, each branch ends up holding a single item. A nearest-neighbor search inside a branch with one occupant has no neighbors to compare against, so recall gets worse, not better. You have not made search faster, you have made it meaningless.

Splitting a bookstore into one building per book does not help anyone find a similar book.

The documentation’s example sits in the middle: location data partitioned by US state gives you about fifty values, each holding a meaningful population of vectors for good recall, and about fifty times the horizontal throughput. Good candidates have low-to-medium cardinality relative to the size and distribution of your dataset, hold enough vectors per value that nearest-neighbor search still has a meaningful population to search, and line up with a scope your application naturally searches on its own.

Tenant, workspace, geography, product category, or document collection can all work, but only when each value contains a real population. User ID is excellent if each user accumulates thousands of memory items and poor if each user has five. Nothing is automatically a good partition key.

The constraint also runs the other direction, which forces genuine design work. If your application truly needs to search across all tenants or all collections at once, you have two choices.

You can omit the partition key and accept one shared search space, where every query competes for a single allowance and examines more data as your indexed collection grows.

Or you can issue N separate SearchVectors calls and merge the ranked results yourself.

Merging is easy when the distance function is consistent across calls, but you pay for the aggregate bytes examined and returned across all N calls, and you inherit both the extra code and a worse tail latency.

Tail latency is the slow end of your response-time spread: not how long a typical request takes, but how long the unlucky few take. Fan-out makes it worse for a specific reason.

A fan-out query cannot finish until its slowest branch answers, and the more branches you query in parallel, the higher the chance that at least one of them lands in its own slow tail.

Choose carefully, because this is the decision the title of this post is about.

To filter more narrowly inside a partition, use inline filters instead, which the next sections cover.

Partition Keys Are Not Walls

This deserves its own section because it is the single most consequential thing in the documentation that the announcement does not mention, and because the natural way to use partition keys walks straight into it.

If you partition by tenant ID, it is tempting to conclude you have isolated your tenants. You have not.

The documentation is worth reading slowly: partition key scoping is a data-locality and performance optimization, not an access-control mechanism.

Any principal holding dynamodb:SearchVectors permission on the index can search any partition key value.

Principal is AWS’s word for whoever is making the call, whether that is a human user, an application, or another AWS service acting on your behalf.

The reason is a gap in the permission system.

Permissions in AWS are written as IAM policies, IAM being Identity and Access Management, the service that decides who is allowed to do what.

DynamoDB normally offers fine-grained access control, which lets an IAM policy say “this credential may only touch rows whose key starts with this tenant’s ID,” via a condition called dynamodb:LeadingKeys.

Think of it as a keycard that opens only your own floor of the building. That condition does not apply to SearchVectors.

Fine-grained access control is not supported for the SearchVectors API. The keycard reader is not installed on this door.

The practical consequence: a partition key is a signpost telling the search where to look, not a wall preventing it from looking elsewhere.

Any bug, and any code path where the caller gets to influence which partition key value your service searches on their behalf, becomes a cross-tenant data leak, and no IAM policy will stop it.

The shape to watch for is a tenant identifier that arrives in the request instead of being derived from the authenticated session, because at that point the caller is choosing which tenant’s data your trusted credentials go read.

If your workload requires strict tenant isolation at the data layer, AWS’s own recommendation is to use separate tables or separate indexes with distinct IAM grants per tenant, and to accept the operational cost that comes with that.

A Written Byte Costs 260 Times More Than a Searched Byte

Vector search bills on three dimensions, all charged on top of the normal costs of the underlying table:

Vector writes: $0.52 per GB written into the index, covering the vector plus any attributes copied along with it
Vector search: $0.002 per GB of data processed to build the response, including data returned
Storage: $0.25 per GB-month, the same rate as ordinary table storage

Look at the first two rates together.

Per gigabyte, writing costs 260 times more than searching. That ratio is the most surprising thing on the pricing page, and it points the opposite way from where most people expect the money to go.

AWS’s own worked example shows it landing. Take a knowledge base of one million items with 768-dimension vectors and 1 KB of projected attributes, running ten writes and ten searches per second for thirty days.

The searches, all 25.92 million of them, process 1,586 GB and cost $3.17.

The writes, also 25.92 million of them, cost $51.42. Storage adds $0.95. With equal numbers of reads and writes, the writes dominate by roughly sixteen times.

Be careful about what that does and does not prove. It is not a law that writes always dominate.

Your own balance depends on how often your content changes, how many searches you serve, how big each partition is, how many dimensions you chose, how much you project, and therefore how much data each search examines.

A workload serving millions of searches against a rarely-updated set of documents can easily spend more on searching than on writing.

What the example does establish is that the write side deserves attention it usually does not get, and that backfilling embeddings for an existing table is a real one-time cost worth estimating before you start.

One detail from the monitoring documentation turns into a genuine optimization. You are charged vector write capacity each time you write, update, or delete an item in a way that changes an attribute the vector index holds, and writes that touch nothing in the index cost nothing on it.

The condition matters more than it first appears.

If a frequently-updated field such as a view counter is not projected into the index and is not part of its SearchSchema, updating it incurs no vector write charge.

But with ProjectionType: ALL, that counter is in the index, so every increment is a vector write you pay for.

This is one of the places where a lazy projection choice quietly becomes a recurring bill, which leads directly into the next point.

On the search side, resist the temptation to reverse-engineer per-query cost from index size.

AWS does not publish what fraction of an index a query examines, and the honest answer is that you cannot derive it from the documentation.

What you can do is measure it, because DynamoDB reports it directly.

Set ReturnConsumedCapacity on your requests and you get back VectorSearchRequestBytes for searches and VectorWriteRequestBytes for writes, both also published to CloudWatch, AWS’s monitoring service for metrics from AWS services and applications.

Those two metrics, measured against your own data and your own query mix, will tell you more than any published estimate.

Two more levers matter for cost, both about restraint.

Projection controls which table attributes get copied into the index, and a broader projection increases both storage and write cost. Project only what you read directly from search results and fetch the rest with a follow-up GetItem.

Separately, returning the vector attribute itself in your results is expensive, because the response then carries the full list of coordinates. You almost never need it.

Finally, dimensions cost money twice. A 1,536-dimension vector uses roughly four times the vector storage of a 384-dimension one, and higher dimensions raise both search and write charges because every vector carries more data.

Embeddings are stored in the index at 32-bit floating point precision, about four bytes per dimension, so the vector portion of a 1,536-dimension entry runs roughly 6 KB before you add projected attributes.

Higher-precision values are accepted but lose precision on the way into the index. Choose the smallest number of dimensions that meets your relevance needs, and remember you cannot change it later.

What the API Will Not Do For You

Several limitations are documented clearly and are easy to miss when you are reading a launch post.

Search results are eventually consistent. The documentation states that there may be a brief delay between writing or updating a vector and its appearing in search results.

“Real-time” in the launch title describes how fast a search returns, not how fast a new vector becomes findable.

For many product-catalog workloads a brief propagation delay is acceptable, though not all of them: newly added items, price changes, and stock status can all be cases where it is not.

For agent memory, where an AI assistant stores what it learned during one turn of a conversation so it can look the fact up on the very next turn, it becomes a correctness question.

Either way, measure the actual lag against your own write pattern before you design around it.

Filters are exact-match only. Inline filters let you narrow results on non-vector attributes, up to 18 per index, but only on exact values.

No BETWEEN, no BEGINS_WITH, no ranges of any kind.

That excludes a lot of what people actually want: price ranges, date windows, numeric thresholds, prefix matching.

The workaround is bucketing, encoding a price as a tier or a timestamp as a day key and matching exactly against the bucket.

It works, at the cost of granularity and a schema decision you must get right before building the index.

There is no keyword search. DynamoDB offers no lexical or BM25 component, meaning no scoring based on literal word matches.

Hybrid search, which blends literal matching with semantic matching and often beats either alone for document retrieval, is therefore not a single call here. You either run a second system for the lexical half and combine results in your application, or you accept semantic-only retrieval.

Responses cap at 16 MB with no pagination. You cannot ask for the next page. The documentation warns about the specific combination that hits this: projecting all attributes, with large items, at a high top-K.

If your items are big, narrow the projection or lower top-K.

You cannot use Query, Scan, or PartiQL against a vector index. Those are DynamoDB’s three normal ways of reading data, PartiQL being an SQL-like query language AWS offers as an alternative to the native API for people who would rather write something resembling SELECT.

None of them work here. SearchVectors is the only way to read from a vector index.

DynamoDB will not regenerate your embeddings. This one causes silent, hard-to-debug quality decay. If you edit a product description and do not recompute its embedding, the index keeps answering from the old address.

The text and its meaning-coordinates have drifted apart, and nothing errors out. Search quality just quietly gets worse.

AWS suggests catching content changes with DynamoDB Streams, a feed that reports every change made to your table as it happens, like a conveyor belt carrying a receipt for each edit past you, and running a downstream process that reads those receipts, regenerates the affected embeddings, and writes them back.

Build that on day one, not after someone complains about relevance.

An item can vanish from search results without any error.

If you remove the partition key attribute from an item, or forget to include it when writing, DynamoDB does not complain.

The item is silently de-indexed and stops appearing in searches, even though the base table row and its embedding are both still sitting there perfectly intact.

The book is still in the building; you just tore the branch label off its spine, and now nobody can find it.

If an item mysteriously disappears from results, check whether its partition key attribute is still present.

You cannot search an index while it is still filling up. After you create a vector index, DynamoDB backfills it from your existing items.

Searching before that finishes returns an error. Poll DescribeTable until IndexStatus is ACTIVE and Backfilling is false.

The same applies after restoring a table from a backup or from point-in-time recovery, DynamoDB’s continuous backup feature that lets you rewind a table to any second within a retention window, because in both cases DynamoDB rebuilds the index from the restored data rather than copying the old index wholesale.

The clerk has to retype every card.

DAX does not support SearchVectors. DAX is DynamoDB Accelerator, a cache that sits in front of your table and keeps recently-read items in memory so repeat reads skip the database entirely, the way a shop clerk keeps the ten most-requested titles on the counter instead of walking to the shelves each time.

Vector searches cannot use it. If your application reads through DAX today, vector searches have to bypass the counter and go to DynamoDB directly, which means they do not get the cache’s latency benefit.

Your ordinary cached reads carry on unaffected.

One small piece of good news among all this: only items that actually contain a valid vector attribute get replicated into the index.

Items without an embedding consume no vector index storage, so you can mix indexed and non-indexed items in the same table without paying for the latter.

Global tables are DynamoDB’s way of keeping copies of the same table in several AWS Regions at once, so users in Frankfurt and Sydney each read from a nearby copy instead of reaching across an ocean.

Each copy is a replica. If you run global tables, DynamoDB creates the vector index on every replica automatically from the definition you gave it once, so you do not set it up Region by Region.

Two behaviors are worth knowing.

Copying a new vector to the other Regions and indexing it there happen asynchronously, meaning the write finishes and confirms before the other copies have caught up, so a vector written in Frankfurt may not be findable in Sydney for a moment.

This holds even on tables using multi-Region strong consistency, the stricter mode where a strongly consistent read against any replica is guaranteed to see the latest successful write. That guarantee covers strongly consistent reads, and vector search sits outside it.

And because the search is approximate, the same query against identical data in two Regions can legitimately return slightly different results or ordering. That is not a bug to chase.

The state of local development support is worth confirming separately before you commit a team to this path. I found no current official documentation stating whether DynamoDB Local supports vector indexes, so treat it as an open question to verify rather than an assumption either way.

Choosing Between DynamoDB, S3 Vectors, OpenSearch, and Postgres

The “goodbye S3 Vectors” reaction is the wrong conclusion, and the pricing structures show why they are built for different jobs.

S3 Vectors charges $0.06 per GB-month for storage against DynamoDB’s $0.25 on the Standard table class, roughly 4.2 times cheaper, and $0.20 per GB uploaded against $0.52. A table class is which pricing plan a DynamoDB table sits on, and that storage gap narrows if you move to the Standard-Infrequent Access class, which cuts storage to 40% of Standard while raising request charges to 125%.

S3 Vectors also charges a fixed $2.50 per million queries plus tiered data processing that gets cheaper as the index grows, plus a charge for data returned above a small free allowance.

DynamoDB has no fixed per-request fee at all; you pay purely for bytes processed and returned.

Read those structures side by side and the split is clear. S3 Vectors is priced to reward large indexes queried at moderate rates. DynamoDB is priced to reward small partitions queried at high rates with low latency.

Rather than assigning use cases absolutely, it is more accurate to say which way each option leans:

DynamoDB vector search favors data already living in DynamoDB, single-digit millisecond requirements, high query rates, and searches that naturally scope to one partition.
S3 Vectors favors much larger volumes of vectors, lower query frequency, and workloads where roughly 100 millisecond to sub-second latency is acceptable and storage economics dominate. AWS positions it for agentic workloads too, so this is a leaning, not a boundary.
OpenSearch favors rich literal-word search, range and metadata filtering, aggregations, and native hybrid retrieval combining keyword and vector scoring in one query.
PostgreSQL with pgvector favors cases where you need joins, range conditions, aggregations, and vector similarity together in one database with transactional guarantees.

Two capabilities in that list carry the weight, because the loose phrase “you no longer need Postgres or OpenSearch” leans on both.

An aggregation answers a question about a group rather than about individual rows, such as how many matches fall in each category, and vector search returns neither. A join answers one question from two separately stored collections at once, such as returning matching products along with each supplier’s name.

PostgreSQL does joins natively.

OpenSearch is a search engine, excellent at literal and hybrid retrieval, but it does not do relational joins.

They are not interchangeable, and neither is replaced by a SearchVectors call.

Several practitioners raised fair objections in the launch discussion. One noted that OpenSearch is frequently among the most expensive data stores in an AWS estate and that schema changes on a large cluster are painful.

Both observations are accurate, and neither makes DynamoDB a drop-in substitute for a search engine.

The sharpest pushback came from someone running a self-managed MongoDB cluster: five substantial nodes, 2 TB of data, about $1,400 per month, with a DynamoDB migration estimated above $15,000.

The counterargument arrived immediately and is equally valid: what does the engineer maintaining that cluster cost, and what availability, durability, and tail latency does it actually deliver?

Both sides are right, which is precisely why this is an architecture decision and not a price lookup.

If you already run reliable infrastructure and employ the people to keep running it, the premium you pay AWS to operate the thing for you buys you less. If your alternative is turning a small product team into a part-time database operations group, it buys you a great deal.

The genuinely new option is narrower and more useful than the headline suggests: you can now add similarity search to an application whose data already lives in DynamoDB, without standing up a second database and without maintaining a synchronization pipeline to keep the two copies aligned.

That pipeline was never the interesting part of anyone’s architecture, and it broke often enough to matter. Deleting it is the real win.

Working Through the Decision

Take this path if your data already lives in DynamoDB, your table uses on-demand capacity or can reasonably move to it, you can name a partition key today that both matches your query scope and holds a real population of vectors per value, your filters are exact-match or can be bucketed into exact matches, and either your tenants do not require data-layer isolation or you are willing to give each one its own table or index. Under those conditions this beats the alternative comfortably, because the alternative means a second database and a synchronization pipeline you would rather not own.

Look elsewhere if you need range filters or hybrid keyword-and-semantic retrieval, if your indexed data is large and cold and your query volume is modest, which is the S3 Vectors profile, if your access pattern requires searching all of it at once, or if strict multi-tenant isolation at the IAM layer is non-negotiable.

Whichever way you lean, measure three things before committing.

Track VectorSearchRequestBytes and VectorWriteRequestBytes against your real data and query mix, because they replace every estimate in this post with a number from your own workload.

Measure actual propagation lag between writing a vector and finding it.

And test p99 search latency while ordinary key-value traffic runs against the same table at production volume.

The p99, or 99th percentile, is the time within which 99 out of 100 requests complete, which makes it a measure of your worst hundredth rather than your typical case.

Averages hide that request entirely, and it is the one the user notices and complains about, which is why it is the number worth watching. Test it under mixed load because vector search shares the table’s underlying infrastructure and mixed-workload behavior under load is the one variable nobody has published numbers for.

Whatever you find there will tell you more than any launch post, including this one.

I publish every week at buildwithaws.substack.com. Subscribe. It's free.

Amazon Bedrock Service Tiers: Priority vs Flex

Kayne Rodrigo — Tue, 18 Aug 2026 13:47:06 +0000

The Problem: Every Request Gets the Same Tier

When I first saw Bedrock's new service tiers, I thought the decision was going to be
pretty straightforward: use Priority when latency matters, Default for normal traffic,
and Flex for anything that can wait.

But before putting that logic into a router, I wanted to answer a simpler question:
does Priority actually make my requests faster?

The pricing table makes the case seem obvious — Priority costs roughly 1.75× Default,
Flex costs roughly 0.5× Default. The implication baked into that pricing is that you
get something proportional in return. I didn't want to build a router on top of that
assumption without testing it first. So I tested it.

The results changed how I thought about the whole problem.

Why This Experiment, Why Now

AWS documentation tells you what each tier is intended for. Pricing tells you the
obvious economic incentive. But neither tells you what happens with your specific
workload, region, and traffic pattern.

I didn't want to build another "Flex is for batch, Priority is for real-time" demo.
I wanted to see what actually happened when I ran real requests through all three
tiers, modeled the economics across different traffic distributions, and built a
routing layer I could actually read, reason about, and change without guessing at
the consequences.

That is what led to this project: a measurable, reproducible experiment rather than
a confident assumption presented as a tutorial.

Architecture: Four Small Modules, One Clean Pipeline

I intentionally kept the router boring.

No LangChain. No LLM classifier. No abstraction layers. Just four small Python
modules doing one thing each: validate the workload label, choose a tier, check
whether that tier is available, and return a decision. I wanted to look at any
routing outcome and immediately understand why it happened.

classify → policy → capability check → routing decision

Component responsibilities:

Module	Role
`router/classifier.py`	Validates and normalizes workload category strings
`router/policy.py`	Maps workload categories to preferred service tiers
`router/capability.py`	Checks tier availability; selects deterministic fallbacks
`router/router.py`	Orchestrates classify → policy → capability → decision

Why four modules instead of one function? I split the concerns because the
policy is the part I expect to change most often. By isolating it in a frozen
dataclass, I can swap in a different policy — database-backed, A/B split,
per-tenant — without touching the capability checker or the orchestrator.

AWS services used:

Amazon Bedrock Runtime (bedrock-runtime) — the converse API with the serviceTier parameter. This is how you specify which tier to use; omitting it defaults to Default.
boto3 — the AWS SDK for Python.

Why not a framework? The routing logic is a pure decision function. Adding
LangChain or a similar framework would add indirection without adding value. The
router is a component that plugs into your existing Bedrock call, not a
replacement for it.

Implementation Walkthrough

Step 1: Validate the workload category

I wanted invalid workload labels to fail early rather than silently becoming a
potentially expensive routing decision.

# router/classifier.py

class WorkloadCategory(str, Enum):
    CRITICAL    = "critical"
    INTERACTIVE = "interactive"
    BACKGROUND  = "background"


def classify_workload(workload_category: str | WorkloadCategory) -> WorkloadCategory:
    if workload_category is None:
        raise InvalidWorkloadCategoryError("Workload category is required.")

    if isinstance(workload_category, WorkloadCategory):
        return workload_category

    normalized = workload_category.strip().lower()

    try:
        return WorkloadCategory(normalized)
    except ValueError as exc:
        valid = ", ".join(c.value for c in WorkloadCategory)
        raise InvalidWorkloadCategoryError(
            f"Unknown workload category: {workload_category!r}. "
            f"Expected one of: {valid}."
        ) from exc

The str enum base class means a WorkloadCategory behaves like a string in
comparisons and CSV output — no .value everywhere.

Step 2: Apply the routing policy

Keeping the policy in its own module was deliberate. I expect this to be the part
I change most often as I learn more about the actual workload.

# router/policy.py

@dataclass(frozen=True)
class RoutingPolicy:
    mapping: dict[WorkloadCategory, ServiceTier]

    @classmethod
    def default(cls) -> "RoutingPolicy":
        return cls(
            mapping={
                WorkloadCategory.CRITICAL:    ServiceTier.PRIORITY,
                WorkloadCategory.INTERACTIVE: ServiceTier.DEFAULT,
                WorkloadCategory.BACKGROUND:  ServiceTier.FLEX,
            }
        )

    def preferred_tier(self, workload: WorkloadCategory) -> ServiceTier:
        try:
            return self.mapping[workload]
        except KeyError as exc:
            raise UnsupportedPolicyError(
                f"No routing policy exists for workload: {workload!r}."
            ) from exc

Step 3: Check capability and resolve fallbacks

This ended up being more important than I initially expected. Choosing a tier is
one thing; actually being able to use it is another. The capability checker
resolves to an available fallback using a configured chain:

# router/capability.py (fallback defaults)
#   priority → default
#   flex     → default
#   default  → no fallback (RuntimeError if unavailable)

def resolve(self, requested_tier: str | ServiceTier) -> tuple[ServiceTier, bool]:
    requested = self.normalize_tier(requested_tier)

    if self.is_available(requested):
        return requested, False       # (resolved_tier, used_fallback)

    fallback = self._fallback_order.get(requested)

    if fallback is not None and self.is_available(fallback):
        return fallback, True

    raise RuntimeError(
        f"Requested tier '{requested.value}' is unavailable and no "
        "available fallback is configured."
    )

Step 4: Compose in the Router

At this point the router is intentionally simple: it turns a workload label into
a concrete tier decision.

# router/router.py

class Router:
    def __init__(
        self,
        policy: RoutingPolicy | None = None,
        capability_checker: TierCapabilityChecker | None = None,
    ) -> None:
        self.policy = policy or RoutingPolicy.default()
        self.capability_checker = capability_checker or TierCapabilityChecker()

    def route(self, workload_category: str | WorkloadCategory) -> RoutingDecision:
        workload       = classify_workload(workload_category)
        requested_tier = self.policy.preferred_tier(workload)
        resolved_tier, used_fallback = self.capability_checker.resolve(requested_tier)

        return RoutingDecision(
            workload=workload,
            requested_tier=requested_tier,
            resolved_tier=resolved_tier,
            used_fallback=used_fallback,
        )

Step 5: Pass the resolved tier to Bedrock

This is the part that makes the project more than a routing abstraction — the
decision ultimately becomes a real serviceTier parameter in a live Bedrock call.

decision = router.route("background")   # → RoutingDecision(resolved_tier=FLEX, ...)

response = bedrock.converse(
    modelId="apac.amazon.nova-pro-v1:0",
    messages=[{"role": "user", "content": [{"text": prompt}]}],
    inferenceConfig={"maxTokens": 128, "temperature": 0},
    serviceTier={"type": decision.resolved_tier.value},   # ← this is the key param
)

The serviceTier parameter was added to the converse API alongside the tier
launch. If you are on an older boto3 version (pre-1.34), it will not exist —
upgrade to at least boto3==1.43.

IAM permissions required — no new permissions beyond standard model invocation:

{
  "Effect": "Allow",
  "Action": ["bedrock:InvokeModel"],
  "Resource": "arn:aws:bedrock:ap-southeast-1::foundation-model/amazon.nova-pro-v1:0"
}

Tier selection is a parameter in the existing converse call, not a separate API.

The Gotcha: Two Things I Expected That Turned Out to Be Wrong

Gotcha 1: Priority did not demonstrate lower latency in the experiment

This was the assumption I was most confident about going in: Priority should be
faster. The documentation describes it as the fastest tier and says it prioritizes
requests over Default and Flex. I fully expected to see that in the data.

The controlled tier experiment ran 300 requests across all three tiers in
randomized order. Here is what came back:

Tier	Mean (ms)	P95 (ms)
Priority	~803	~1,080
Default	~733	~1,045
Flex	~711	~903

Honestly, I was surprised. The documentation says Priority is the fastest tier,
but the experiment didn't show a statistically significant latency advantage for it.

I don't think those two things are actually contradictory — I think the experiment
just didn't create conditions where the difference becomes visible. The requests
were intentionally tiny: "Explain Amazon SQS in exactly three concise sentences."
That is roughly 10 input tokens and ~58 output tokens per request, running at 20 RPM
under light load. There is no real demand contention for Priority to resolve in your
favor under those conditions.

My hypothesis is that the difference would become more observable with larger prompts
and at higher request rates, where tiers would actually compete for inference capacity.
I haven't tested that yet, so I won't claim it — but it is the next experiment I would
run.

For now, if I had to explain Priority tier to a stakeholder, I would frame it this
way: you are paying for prioritized access, not raw speed. That distinction matters
more when there is actual demand competing for capacity. For short, low-frequency
requests, you are unlikely to feel it.

Gotcha 2: Workload-aware routing can cost more, not less

My second assumption was even simpler: if Flex is cheaper, sending batch workloads
there should obviously save money.

It does — but only if the rest of your workload does not contain too much Priority
traffic.

Here is the break-even rule I derived from the observed token profile:

~1.48 Flex-routed background requests are required to offset the cost of
one Priority-routed critical request.

The policy sensitivity model confirmed the consequence. Of 231 simulated workload
mixes, only 96 (42%) produced a cheaper result than All-Default. 134 (58%)
were more expensive. The model makes the extremes concrete:

Workload mix	Savings vs. All-Default
0% critical / 100% background	+50.00%
100% critical / 0% background	−75.00%

If your batch workload is genuinely deferrable, Flex is a compelling default. But
I wouldn't route something to Flex just because it's called "batch." The real
question is how much latency and availability variance you are willing to trade for
the lower cost. "Batch" tells you how the job runs; it doesn't tell you how tolerant
that job is to degraded service. Those are different questions, and the routing
decision should answer the second one.

Results: What the 100-Request Benchmark Actually Showed

The benchmark ran 100 live Bedrock requests in ap-southeast-1 against
apac.amazon.nova-pro-v1:0:

20 critical → Priority
50 interactive → Default
30 background → Flex

Routing

This was the part I most wanted to verify: did the router actually do what I told
it to do?

Metric	Result
Policy mapping accuracy	100.00%
Tier resolution accuracy	100.00%
Request success rate	100.00%
Fallback rate	0.00%

In this run, yes. Every workload resolved to the intended tier, every request
succeeded, and the fallback path was never needed.

Cost

Metric	Value
Estimated router cost	$0.019490
All-Default baseline	$0.019523
Savings	$0.000034 (0.17%)

This was smaller than I expected. The Priority premium on 20 critical requests
almost exactly cancelled the Flex savings on 30 background requests. The takeaway
is not that the router fails — it is that workload composition matters more than
simply "using tiers." The router gives you the lever; your traffic distribution
determines whether that lever saves money or costs you more.

Token usage

The benchmark deliberately used a small, standardized prompt so the tier comparison
stayed controlled: 1,000 input tokens and 5,851 output tokens across 100 requests,
averaging about 10 input and 58 output tokens per call. That also means the result
should not be generalized to large-context workloads.

Lessons Learned: What I Would Do Differently

1. Randomize request order from the start

Running critical → interactive → background in contiguous blocks means workload
category is correlated with request time. Any time-varying service behavior
contaminates the comparison. In the next experiment, I randomize.

2. Don't leave classification until the end

I built the router around an explicit label first because it made the experiment
cleaner. But that exposed a gap: in a real application, something still has to
decide whether a request is critical, interactive, or background. That problem is
non-trivial, and I would solve it before calling this production-ready. A
lightweight heuristic, or a Haiku-class model classifying on request metadata, is
probably the next piece.

3. Instrument the workload mix before you ship

This became obvious only after I saw the 0.17% result. The economic value of this
router is entirely determined by your critical-to-background ratio. Without a
dashboard showing that ratio in real time, you have no idea whether the router is
saving or costing money on any given day. Add the metric before the feature,
not after.

4. Stress-test Flex before relying on it

Flex is the only tier with an explicit throttling caveat in the AWS documentation.
I tested it at 20 RPM under light load and saw zero fallbacks. That is not a stress
test. Before routing anything important to Flex, verify how it behaves at or above
expected peak load.

5. Re-verify pricing per region before any billing claim

The pricing table I used reflects ap-southeast-1 at project time. Cross-region
inference profiles, other regions, and tier pricing can all differ. Any cost claim
in production needs current figures from the AWS pricing page for the exact model
and configuration.

6. Test different prompt sizes

This is probably the biggest open question I have after finishing the experiment.
Tiny prompts are good for controlled comparison but limit how much the latency
result generalizes. A follow-up should stratify by token count to test whether tier
differences become more observable as input and output sizes grow — which is also
where the cost differences become more meaningful.

What This Is, and What It Isn't

After running the experiments, this is the claim I am comfortable making:

A deterministic workload-aware router can successfully map critical,
interactive, and background workloads to Priority, Default, and Flex service
tiers respectively — with 100% routing accuracy in a 100-request benchmark,
an explicit fallback mechanism, and a measurable economic model whose value
is determined by workload distribution.

It is not a claim that the router universally saves money, that Priority is
reliably faster, or that this policy is production-optimal. Those claims would
require more evidence than one benchmark run against one model in one region
at light load.

I started this project thinking the tier decision would be straightforward.
The experiments made that mental model considerably less simple.

Priority didn't produce the latency advantage I expected under small-prompt
conditions. Flex can reduce cost, but only when enough of the workload can safely
tolerate it. And the economics can flip quickly once Priority traffic becomes a
large share of the mix.

That is ultimately why I think the router is useful — not because it magically
makes Bedrock cheaper, but because it forces the tier decision to become explicit,
measurable, and testable. Before building this, I was making implicit assumptions.
The router turned those assumptions into a policy I can read, change, and validate
against data.

Get the Code

The full project — router, benchmark scripts, analysis, and results — is on
GitHub: bedrock-tier-router

To run the unit tests locally (no AWS credentials needed):

git clone https://github.com/<your-org>/bedrock-tier-router.git
cd bedrock-tier-router
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pytest -v

Questions, corrections, and production war stories about Bedrock tier behavior
are welcome in the repo issues or in the AWS Community Builders Slack.

Kayne Rodrigo — AWS Community Builder, AI/ML Engineering Track

Appendix: Pricing Assumptions

These are the analytical rates used in all cost calculations in this post.
Re-verify against current AWS pricing before using for any billing estimate.

Tier	Input / 1M tokens	Output / 1M tokens
Default	$0.80	$3.20
Priority	$1.40	$5.60
Flex	$0.40	$1.60

Model: apac.amazon.nova-pro-v1:0, Region: ap-southeast-1,
cross-region inference profile.

How I Built a Kiro Crew App in 5 Minutes - Full Tutorial With Code

Sarvar Nadaf — Tue, 18 Aug 2026 12:05:57 +0000

Parts 1-4 showed you what Kiro Crew can do. Investigate incidents. Automate weekly toil. Block dangerous commands. All using the built-in agent.

Solves persistent cross-session memory limits

Sarvar Nadaf for AWS Community Builders

Aug 5

Introducing Kiro Crew: AWS's Open-Source AI Agent Orchestrator

#discuss #agents #ai #aws

12 min read

Unsupervised agents cost $2.10 weekly

Sarvar Nadaf for AWS Community Builders

Aug 7

How Kiro Crew's Cron Jobs Replaced 4 Hours of Weekly Toil

#showdev #agents #ai #devops

7 min read

But here's what nobody's talking about: Kiro Crew has an App Store. And you can build your own apps for it. In five minutes.

Not plugins. Not scripts. Full apps with their own agents, skills, cron jobs, and dashboard pages. Package them. Publish them. Other users install with one click.

I built one. A Daily Standup Bot. It reads my git commits every morning and generates standup notes so I never have to write "worked on X" again. Let me show you how.

What the App Kit actually is
What we're building
Step 1: The manifest (app.json)
Step 2: The agent
Step 3: The skill
Step 4: The dashboard page
Step 5: The cron job
Install and run
What it looks like live
Publishing to the App Store
What else you could build
Try it yourself

What the App Kit actually is

An app is a package that contributes any combination of:

Component	What it does
Agents	Custom AI agent with its own model, prompt, and tool access
Skills	On-demand knowledge files that teach the agent specific capabilities
MCP servers	New tools the LLM can call
Cron jobs	Scheduled tasks the app owns
UI pages	Custom pages in the dashboard sidebar
Backend processes	HTTP servers reverse-proxied through the gateway

An app that only ships a skill is one markdown file. An app that ships everything is a full project. You decide the scope.

The key difference from "just adding a skill": apps are installable, versioned, publishable, and isolated. Crew manages their lifecycle. Users install from the App Store with one click.

What we're building

A Daily Standup Bot that:

Reads git commits from the last 24 hours
Formats them as "What I Did / What's Blocked / What's Next"
Runs every weekday at 9 AM automatically
Shows standup history in a custom dashboard page

Five files. Five minutes. A real app you'd actually use.

standup-bot/
├── app.json                    ← manifest (identity + resources)
├── agents/
│   └── standup-agent.json      ← agent definition
├── skills/
│   └── standup-format/
│       └── SKILL.md            ← formatting rules
└── ui/
    └── src/App.tsx             ← dashboard page

Step 1: The manifest (app.json)

Every app needs one file: app.json. This is the single source of truth.

{
  "name": "standup-bot",
  "version": "1.0.0",
  "displayName": "Daily Standup Bot",
  "description": "Auto-generates standup notes from git commits.",
  "author": "sarvar_04",
  "agents": ["agents/standup-agent.json"],
  "skills": ["skills/standup-format"],
  "ui": {
    "entry": "dist/index.mjs",
    "pages": [{
      "route": "/apps/standup-bot",
      "label": "Standups",
      "icon": "ClipboardList"
    }]
  },
  "crons": [{
    "name": "morning-standup",
    "cron_expr": "0 9 * * 1-5",
    "message": "Generate today's standup summary from yesterday's git activity",
    "agent": "standup-agent"
  }]
}

That's agents, skills, a dashboard page, and a cron job. All declared in one file. Crew reads this and wires everything up.

Step 2: The agent

agents/standup-agent.json:

{
  "name": "standup-agent",
  "model": "auto",
  "description": "Generates standup summaries from git activity",
  "prompt": "You are a standup summary assistant. Analyze git commits from the last 24 hours and generate concise standup notes. Format: What I Did, What's Blocked, What's Next.",
  "tools": ["@kirocrew-core"]
}

Eight lines. The @kirocrew-core tool reference gives it access to spawn processes, read files, and interact with the system. The model: "auto" lets Crew pick the best available model.

Step 3: The skill

skills/standup-format/SKILL.md:

---
name: standup-format
description: How to format daily standup updates
triggers: [standup, daily, summary, morning]
always: false
---

# Standup Format

When generating standup notes:

1. **What I did** - List completed work from git commits (group by feature/fix)
2. **What's blocked** - Identify stale PRs, failing CI, unresolved issues
3. **What's next** - Infer from branch names and open issues

Rules:
- One line per bullet
- Past tense for "did", present for "blocked", future for "next"
- Group related commits into one bullet
- Skip merge commits and dependency bumps
- Flag anything unmerged for >24 hours

Skills are markdown. They load on-demand when trigger words appear in the conversation. No code. No compilation. Just knowledge the agent uses when relevant.

Step 4: The dashboard page

ui/src/App.tsx:

import { useAppApi, useAppEvents } from '@kirocrew/app-sdk'
import { Card, CardTitle, PageHeader, StatCard, Badge } from '@kirocrew/app-sdk/ui'
import { useState, useEffect } from 'react'

export default function StandupDashboard() {
  const api = useAppApi()
  const [standups, setStandups] = useState([])

  useEffect(() => {
    api.get('/api/apps/standup-bot/history').then(setStandups)
  }, [])

  return (
    <>
      <PageHeader title="Daily Standups" subtitle="Auto-generated from git activity" />
      <div className="px-6 pb-8">
        <div className="grid gap-3.5 grid-cols-4 mb-6">
          <StatCard label="Today" value="Pending" accent />
          <StatCard label="This Week" value={`${standups.length} standups`} />
          <StatCard label="Total Commits" value="0" />
          <StatCard label="Next Run" value="Mon 9:00 AM" />
        </div>
      </div>
    </>
  )
}

You don't npm install @kirocrew/app-sdk. The dashboard provides it at runtime. Your app stays tiny. Build with Vite, mark Crew's SDK as external, output a single .mjs file.

Step 5: The cron job

Already declared in app.json:

"crons": [{
  "name": "morning-standup",
  "cron_expr": "0 9 * * 1-5",
  "message": "Generate today's standup summary from yesterday's git activity",
  "agent": "standup-agent"
}]

Crew registers the cron on enable. Deregisters on disable. Every weekday at 9 AM, it spawns a session, runs the message through standup-agent, and stores the result. No daemon. No systemd timer. Just a line in your manifest.

Install and run

# Get your auth token
TOKEN=$(kirocrew token | grep -oP 'token=\K[^&]+')

# Install (one command - point to your app directory)
curl -s -X POST "http://localhost:5476/api/apps/install?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "./standup-bot"}' | python3 -m json.tool

# Enable - agents, skills, crons all activate
curl -s -X POST "http://localhost:5476/api/apps/standup-bot/enable?token=$TOKEN" \
  | python3 -m json.tool

Response:

{
    "ok": true,
    "name": "standup-bot",
    "message": "enabled standup-bot",
    "registration": {
        "agents": ["standup-bot/standup-agent"],
        "skills": ["standup-bot/standup-format"],
        "crons": ["standup-bot/morning-standup"],
        "mcp_servers": [],
        "errors": []
    },
    "hooks": {
        "crons_registered": ["standup-bot/morning-standup"]
    }
}

Agent registered. Skill loaded. Cron scheduled. Dashboard page live.

Refresh the dashboard. "Standups" is now in your sidebar. That's it.

What it looks like live

After installation, "Standups" appears in the sidebar. The dashboard shows stat cards and an empty state waiting for the first standup.

Trigger it manually in a chat session:

Use the standup-agent to generate today's standup from ~/projects/payment-api.
Run git log, analyze every commit, group by feature area.

The agent runs git log --since="24 hours ago" --oneline --no-merges, analyzes each commit, and produces:

What I Did:

Payment Processing:

Implemented rate limiting middleware for /api/payments (max 100 req/min per API key)
Fixed currency conversion rounding bug - was truncating before conversion
Added retry logic for failed Stripe webhook deliveries (exponential backoff, max 5)

API & Docs:

Updated OpenAPI spec with new error codes (429, 503, 504)
Added request validation for multi-currency checkout (USD, EUR, GBP, JPY)
Refactored payment intent creation to use idempotency keys

Infrastructure:

Configured DynamoDB TTL for expired sessions (7-day retention)
Added CloudWatch alarms for payment failure rate > 5%

What's Blocked:

PCI compliance security review - waiting on AppSec team (2 days)
Stripe Connect onboarding - blocked on legal approval

What's Next:

Subscription billing with usage-based metering
Payment analytics dashboard (revenue, failure rates, top merchants)

11 commits analyzed. 9 seconds. Navigate to the Standups page - it's already there.

Publishing to the App Store

The App Store is a curated registry. Publishing means opening a PR:

// In app-registry.json:
{
  "name": "standup-bot",
  "gitUrl": "https://github.com/simplynadaf/kiro-crew-standup-bot",
  "branch": "main"
}

Once merged, your app shows up in Explore → Library for all Crew users. Search "standup" and there it is:

Daily Standup Bot
v1.0.0 · Enabled · Registry

Auto-generates standup notes from git commits. Runs daily at 9 AM Mon-Fri.

sarvar_04
1 agent · 1 skill · 1 cron · 1 page

[Open]  [Disable]  [Sync]  [Uninstall]

Your app sits alongside the built-in ones - Code Review Sage, Research Lab, Task Runner. First-class citizen. Teams can also host private registries for internal apps that shouldn't be public.

What else you could build

The standup bot took 5 files and 5 minutes. Here's what's possible with the same pattern:

App idea	Components
PR Review Bot	Agent + skill (code review rules) + cron (check PRs hourly)
Incident Postmortem Generator	Agent + skill (postmortem template) + UI (history page)
Cost Anomaly Alerter	Agent + cron (daily AWS cost check) + Slack notification
Onboarding Buddy	Agent + skill (team knowledge) + UI (progress tracker)
Sprint Health Monitor	Agent + cron (daily Jira check) + UI (burndown chart)

Any workflow that's "check something + format it + deliver it on schedule" is a Crew app waiting to happen.

Try it yourself

Kiro Crew is open source (Apache 2.0). The standup-bot code is in this article.

# Install Crew
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh
kirocrew gateway

# Enable third-party apps
# In ~/.kiro/crew/config.json set: "apps_allow_third_party": true

# Create the app
mkdir -p standup-bot/agents standup-bot/skills/standup-format standup-bot/ui/src
# Create the 5 files shown above (app.json, agent, skill, UI, vite config)

# Build UI
cd standup-bot/ui && npm install && npm run build && cd ../..

# Install + enable
TOKEN=$(kirocrew token | grep -oP 'token=\K[^&]+')
curl -s -X POST "http://localhost:5476/api/apps/install?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "./standup-bot"}'
curl -s -X POST "http://localhost:5476/api/apps/standup-bot/enable?token=$TOKEN"

# Open dashboard - "Standups" is in the sidebar
kirocrew open

The full app code and docs: Build your first app

simplynadaf / kiro-crew-standup-bot

Daily Standup Bot — A Kiro Crew app that reads git commits and generates standup notes. Agent + Skill + Cron + Dashboard in 5 files.

🤖 Daily Standup Bot

A Kiro Crew App That Writes Your Standups For You

5 files. 5 minutes. Never write "worked on X" again.

An AI agent that reads your git commits every morning and generates formatted standup notes - installed with one command on Kiro Crew.

📺 Watch the Demo · 🚀 Quick Start · 📦 App Structure · 📝 Article

✨ Features

Component	What It Does
🤖 Agent	Reads git commits from the last 24 hours, groups by feature area
📚 Skill	Teaches the agent the standup format (What I Did / Blocked / Next)
⏰ Cron	Runs every weekday at 9 AM automatically
📊 Dashboard	Shows standup history, stats, and today's summary in the sidebar

🎬 Demo

Agent analyzes 11 commits → generates standup in 9 seconds → dashboard updates live

🚀 Quick Start

# Prerequisites: Kiro Crew running
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh
kirocrew gateway

…

View on GitHub

kirodotdev / KiroCrew

A persistent workspace for development work that self-improves and continues beyond one session.

Kiro Crew

A persistent workspace for development work that self-improves and continues beyond one session.

Kiro Crew is an open source development workspace that runs locally or remotely on your hardware. It is persistent, self-learning, and self-evolving. Work with it from the desktop app, web dashboard, and CLI, or continue the same work through connection tools like Slack and Discord Your multi-step tasks can run unattended, recurring jobs run on your schedule and heartbeats monitor systems until something needs attention. Kiro Crew Apps tailor that experience to a specific job, combining a purpose-built interface with agents, skills, schedules, integrations, and backend services.

Quick start · Build from source · Why Kiro Crew · Capabilities · How it works · Security · Install · Telemetry · Docs

Quick start

You choose how to run Kiro Crew: the desktop app with automatic updates, a one-line install on your machine or a remote…

View on GitHub

What's next

Part 6 will show the multi-interface story. Start a task on CLI. Continue it on Slack. Check progress on the dashboard. Get notified on your phone. Same agent, same memory, zero context loss.

The App Kit is what turns Kiro Crew from "my AI coding assistant" into "my team's AI platform." The store is empty right now. First movers win.

What would you build? A PR reviewer? A docs-from-code generator? An automated changelog? Drop it in the comments. If it's interesting enough, I'll build it in Part 7.