canaries

Creates, updates, deletes or gets a canary resource or lists canaries in a region

Overview

Name	canaries
Type	Resource
Description	Resource Type definition for AWS::Synthetics::Canary
Id	aws.synthetics.canaries

Fields

Name	Datatype	Description
name	string	Name of the canary.
id	string	Id of the canary
state	string	State of the canary
code	object	Provide the canary script source
artifact_s3_location	string	Provide the s3 bucket output location for test results
artifact_config	object	Provide artifact configuration
schedule	object	Frequency to run your canaries
execution_role_arn	string	Lambda Execution role used to run your canaries
runtime_version	string	Runtime version of Synthetics Library
success_retention_period	integer	Retention period of successful canary runs represented in number of days
failure_retention_period	integer	Retention period of failed canary runs represented in number of days
tags	array
vpc_config	object	Provide VPC Configuration if enabled.
run_config	object	Provide canary run configuration
start_canary_after_creation	boolean	Runs canary if set to True. Default is False
visual_reference	object	Visual reference configuration for visual testing
delete_lambda_resources_on_canary_deletion	boolean	Deletes associated lambda resources created by Synthetics if set to True. Default is False
region	string	AWS region.

Methods

Name	Accessible by	Required Params
create_resource	INSERT	Name, Code, ArtifactS3Location, ExecutionRoleArn, Schedule, RuntimeVersion, region
delete_resource	DELETE	data__Identifier, region
update_resource	UPDATE	data__Identifier, data__PatchDocument, region
list_resources	SELECT	region
get_resource	SELECT	data__Identifier, region

SELECT examples

Gets all canaries in a region.

SELECT
region,
name,
id,
state,
code,
artifact_s3_location,
artifact_config,
schedule,
execution_role_arn,
runtime_version,
success_retention_period,
failure_retention_period,
tags,
vpc_config,
run_config,
start_canary_after_creation,
visual_reference,
delete_lambda_resources_on_canary_deletion
FROM aws.synthetics.canaries
WHERE region = 'us-east-1';

Gets all properties from an individual canary.

SELECT
region,
name,
id,
state,
code,
artifact_s3_location,
artifact_config,
schedule,
execution_role_arn,
runtime_version,
success_retention_period,
failure_retention_period,
tags,
vpc_config,
run_config,
start_canary_after_creation,
visual_reference,
delete_lambda_resources_on_canary_deletion
FROM aws.synthetics.canaries
WHERE region = 'us-east-1' AND data__Identifier = '<Name>';

INSERT example

Use the following StackQL query and manifest file to create a new canary resource, using stack-deploy.

Required Properties

/*+ create */
INSERT INTO aws.synthetics.canaries (
 Name,
 Code,
 ArtifactS3Location,
 Schedule,
 ExecutionRoleArn,
 RuntimeVersion,
 region
)
SELECT 
'{{ Name }}',
 '{{ Code }}',
 '{{ ArtifactS3Location }}',
 '{{ Schedule }}',
 '{{ ExecutionRoleArn }}',
 '{{ RuntimeVersion }}',
'{{ region }}';

All Properties

/*+ create */
INSERT INTO aws.synthetics.canaries (
 Name,
 Code,
 ArtifactS3Location,
 ArtifactConfig,
 Schedule,
 ExecutionRoleArn,
 RuntimeVersion,
 SuccessRetentionPeriod,
 FailureRetentionPeriod,
 Tags,
 VPCConfig,
 RunConfig,
 StartCanaryAfterCreation,
 VisualReference,
 DeleteLambdaResourcesOnCanaryDeletion,
 region
)
SELECT 
 '{{ Name }}',
 '{{ Code }}',
 '{{ ArtifactS3Location }}',
 '{{ ArtifactConfig }}',
 '{{ Schedule }}',
 '{{ ExecutionRoleArn }}',
 '{{ RuntimeVersion }}',
 '{{ SuccessRetentionPeriod }}',
 '{{ FailureRetentionPeriod }}',
 '{{ Tags }}',
 '{{ VPCConfig }}',
 '{{ RunConfig }}',
 '{{ StartCanaryAfterCreation }}',
 '{{ VisualReference }}',
 '{{ DeleteLambdaResourcesOnCanaryDeletion }}',
 '{{ region }}';

Manifest

version: 1
name: stack name
description: stack description
providers:
  - aws
