¿Cómo utilizo el Provider Framework de AWS CDK para operaciones de recursos personalizados de larga duración?
Tengo un recurso personalizado que ejecuta una operación de AWS que ha superado el tiempo de espera de AWS Lambda. Quiero usar el Provider Framework de AWS Cloud Development Kit (AWS CDK) para administrar la operación de larga duración.
Descripción corta
Los proveedores de recursos personalizados de AWS CDK que se ejecutan en funciones de Lambda tienen un tiempo de espera máximo de 15 minutos. Para administrar operaciones que superen los 15 minutos, utiliza el soporte de operaciones asincrónicas integrado del Provider Framework AWS CDK. Por ejemplo, puedes usar Provider Framework para una ejecución de AWS Step Functions, una migración de bases de datos o un trabajo de entrenamiento en machine learning.
Para usar Provider Framework, debes crear dos funciones de Lambda. A continuación, configura las funciones con el componente Provider en tu pila de AWS CDK. El controlador onEvent inicia la operación y devuelve un valor PhysicalResourceId. El controlador isComplete sondea el estado de la operación hasta que finalice o se agote el tiempo de espera.
Resolución
Nota: Si se muestran errores al ejecutar comandos de la Interfaz de la línea de comandos de AWS (AWS CLI), consulta Solución de errores para la AWS CLI. Además, asegúrate de utilizar la versión más reciente de AWS CLI. La siguiente resolución usa Provider Framework para administrar la ejecución de Step Functions como una operación de larga duración.
Requisitos previos:
-
Configura las credenciales de AWS CLI para la cuenta de AWS y la región de AWS en las que deseas realizar el despliegue. El AWS CDK usa el perfil predeterminado de AWS CLI, a menos que especifiques uno diferente. Para usar un perfil o una región específicos, configura las variables de entorno AWS_PROFILE y AWS_REGION. Alternativamente, añade --profile profile-name a cada comando de AWS CDK. Para obtener más información, consulta Opciones de los archivos de configuración y credenciales en la AWS CLI.
-
Instala Node.js 22.x o una versión posterior. Para descargar la herramienta, consulta Download Node.js (Descarga de Node.js) en el sitio web de Node.js.
-
Instala la Interfaz de la línea de comandos (CLI) de AWS CDK.
-
Crea una aplicación de TypeScript CDK. Si no tienes una aplicación existente, ejecuta el siguiente comando para crear un directorio vacío, cambiar al directorio e inicializar un nuevo proyecto:
mkdir my-async-resource && cd my-async-resource && cdk init app --language typescript -
Ejecuta el siguiente comando desde la raíz de tu proyecto de AWS CDK para agregar el paquete @aws-sdk/client-sfn para la verificación de tipos de TypeScript durante el desarrollo:
npm install --save-dev @aws-sdk/client-sfn
Cómo crear el controlador onEvent
En el directorio de proyectos de AWS CDK, crea un archivo denominado handlers/on-event.ts con el siguiente código:
import { SFNClient, StartExecutionCommand } from '@aws-sdk/client-sfn'; const sfn = new SFNClient({}); export async function onEvent(event: any) { console.log('Event:', JSON.stringify(event, null, 2)); const stateMachineArn = process.env.STATE_MACHINE_ARN; if (!stateMachineArn) { throw new Error('STATE_MACHINE_ARN environment variable is not set.'); } if (event.RequestType === 'Create' || event.RequestType === 'Update') { const command = new StartExecutionCommand({ stateMachineArn: stateMachineArn, input: JSON.stringify({ requestId: event.RequestId, resourceProperties: event.ResourceProperties }) }); const response = await sfn.send(command); return { PhysicalResourceId: response.executionArn, Data: { ExecutionArn: response.executionArn } }; } if (event.RequestType === 'Delete') { return { PhysicalResourceId: event.PhysicalResourceId }; } throw new Error(`Unknown request type: ${event.RequestType}`); }
Nota: El código de controlador anterior inicia una ejecución de Step Functions.
Cómo crear el controlador isComplete
En el directorio de proyectos de AWS CDK, crea un archivo denominado handlers/is-complete.ts con el siguiente código:
import { SFNClient, DescribeExecutionCommand } from '@aws-sdk/client-sfn'; const sfn = new SFNClient({}); export async function isComplete(event: any) { console.log('IsComplete Event:', JSON.stringify(event, null, 2)); if (event.RequestType === 'Delete') { return { IsComplete: true }; } const executionArn = event.PhysicalResourceId; const command = new DescribeExecutionCommand({ executionArn: executionArn }); const response = await sfn.send(command); if (response.status === 'SUCCEEDED') { return { IsComplete: true, Data: { ExecutionArn: executionArn, Status: response.status, Output: response.output } }; } if (response.status === 'FAILED' || response.status === 'TIMED_OUT' || response.status === 'ABORTED') { throw new Error(`Execution failed with status: ${response.status}`); } return { IsComplete: false }; }
El código anterior utiliza AWS CloudFormation para comprobar el estado de la operación. Cuando la operación se realiza correctamente, el controlador isComplete devuelve el valor {IsComplete: true}. Si la operación sigue ejecutándose, el valor de isComplete es false. Si la operación falla, se mostrará un mensaje de error.
Configuración del componente Provider en una pila de AWS CDK
El componente Provider conecta los dos controladores.
Para configurar el componente Provider, añade el siguiente código a tu archivo de pila de AWS CDK, como lib/my-stack.ts:
import * as cdk from 'aws-cdk-lib'; import * as cr from 'aws-cdk-lib/custom-resources'; import * as nodejs from 'aws-cdk-lib/aws-lambda-nodejs'; import * as lambda from 'aws-cdk-lib/aws-lambda'; import * as sfn from 'aws-cdk-lib/aws-stepfunctions'; import * as path from 'path'; import { Construct } from 'constructs'; export class AsyncCustomResourceStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Step Functions state machine that represents the long-running operation. // Replace this example with your own state machine, or import an existing // one using sfn.StateMachine.fromStateMachineArn(). const stateMachine = new sfn.StateMachine(this, 'WorkflowStateMachine', { definitionBody: sfn.DefinitionBody.fromChainable( new sfn.Wait(this, 'WaitStep', { time: sfn.WaitTime.duration(cdk.Duration.minutes(5)) }) ), timeout: cdk.Duration.hours(1) }); const onEventHandler = new nodejs.NodejsFunction(this, 'OnEventHandler', { runtime: lambda.Runtime.NODEJS_22_X, handler: 'onEvent', entry: path.join(__dirname, 'handlers', 'on-event.ts'), environment: { STATE_MACHINE_ARN: stateMachine.stateMachineArn }, timeout: cdk.Duration.minutes(2), bundling: { externalModules: ['@aws-sdk/*'] } }); const isCompleteHandler = new nodejs.NodejsFunction(this, 'IsCompleteHandler', { runtime: lambda.Runtime.NODEJS_22_X, handler: 'isComplete', entry: path.join(__dirname, 'handlers', 'is-complete.ts'), timeout: cdk.Duration.minutes(2), bundling: { externalModules: ['@aws-sdk/*'] } }); // Grant permissions to the handlers. // grantStartExecution() grants states:StartExecution to the onEvent handler. stateMachine.grantStartExecution(onEventHandler); // grantRead() grants states:DescribeExecution (and related read actions) // to the isComplete handler so it can poll execution status. stateMachine.grantRead(isCompleteHandler); const provider = new cr.Provider(this, 'AsyncProvider', { onEventHandler: onEventHandler, isCompleteHandler: isCompleteHandler, queryInterval: cdk.Duration.seconds(30), totalTimeout: cdk.Duration.hours(2) }); new cdk.CustomResource(this, 'AsyncResource', { serviceToken: provider.serviceToken, properties: { Message: 'This triggers an async operation' } }); } }
Nota: Para cambiar la frecuencia con la que CloudFormation sondea el controlador isComplete, actualiza el valor de queryInterval. Para cambiar el tiempo máximo de espera, actualiza el valor de totalTimeout. Si tus controladores importan un cliente @aws-sdk/* que no está incluido en tu versión ejecutable, elimina '@aws-sdk/*' de externalModules para empaquetar tu cliente con tu código de función. El ejemplo anterior utiliza una máquina de estados de Step Functions. Sustituye la máquina de estados por tu flujo de trabajo de larga duración.
La configuración externalModules: ['@aws-sdk/*'] excluye el AWS SDK del paquete de despliegue porque el SDK ya está disponible en la versión ejecutable de Lambda de Node.js.
También puedes personalizar la agrupación con externalModules para agregar dependencias, minify para reducir el tamaño del paquete y sourceMap para activar los mapas de origen para la depuración. Para obtener más opciones de empaquetado, consulta interface BundlingOptions.
Despliegue y verificación del recurso personalizado
Desde la raíz de tu proyecto de AWS CDK, ejecuta los siguientes comandos para sintetizar la plantilla de CloudFormation y desplegar la pila:
cdk synth cdk deploy
Nota: Los comandos anteriores utilizan el perfil predeterminado de AWS CLI.
Para confirmar que el recurso personalizado se ha completado correctamente, realiza una o más de las siguientes acciones:
- En la consola de CloudFormation, verifica que el estado de la pila haya cambiado de CREATE_IN_PROGRESS a CREATE_COMPLETE.
Nota: La máquina de estados incluye un paso de espera de 5 minutos. El estado CREATE_IN_PROGRESS de CloudFormation dura aproximadamente el mismo tiempo. - Asegúrate de que la máquina de estados que inició el recurso del cliente se encuentre en el estado Succeeded en la sección Visualización de los detalles de ejecución en la consola de Step Functions.
- Consulta los registros de Amazon CloudWatch para ver las funciones de Lambda onEvent e isComplete. El registro onEvent muestra una única invocación en el despliegue de la pila. El registro isComplete muestra las invocaciones repetidas en función de tu queryInterval y termina con {"IsComplete": true}.
Limpieza de la configuración
Para evitar cargos futuros, elimina los recursos que creaste cuando ya no los necesites. Ejecuta el siguiente comando desde la raíz de tu proyecto de AWS CDK:
cdk destroy
Cuando AWS CDK elimina la pila de tu cuenta, elimina los siguientes recursos:
- La máquina de estado de Step Functions
- Las funciones del controlador de Lambda
- La máquina de estados interna de Provider Framework
- Roles asociados de AWS Identity and Access Management (IAM)
- La pila de CloudFormation
Nota: De forma predeterminada, AWS CDK conserva los grupos de registros para las funciones de Lambda. Para eliminar los grupos de registros, elimínalos manualmente. Alternativamente, configura tus componentes de NodejsFunction con un valor de logRetention que permita a AWS CDK administrar el ciclo de vida del grupo de registros.
Solución de problemas
El tiempo de espera de la operación se agota
Si se agota el tiempo de espera de la operación, aumenta el valor totalTimeout en el controlador isComplete.
Si el tiempo de espera de la operación sigue agotándose, consulta los registros de CloudWatch para ver el controlador isComplete para identificar si la operación está bloqueada. Si la operación subyacente se bloquea, cancélala manualmente. Por ejemplo, detén la ejecución de Step Functions. A continuación, aumenta el valor de totalTimeout.
La configuración no ha llamado al controlador isComplete
Consulta los registros de CloudWatch para comprobar que el controlador onEvent ha devuelto un PhysicalResourceId y no ha mostrado ningún error. Si hay errores, asegúrate de que el rol de ejecución de Lambda tenga los permisos necesarios para ejecutar las funciones.
La operación finaliza, pero CloudFormation muestra que está en curso
Confirma que el controlador isComplete devuelve { IsComplete: true } en el formato de respuesta correcto. Para obtener información sobre el formato de respuesta esperado, consulta Proveedores asincrónicos: isComplete.
Información relacionada
AWS CDK custom resources (Recursos personalizados de AWS CDK)
class Provider (construct) (Proveedor de clases [componente])
Crear una lógica de aprovisionamiento personalizada con recursos personalizados
AWS SDK for JavaScript (AWS SDK para JavaScript)
- Etiquetas
- AWS Cloud Development Kit (CDK)
- Idioma
- Español

Contenido relevante
preguntada hace un año
- Respuesta aceptada
preguntada hace 2 años
preguntada hace un año
preguntada hace 2 años
- Respuesta aceptada
preguntada hace 2 años
OFICIAL DE AWSActualizada hace 8 meses
OFICIAL DE AWSActualizada hace 8 meses