@aws-cdk/custom-resources

constructor

constructor(scope: Construct, id: string, props: AwsCustomResourceProps);

property grantPrincipal

readonly grantPrincipal: iam.IPrincipal;

method getResponseField

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.

  Parameter dataPath

  the path to the data

method getResponseFieldReference

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

  Parameter dataPath

  the path to the data

property ANY_RESOURCE

static readonly ANY_RESOURCE: string[];

• Use this constant to configure access to any resource.

property resources

readonly resources?: string[];

property statements

readonly statements: iam.PolicyStatement[];

method fromSdkCalls

static fromSdkCalls: (options: SdkCallsPolicyOptions) => AwsCustomResourcePolicy;

• Generate IAM Policy Statements from the configured SDK calls.

  Each SDK call with be translated to an IAM Policy Statement in the form of: call.service:call.action (e.g s3:PutObject).

  This policy generator assumes the IAM policy name has the same name as the API call. This is true in 99% of cases, but there are exceptions (for example, S3's PutBucketLifecycleConfiguration requires s3:PutLifecycleConfiguration permissions, Lambda's Invoke requires lambda:InvokeFunction permissions). Use fromStatements if you want to do a call that requires different IAM action names.

  Parameter options

  options for the policy generation

method fromStatements

static fromStatements: (
    statements: iam.PolicyStatement[]
) => AwsCustomResourcePolicy;

• Explicit IAM Policy Statements.

  Parameter statements

  the statements to propagate to the SDK calls.

property id

readonly id?: string;

property responsePath

readonly responsePath?: string;

method fromResponse

static fromResponse: (responsePath: string) => PhysicalResourceId;

• Extract the physical resource id from the path (dot notation) to the data in the API call response.

method of

static of: (id: string) => PhysicalResourceId;

• Explicit physical resource id.

property creationStack

readonly creationStack: string[];

method resolve

resolve: (_: cdk.IResolveContext) => any;

method toJSON

toJSON: () => string;

• toJSON serialization to replace PhysicalResourceIdReference with a magic string.

method toString

toString: () => string;

constructor

constructor(scope: Construct, id: string, props: ProviderProps);

property isCompleteHandler

readonly isCompleteHandler?: lambda.IFunction;

• The user-defined AWS Lambda function which is invoked asynchronously in order to determine if the operation is complete.

property onEventHandler

readonly onEventHandler: lambda.IFunction;

• The user-defined AWS Lambda function which is invoked for all resource lifecycle operations (CREATE/UPDATE/DELETE).

property serviceToken

readonly serviceToken: string;

• The service token to use in order to define custom resources that are backed by this provider.

method bind

bind: (_scope: CoreConstruct) => CustomResourceProviderConfig;

• Called by CustomResource which uses this provider.

  Deprecated

  use provider.serviceToken instead

property functionName

readonly functionName?: string;

• 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.

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

property installLatestAwsSdk

readonly installLatestAwsSdk?: boolean;

• Whether to install the latest AWS SDK v2. Allows to use the latest API calls documented at https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html.

  The installation takes around 60 seconds.

  true

property logRetention

readonly logRetention?: logs.RetentionDays;

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

  logs.RetentionDays.INFINITE

property onCreate

readonly onCreate?: AwsSdkCall;

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

  - the call when the resource is updated

property onDelete

readonly onDelete?: AwsSdkCall;

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

  - no call

property onUpdate

readonly onUpdate?: AwsSdkCall;

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

  - no call

property policy

readonly policy: 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.

  See Also

  • Policy.fromStatements

  • Policy.fromSdkCalls

property resourceType

readonly resourceType?: string;

• Cloudformation Resource type.

  - Custom::AWS

property role

readonly role?: iam.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.

  - a new role is created

property timeout

readonly timeout?: cdk.Duration;

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

  Duration.minutes(2)

property action

readonly action: string;

• The service action to call

  See Also

  • https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html

property apiVersion

readonly apiVersion?: string;

• API version to use for the service

  See Also

  • https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/locking-api-versions.html - use latest available API version

property assumedRoleArn

readonly assumedRoleArn?: string;

• Used for running the SDK calls in underlying lambda with a different role Can be used primarily for cross-account requests to for example connect hostedzone with a shared vpc

  Example for Route53 / associateVPCWithHostedZone

  - run without assuming role

