Posts Tagged - azurefunctions

Design reliable workflow steps (Durable Functions)

Durable orchestration preserva el workflow progress, pero la persistencia por si sola no hace que las operaciones externas sean seguras. Los model endpoints pueden hacer throttle de requests, los storage writes pueden sufrir timeouts y un host se pueden reiniciar.

Classify failures before retrying

Los retries ayudan con los fallos que sean efimeros. Consumen recursos por lo que no se reintentar de manera indiscriminada. Clasificar los fallos ayuda a poder resolverlos:

  • Transient failure Aplicar una bounded retry policy
  • Permanent failure Validar early y enrutar el item a un terminal outcome
  • Auth failure Revisar
  • Timeout Compensar el tiempo, escalar o preservar para auditar
  • Business-rule failure Una confidence score baja o un approval rechazado podemos enrutarlo a una workflow branch explicita

Las activity functions deberian raise failures que el orchestrator necesita tratar como errores técnicos. Pueden devolver outputs estructurados para distinguir casos que no se puedan cumplir de consumir retry attempts.

Apply bounded activity retries

Durable Functions pueden hacer schedule de una actividad con una retry policy. El durable runtime graba cada intento y espera entre intentos el solo. Ponemos un maximum attempt count para que un fallo persistente eventualmente llegue al orchestrator.

en python usamos la RetryOptions API

# Code fragment - focus on a bounded activity retry
import azure.durable_functions as df

retry_options = df.RetryOptions(
    first_retry_interval_in_milliseconds=5_000,
    max_number_of_attempts=3,
)

result = yield context.call_activity_with_retry(
    "process_document",
    retry_options,
    {
        "operation_id": operation_id,
        "document_id": document["document_id"],
        "blob_url": document["blob_url"],
    },
)

NO debemos hacer nest de muchos retry layers no controladas. Calcular el maximo numero de retry attempts y tiempo combinado y configurar ambas capas de manera intencional

Enforce durable timeouts

Una retry policy limita los intentos, mientras que un timeout limita cuanto tiempo espera el workflow por un outcome. Durable timers permiten a un orchestrator expresar una deadline sin mantener recursos activos.

Un timer que gane a task_any() no cancela automaticamente una activity que ya ha comenzado. La activity puede todavia finalizar y producir external side effects. Usamos operation record o cancellation flag que el activity comprueba cuando es necesario, haciendo un eventual write idempotente. Diseñamos el workflow para ignorar un late result tras una terminal deadline.

Timeout scopes:

  • Client request timeout Bound one HTTP o SDK call dentro de una activity
  • Activity retry window Bound de attempts y delays para un durable step
  • Workflow step timeout Race durable task against durable timer
  • End-to-end deadline Stop or compensates workflow when the business process exceeds its allowed duration

Make activity side effects idempotent

IMPORTANTE

Durable Functions proveen de at-least-once activity execution. Una activity puede completar un external write y entonces ejecutarse de nuevo si el host falla antes de que el runtime grabe sus resultados.

La idempotencia asegura que repetir las mismas operaciones produce el mismo resultado, en vez de crear duplicados

Derivar una stable operation ID de orchestration input, o crear una con context.new_uuid() y lo pasamos a la activity. Usamos ese ID como database key, blob name, o cualquier otra key.

NUNCA crear operation ID con uuid.uuid4() ya que esto causaria que cada reintento parezca que es trabajo nuevo, cuando en realidad estaríamos creando duplicados

/IMPORTANTE

usamos operation ID como blob name y creamos el resultado solo cuando no exista

# Code fragment - focus on an idempotent result write
import json
from azure.core.exceptions import ResourceExistsError


def persist_result(request: dict) -> dict:
    blob_name = f"results/{request['operation_id']}.json"
    blob_client = results_container.get_blob_client(blob_name)
    payload = json.dumps(request["result"])

    try:
        blob_client.upload_blob(payload, overwrite=False)
        write_status = "Created"
    except ResourceExistsError:
        write_status = "AlreadyExists"

    return {
        "operation_id": request["operation_id"],
        "result_url": blob_client.url,
        "write_status": write_status,
    }

Compoensate completed side effects

Distributed workflows por lo general no pueden hacer rollback de varios servicios como si fuera una transacción. Tenemos que compensar manualmente cualqueir side effect.
Ejemplo: una activity podria marcar como invalid un rejected claim summary, moverlo a un quarantine container, o esconderlo de downstream consumers.

La compensación debe ser idempotente.

schedule compensation when document processing exhausts its retries. La exception se vuelve a relanzar tras compensar para que el orchestrator mantenga un failed terminal status

# Code fragment - focus on compensation after a failed durable step
try:
    result = yield context.call_activity_with_retry(
        "process_document",
        retry_options,
        process_request,
    )
except Exception:
    yield context.call_activity(
        "compensate_document",
        {
            "operation_id": process_request["operation_id"],
            "reason": "ProcessingFailed",
        },
    )
    raise

Expose terminal status and diagnostics

Cada workflow branch deberia llegar a un status como Completed, Rejected, TimedOut, Compensated o Failed.

Incluir IDs para poder trackear requests.

No hacer logging de document contents, prompts, model credentials o tokens.

Read More

Create triggers and bindings (Azure Functions)

Los triggers y los bindings ofrecen una manera declarativa de conectar funciones a servicios externos.

  • Trigger determina como se invoca la función
  • Binding mueven data into - and out of - functions a través de configuración

Cada función tiene un único trigger que determina el tipo de event source que invoca la función. Ej: HTTP requests, queue messages, timer schedules, database change feeds. El trigger también sirve como input binding, proveyendo el event data a tu función.

Los bindings son opcionales. Una función puede tener 0 o múltiples bindings de cualquier tipo. El runtime se encarga de la auth y data serialization.

Create HTTP triggers (inference endpoint)

Soportan GET, POST y otros HTTP methods.

En Python v2 se definen HTTP triggers usando @app.route(). Especificas la ruta, HTTP method y Auth level. La función recibe un HttpRequest que contiene los headers, query params y body. La función devuelve HttpResponse con el resultado.

# Code fragment - focus on HTTP trigger for an inference endpoint
import azure.functions as func
import json

app = func.FunctionApp()

