Skip to content

Resource: awsSyntheticsCanary

Provides a Synthetics Canary resource.

\~> NOTE: When you create a canary, AWS creates supporting implicit resources. See the Amazon CloudWatch Synthetics documentation on DeleteCanary for a full list. Neither AWS nor Terraform deletes these implicit resources automatically when the canary is deleted. Before deleting a canary, ensure you have all the information about the canary that you need to delete the implicit resources using Terraform shell commands, the AWS Console, or AWS CLI.

Example Usage

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.syntheticsCanary.SyntheticsCanary(this, "some", {
  artifactS3Location: "s3://some-bucket/",
  executionRoleArn: "some-role",
  handler: "exports.handler",
  name: "some-canary",
  runtimeVersion: "syn-1.0",
  schedule: {
    expression: "rate(0 minute)",
  },
  zipFile: "test-fixtures/lambdatest.zip",
});

Argument Reference

The following arguments are required:

  • artifactS3Location - (Required) Location in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.
  • executionRoleArn - (Required) ARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.
  • handler - (Required) Entry point to use for the source code when running the canary. This value must end with the string handler .
  • name - (Required) Name for this canary. Has a maximum length of 21 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.
  • runtimeVersion - (Required) Runtime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include synPythonSelenium10, synNodejsPuppeteer30, synNodejs22, synNodejs21, synNodejs20, and syn10.
  • schedule - (Required) Configuration block providing how often the canary is to run and when these test runs are to stop. Detailed below.

The following arguments are optional:

  • deleteLambda - (Optional) Specifies whether to also delete the Lambda functions and layers used by this canary. The default is false.
  • vpcConfig - (Optional) Configuration block. Detailed below.
  • failureRetentionPeriod - (Optional) Number of days to retain data about failed runs of this canary. If you omit this field, the default of 31 days is used. The valid range is 1 to 455 days.
  • runConfig - (Optional) Configuration block for individual canary runs. Detailed below.
  • s3Bucket - (Optional) Full bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.
  • s3Key - (Optional) S3 key of your script. Conflicts with zipFile.
  • s3Version - (Optional) S3 version ID of your script. Conflicts with zipFile.
  • startCanary - (Optional) Whether to run or stop the canary.
  • successRetentionPeriod - (Optional) Number of days to retain data about successful runs of this canary. If you omit this field, the default of 31 days is used. The valid range is 1 to 455 days.
  • tags - (Optional) Key-value map of resource tags. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
  • artifactConfig - (Optional) configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.
  • zipFile - (Optional) ZIP file that contains the script, if you input your canary script directly into the canary instead of referring to an S3 location. It can be up to 225KB. Conflicts with s3Bucket, s3Key, and s3Version.

artifactConfig

  • s3Encryption - (Optional) Configuration of the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See S3 Encryption.

s3Encryption

  • encryptionMode - (Optional) The encryption method to use for artifacts created by this canary. Valid values are: SSE_S3 and SSE_KMS.
  • kmsKeyArn - (Optional) The ARN of the customer-managed KMS key to use, if you specify SSE_KMS for encryptionMode.

schedule

  • expression - (Required) Rate expression or cron expression that defines how often the canary is to run. For rate expression, the syntax is rate(numberUnit). unit can be minute, minutes, or hour. For cron expression, the syntax is cron(expression). For more information about the syntax for cron expressions, see Scheduling canary runs using cron.
  • durationInSeconds - (Optional) Duration in seconds, for the canary to continue making regular runs according to the schedule in the Expression value.

runConfig

  • timeoutInSeconds - (Optional) Number of seconds the canary is allowed to run before it must stop. If you omit this field, the frequency of the canary is used, up to a maximum of 840 (14 minutes).
  • memoryInMb - (Optional) Maximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.
  • activeTracing - (Optional) Whether this canary is to use active AWS X-Ray tracing when it runs. You can enable active tracing only for canaries that use version syn-nodejs-2.0 or later for their canary runtime.
  • environmentVariables - (Optional) Map of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.

vpcConfig

If this canary tests an endpoint in a VPC, this structure contains information about the subnet and security groups of the VPC endpoint. For more information, see Running a Canary in a VPC.

  • subnetIds - (Required) IDs of the subnets where this canary is to run.
  • securityGroupIds - (Required) IDs of the security groups for this canary.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

  • arn - Amazon Resource Name (ARN) of the Canary.
  • engineArn - ARN of the Lambda function that is used as your canary's engine.
  • id - Name for this canary.
  • sourceLocationArn - ARN of the Lambda layer where Synthetics stores the canary script code.
  • status - Canary status.
  • tagsAll - A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.
  • timeline - Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.

vpcConfig

  • vpcId - ID of the VPC where this canary is to run.

timeline

  • created - Date and time the canary was created.
  • lastModified - Date and time the canary was most recently modified.
  • lastStarted - Date and time that the canary's most recent run started.
  • lastStopped - Date and time that the canary's most recent run ended.

Import

Synthetics Canaries can be imported using the name, e.g.,

$ terraform import aws_synthetics_canary.some some-canary