aws-cdk-lib.custom_resources.AwsCustomResource

class AwsCustomResource (construct)

LanguageType name
.NETAmazon.CDK.CustomResources.AwsCustomResource
Gogithub.com/aws/aws-cdk-go/awscdk/v2/customresources#AwsCustomResource
Javasoftware.amazon.awscdk.customresources.AwsCustomResource
Pythonaws_cdk.custom_resources.AwsCustomResource
TypeScript (source)aws-cdk-lib » custom_resources » AwsCustomResource

Implements IConstruct, IDependable, IGrantable

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.

Example

const getParameter = new cr.AwsCustomResource(this, 'GetParameter', {
  onUpdate: { // will also be called for a CREATE event
    service: 'SSM',
    action: 'getParameter',
    parameters: {
      Name: 'my-parameter',
      WithDecryption: true,
    },
    physicalResourceId: cr.PhysicalResourceId.of(Date.now().toString()), // Update physical id to always fetch the latest version
  },
  policy: cr.AwsCustomResourcePolicy.fromSdkCalls({
    resources: cr.AwsCustomResourcePolicy.ANY_RESOURCE,
  }),
});

// Use the value in another construct with
getParameter.getResponseField('Parameter.Value');

Initializer

new AwsCustomResource(scope: Construct, id: string, props: AwsCustomResourceProps)

Parameters

  • scope Construct
  • id string
  • props AwsCustomResourceProps

Construct Props

NameTypeDescription
functionName?stringA name for the singleton Lambda function implementing this custom resource.
installLatestAwsSdk?booleanWhether to install the latest AWS SDK v2.
logRetention?RetentionDaysThe number of days log events of the singleton Lambda function implementing this custom resource are kept in CloudWatch Logs.
onCreate?AwsSdkCallThe AWS SDK call to make when the resource is created.
onDelete?AwsSdkCallThe AWS SDK call to make when the resource is deleted.
onUpdate?AwsSdkCallThe AWS SDK call to make when the resource is updated.
policy?AwsCustomResourcePolicyThe policy that will be added to the execution role of the Lambda function implementing this custom resource provider.
removalPolicy?RemovalPolicyThe policy to apply when this resource is removed from the application.
resourceType?stringCloudformation Resource type.
role?IRoleThe execution role for the singleton Lambda function implementing this custom resource provider.
timeout?DurationThe timeout for the singleton Lambda function implementing this custom resource.
vpc?IVpcThe vpc to provision the lambda function in.
vpcSubnets?SubnetSelectionWhich subnets from the VPC to place the lambda function in.

functionName?

Type: string (optional, default: AWS CloudFormation generates a unique physical ID and uses that ID for the function's name. For more information, see Name Type.)

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.


installLatestAwsSdk?

Type: boolean (optional, default: The value of @aws-cdk/customresources:installLatestAwsSdkDefault, otherwise true)

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.


logRetention?

Type: RetentionDays (optional, default: logs.RetentionDays.INFINITE)

The number of days log events of the singleton Lambda function implementing this custom resource are kept in CloudWatch Logs.


onCreate?

Type: AwsSdkCall (optional, default: the call when the resource is updated)

The AWS SDK call to make when the resource is created.


onDelete?

Type: AwsSdkCall (optional, default: no call)

The AWS SDK call to make when the resource is deleted.


onUpdate?

Type: AwsSdkCall (optional, default: no call)

The AWS SDK call to make when the resource is updated.


policy?

Type: AwsCustomResourcePolicy (optional, default: no policy added)

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.

See also: Policy.fromSdkCalls


removalPolicy?

Type: RemovalPolicy (optional, default: cdk.RemovalPolicy.Destroy)

The policy to apply when this resource is removed from the application.


resourceType?

Type: string (optional, default: Custom::AWS)

Cloudformation Resource type.


role?

Type: IRole (optional, default: a new role is created)

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.


timeout?

Type: Duration (optional, default: Duration.minutes(2))

The timeout for the singleton Lambda function implementing this custom resource.


vpc?

Type: IVpc (optional, default: the function is not provisioned inside a vpc.)

The vpc to provision the lambda function in.


vpcSubnets?

Type: SubnetSelection (optional, default: the Vpc default strategy if not specified)

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.

Properties

NameTypeDescription
grantPrincipalIPrincipalThe principal to grant permissions to.
nodeNodeThe tree node.
static PROVIDER_FUNCTION_UUIDstringThe uuid of the custom resource provider singleton lambda function.

grantPrincipal

Type: IPrincipal

The principal to grant permissions to.


node

Type: Node

The tree node.


static PROVIDER_FUNCTION_UUID

Type: string

The uuid of the custom resource provider singleton lambda function.

Methods

NameDescription
getResponseField(dataPath)Returns response data for the AWS SDK call as string.
getResponseFieldReference(dataPath)Returns response data for the AWS SDK call.
toString()Returns a string representation of this construct.

getResponseField(dataPath)

public getResponseField(dataPath: string): string

Parameters

  • dataPath string — the path to the data.

Returns

  • string

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.


getResponseFieldReference(dataPath)

public getResponseFieldReference(dataPath: string): Reference

Parameters

  • dataPath string — the path to the data.

Returns

  • Reference

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.


toString()

public toString(): string

Returns

  • string

Returns a string representation of this construct.