@app.route(route="classify", methods=["POST"], auth_level=func.AuthLevel.FUNCTION)
def classify_document(req: func.HttpRequest) -> func.HttpResponse:
    payload = req.get_json()
    document_text = payload.get("text")

    # Call inference logic or Azure AI service
    classification = perform_classification(document_text)

    return func.HttpResponse(
        json.dumps({"category": classification}),
        status_code=200,
        mimetype="application/json"
    )

HTTP-triggered functions tienen un timeout de 230 segundos impuesto por el Azure Load Balancer. Para tareas de inferencia que tarden más, devolver un 202 Accepted con un status endpoint URL y procesar el trabajo de manera asincrona usando un Service Bus trigger (async request-repply pattern)

Authorization levels

Los Auth levels controlan quien puede invocar la función

  • anonymous no key - para development e internal health check endpoints
  • function - requiere una key function-specific enviada en functions-keys header o code query param. recomendado para PROD
  • admin - requiere la master key. reservarla para administrative operations

El uso de auth keys es una base pero, no sustituye a Entra ID.

Create Service Bus Triggers (Batch Processing)

Hacer trigger de la function cuando llega un message a la Azure Service Bus queue. Este trigger es la base para async AI processing patterns donde el work item se envia a través de una interfaz y se procesa a un ritmo independiente determinado por los compute resources.

Service Bus triggers administran de manera automática la retry logic, dead-letter management y concurrency scaling.

Service Bus ofrece features complejas como:

  • message sessions
  • duplication detection
  • scheduled delivery

En Python v2 definimos Service Bus queue triggers usando @app.service_bus_queue_trigger(). Especifica queue name y connection setting que resuelve al Service Bus namespace conn string (o identity-based conn)

# Code fragment - focus on Service Bus queue trigger for processing work items
@app.service_bus_queue_trigger(arg_name="msg", queue_name="document-jobs", connection="ServiceBusConnection")
def process_document(msg: func.ServiceBusMessage) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))
    document_url = job["document_url"]
    job_id = job["job_id"]

    # Perform document processing and classification
    result = extract_and_classify(document_url)

    # Store result (using output binding or SDK client)
    save_result(job_id, result)
  • Podemos configurar el concurrency behavior para Service Bus triggers en host.json
  • maxConcurrentCalls controla cuantos mensajes puede procesar cada instancia de manera simultánea - un valor de 1 asegura que cada mensaje tiene full instance resources
  • maxAutoLockRenewalDuration controla cuanto tiempo el runtime renueva el message lock (esto es, el procesamiento continúa) - debería ponerse tan alto como para cubrir tu caso más largo para que el lock no expire mientras la AI service call is WIP
  • maxDeliveryCount (default: 10) Cuando un mensaje se pasa de este valor, el Service Bus broker automáticamente lo mueve a la dead-letter sub-queue. Esta cola es para mensajes que han fallado repetidamente el procesamiento y se puede monitorizar.
{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "maxConcurrentCalls": 1,
            "maxAutoLockRenewalDuration": "00:05:00"
        }
    }
}

HTTP Function + Service Bus Function (decoupling pattern)

Un common AI pattern empareja un HTTP endpoint con un Service Bus trigger.

La HTTP function acepta un batch request, valida el input, manda los mensajes individuales a la Service Bus queue y devuelve inmediatamente. Una Service Bus triggered-function procesa entonces cada item de manera independiente ejecutando inferencias, llamando Azure AI Services y escribiendo los resultados a un storage.

Esta separación separa la ingestión del procesamiento, permitiendo que cada servicio escale a su propio ritmo.

Use output bindings to store results

Los output bindings escriben data a external service ocupándose el runtime de manejar connection management, auth y serialization basandose en la binding config.

Para AI backends, los output bindings proveen de una manera concisa de persistir inference results, processed documents y derived data a storage services.

Common output binding targets son

  • Azure Blob Storage store processed documents y binary artifacts
  • Azure Cosmos DB writing structured inference results
  • Azure Service Bus send out work to downstream processors

Service bus-triggered function que usa Blob Storage output binding para guardar processed text

# Code fragment - focus on output binding for storing results
@app.service_bus_queue_trigger(arg_name="msg", queue_name="document-jobs", connection="ServiceBusConnection")
@app.blob_output(arg_name="output_blob", path="results/{rand-guid}.json", connection="AzureWebJobsStorage")
def process_and_store(msg: func.ServiceBusMessage, output_blob: func.Out[str]) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))

    result = extract_and_classify(job["document_url"])

    output_blob.set(json.dumps({
        "job_id": job["job_id"],
        "classification": result["category"],
        "confidence": result["score"]
    }))

Cuando una function necesita devolver una HTTP response y escribir a un output binding de manera simultanea, Python v2 soporta multiples outputs a través de un custom return type.
Defines la HTTP response y el output binding como properties separadas, por lo que la function puede responder al caller y persistir data en una unica invocacion

CosmosDB output bindings hacen write de JSON documents directamente a un contenedor. Especificas database name, container name, connection setting

# Code fragment - focus on Cosmos DB output binding
@app.service_bus_queue_trigger(arg_name="msg", queue_name="classification-results", connection="ServiceBusConnection")
@app.cosmos_db_output(
    arg_name="output_doc",
    database_name="ai-results",
    container_name="classifications",
    connection="CosmosDBConnection"
)
def store_classification(msg: func.ServiceBusMessage, output_doc: func.Out[func.Document]) -> None:
    result = json.loads(msg.get_body().decode("utf-8"))

    output_doc.set(func.Document.from_dict({
        "id": result["job_id"],
        "category": result["category"],
        "confidence": result["score"],
        "processed_at": datetime.utcnow().isoformat()
    }))

Connect to Azure AI services from a function

Los triggers y los binding models no cubren cada Azure service. Para servicios sin bindings dedicados puedes usar SDK clients directamente en código.

Este approach te da full access a la API del servicio y se beneficia del hosting y scaling de las Azure Functions.

Al crear SDK clients, inicializa el cliente fuera de la function handler para que persista la misma instancia entre invocaciones.

Usar DefaultAzureCredential para auth permite que el mismo código funcione localmente (usando developer credentials de Azure CLI o el IDE) y en PROD (usando la function managed identity)

