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
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"
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"
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"
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"
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"
Parameters
-
arn
optional computed - string -
artifact_s3_location
required - string -
engine_arn
optional computed - string -
execution_role_arn
required - string -
failure_retention_period
optional - number -
handler
required - string -
id
optional computed - string -
name
required - string -
runtime_version
required - string -
s3_bucket
optional - string -
s3_key
optional - string -
s3_version
optional - string -
source_location_arn
optional computed - string -
start_canary
optional - bool -
status
optional computed - string -
success_retention_period
optional - number -
tags
optional - map from string to string -
timeline
optional computed - list of object-
created
- string -
last_modified
- string -
last_started
- string -
last_stopped
- string
-
-
zip_file
optional - string -
run_config
list block-
active_tracing
optional - bool -
memory_in_mb
optional computed - number -
timeout_in_seconds
optional - number
-
-
schedule
list block-
duration_in_seconds
optional - number -
expression
required - string
-
-
vpc_config
list block-
security_group_ids
optional - set of string -
subnet_ids
optional - set of string -
vpc_id
optional computed - string
-
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
Type: AWS::Synthetics::Canary
Properties:
Name: !Ref CanaryName
ExecutionRoleArn: !Sub arn:aws:iam::${AWS::AccountId}:role/${CloudWatchSyntheticsRole}
Code:
Handler: pageLoadBlueprint.handler
Type: AWS::Synthetics::Canary
Properties:
Name:
Fn::Sub: ${CanaryName}
Code:
Handler: exports.handler
Type: "AWS::Synthetics::Canary"
Properties:
Name: greeting-api-canary
Code:
Handler: apiCanary.handler
Script: |
Type: AWS::Synthetics::Canary
Condition: CreateCanary
Properties:
Name: equality-info-health #Update name accordingly, max 21 characters
Code:
Handler: pageLoadBlueprint.handler
Type: AWS::Synthetics::Canary
Condition: CreateCanary
Properties:
Name: patches-areas-health #Update name accordingly, max 21 characters
Code:
Handler: pageLoadBlueprint.handler
"Type": "AWS::Synthetics::Canary",
"Properties": {
"ArtifactS3Location": {
"Fn::Join": [
"",
[
"Type": "AWS::Synthetics::Canary",
"Properties": {
"ArtifactS3Location": {
"Fn::Join": [
"",
[
"Type": "AWS::Synthetics::Canary",
"Properties": {
"ArtifactS3Location": {
"Fn::Join": [
"",
[
"Type": "AWS::Synthetics::Canary",
"Properties": {
"ArtifactS3Location": {
"Fn::Join": [
"",
[
"Type": "AWS::Synthetics::Canary",
"Properties": {
"ArtifactS3Location": {
"Fn::Join": [
"",
[
Parameters
-
Name
required - String -
Code
required - Code -
ArtifactS3Location
required - String -
ArtifactConfig
optional - ArtifactConfig -
Schedule
required - Schedule -
ExecutionRoleArn
required - String -
RuntimeVersion
required - String -
SuccessRetentionPeriod
optional - Integer -
FailureRetentionPeriod
optional - Integer -
Tags
optional - List of Tag -
VPCConfig
optional - VPCConfig -
RunConfig
optional - RunConfig -
StartCanaryAfterCreation
required - Boolean -
VisualReference
optional - VisualReference
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 theiam:CreateRole
,iam:CreatePolicy
andiam: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.