AwsCustomResource

class aws_cdk.custom_resources.AwsCustomResource(scope, id, *, function_name=None, install_latest_aws_sdk=None, log_group=None, log_retention=None, on_create=None, on_delete=None, on_update=None, policy=None, removal_policy=None, resource_type=None, role=None, timeout=None, vpc=None, vpc_subnets=None)

Bases: Construct

Defines a custom resource that is materialized using specific AWS API calls.

These calls are created using a singleton Lambda function.

Use this to bridge any gap that might exist in the CloudFormation Coverage. You can specify exactly which calls are invoked for the ‘CREATE’, ‘UPDATE’ and ‘DELETE’ life cycle events.

ExampleMetadata:: infused

Example:

get_parameter = cr.AwsCustomResource(self, "GetParameter",
    on_update=cr.AwsSdkCall( # will also be called for a CREATE event
        service="SSM",
        action="GetParameter",
        parameters={
            "Name": "my-parameter",
            "WithDecryption": True
        },
        physical_resource_id=cr.PhysicalResourceId.of(Date.now().to_string())),
    policy=cr.AwsCustomResourcePolicy.from_sdk_calls(
        resources=cr.AwsCustomResourcePolicy.ANY_RESOURCE
    )
)

# Use the value in another construct with
get_parameter.get_response_field("Parameter.Value")

Parameters:

scope (Construct) –
id (str) –
function_name (Optional[str]) – A name for the singleton Lambda function implementing this custom resource. The function name will remain the same after the first AwsCustomResource is created in a stack. Default: - AWS CloudFormation generates a unique physical ID and uses that ID for the function’s name. For more information, see Name Type.
install_latest_aws_sdk (Optional[bool]) – Whether to install the latest AWS SDK v2. If not specified, this uses whatever JavaScript SDK version is the default in AWS Lambda at the time of execution. Otherwise, installs the latest version from ‘npmjs.com’. The installation takes around 60 seconds and requires internet connectivity. The default can be controlled using the context key @aws-cdk/customresources:installLatestAwsSdkDefault is. Default: - The value of @aws-cdk/customresources:installLatestAwsSdkDefault, otherwise true
log_group (Optional[ILogGroup]) – The Log Group used for logging of events emitted by the custom resource’s lambda function. Providing a user-controlled log group was rolled out to commercial regions on 2023-11-16. If you are deploying to another type of region, please check regional availability first. Default: - a default log group created by AWS Lambda
log_retention (Optional[RetentionDays]) – The number of days log events of the singleton Lambda function implementing this custom resource are kept in CloudWatch Logs. This is a legacy API and we strongly recommend you migrate to logGroup if you can. logGroup allows you to create a fully customizable log group and instruct the Lambda function to send logs to it. Default: logs.RetentionDays.INFINITE
on_create (Union[AwsSdkCall, Dict[str, Any], None]) – The AWS SDK call to make when the resource is created. Default: - the call when the resource is updated
on_delete (Union[AwsSdkCall, Dict[str, Any], None]) – The AWS SDK call to make when the resource is deleted. Default: - no call
on_update (Union[AwsSdkCall, Dict[str, Any], None]) – The AWS SDK call to make when the resource is updated. Default: - no call
policy (Optional[AwsCustomResourcePolicy]) – The policy that will be added to the execution role of the Lambda function implementing this custom resource provider. The custom resource also implements iam.IGrantable, making it possible to use the grantXxx() methods. As this custom resource uses a singleton Lambda function, it’s important to note the that function’s role will eventually accumulate the permissions/grants from all resources. Note that a policy must be specified if role is not provided, as by default a new role is created which requires policy changes to access resources. Default: - no policy added
removal_policy (Optional[RemovalPolicy]) – The policy to apply when this resource is removed from the application. Default: cdk.RemovalPolicy.Destroy
resource_type (Optional[str]) – Cloudformation Resource type. Default: - Custom::AWS
role (Optional[IRole]) – The execution role for the singleton Lambda function implementing this custom resource provider. This role will apply to all AwsCustomResource instances in the stack. The role must be assumable by the lambda.amazonaws.com service principal. Default: - a new role is created
timeout (Optional[Duration]) – The timeout for the singleton Lambda function implementing this custom resource. Default: Duration.minutes(2)
vpc (Optional[IVpc]) – The vpc to provision the lambda function in. Default: - the function is not provisioned inside a vpc.
vpc_subnets (Union[SubnetSelection, Dict[str, Any], None]) – Which subnets from the VPC to place the lambda function in. Only used if ‘vpc’ is supplied. Note: internet access for Lambdas requires a NAT gateway, so picking Public subnets is not allowed. Default: - the Vpc default strategy if not specified

Methods

get_response_field(data_path)

Returns response data for the AWS SDK call as string.

Example for S3 / listBucket : ‘Buckets.0.Name’

Note that you cannot use this method if ignoreErrorCodesMatching is configured for any of the SDK calls. This is because in such a case, the response data might not exist, and will cause a CloudFormation deploy time error.

Parameters:: data_path (str) – the path to the data.
Return type:: str

get_response_field_reference(data_path)

Returns response data for the AWS SDK call.

Example for S3 / listBucket : ‘Buckets.0.Name’

Use Token.asXxx to encode the returned Reference as a specific type or use the convenience getDataString for string attributes.

Note that you cannot use this method if ignoreErrorCodesMatching is configured for any of the SDK calls. This is because in such a case, the response data might not exist, and will cause a CloudFormation deploy time error.

Parameters:: data_path (str) – the path to the data.
Return type:: Reference

to_string()

Returns a string representation of this construct.

Return type:: str

Attributes

PROVIDER_FUNCTION_UUID = '679f53fa-c002-430c-b0da-5b7982bd2287'

grant_principal: The principal to grant permissions to.

node: The tree node.

Static Methods

classmethod is_construct(x)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters:: x (Any) – Any object.
Return type:: bool
Returns:: true if x is an object created from a class which extends Construct.