# Code fragment - focus on SDK client initialization and reuse
from azure.identity import DefaultAzureCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient
import os

credential = DefaultAzureCredential()

doc_intelligence_client = DocumentIntelligenceClient(
    endpoint=os.environ["DOCUMENT_INTELLIGENCE_ENDPOINT"],
    credential=credential
)

@app.service_bus_queue_trigger(arg_name="msg", queue_name="document-jobs", connection="ServiceBusConnection")
def analyze_document(msg: func.ServiceBusMessage) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))

    poller = doc_intelligence_client.begin_analyze_document(
        "prebuilt-layout",
        analyze_request={"url_source": job["document_url"]},
        content_type="application/json"
    )
    result = poller.result()
    # Process extraction results...

Read More

Manage secrets and configurations (Azure Functions)

Use application settings for configuration

Los application settings son pares clave-valor que se configuran a través de:

  • Azure portal
  • Azure CLI
  • infrastructure-as-code

El runtime de las Azure Functions exponen estas settings a tu funcion como environment variables.

Azure encripta application settings at rest y lo desencripta solo cuando se inyecta en la app’s process memory, para que no se guarden en plaintext en el disco.

En python se accede a las app settings usando

  • os.environ para required settings
  • os.getenv para settings con fallback defaults

Este patron ayuda a mantener las functions environment-agnostic, ya que el mismo codigo lee config de local.settings.json en development y de las app settings en PROD.

# Code fragment - focus on reading application settings
import os

ai_endpoint = os.environ["AI_SERVICE_ENDPOINT"]
model_id = os.environ["MODEL_ID"]
confidence_threshold = float(os.getenv("CONFIDENCE_THRESHOLD", "0.85"))
max_batch_size = int(os.getenv("MAX_BATCH_SIZE", "10"))

Ignorar siempre local.settings.json del .gitignore

Reference secrets de Azure Key Vault

Las referencias a Key Vault permiten guardar valores sensibles directamente en Azure Key Vault y referenciarlos desde las app settings.

El runtime resuelve la referencia en app startup time, obtiene el secreto de la key vault y lo inyecta como environment variable, por lo que es transparente para la app.

Reference syntaxes

URI syntax - points to specific secret version (or latest)

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/AiServiceKey/)

Named syntax - uses vault name and secret name

@Microsoft.KeyVault(VaultName=myvault;SecretName=AiServiceKey)

Ambos tipos requieren que la Function App tenga una managed identity (system-assigned o user-assigned) con el rol Key Vault Secrets User en el target vault. Sin este rol, el runtime no puede obtener el secreto para la app.

Las Key Vault references se resuelven en app startup time. Al cambiar un secreto la nueva versión se usa dentro de las primeras 24 horas. Cualqueir cambio a la configuración de la app causa inmediatamente un refetch de los secretos.

Para AI backends que usen rotacion la recomendacion es usar versionless URIs para que el runtime pille la rotación automáticamente.

Los beneficioes de usar Key Vault son seguridad, centralizacion de secret management a través de multiple Function Apps y services, audir logging, separate secret ownership from app deployment. Un equipo de seguridad puede hacer management y rotar secretos sin tener que acceder a la config de la aplicacion.

Integrate with Azure App Configuration

IMPORTANTE

Azure App Configuration provee un store centralizado para non-secret configuration values y feature flags.

  • Application settings funciona bien para individual function apps.
  • App Configuration es util cuando multiples function apps o micros comparten valores comunes de config, como model endpoint URLs o feature toggles. Cambiar un setting una unica vez en App Configuration propaga este cambio a todas las apps conectadas.

/IMPORTANTE

En python se conecta a App Configuration usando una libreria a través de azure-appconfiguration-provider. Esto carga los config values en memoria y los pone disponibles para que la app los lea.

Soporta label-based filtering. Te permite cargar diferentes sets de valores para diferentes entornos.

# Code fragment - focus on loading configuration from App Configuration
from azure.appconfiguration.provider import load
from azure.identity import DefaultAzureCredential
import os

config = load(
    endpoint=os.environ["APP_CONFIG_ENDPOINT"],
    credential=DefaultAzureCredential(),
    selects=[{"key_filter": "AIBackend/*"}]
)

model_endpoint = config["AIBackend/ModelEndpoint"]
inference_timeout = int(config["AIBackend/InferenceTimeout"])

Una arquitectura comun es combinar App Configuration para nonsecret-values y Key Vault para secretos.

App Configuration soporta Key Vault references. Esto crea una configuration surface unificada para poder obtener todos los valores a través del mismo proveedor

Handle configuration in the local development workflow

Para desarrollo local necesitamos reproducir la misma config structure que corre en Azure, pero apuntando a local services y emuladores en vez de cloud resources.

El local.settings.json file hace mirror de las settings que ofrece el Azure portal.

Puedes hacer pull de current app settings de una deployed function app, a tu config local, usando Azure Functions Core Tools command. Este comando descarga todos los settings y los escribe a local.settings.json, lo cual es util para replicar PROD de manera rapida.

func azure functionapp fetch-app-settings <function-app-name>

Ya que este local.settings.json puede contener conn strings sensibles, podemos encriptar el fichero con Core Tools para proteger los secretos at rest en tu maquina. El local Functions runtime puede leer los valores, pero estos no son visibles si abres el fichero.

func settings encrypt

Para el dia a dia apuntar AzureWebJobsStorage a UseDevelopmentStorage=true para usar Azurite.

Read More

Configurar identity y access (Azure Functions)

Replace connection strings with identity-based connections

Azure Functions binding extensions soportan identity-based connections, las cuales usan la function app’s manage identity para autenticar, en vez de requerir una connection string guardada en application settings.

Este approach elimina secretos del trigger y binding configuration. En vez de guardar una full connection string que contiene account keys o shared access signatures, configuras el binding con una named connection, que incluye solo el service endpoint o account name.
El runtime se encarga de la auth de manera transparente usando la assigned managed identity.

Para preparar una identity-based connection, activa un system-assigned managed identity para la function app, entonces asignar los Azure rules necesarios para el target resource.
La function app autentica usando la identidad y no tenemos secret values que aparezcan en el app settings.
Esto es particularmente util para AI backends que conectan a multiples Azure services, ya que cada conexion adicional en la config expande el surface area para ataques.

