Basic usage

Resource types

By default, the class name is assumed to be the expected resource type name (i.e., Custom:: + the class name), and incoming requests are validated against this. To disable this, set a class field RESOURCE_TYPE_SPEC=None. To validate incoming requests against types other than the class name, set RESOURCE_TYPE_SPEC to be a string or a list of strings.

Physical resource ids

By default, before create is called, self.physical_resource_id is set to a value that is generated similar to how CloudFormation does it: {stack_id}-{logical resource id}-{random string}. This value should be used to name the resource being created.

If instead, the physical resource id is generated by the resource itself (for example, Cognito pools have a unique id generated by Cognito), then you should set the class field DISABLE_PHYSICAL_RESOURCE_ID_GENERATION=True, and set self.physical_resource_id yourself within the create method. Customization of the generated id is available; see Advanced usage.

Results

Each of the create, update and delete methods can indicate success or failure in one of two ways:

• Simply return or raise an exception
• Set self.status to self.STATUS_SUCCESS or self.STATUS_FAILED In the case of failure, self.failure_reason can be set to a string to provide an explanation in the response. These methods can also populate the self.resource_outputs dictionary with fields that then will be available in CloudFormation. If the return value of the function is a dict, that is merged into resource_outputs. If it is not a dict, the value is stored under the 'Value' key.

AWS SDK

The class provides methods get_boto3_client and get_boto3_resource that work just like the boto3.client and boto3.resource functions, and cache the resulting clients/resources in the class, reducing overhead in the Lambda invocations. These also rely on the get_boto3_session() method, which in turn uses BOTO3_SESSION_FACTORY if it is set, allowing overriding with mock sessions for testing (see placebo). Similarly, BOTO3_CLIENT_FACTORY and BOTO3_RESOURCE_FACTORY, both of which can be set to callables that take a session and a name, can be set to override client and resource creation for testing purposes.