# AwsCustomResource

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.

Extends: Construct › AwsCustomResource
Implements: IGrantable, IConstruct, IDependable

- Source: [`custom-resources/lib/aws-custom-resource/aws-custom-resource.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts#L462)
- Type last changed: v2.196.0 · 16 May 2025

## Example

```ts
const crossAccountRoleArn = 'arn:aws:iam::OTHERACCOUNT:role/CrossAccountRoleName'; // arn of role deployed in separate account

const callRegion = 'us-west-1'; // sdk call to be made in specified region (optional)

new cr.AwsCustomResource(this, 'CrossAccount', {
  onCreate: {
    assumedRoleArn: crossAccountRoleArn,
    region: callRegion, // optional
    service: 'sts',
    action: 'GetCallerIdentity',
    physicalResourceId: cr.PhysicalResourceId.of('id'),
  },
  policy: cr.AwsCustomResourcePolicy.fromStatements([iam.PolicyStatement.fromJson({
    Effect: "Allow",
    Action: "sts:AssumeRole",
    Resource: crossAccountRoleArn,
  })]),
});
```

## Initializer

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

## Construct Props

- `functionName`: string — A name for the singleton Lambda function implementing this custom resource.

  **Default:** AWS CloudFormation generates a unique physical ID and uses that ID for the function's name. For more information, see Name Type.

  The function name will remain the same after the first AwsCustomResource is created in a stack.

- `installLatestAwsSdk`: boolean — Whether to install the latest AWS SDK v3.

  **Default:** The value of `@aws-cdk/customresources:installLatestAwsSdkDefault`, otherwise `true`

  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.

- `logGroup`: [ILogGroupRef](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_logs.ILogGroupRef.html) — The Log Group used for logging of events emitted by the custom resource's lambda function.

  **Default:** a default log group created by AWS Lambda

  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.

- `logRetention`: [RetentionDays](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.RetentionDays.html) = logs.RetentionDays.INFINITE — 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.

- `memorySize`: number — The memory size for the singleton Lambda function implementing this custom resource.

  **Default:** 512 mega in case if installLatestAwsSdk is false.

- `onCreate`: [AwsSdkCall](/cdk/api/v2/docs/aws-cdk-lib.custom_resources.AwsSdkCall.html) — The AWS SDK call to make when the resource is created.

  **Default:** the call when the resource is updated

- `onDelete`: [AwsSdkCall](/cdk/api/v2/docs/aws-cdk-lib.custom_resources.AwsSdkCall.html) — The AWS SDK call to make when the resource is deleted.

  **Default:** no call

- `onUpdate`: [AwsSdkCall](/cdk/api/v2/docs/aws-cdk-lib.custom_resources.AwsSdkCall.html) — The AWS SDK call to make when the resource is updated.

  **Default:** no call

- `policy`: [AwsCustomResourcePolicy](/cdk/api/v2/docs/aws-cdk-lib.custom_resources.AwsCustomResourcePolicy.html) — The policy that will be added to the execution role of the Lambda function implementing this custom resource provider.

  **Default:** no policy added

  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.

- `removalPolicy`: [RemovalPolicy](/cdk/api/v2/docs/aws-cdk-lib.RemovalPolicy.html) = cdk.RemovalPolicy.Destroy — The policy to apply when this resource is removed from the application.

- `resourceType`: string = Custom::AWS — Cloudformation Resource type.

- `role`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — The execution role for the singleton Lambda function implementing this custom resource provider.

  **Default:** a new role is created

  This role will apply to all `AwsCustomResource`
  instances in the stack. The role must be assumable by the
  `lambda.amazonaws.com` service principal.

- `serviceTimeout`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.seconds(3600) — The maximum time that can elapse before a custom resource operation times out.

  You should not need to set this property. It is intended to allow quick turnaround
  even if the implementor of the custom resource forgets to include a `try/catch`.
  We have included the `try/catch`, and AWS service calls usually do not take an hour
  to complete.

  The value must be between 1 second and 3600 seconds.

- `timeout`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.minutes(2) — The timeout for the singleton Lambda function implementing this custom resource.

- `vpc`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) — The vpc to provision the lambda function in.

  **Default:** the function is not provisioned inside a vpc.

- `vpcSubnets`: [SubnetSelection](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.SubnetSelection.html) — Which subnets from the VPC to place the lambda function in.

  **Default:** the Vpc default strategy if not specified

  Only used if 'vpc' is supplied. Note: internet access for Lambdas
  requires a NAT gateway, so picking Public subnets is not allowed.

## Properties

- `grantPrincipal`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) — The principal to grant permissions to.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class.

- `PROVIDER_FUNCTION_UUID`: string (static) — The uuid of the custom resource provider singleton lambda function.

## Methods

- `getResponseField(dataPath: string): 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.

  **Parameters**

  - `dataPath` — the path to the data.

- `getResponseFieldReference(dataPath: string): 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.

  **Parameters**

  - `dataPath` — the path to the data.

- `isConstruct(x: any): boolean` (static) — 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 object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.

  **Parameters**

  - `mixins` — The mixins to apply.

  **Returns:** This construct for chaining