El identity-based connection mas comun es el runtime own storage dependency. Podemos reemplazar el AzureWebJobsStorage tradicional connection string con identity-based settings, configurando el storage account name y asignando roles

AzureWebJobsStorage__accountName = mystorageaccount

El runtime autentica con la function app’s managed identity. El rol minimo requerido es Storage Blob Data Owner. Si tu app usa blob triggers, tambien necesitas Storage Queue Data Contributor y Storage Account Contributor ya que blob triggers internamente usan storage queues para blob receipts. Para Service Bus y CosmosDB, usar solo Storage Blob Data Owner es suficiente.

Usar identity-based connections for trigger y output bindings

Identity-based connection config difiere de connection string configs en la manera de hacer setup del named connection prefix. Cada binding’s connection property en function_app.py referencia un named prefix (ejemplo connection="ServiceBusConnection"). Con connection strings, creas una single app setting con el prefix name, que contiene el full connection string. Con identity-based connections, creas settings usando el prefijo con property suffixes que especifican el service endpoint.

Ejemplos:

Service Bus trigger with identity-based connection

Remplaza la Service Bus connection string, con el fully qualified namespace.
Asigna Azure Service Bus Data Receiver role a la function app’s managed identity en el Service Bus namespace. Para output bindings, asigna Azure Service Bus Data Sender role instead.

ServiceBusConnection__fullyQualifiedNamespace = mynamespace.servicebus.windows.net 
# Code fragment - focus on Service Bus trigger with identity-based connection
@app.service_bus_queue_trigger(
    arg_name="msg",
    queue_name="document-jobs",
    connection="ServiceBusConnection"
)
def process_document(msg: func.ServiceBusMessage) -> None:
    job = json.loads(msg.get_body().decode("utf-8"))
    # Process the document...

CosmosDB output binding with identity-based connection

Reemplaza la CosmosDB connection string, con el account endpoints.

Asigna el rol Csomos DB Built-in Data Contributor a la function app’s managed identity.

CosmosDBConnection__accountEndpoint = https://mycosmosaccount.documents.azure.com:443/

Cada binding extension documenta su supported identity properties y required roles. El suffix pattern difiere por servicio

  • storage bindings usan __acountName o service-specific URIs
  • CosmosDB usa __accountEndpoint
  • Messaging services usan __fullyQualifiedNamespace

Autenticar SDK clients con managed identity

Para Azure services sin dedicated binding support, creamos SDK clients directamente en function code. Estos clients se autenticar usando la misma managed identity que sirve el trigger y las binding connections.

DefaultAzureCredential provee de credential chain para entornos locales y cloud.

Inicializamos ambos el credential objhect y el service client fuera del function handler, al nivel del modulo. Esto asegura que el objeto persista entre invocaciones en la misma instancia, evitando tener que crearlo cada vez.

# Code fragment - focus on module-level client initialization
import os
from azure.identity import DefaultAzureCredential
from azure.ai.documentintelligence import DocumentIntelligenceClient
from azure.search.documents import SearchClient

credential = DefaultAzureCredential()

doc_client = DocumentIntelligenceClient(
    endpoint=os.environ["DOCUMENT_INTELLIGENCE_ENDPOINT"],
    credential=credential
)

search_client = SearchClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    index_name=os.environ["SEARCH_INDEX"],
    credential=credential
)

Secure HTTP endpoints con authorization keys

Las Azure Functions usan access keys para restringir acceso a HTTP-triggered function endpoints. Esto es especifico para Azure Functions y opera independiente de Entra ID para auth.

IMPORTANTE

Access keys son una barrera basica para evitar invokers no autorizados, pero no comprueban la caller identity ni ofrecen fine-grained acess control.

Tipos de keys

  • Function keys Scoped a una single function. Cada function puede tener multiples named keys. Se incluyen en el header x-functions-key o el query param code, al llamar a la funcion
  • Host keys Scoped a todas las funciones en la function app. Una single host key da acceso a todas las HTTP-triggered functions. Usarlas para administrative tools o monitorizacion
  • System keys Usadas por extensiones especificas o para auth de ops internas. La MCP extension usa mcp_extension system key para autenticar MCP client connections a la function app. Son managed por el runtime y no se deben compartir
  • Master key Acceso administrativo y hace override de todas las otras keys. Nunca jamas compartirla en apps

Se establece el auth level por HTTP trigger usando auth_level en @app.route()

Recordamos:

  • anonymous no requiere key (health check endpoints o funciones que manejan la auth de manera separada)
  • function erquiere function-specific key o host key (baseline for PROD)
  • admin requiere master key (administrative ops)
# Code fragment - focus on authorization levels
@app.route(route="classify", methods=["POST"], auth_level=func.AuthLevel.FUNCTION)
def classify_document(req: func.HttpRequest) -> func.HttpResponse:
    # This function requires a function key or host key to invoke
    pass

