Referencia de solicitud y respuesta de recursos personalizados de CloudFormation
CloudFormation administra los recursos personalizados mediante un protocolo de solicitud-respuesta que se comunica con su proveedor de recursos personalizados. Cada solicitud incluye un tipo de solicitud (Create, Update o Delete) y sigue este flujo de trabajo de alto nivel:
-
Un desarrollador de plantillas define un recurso personalizado con un ServiceToken y ServiceTimeout en la plantilla e inicia una operación de pila.
-
CloudFormation envía una solicitud JSON al proveedor de recursos personalizados a través de SNS o Lambda.
-
El proveedor de recursos personalizados procesa la solicitud y devuelve una respuesta JSON a una URL de bucket de Amazon S3 prefirmada antes de que venza el tiempo de espera.
-
CloudFormation lee la respuesta y continúa con la operación de la pila. Si no se recibe respuesta alguna antes de que finalice el tiempo de espera, se considera que la solicitud no se ha realizado en la forma correcta y la operación de la pila fallará.
Para obtener más información, consulte Cómo funcionan los recursos personalizados.
En esta sección se describen la estructura, los parámetros y las respuestas esperadas para cada tipo de solicitud.
El tamaño total del cuerpo de la respuesta no puede superar los 4096 bytes.
Configuración de la plantilla
Al definir un recurso personalizado en una plantilla, el desarrollador de la plantilla utiliza AWS::CloudFormation::CustomResource con las siguientes propiedades:
ServiceToken-
Un ARN de tema de Amazon SNS o un ARN de función de Lambda de la misma región que la pila.
Obligatorio: sí
Tipo: cadena
ServiceTimeout-
El tiempo máximo, en segundos, antes de que una operación de recurso personalizado agote el tiempo de espera. Este valor debe estar entre 1 y 3600. Valor predeterminado: 3600 segundos (1 hora).
Obligatorio: no
Tipo: cadena
Se admiten las propiedades del recurso adicional. Las propiedades de los recursos se incluirán como ResourceProperties en la solicitud. El proveedor de recursos personalizados debe determinar qué propiedades son válidas y sus valores aceptables.
Objeto de solicitud
- Create
-
Cuando el desarrollador de la plantilla crea una pila que contiene un recurso personalizado, CloudFormation envía una solicitud con RequestType establecido en Create.
Cree solicitudes que contengan los siguientes campos:
RequestType-
Create.
Obligatorio: sí
Tipo: cadena
RequestId-
Un ID único para la solicitud.
La combinación de StackId con RequestId forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
Obligatorio: sí
Tipo: cadena
StackId-
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado.
La combinación de StackId con RequestId forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
Obligatorio: sí
Tipo: cadena
ResponseURL-
La URL de respuesta identifica un bucket de S3 prefirmado que recibe respuestas del proveedor de recursos personalizados para CloudFormation.
Obligatorio: sí
Tipo: cadena
ResourceType-
El tipo de recurso elegido por el desarrollador de plantillas del recurso personalizado en la plantilla de CloudFormation. Los nombres de tipos de recursos personalizados pueden tener una longitud máxima de 60 caracteres y pueden incluir caracteres alfanuméricos y los siguientes caracteres: _@-.
Obligatorio: sí
Tipo: cadena
LogicalResourceId-
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation.
Obligatorio: sí
Tipo: cadena
ResourceProperties-
Este campo contiene el contenido del objeto Properties enviado por el desarrollador de la plantilla. El proveedor de recursos personalizado define su contenido.
Obligatorio: no
Tipo: objeto JSON
Ejemplo
{
"RequestType" : "Create",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-create-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"ResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
- Update
-
Cuando el desarrollador de la plantilla realiza cambios en las propiedades de un recurso personalizado dentro de la plantilla y actualiza la pila, CloudFormation envía una solicitud al proveedor del recurso personalizado con RequestType establecido en Update. Esto significa que el código de su recurso personalizado no tiene que detectar cambios en los recursos, porque sabe que sus propiedades cambiaron cuando el tipo de solicitud es Update.
Actualice solicitudes que contengan los siguientes campos:
RequestType-
Update.
Obligatorio: sí
Tipo: cadena
RequestId-
Un ID único para la solicitud.
La combinación de StackId con RequestId forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
Obligatorio: sí
Tipo: cadena
StackId-
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado.
La combinación de StackId con RequestId forma un valor que puede usar para identificar de forma única una solicitud en un recurso personalizado en particular.
Obligatorio: sí
Tipo: cadena
ResponseURL-
La URL de respuesta identifica un bucket de S3 prefirmado que recibe respuestas del proveedor de recursos personalizados para CloudFormation.
Obligatorio: sí
Tipo: cadena
ResourceType-
El tipo de recurso elegido por el desarrollador de plantillas del recurso personalizado en la plantilla de CloudFormation. Los nombres de tipos de recursos personalizados pueden tener una longitud máxima de 60 caracteres y pueden incluir caracteres alfanuméricos y los siguientes caracteres: _@-. No puede cambiar el tipo durante una actualización.
Obligatorio: sí
Tipo: cadena
LogicalResourceId-
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation.
Obligatorio: sí
Tipo: cadena
PhysicalResourceId-
Un ID físico definido por el proveedor de recursos personalizados que es exclusivo de dicho proveedor.
Obligatorio: sí
Tipo: cadena
ResourceProperties-
Este campo contiene el contenido del objeto Properties enviado por el desarrollador de la plantilla. El proveedor de recursos personalizado define su contenido.
Obligatorio: no
Tipo: objeto JSON
OldResourceProperties-
Usado solo para solicitudes Update. Los valores de propiedades de recursos declarados con anterioridad por el desarrollador de plantillas en la plantilla de CloudFormation.
Obligatorio: sí
Tipo: objeto JSON
Ejemplo
{
"RequestType" : "Update",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-update-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"PhysicalResourceId" : "provider-defined-physical-id",
"ResourceProperties" : {
"key1" : "new-string",
"key2" : [ "new-list" ],
"key3" : { "key4" : "new-map" }
},
"OldResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
- Delete
-
Cuando el desarrollador de la plantilla elimina la pila o elimina el recurso personalizado de la pila y, a continuación, actualiza la pila, CloudFormation envía una solicitud con RequestType establecido en Delete.
Elimine las solicitudes que contienen los siguientes campos:
RequestType-
Delete.
Obligatorio: sí
Tipo: cadena
RequestId-
Un ID único para la solicitud.
Obligatorio: sí
Tipo: cadena
StackId-
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado.
Obligatorio: sí
Tipo: cadena
ResponseURL-
La URL de respuesta identifica un bucket de S3 prefirmado que recibe respuestas del proveedor de recursos personalizados para CloudFormation.
Obligatorio: sí
Tipo: cadena
ResourceType-
El tipo de recurso elegido por el desarrollador de plantillas del recurso personalizado en la plantilla de CloudFormation. Los nombres de tipos de recursos personalizados pueden tener una longitud máxima de 60 caracteres y pueden incluir caracteres alfanuméricos y los siguientes caracteres: _@-.
Obligatorio: sí
Tipo: cadena
LogicalResourceId-
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation.
Obligatorio: sí
Tipo: cadena
PhysicalResourceId-
Un ID físico definido por el proveedor de recursos personalizados que es exclusivo de dicho proveedor.
Obligatorio: sí
Tipo: cadena
ResourceProperties-
Este campo contiene el contenido del objeto Properties enviado por el desarrollador de la plantilla. El proveedor de recursos personalizado define su contenido.
Obligatorio: no
Tipo: objeto JSON
Ejemplo
{
"RequestType" : "Delete",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-delete-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"PhysicalResourceId" : "provider-defined-physical-id",
"ResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
Objeto de respuesta
El proveedor de recursos personalizados envía una respuesta a la URL prefirmada para todos los tipos de recursos. Si el proveedor de recursos personalizados no envía una respuesta, CloudFormation espera hasta que se agote el tiempo de espera de la operación.
La respuesta debe ser un objeto JSON con los campos siguientes:
Status-
Debe ser SUCCESS o FAILED.
Obligatorio: sí
Tipo: cadena
RequestId-
Un ID único para la solicitud. Copie este valor exactamente como aparece en la solicitud.
Obligatorio: sí
Tipo: cadena
StackId-
El nombre de recurso de Amazon (ARN) que identifica la pila que contiene el recurso personalizado. Copie este valor exactamente como aparece en la solicitud.
Obligatorio: sí
Tipo: cadena
LogicalResourceId-
El nombre elegido por el desarrollador de la plantilla (ID lógico) del recurso personalizado en la plantilla de CloudFormation. Copie este valor exactamente como aparece en la solicitud.
Obligatorio: sí
Tipo: cadena
PhysicalResourceId-
Este valor debe ser un identificador exclusivo del proveedor de recursos personalizados y puede tener un tamaño máximo de 1 KB. El valor debe ser una cadena que no esté vacía y debe ser idéntica para todas las respuestas del mismo recurso.
Al actualizar los recursos personalizados, el valor devuelto para PhysicalResourceId determina el comportamiento de la actualización. Si el valor devuelto es el mismo, CloudFormation lo considera una actualización normal. Si el valor cambia, CloudFormation interpreta la actualización como un reemplazo y envía una solicitud de eliminación al antiguo recurso. Para obtener más información, consulte AWS::CloudFormation::CustomResource.
Obligatorio: sí
Tipo: cadena
Reason-
Describe el motivo de una respuesta de error.
Obligatorio si Status es FAILED. De lo contrario, es opcional.
Obligatorio: condicional
Tipo: cadena
NoEcho-
Indique si se enmascara la salida del recurso personalizado cuando se recupera con la función Fn::GetAtt. Si se establece en true, todos los valores devueltos se enmascaran con asteriscos (*****), excepto los almacenados en la sección Metadata de la plantilla. CloudFormation no transforma, modifica ni redacta ninguna información que incluya en la sección Metadata. El valor predeterminado es false.
Para obtener más información sobre el uso de NoEcho para enmascarar información confidencial, consulte la práctica recomendada de No integre credenciales en sus plantillas.
Disponible solo para respuestas Create y Update. No se admite para las respuestas Delete.
Obligatorio: no
Tipo: booleano
Data-
Los pares de nombre-valor definidos por el proveedor de recursos personalizados que se enviarán con la respuesta. Puede acceder a los valores proporcionados aquí por nombre en la plantilla con Fn::GetAtt.
Disponible solo para respuestas Create y Update. No se admite para las respuestas Delete.
Si los pares nombre-valor contienen información confidencial, debe usar el campo NoEcho para enmascarar la salida del recurso personalizado. De lo contrario, los valores son visibles a través de las API que muestran valores de propiedades (como DescribeStackEvents).
Obligatorio: no
Tipo: objeto JSON
Ejemplos de respuestas satisfactorias
Respuesta Create y Update
{
"Status": "SUCCESS",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id",
"NoEcho": true,
"Data": {
"key1": "value1",
"key2": "value2"
}
}
DeleteRespuesta de
{
"Status": "SUCCESS",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id"
}
Respuesta de ejemplo con error
{
"Status": "FAILED",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id",
"Reason": "Required failure reason string"
}
