custom-resources: add refresh trigger property to AwsCustomResource

[faridnsh]

Describe the feature

Add an optional property to AwsCustomResource whose only purpose is to participate in CloudFormation change detection.

When the value of this property changes, CloudFormation would send an Update event to the custom resource, causing the configured onUpdate SDK call to run again.

The property would not be passed to the AWS SDK call itself.

For example:

new AwsCustomResource(this, 'Resource', {
  onUpdate: {
    service: 'SomeService',
    action: 'someAction',
    parameters: {
      // ...
    },
    physicalResourceId: PhysicalResourceId.of('Resource'),
  },
  updateTrigger: someParameter.valueAsString,
  policy: AwsCustomResourcePolicy.fromSdkCalls({
    resources: AwsCustomResourcePolicy.ANY_RESOURCE,
  }),
});

Use Case

There are cases where an AwsCustomResource needs to rerun its onUpdate call because some external deployment input changed, even though that input is not itself a parameter to the AWS SDK operation.

For example, an SSM parameter, configuration version, hash, or another resource attribute may determine when the SDK call should be refreshed.

Proposed Solution

No response

Other Information

Would be happy to make a pull request if the maintainers are happy with this feature.

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.269.0

AWS CDK CLI version

2.1141.0

Environment details (OS name and version, etc.)

Not relevant

[pahud]

Thanks for the well-scoped request. This is a reasonable gap. Since it's a feature request
there's nothing to reproduce, but I confirmed the behavior from the source: the custom
resource template only carries the create/update/delete SDK-call payloads, so the only
levers that affect CloudFormation change detection today are parameters (forwarded to the
SDK call) and physicalResourceId (changing it replaces the resource).

https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/custom-resources/lib/aws-custom-resource/aws-custom-resource.ts

In the meantime, the general approach today is to pass an extra key in parameters to
force the update, e.g.:

onUpdate: {
  service: 'SomeService',
  action: 'someAction',
  parameters: {
    // ... real parameters
    triggerTimestamp: Date.now().toString(), // only here to force change detection
  },
  physicalResourceId: PhysicalResourceId.of('Resource'),
},

This works in most cases because the SDK v3 clients only serialize modeled fields, so an
unknown top-level key participates in the CloudFormation diff without reaching the service.
It does rely on that serialization behavior though, which is part of why a first-class
property like the one you're proposing makes sense.

On the mechanism itself: your proposal is a good fit because the handler only consumes the
create/update/delete keys, so a new top-level property would participate in the CFN
diff (triggering an Update) while being ignored by the SDK call — exactly the behavior you
described. In my opinion the cleanest shape is an optional string prop that is serialized
into the CustomResource properties but excluded from the SDK payload.

Since you mentioned you're open to implementing this — please feel free to submit a PR and
discuss the design details (property name, whether it lives on the props or per-AwsSdkCall,
and docs) with the maintainers from there.

[Srijan229]

Hi @faridnsh and @pahud , I’d be interested in implementing this. I plan to add an optional updateTrigger?: string to AwsCustomResourceProps, serialize it as a top-level custom-resource property, and add synthesis tests confirming that it participates in the CloudFormation properties without being included in the SDK call payload. If this direction looks good, I can open a PR.