@app.route(route="health", methods=["GET"], auth_level=func.AuthLevel.ANONYMOUS)
def health_check(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("OK", status_code=200)

Las access keys son una barrea basica pero no reemplazan la auth para PROD AI endpoints. Para paps que requieran verificar al caller, juntarlo con Azure API Management o App Service Authentication (Easy Auth) on top of access keys.

  • API Management añade rate limiting, request validation y OAuth 2.0 token verification
  • Easy Auth integra Entra ID directamente en la function app

/IMPORTANTE

Read More

Azure Durable Functions

Las Azure Durable Functions permiten que un AI workflow sobreviva a reinicios del host y a long delays. Graban cada operación y permiten hacer un replay para reconstruir el estado local que teníamos antes del reinicio.

Durable workflows

Un durable workflow combina una client function, una orchestrator function y una o más activity functions.

Cuando un cliente comienza una orchestration, el Durable Task runtime graba el input y cada durable action en la orchestration history. El runtime chequea el progreso cuando el orchestrator asigna trabajo o recibe un resultado. Si el host se restartea, el runtime hace replay del history a través del orchestrator hasta que llega a la ultima accion no terminada.

Este modelo hace restore de local variables y workflow position sin que tengas que escribir ningún checkpoint.

Client Function

Una Client function comienza la orquestación, hace query del status, lo temrmina, o envía un evento externo.

Un cliente triggeado por HTTP, normalmente, devuelve una status URL que el caller usa para hacer track de long-running workflows

Orchestrator Function

Una Orchestrator function define la workflow sequence, branching rules, parallel tasks, durable waits y result aggregation.

El orchestrator pone en cola el durable work, en vez de hacer ese trabajo por si mismo

Activity Function

Una Activity function hace una unidad de trabajo no determinista como leer un blob, llamar un model endpoint, enviar una notificacion o hacer update de una BBDD

Son las que pueden ejecutar trabajo no-determinista como language libraries o Azure SDK Clients

Entity Function

Una Entity function administra una pieza de durable state state a través de operaciones explicitas.

Las Entities pueden ayudar a coordinar ese shared state. No son obligatorias. con un orchestrator y activity functions puede ser suficiente.

Keep orchestrator logic deterministic

Un orchestrator puede hacer replay muchas veces durante una workflow instance. Un codigo determinista produce la misma secuencia de durable actions con el mismo orchestration history, para que el runtime pueda hacer match de las acciones que se ha hecho replay para completar el trabajo.

Si hay trabajo no determinista puede causar que el workflow falle o se comporte de manera no predecible.

Puedes usar de manera segura calculos locales, loops sobre stable inputs y resultados devueltos por durable tasks. Usa orchestration context APIs cuando una decision requiere del current time o un identificador unico.

Ejemplos

  • context.current_utc_datetime devuelve un replay-safe time.
  • context.new_uuid() crea un ID determinista para el orchestration history

Evita las siguientes operaciones en orchestrator functions:

  • Direct HTTP, DDBB, file system o Azure SDK calls
  • Model inference o embedding requests
  • Random-number generators y nondeterministic UUID APIs
  • Language-native current time como datetime.now()
  • Block waits como time.sleep()
  • Threads, multiprocessing y async ops que el Durable Task runtime no schedulea
  • Environment-dependent decisions que pueden cambiar entre replays

ejemplo que usa orchestration-safe time para calcular una review deadline. En el replay context.current_utc_datetime devuelve el mismo valor

# Code fragment - focus on deterministic orchestration time
from datetime import timedelta
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    review_deadline = context.current_utc_datetime + timedelta(hours=24)
    review_timer = context.create_timer(review_deadline)

    yield review_timer
    return {"status": "ReviewTimedOut"}

Move model calls e input/output a activities

Activity functions no hacen replay bajo el orchestrator deterministic execution rules. Pueden llamar Azure Services, usar SDK clients, generar random values y ejecutar otras operaciones externas.

Las activities son la unidad que las Durable Functions distribuyen across workers disponibles y se reintentan segun la orchestration policy.

La separación importa para AI workloads ya que las respuestas de los modelos son no deterministas y las llamadas a servicios pueden ser lentas o tener fallos transientes. El orchestrator pasa una request estable a una activity y hace record solo del activity result.

el orchestrator hace schedule de una actividad con una compact blob reference. La activity entonces lee el documento y llama al model client configurado

# Code fragment - focus on orchestration and activity boundaries
import azure.durable_functions as df

app = df.DFApp()


@app.orchestration_trigger(context_name="context")
def document_orchestrator(
    context: df.DurableOrchestrationContext,
):
    document = context.get_input()
    result = yield context.call_activity("analyze_document", document)
    return result


@app.activity_trigger(input_name="document")
def analyze_document(document: dict) -> dict:
    document_text = read_blob_text(document["blob_url"])
    model_result = call_classification_model(document_text)
    return {
        "document_id": document["document_id"],
        "category": model_result["category"],
        "confidence": model_result["confidence"],
    }

Llamar read_blob_text() o call_classification_model() desde el orchestrator violawria la regla de ejecucion determinista. Mantener esas operaciones en analyze_document mantiene efectos externos fuera del replaying orchestrator code y permite aplicar una retry policy especifica al external work.
Activity functions tienen at-least-once execution semantics, por lo que sus efectos deben ser idempotentes.

Control data in orchestration history

Durable Functions serializan orchestration inputs, activity inputs / outputs y otros workflow state en el durable store configurado. Payloads grandes incrementar el coste de las operaciones, replay time, memory use. Evitar pasar documentos completos, imagenes, prompts, embeddings, etc, a través de una orchestration.

Para nuevas Durtable Function Apps, se recomienda Durable Task Scheduler como el managed storage provider.

Guarda datos grandes en un servicio apropiado como Durable Task Scheduler o Azure Blob Storage. Pasa una referencia y los metadatos minimos necesarios para workflow decisiones como document ID, blob URL, content type, confidence score, etc. Una activity puede leer el source content y escribir un resultado detallado, mientras que el orchestrator recibe solo el status y los campos requeridos para su next branch.

Considerar el impacto de seguridad de la durable data. No poner secretos en orchestration inputs u outputs. Usa managed identities para credenciales.

Account for replay in telemetry

El replay puede ejecutar un orchestrator’s logging más de una vez. Los mensajes duplicados pueden llevar a confusión. Usar replay-safe logging support.

# Code fragment - focus on replay-aware orchestrator logging
import logging

if not context.is_replaying:
    logging.info(
        "Scheduling document analysis for orchestration %s",
        context.instance_id,
    )

Read More

Process independent work with fan-out/fan-in (Durable Functions)

El Durable Functions fan-out/fan-in pattern se usa para operaciones independientes que no tienen por que ejecutarse secuencialmente.

Fan-out/fan-in permite hacer schedule de esas operaciones de manera simultánea, esperar a que el grupo acabe y combinar los resultados.

Este patrón puede reducir batch latency mientras que mantiene la coordinacion y los checkpoints en el durable runtime.

Identify independent work

Fan-out/fan-in funciona mejor cuando cada work item se puede completar sin cambiar los inputs ed otro item (es completamente independiente).

Algunos ejemplos son extraer texto de varios documentos, clasificar imágenes, generar embeddings para chunks separados.

La fase fan-out distribuye estas tasks a lo largo de activity executions, mientras que la fase fan-in le da al orchestrator un result set completo para la siguiente decisión.

Schedule tasks before awaiting results

El python durable functions SDK representa activity calls como durable tasks. Para fan-out, el orchestrator crea una task para cada referencia work-item y guarda las tasks en una lista. Entonces entrega context.task_all(tasks para hacer wait de cada scheduled activity y recibir los resultados.

schedule una activity por document reference. Cada activity puede leer su source blob, llamar al AI model requerido y escribir un output detallado al storage. El orchestrator recibe compact fields que puede agregar sin poner large model responses en orchestration history

# Code fragment - focus on fan-out/fan-in coordination
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    batch = context.get_input()
    tasks = []

    for document in batch["documents"]:
        tasks.append(
            context.call_activity(
                "process_document",
                {
                    "batch_id": batch["batch_id"],
                    "document_id": document["document_id"],
                    "blob_url": document["blob_url"],
                },
            )
        )

    results = yield context.task_all(tasks)

    return {
        "batch_id": batch["batch_id"],
        "processed": len(results),
        "requires_review": [
            item["document_id"]
            for item in results
            if item["confidence"] < 0.80
        ],
    }

El orden de las listas devueltas hace match con la task list, aun cuando las activities acaban en un orden distinto.
Una activity fallida causa que la task_all operation haga raise de un task failure al orchestrator. El orchestrator puede hace catch de ese error y puede elegir si falla el batch entero, compensa el trabajo completado o lo marca para investigación

Design compact fan-in results

fan-in se ejecuta dentro de una orchestrator instance, por lo que la agregación se debe mantener determinista y lightweight. Puedes contar status, seleccionar documentos por debajo de un confidence threshold o construir un summary compacto para activity outputs.

Las expensive transformations y external writes pertenecen a otra acticity

Una document-processing activity podria devolver los siguientes campos:

  • Document ID: correlacionar resultado con original work item
  • Status: success/validation failure
  • Confidence: soporta deterministic routing a un approval step
  • Result URL: apunta al full output almacenado en Blob Storage o BBDD
  • Operation ID: para idempotent updates y trazas

No devuelvas extracted text, full model prompts, large arrays of embeddings. Estos valores expanden la orchestration history y las Durable Functions los tienen que cargar durante el replay. Escribe estos resultados desde la activity a un external store y devuelve una referencia.

Si la agregacion en si misma requiere mucha CPU, memoria, IO ops - haz schedule de una AggregateResults activity tras task_all. El orchestrator puede pasar compact result references a esa activity y esperar un final summary. Este diseño preserva un small orchestration history mientras permite la agregacion del trabajo par usar normal function execution.

Bound parallel work

Un batch con miles de documentos puede hacer schedule de un gran numero de activities de a una. El durable runtime puede grabar esas tasks, pero el historial resultado y fan-in work puede volverse muy caro.
Asi mismo, un burst de trabajo puede exceder los rate limits de los modelos.

Puedes dividir inputs grandes en bounded batches y procesar los batches de uno en uno. Cada batch ejecuta sus items en paralelo, pero el workflow espera antes de asignar el siguiente grupo.

# Code fragment - focus on bounded fan-out
batch_size = 20
all_results = []

for start in range(0, len(documents), batch_size):
    current_batch = documents[start : start + batch_size]
    tasks = [
        context.call_activity("process_document", document)
        for document in current_batch
    ]
    batch_results = yield context.task_all(tasks)
    all_results.extend(batch_results)

Los Bounded Batches limitan el trabajo asignado pero no ofrecen un limite preciso de requests-por-segundo.

Scale aggregation with sub-orchestration

Un orchestrator ejecuta el fan-in step en un worker a la vez. Un solo flat fan-in puede convertirse en un cuello de botella cuando tiene que cargar y agregar muchos resultados. Sub-orchestrations te permiten crear una jerarquia en la cual child orchestration procesan particiones separadas y un padre combina sus summaries.

Por ejemplo un parent orchestration divide un claim archive grande por policy o mes.
Cada child orchestration hace fan out de su propio document activities y devuelve counts + result locations.
El parent entonces agregar esos summaries en vez de cada document result individual.

Este approach reduce la cantidad de estado manejada por una orquestacion y da a cada particion su estado independiente.

La sub-orquestacion junta coordinacion y history records, por lo que no son necesarios para small batches. Comienza con un fan-out/fan-in pattern, mide la ejecucion y el replay behavior, e introduce partitioning cuando el batch size o el coste de agregacion justifique la estructura añadida.

Read More

Coordinate human approval with external events (Durable Functions)

Algunos workflwos requieren de input por parte de una persona u otro sistema cuando el proceso automatizado termina. Las Durable Functions pueden suspender una orchestration mientras espera por un external event, y entonces recomenzar desde su durable state cuando ese event llega.

La orchestration suspendida no mantiene un worker ni una invocacion de funcion activa. Esto se recomienda para approval windows de horas a dias.

Model an approval as an external event

Un external event es un one-way message, con nombre, enviado a una instancia especifica de orquestacion. El orchestrator crea una durable task con wait_for_external_event() y cede esa task cuando necesita del event data.

Las Durable Functions extensions persisten un evento que llega al orchestrator antes de que este comience la espera, para que el workflow pueda consumir ese buffered event más tarde.

Para un document-processing workflow, una activity primero crea un approval record y notifica al adjuster asignado. El orchestrator entonces espera a un evento ApprovalResponse que contiene la decision y la identidad del reviewer.

Diseña el event contract alrededor de workflow decisions, en vez de una user-interface action. Un approval payload compacto puede contener:

  • Decision Un valor fijo como Approved o Rejected
  • Reviewer ID para auditar y correlacionar
  • Document ID el work item que el reviewer ha evaluado
  • Approval version Un valor que ayuda al workflow a rechazar una respuesta para una review request viaje
  • Comment reference URL para cargar detalles, almacenado fuera del flujo

Combina un external event con un durable timer

Un approval process necesita una deadline para que un workflow no espere de manera infinita.
Usa context.create_timer() con context.current_utc_datetime. NO USAR time.sleep() u otras APIs bloqueantes. Un durable timer graba el deadline en la orchestration history y no requiere que el worker se mantenga activo mientras no hay trabajo.

Patrón human interaction - es una carrera entre el event task contra el timer task con context.task_any(). Si el evento gana, el orchestrator lee el event result y cancela el timer. Si el timer gana, el orchestrator sigue el timeout path.

ejemplo que implementa approval, rejection y timeout outcomes. Usa un input estable y orchestration-safe time para el replay

# Code fragment - focus on the event-and-timer race
from datetime import timedelta
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    review_request = context.get_input()

    yield context.call_activity("notify_approver", review_request)

    approval_task = context.wait_for_external_event("ApprovalResponse")
    deadline = context.current_utc_datetime + timedelta(hours=24)
    timeout_task = context.create_timer(deadline)

    winner = yield context.task_any([approval_task, timeout_task])

    if winner == approval_task:
        if not timeout_task.is_completed:
            timeout_task.cancel()

        response = approval_task.result
        if response["decision"] == "Approved":
            return {"status": "Approved"}

        return {"status": "Rejected"}

    return {"status": "TimedOut"}

Una external event task no requiere cancelación después de que el timer gane. Si el workflow puede recibir otro evento con el mismo nombre despues, definimos si la app ignora ese evento tardia, lo graba para auditarlo, o lo enruta hacia orta orchestration instance nueva.

Send an event to the correct instance

Una client function usa las Durable Functions orchestration client binding para enviar un evento. El cliente debe conocer el orchestration instance ID o usar el mismo event name que el orchestrator espera. Los event names deberian ser estables.

fragmento que muestra Durable Function call tras un OK de app-specific auth y validacion. El endpoint devuelve 202 ya que el event delivery retoma la orchestration de manera asincrona

# Code fragment - focus on raising an external event
import json
import azure.functions as func
import azure.durable_functions as df

app = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)


@app.route(route="approvals/{instance_id}", methods=["POST"])
@app.durable_client_input(client_name="client")
async def submit_approval(
    req: func.HttpRequest,
    client: df.DurableOrchestrationClient,
) -> func.HttpResponse:
    instance_id = req.route_params["instance_id"]
    response = req.get_json()

    reviewer = authorize_reviewer(req)
    validated_event = validate_approval_response(response, reviewer)

    await client.raise_event(
        instance_id,
        "ApprovalResponse",
        validated_event,
    )

    return func.HttpResponse(
        json.dumps({"status": "Accepted"}),
        status_code=202,
        mimetype="application/json",
    )

Handle duplicate and out-of-order responses

Diferentes servicios pueden mandar la misma decision mas de una vez. External events tienen at-least-once delivery guarantee, por lo que restarts, escalado o fallos pueden producir deliveries duplicadas. Sigue siendo nuestra responsabilidad garantizar idempotencia ya que un evento duplicado no debería crear un segundo approval record o repetir una operación downstream.

Podemos incluir un ID estable para approvals y que una actividad de manera atómica compruebe este ID para reportar si la operación ya existe.

Respuestas out-of-order requieren de una policy explicita. Evitar usar solo el orden de llegada cuando hay múltiples sistemas que pueden mandar eventos.

Choose a timeout outcome

Un timeout es un outcome pero no necesariamente un fallo técnico. El orchestrator debe elegir un terminal path y hacer schedule de cualquier update requerida, a través de activities.

Read More

Set up local dev environment (Azure Functions)

Install Azure Functions Core Tool

Para Visual Studio Code instalar la Azure Functions extension. Esta depende de Azure Functions Core Tools, la cual permite ejecutar una versión local del runtime de las Azure Functions. Tiene el mismo trigger y binding logic que corre en Azure, por lo que funciona de manera consistente entre local y cloud envs.

Gracias a ellas también puedes crear nuevas Functions desde tu local. Esto crea la function y te permite ejecutarla con func start y expone http://localhost:7071 por defecto.

Understand local project structure

El programming model Python v2 usa un single entry point file function_app.py, donde defines tus functions y sus triggers usando decorators. Este approach consolida las function definitions en un solo lugar.

Un único function_app.py funciona bien para projectos con una miriada de funciones como HTTP trigger para inferencias y queue trigger para batch processing.

A medida que el número de functions crece, se puede partir sus definiciones en files separados usando blueprints. Los blueprints permiten definir funciones en modules individuales y registrarlos en el main entry point function_app.py.

El fichero host.json contiene global runtime configs que aplican a todas las funciones de la app. Esto incluye settings como timeout durations, log levels o concurrency limits.

El fichero local.settings.json contiene app settings y conn strings para desarrollo local. El runtime lee valores del Values object en este fichero y los expone como environment vars en código.
Este fichero se excluye de git por defecto. NUNCA. COMMITEES. `local.settings.json`. N.U.N.C.A

El folder .vscode contiene config files generadas por la Azure Functions extension. El launch.json file configura el debugger, tasks.json define el build y host start.

El fichero requirements.txt (python) o package.json (Node.js) contienen las dependencias del proyecto para funcionar. El runtime instala estas dependencias durante deployment.

El fichero .funcignore especifica files y folders a exlcuir de los deployment packages, manteniendo tus artefactos con poco tamaño, omitiendo ficheros de testing, documentación, etc.

Use Azurite for Functions runtime storage dependency

Azurite provee de implementaciones locales de Azure Blob Storage, Queue Storage y Table Storage, que se comportan como si fuera un cloud service. Así, Azurite elimina la necesidad de crear un Storage account para desarrollo local

El runtime de las Azure Functions requiere una connection a un storage account (configurado a través de AzureWebJobsStorage) para coordinaciones internas. Esta dependencia existe aunque tu app use Azure Storage directamente.

Para desarrollo local puedes enrutas esta dependencia al Azurite emulator poniendo AzureWebJobsStorage como UseDevelopmentStorage=true en local.settings.json.

La manera más simple de usar Azurite es instalar su extension, la cual enciende el emulador cuando haces start del programa local.

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "python"
    }
}

