AWS CloudWatch Synthetics Canary

This page shows how to write Terraform and CloudFormation for CloudWatch Synthetics Canary and write them securely.

aws_synthetics_canary (Terraform)

The Canary in CloudWatch Synthetics can be configured in Terraform with the resource name aws_synthetics_canary. The following sections describe 5 examples of how to use the resource and its parameters.

Example Usage from GitHub

c14-05-cloudwatch-synthetics.tf#L14
resource "aws_synthetics_canary" "sswebsite2" {
  name                 = "sswebsite2"
  artifact_s3_location = "s3://cw-syn-results-180789647333-us-east-1/canary/us-east-1/sswebsite2"
  execution_role_arn   = "arn:aws:iam::180789647333:role/service-role/CloudWatchSyntheticsRole-app1-canary-test-eaf-ff4674189c99"
  handler              = "sswebsite2.handler"
  zip_file             = "sswebsite2/sswebsite2v1.zip"
c14-05-cloudwatch-synthetics.tf#L14
resource "aws_synthetics_canary" "sswebsite2" {
  name                 = "sswebsite2"
  artifact_s3_location = "s3://cw-syn-results-180789647333-us-east-1/canary/us-east-1/sswebsite2"
  execution_role_arn   = "arn:aws:iam::180789647333:role/service-role/CloudWatchSyntheticsRole-app1-canary-test-eaf-ff4674189c99"
  handler              = "sswebsite2.handler"
  zip_file             = "sswebsite2/sswebsite2v1.zip"
c14-05-cloudwatch-synthetics.tf#L14
resource "aws_synthetics_canary" "sswebsite2" {
  name                 = "sswebsite2"
  artifact_s3_location = "s3://cw-syn-results-180789647333-us-east-1/canary/us-east-1/sswebsite2"
  execution_role_arn   = "arn:aws:iam::180789647333:role/service-role/CloudWatchSyntheticsRole-app1-canary-test-eaf-ff4674189c99"
  handler              = "sswebsite2.handler"
  zip_file             = "sswebsite2/sswebsite2v1.zip"
c14-05-cloudwatch-synthetics.tf#L14
resource "aws_synthetics_canary" "sswebsite2" {
  name                 = "sswebsite2"
  artifact_s3_location = "s3://cw-syn-results-180789647333-us-east-1/canary/us-east-1/sswebsite2"
  execution_role_arn   = "arn:aws:iam::180789647333:role/service-role/CloudWatchSyntheticsRole-app1-canary-test-eaf-ff4674189c99"
  handler              = "sswebsite2.handler"
  zip_file             = "sswebsite2/sswebsite2v1.zip"
c14-05-cloudwatch-synthetics.tf#L14
resource "aws_synthetics_canary" "sswebsite2" {
  name                 = "sswebsite2"
  artifact_s3_location = "s3://cw-syn-results-180789647333-us-east-1/canary/us-east-1/sswebsite2"
  execution_role_arn   = "arn:aws:iam::180789647333:role/service-role/CloudWatchSyntheticsRole-app1-canary-test-eaf-ff4674189c99"
  handler              = "sswebsite2.handler"
  zip_file             = "sswebsite2/sswebsite2v1.zip"

Review your Terraform file for AWS best practices

Shisho Cloud, our free checker to make sure your Terraform configuration follows best practices, is available (beta).

Parameters

Explanation in Terraform Registry

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.

AWS::Synthetics::Canary (CloudFormation)

The Canary in Synthetics can be configured in CloudFormation with the resource name AWS::Synthetics::Canary. The following sections describe 10 examples of how to use the resource and its parameters.

Example Usage from GitHub

synthetics.yml#L87
    Type: AWS::Synthetics::Canary
    Properties:
      Name: !Ref CanaryName
      ExecutionRoleArn: !Sub arn:aws:iam::${AWS::AccountId}:role/${CloudWatchSyntheticsRole}
      Code:
        Handler: pageLoadBlueprint.handler
canary.yml#L78
    Type: AWS::Synthetics::Canary
    Properties:
      Name:
        Fn::Sub: ${CanaryName}
      Code:
        Handler: exports.handler
canary.yml#L62
    Type: "AWS::Synthetics::Canary"
    Properties:
      Name: greeting-api-canary
      Code:
        Handler: apiCanary.handler
        Script: |
serverless.yml#L153
      Type: AWS::Synthetics::Canary
      Condition: CreateCanary
      Properties:
        Name: equality-info-health #Update name accordingly, max 21 characters
        Code:
          Handler: pageLoadBlueprint.handler
serverless.yml#L144
      Type: AWS::Synthetics::Canary
      Condition: CreateCanary
      Properties:
        Name: patches-areas-health #Update name accordingly, max 21 characters
        Code:
          Handler: pageLoadBlueprint.handler
integ.canary.expected.json#L92
      "Type": "AWS::Synthetics::Canary",
      "Properties": {
        "ArtifactS3Location": {
          "Fn::Join": [
            "",
            [
integ.canary.expected.json#L92
      "Type": "AWS::Synthetics::Canary",
      "Properties": {
        "ArtifactS3Location": {
          "Fn::Join": [
            "",
            [
integ.canary.expected.json#L92
      "Type": "AWS::Synthetics::Canary",
      "Properties": {
        "ArtifactS3Location": {
          "Fn::Join": [
            "",
            [
integ.canary.expected.json#L92
      "Type": "AWS::Synthetics::Canary",
      "Properties": {
        "ArtifactS3Location": {
          "Fn::Join": [
            "",
            [
integ.canary.expected.json#L92
      "Type": "AWS::Synthetics::Canary",
      "Properties": {
        "ArtifactS3Location": {
          "Fn::Join": [
            "",
            [

Parameters

Explanation in CloudFormation Registry

Creates or updates a canary. Canaries are scripts that monitor your endpoints and APIs from the outside-in. Canaries help you check the availability and latency of your web services and troubleshoot anomalies by investigating load time data, screenshots of the UI, logs, and metrics. You can set up a canary to run continuously or just once. To create canaries, you must have the CloudWatchSyntheticsFullAccess policy. If you are creating a new IAM role for the canary, you also need the the iam:CreateRole, iam:CreatePolicy and iam:AttachRolePolicy permissions. For more information, see Necessary Roles and Permissions.

Do not include secrets or proprietary information in your canary names. The canary name makes up part of the Amazon Resource Name (ARN) for the canary, and the ARN is included in outbound calls over the internet. For more information, see Security Considerations for Synthetics Canaries.

Frequently asked questions

What is AWS CloudWatch Synthetics Canary?

AWS CloudWatch Synthetics Canary is a resource for CloudWatch Synthetics of Amazon Web Service. Settings can be wrote in Terraform and CloudFormation.

Where can I find the example code for the AWS CloudWatch Synthetics Canary?

For Terraform, the dev27verma/Terraform, nareshyarragunta/terraform1 and balimidi24/terraform-on-aws-ec2 source code examples are useful. See the Terraform Example section for further details.

For CloudFormation, the PaulDuvall/aws-5-mins, stuartellis/ec2-evergreen and thalesvon/greeting-api source code examples are useful. See the CloudFormation Example section for further details.