property ignoreErrorCodesMatching

readonly ignoreErrorCodesMatching?: string;

• The regex pattern to use to catch API errors. The code property of the Error object will be tested against this pattern. If there is a match an error will not be thrown.

  - do not catch errors

property outputPath

readonly outputPath?: string;

• Restrict the data returned by the custom resource to a specific path in the API response. Use this to limit the data returned by the custom resource if working with API calls that could potentially result in custom response objects exceeding the hard limit of 4096 bytes.

  Example for ECS / updateService: 'service.deploymentConfiguration.maximumPercent'

  - return all data

  Deprecated

  use outputPaths instead

property outputPaths

readonly outputPaths?: string[];

• Restrict the data returned by the custom resource to specific paths in the API response. Use this to limit the data returned by the custom resource if working with API calls that could potentially result in custom response objects exceeding the hard limit of 4096 bytes.

  Example for ECS / updateService: ['service.deploymentConfiguration.maximumPercent']

  - return all data

property parameters

readonly parameters?: any;

• The parameters for the service action

  - no parameters

  See Also

  • https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html

property physicalResourceId

readonly physicalResourceId?: PhysicalResourceId;

• The physical resource id of the custom resource for this call. Mandatory for onCreate or onUpdate calls.

  - no physical resource id

property region

readonly region?: string;

• The region to send service requests to. **Note: Cross-region operations are generally considered an anti-pattern.** **Consider first deploying a stack in that region.**

  - the region where this custom resource is deployed

property service

readonly service: string;

• The service to call

  See Also

  • https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html

property isCompleteHandler

readonly isCompleteHandler?: lambda.IFunction;

• The AWS Lambda function to invoke in order to determine if the operation is complete.

  This function will be called immediately after onEvent and then periodically based on the configured query interval as long as it returns false. If the function still returns false and the alloted timeout has passed, the operation will fail.

  - provider is synchronous. This means that the onEvent handler is expected to finish all lifecycle operations within the initial invocation.

property logRetention

readonly logRetention?: logs.RetentionDays;

• The number of days framework log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to INFINITE.

  logs.RetentionDays.INFINITE

property onEventHandler

readonly onEventHandler: lambda.IFunction;

• The AWS Lambda function to invoke for all resource lifecycle operations (CREATE/UPDATE/DELETE).

  This function is responsible to begin the requested resource operation (CREATE/UPDATE/DELETE) and return any additional properties to add to the event, which will later be passed to isComplete. The PhysicalResourceId property must be included in the response.

property providerFunctionName

readonly providerFunctionName?: string;

• Provider Lambda name.

  The provider lambda function name.

  - CloudFormation default name from unique physical ID

property queryInterval

readonly queryInterval?: Duration;

• Time between calls to the isComplete handler which determines if the resource has been stabilized.

  The first isComplete will be called immediately after handler and then every queryInterval seconds, and until timeout has been reached or until isComplete returns true.

  Duration.seconds(5)

property role

readonly role?: iam.IRole;

• AWS Lambda execution role.

  The role that will be assumed by the AWS Lambda. Must be assumable by the 'lambda.amazonaws.com' service principal.

  - A default role will be created.

property securityGroups

readonly securityGroups?: ec2.ISecurityGroup[];

• Security groups to attach to the provider functions.

  Only used if 'vpc' is supplied

  - If vpc is not supplied, no security groups are attached. Otherwise, a dedicated security group is created for each function.

property totalTimeout

readonly totalTimeout?: Duration;

• Total timeout for the entire operation.

  The maximum timeout is 2 hours (yes, it can exceed the AWS Lambda 15 minutes)

  Duration.minutes(30)

property vpc

readonly vpc?: ec2.IVpc;

• The vpc to provision the lambda functions in.

  - functions are not provisioned inside a vpc.

property vpcSubnets

readonly vpcSubnets?: ec2.SubnetSelection;

• Which subnets from the VPC to place the lambda functions in.

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

  - the Vpc default strategy if not specified

property resources

readonly resources: string[];

• The resources that the calls will have access to.

  It is best to use specific resource ARN's when possible. However, you can also use AwsCustomResourcePolicy.ANY_RESOURCE to allow access to all resources. For example, when onCreate is used to create a resource which you don't know the physical name of in advance.

  Note that will apply to ALL SDK calls.