El valor UseDevelopmentStorage=true solo tiene efecto en local. Al lanzar la Function, Azure crea o requiere de un storage account automáticamente

Use emulators and local services for connected resources

Para servicios como BBDD, caches y otros data-level ops podemos usar emuladores y alternativas locales para poder testear y mantener los costes bajos.

Azure Cosmos DB emulator se ejecuta en local en Windows, Linux y macOS (a través de Docker). Soporta la NoSQL API y provee de un local endpoint que se comporta como el cloud service.

Azure Database for PostgreSQL no tiene un emulador, pero PostgreSQL es open source por lo que puedes instalar una instancia local.

Azure Managed Redis tampoco tiene emulador, pero Redis es open source.

Simplemente cambiamos los valores con local.settings.json.

Synchronize settings between local and Azure

La Azure Functions extension y Core Tools ofrecen maneras de sincronizar settings entre local y Azure.

En Visual Studio Code puedes hacer click derecho en la function app y seleccionar Download Remote Settings para bajarte los settings a tu local.settings.json.
También puedes Upload Local Settings para hacer push de local values a Azure.

Puedes encriptar tus local settings file con func settings encrypt para proteger secretos en tu maquina de desarrollo.

Read More

Azure Functions

El hosting plan que se elige para la Function App determina como inician las instancian, como escala la app bajo carga y cuanta memoria hay disponible.