globals:
  - name: region
    value: '{{ vars.AWS_REGION }}'
resources:
  - name: canary
    props:
      - name: Name
        value: '{{ Name }}'
      - name: Code
        value:
          S3Bucket: '{{ S3Bucket }}'
          S3Key: '{{ S3Key }}'
          S3ObjectVersion: '{{ S3ObjectVersion }}'
          Script: '{{ Script }}'
          Handler: '{{ Handler }}'
          SourceLocationArn: '{{ SourceLocationArn }}'
      - name: ArtifactS3Location
        value: '{{ ArtifactS3Location }}'
      - name: ArtifactConfig
        value:
          S3Encryption:
            EncryptionMode: '{{ EncryptionMode }}'
            KmsKeyArn: '{{ KmsKeyArn }}'
      - name: Schedule
        value:
          Expression: '{{ Expression }}'
          DurationInSeconds: '{{ DurationInSeconds }}'
      - name: ExecutionRoleArn
        value: '{{ ExecutionRoleArn }}'
      - name: RuntimeVersion
        value: '{{ RuntimeVersion }}'
      - name: SuccessRetentionPeriod
        value: '{{ SuccessRetentionPeriod }}'
      - name: FailureRetentionPeriod
        value: '{{ FailureRetentionPeriod }}'
      - name: Tags
        value:
          - Key: '{{ Key }}'
            Value: '{{ Value }}'
      - name: VPCConfig
        value:
          VpcId: '{{ VpcId }}'
          SubnetIds:
            - '{{ SubnetIds[0] }}'
          SecurityGroupIds:
            - '{{ SecurityGroupIds[0] }}'
      - name: RunConfig
        value:
          TimeoutInSeconds: '{{ TimeoutInSeconds }}'
          MemoryInMB: '{{ MemoryInMB }}'
          ActiveTracing: '{{ ActiveTracing }}'
          EnvironmentVariables: {}
      - name: StartCanaryAfterCreation
        value: '{{ StartCanaryAfterCreation }}'
      - name: VisualReference
        value:
          BaseCanaryRunId: '{{ BaseCanaryRunId }}'
          BaseScreenshots:
            - ScreenshotName: '{{ ScreenshotName }}'
              IgnoreCoordinates:
                - '{{ IgnoreCoordinates[0] }}'
      - name: DeleteLambdaResourcesOnCanaryDeletion
        value: '{{ DeleteLambdaResourcesOnCanaryDeletion }}'

DELETE example

/*+ delete */
DELETE FROM aws.synthetics.canaries
WHERE data__Identifier = '<Name>'
AND region = 'us-east-1';

Permissions

To operate on the canaries resource, the following permissions are required:

Create

synthetics:CreateCanary,
synthetics:StartCanary,
synthetics:GetCanary,
synthetics:TagResource,
s3:CreateBucket,
s3:GetObject,
s3:GetObjectVersion,
s3:PutBucketEncryption,
s3:PutEncryptionConfiguration,
s3:GetBucketLocation,
lambda:CreateFunction,
lambda:AddPermission,
lambda:PublishVersion,
lambda:UpdateFunctionConfiguration,
lambda:GetFunctionConfiguration,
lambda:GetLayerVersionByArn,
lambda:GetLayerVersion,
lambda:PublishLayerVersion,
ec2:DescribeVpcs,
ec2:DescribeSubnets,
ec2:DescribeSecurityGroups,
iam:PassRole

Update

synthetics:UpdateCanary,
synthetics:StartCanary,
synthetics:StopCanary,
synthetics:GetCanary,
synthetics:TagResource,
synthetics:UntagResource,
s3:GetObject,
s3:GetObjectVersion,
s3:PutBucketEncryption,
s3:PutEncryptionConfiguration,
s3:GetBucketLocation,
lambda:AddPermission,
lambda:PublishVersion,
lambda:UpdateFunctionConfiguration,
lambda:GetFunctionConfiguration,
lambda:GetLayerVersionByArn,
lambda:GetLayerVersion,
lambda:PublishLayerVersion,
iam:PassRole

Read

synthetics:GetCanary,
synthetics:DescribeCanaries,
synthetics:ListTagsForResource,
iam:ListRoles,
s3:ListAllMyBuckets,
s3:GetBucketLocation

Delete

synthetics:DeleteCanary,
synthetics:GetCanary

List

synthetics:DescribeCanaries