Package software.amazon.awscdk.triggers
Triggers
---
AWS CDK v1 has reached End-of-Support on 2023-06-01. This package is no longer being updated, and users should migrate to AWS CDK v2.
For more information on how to migrate, see the Migrating to AWS CDK v2 guide.
Triggers allows you to execute code during deployments. This can be used for a variety of use cases such as:
- Self tests: validate something after a resource/construct been provisioned
- Data priming: add initial data to resources after they are created
- Preconditions: check things such as account limits or external dependencies before deployment.
Usage
The TriggerFunction
construct will define an AWS Lambda function which is
triggered during deployment:
import software.amazon.awscdk.services.lambda.*; import software.amazon.awscdk.triggers.*; import software.amazon.awscdk.core.Stack; Stack stack; TriggerFunction.Builder.create(stack, "MyTrigger") .runtime(Runtime.NODEJS_14_X) .handler("index.handler") .code(Code.fromAsset(__dirname + "/my-trigger")) .build();
In the above example, the AWS Lambda function defined in myLambdaFunction
will
be invoked when the stack is deployed.
Trigger Failures
If the trigger handler fails (e.g. an exception is raised), the CloudFormation deployment will fail, as if a resource failed to provision. This makes it easy to implement "self tests" via triggers by simply making a set of assertions on some provisioned infrastructure.
Order of Execution
By default, a trigger will be executed by CloudFormation after the associated handler is provisioned. This means that if the handler takes an implicit dependency on other resources (e.g. via environment variables), those resources will be provisioned before the trigger is executed.
In most cases, implicit ordering should be sufficient, but you can also use
executeAfter
and executeBefore
to control the order of execution.
The following example defines the following order: (hello, world) => myTrigger => goodbye
.
The resources under hello
and world
will be provisioned in
parallel, and then the trigger myTrigger
will be executed. Only then the
resources under goodbye
will be provisioned:
import software.constructs.Construct; import software.constructs.Node; import software.amazon.awscdk.triggers.*; Trigger myTrigger; Construct hello; Construct world; Construct goodbye; myTrigger.executeAfter(hello, world); myTrigger.executeBefore(goodbye);
Note that hello
and world
are construct scopes. This means that they can
be specific resources (such as an s3.Bucket
object) or groups of resources
composed together into constructs.
Re-execution of Triggers
By default, executeOnHandlerChange
is enabled. This implies that the trigger
is re-executed every time the handler function code or configuration changes. If
this option is disabled, the trigger will be executed only once upon first
deployment.
In the future we will consider adding support for additional re-execution modes:
executeOnEveryDeployment: boolean
- re-executes every time the stack is deployed (add random "salt" during synthesis).executeOnResourceChange: Construct[]
- re-executes when one of the resources under the specified scopes has changed (add the hash the CloudFormation resource specs).
-
ClassDescriptionInterface for triggers.Internal default implementation for
ITrigger
.A proxy class which represents a concrete javascript instance of this type.Triggers an AWS Lambda function during deployment.A fluent builder forTrigger
.Invokes an AWS Lambda function during deployment.A fluent builder forTriggerFunction
.Props forInvokeFunction
.A builder forTriggerFunctionProps
An implementation forTriggerFunctionProps
Determines.Options forTrigger
.A builder forTriggerOptions
An implementation forTriggerOptions
Props forTrigger
.A builder forTriggerProps
An implementation forTriggerProps