Los dos planes enfocados a serverless AI workloads son: El Flex Consumption y el Premium plan

Cold start and why it matters for AI

Cold start es el delay que ocurre cuando la Azure Functions platform:

  • aloca una nueva instancia
  • carga el runtime
  • inicializa las dependencias de la app

Todo esto antes de que la instancia esté lista para manejar su primera request.

Cada serverless hosting plan que escala a zero sufre este cold start ya que no hay preallocated compute cuando llega la invocación inicial.

Las AI apps suelen amplificar el cold start por las grandes dependencias de grados y librerias de ML que tienen, además de los SDKs y entornos de ejecución de código.

El cold start es por instancia. Solo afecta a la primera request que se enrute a una nueva instancia.

Flex Consumption vs Premium

Son los dos planes enfocados a AI backends.

Flex Consumption

Flex consumption es el recomendado by default.

Características

  • Plan linux-only
  • scaling per-function
  • virtual network connectivity
  • memoria configurable por instancia (512 MB,2048 MB,4096 MB)
  • always-ready instances

Escala hasta 1000 instancias y cobra basado en active execution time + always-ready baseline.

El always-ready permite mantener un número mínimo de instancias calientes para funciones que sean sensibles a la latencia, mientas que otras Functions en la misma Function App se mantienen fully serverless y escaladas a 0.

Premium

Elimina el cold start del todo y mantiene siempre al menos una instancia en caliente.

Características

  • ofrece siempre al menos una pre-warmed instance
  • custom Linux image support
  • virtual network connectivity

Elige Premium cuando:

  • tus funciones se ejecutan continuamente (o casi)
  • el coste de always-on esté justificado
  • tengas cargas de computación más grandes de las que ofrece el flex
  • necesites desplegar functions usando custom container images

Otros planes

  • Dedicated (App Service) plan: cuando tienes underutilized App Service capacity ya existente y quieres ejecutar tus functions en esas instancias sin coste adicional
  • Container Apps hosting: Cuando las functions necesitan GPU access para model inference, custom OS-level packages o ejecutarse al mismo nivel que microservicios contenerizados en el mismo env
  • Consumption plan (Linux): Legacy serverless plan. Los nuevos proyectos deben usar Flex Consumption

Configure scaling and concurrency

El plan Flex Consumption introduce per-function scaling. Cada tipo de trigger escala de manera independiente basándose en su propia demanda por tipo.

Todas las HTTP functions de una Function App escalan juntas como grupo. El resto de tipos como queue triggers, timer triggers o Service Bus triggers escalan de manera independiente. Esta separacion significa que un aumento de peticiones de las queue, no compite por recursos con un aumento de las peticiones HTTP.

Instance memory el default son 2048 MB. Se puede subir a 4096 MB cuando tengamos cargas más grandes o para subir CPU-cores (van proporcionales).

Long-running AI tasks

MUY IMPORTANTE

Las HTTP functions tienen un timeout de 230 segundos impuesto por el Azure Load Balancer que no se puede cambiar, independiente del functionTimeout setting in host.json.

Todas las requests que se pasen de este tiempo devuelven un error al caller, aunque la function se puede seguir ejecutando en el backend. Esto es especialmente peligroso para las AI apps.

La recomendación es usar async request-reply pattern: La HTTP function

  1. acepta la request
  2. valida el input
  3. escribe un mensaje a la Service Bus queue
  4. devuelve inmediatamente un 202 Accepted con una URL de status

Entonces una function separada con Service Bus trigger pilla ese mensaje y ejecuta la long-running task sin ningún tipo de constraint, ya que las service bus-trigger Functions poder ejecutarse de manera indefinida en los planes Flex y Premium.

De este modo, cada componente - HTTP endpoint y Service Bus trigger - escalan de manera independiente.

/MUY IMPORTANTE

Read More

Azure Functions - Fundamentals

Files that compose an Azure Function:

  • a Readme file
  • function.json -> this is an important file. it defines each Azure function in a function App. It specifies things like what event triggers this function, HTTP methods, auth, etc.
  • run.csx

How to create an Azure Function

Create a resource -> Compute -> Function App.

The function name has to be unique.
Create new resource group.
You can choose the OS.

Storage:
Create a new recommended storage.
It offers to create an application insight instance for us. This stores logs and diagnostic information. This is really recommended.

On Configuration > Application settings you can create sys envs which will appear in your code.

There’s a storage explorer where you may see the contents for your function in real time.

Understanding Triggers and Bindings

There’re a lot of trigger types

  • Timers, HTTP requests
  • Queue messages, blobs, Comsos DB

Input / Output Bindings

  • Connect to external resources
  • Reduce amount of code

To work with Azure Functions, you may work with Visual Studio. There’s an option to enable “Azure Development” with which you’ll be able to project and run your functions locally.

Read More

Azure Functions - Introduction

Azure Functions are based in serverless programming. They integrate easily with other Azure services. You provide Code to execute and an event that triggers it.
For example to run background tasks every hour.

They’re brilliant for:

  • experiments and rapid prototyping.
  • automating development processes.
  • decomposing or extending monolithic apps.
  • independent scaling.
  • adapters for integrating systems.

Recommended Read

Azure Functions vs other similar services

Azure Functions is built on top of the web jobs SDK and it’s hosted on the app service platform.

Virtual Machines (IaaS)

With VM you can install whatever you want: web servers, services etc. This is known as IaaS (infrastructure as a service). You can choose OS and have complete control of the server, but you’re responsible for it: Patching, maintaining, scaling, operational overhead.

Read More