Get a detailed overview of this resourceList the top 5 use cases for this resourceBuild a program using aws.synthetics.CanaryRepositoryAWS Classic pulumi/pulumi-awsLicenseApache-2.0NotesThis Pulumi package is based on the aws Terraform Provider.

AWS v7.32.0, May 29 26

Viewing docs for AWS v7.32.0

published on Friday, May 29, 2026 by Pulumi

Schema (JSON)

pulumi/pulumi-aws

v7.32.0 (7.x, latest)v6.83.1 (6.x)v5.43.0 (5.x)

aws.synthetics.Canary Anchor

Explore with Neo

Explain this resource Show real-world scenarios Provision a new instance

Viewing docs for AWS v7.32.0

published on Friday, May 29, 2026 by Pulumi

Schema (JSON)

pulumi/pulumi-aws

v7.32.0 (7.x, latest)v6.83.1 (6.x)v5.43.0 (5.x)

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 this provider 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 the AWS Console, or AWS CLI.

Example Usage Anchor

TypeScript
Python
Go
C#
Java
YAML
HCL PREVIEW

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const some = new aws.synthetics.Canary("some", {
    name: "some-canary",
    artifactS3Location: "s3://some-bucket/",
    executionRoleArn: "some-role",
    handler: "exports.handler",
    zipFile: "test-fixtures/lambdatest.zip",
    runtimeVersion: "syn-1.0",
    schedule: {
        expression: "rate(0 minute)",
    },
});

Copy

import pulumi
import pulumi_aws as aws

some = aws.synthetics.Canary("some",
    name="some-canary",
    artifact_s3_location="s3://some-bucket/",
    execution_role_arn="some-role",
    handler="exports.handler",
    zip_file="test-fixtures/lambdatest.zip",
    runtime_version="syn-1.0",
    schedule={
        "expression": "rate(0 minute)",
    })

Copy

package main

import (
    "github.com/pulumi/pulumi-aws/sdk/v7/go/aws/synthetics"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        _, err := synthetics.NewCanary(ctx, "some", &synthetics.CanaryArgs{
            Name:               pulumi.String("some-canary"),
            ArtifactS3Location: pulumi.String("s3://some-bucket/"),
            ExecutionRoleArn:   pulumi.String("some-role"),
            Handler:            pulumi.String("exports.handler"),
            ZipFile:            pulumi.String("test-fixtures/lambdatest.zip"),
            RuntimeVersion:     pulumi.String("syn-1.0"),
            Schedule: &synthetics.CanaryScheduleArgs{
                Expression: pulumi.String("rate(0 minute)"),
            },
        })
        if err != nil {
            return err
        }
        return nil
    })
}

Copy

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;

return await Deployment.RunAsync(() =>
{
    var some = new Aws.Synthetics.Canary("some", new()
    {
        Name = "some-canary",
        ArtifactS3Location = "s3://some-bucket/",
        ExecutionRoleArn = "some-role",
        Handler = "exports.handler",
        ZipFile = "test-fixtures/lambdatest.zip",
        RuntimeVersion = "syn-1.0",
        Schedule = new Aws.Synthetics.Inputs.CanaryScheduleArgs
        {
            Expression = "rate(0 minute)",
        },
    });

});

Copy

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.synthetics.Canary;
import com.pulumi.aws.synthetics.CanaryArgs;
import com.pulumi.aws.synthetics.inputs.CanaryScheduleArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

public static void stack(Context ctx) {
        var some = new Canary("some", CanaryArgs.builder()
            .name("some-canary")
            .artifactS3Location("s3://some-bucket/")
            .executionRoleArn("some-role")
            .handler("exports.handler")
            .zipFile("test-fixtures/lambdatest.zip")
            .runtimeVersion("syn-1.0")
            .schedule(CanaryScheduleArgs.builder()
                .expression("rate(0 minute)")
                .build())
            .build());

}
}

Copy

resources:
  some:
    type: aws:synthetics:Canary
    properties:
      name: some-canary
      artifactS3Location: s3://some-bucket/
      executionRoleArn: some-role
      handler: exports.handler
      zipFile: test-fixtures/lambdatest.zip
      runtimeVersion: syn-1.0
      schedule:
        expression: rate(0 minute)

Copy

pulumi {
  required_providers {
    aws = {
      source = "pulumi/aws"
    }
  }
}

resource "aws_synthetics_canary" "some" {
  name                 = "some-canary"
  artifact_s3_location = "s3://some-bucket/"
  execution_role_arn   = "some-role"
  handler              = "exports.handler"
  zip_file             = "test-fixtures/lambdatest.zip"
  runtime_version      = "syn-1.0"
  schedule = {
    expression = "rate(0 minute)"
  }
}

Copy

Create Canary Resource Anchor

Resources are created with functions called constructors. To learn more about declaring and configuring resources, see Resources.

Constructor syntax Anchor

TypeScript
Python
Go
C#
Java
YAML
HCL PREVIEW

new Canary(name: string, args: CanaryArgs, opts?: CustomResourceOptions);

@overload
def Canary(resource_name: str,
           args: CanaryArgs,
           opts: Optional[ResourceOptions] = None)

@overload
def Canary(resource_name: str,
           opts: Optional[ResourceOptions] = None,
           handler: Optional[str] = None,
           artifact_s3_location: Optional[str] = None,
           schedule: Optional[CanaryScheduleArgs] = None,
           execution_role_arn: Optional[str] = None,
           runtime_version: Optional[str] = None,
           run_config: Optional[CanaryRunConfigArgs] = None,
           s3_version: Optional[str] = None,
           region: Optional[str] = None,
           artifact_config: Optional[CanaryArtifactConfigArgs] = None,
           failure_retention_period: Optional[int] = None,
           s3_bucket: Optional[str] = None,
           s3_key: Optional[str] = None,
           name: Optional[str] = None,
           delete_lambda: Optional[bool] = None,
           start_canary: Optional[bool] = None,
           success_retention_period: Optional[int] = None,
           tags: Optional[Mapping[str, str]] = None,
           vpc_config: Optional[CanaryVpcConfigArgs] = None,
           zip_file: Optional[str] = None)

func NewCanary(ctx *Context, name string, args CanaryArgs, opts ...ResourceOption) (*Canary, error)

public Canary(string name, CanaryArgs args, CustomResourceOptions? opts = null)

public Canary(String name, CanaryArgs args)
public Canary(String name, CanaryArgs args, CustomResourceOptions options)

type: aws:synthetics:Canary
properties: # The arguments to resource properties.
options: # Bag of options to control resource's behavior.

resource "aws_synthetics_canary" "name" {
    # resource properties
}

Parameters Anchor

nameThis property is required.stringThe unique name of the resource.argsThis property is required.CanaryArgsThe arguments to resource properties.optsCustomResourceOptionsBag of options to control resource's behavior.

resource_nameThis property is required.strThe unique name of the resource.argsThis property is required.CanaryArgsThe arguments to resource properties.optsResourceOptionsBag of options to control resource's behavior.

ctxContextContext object for the current deployment.nameThis property is required.stringThe unique name of the resource.argsThis property is required.CanaryArgsThe arguments to resource properties.optsResourceOptionBag of options to control resource's behavior.

nameThis property is required.StringThe unique name of the resource.argsThis property is required.CanaryArgsThe arguments to resource properties.optionsCustomResourceOptionsBag of options to control resource's behavior.

Constructor example Anchor

The following reference example uses placeholder values for all input properties.

TypeScript
Python
Go
C#
Java
YAML
HCL PREVIEW

var canaryResource = new Aws.Synthetics.Canary("canaryResource", new()
{
    Handler = "string",
    ArtifactS3Location = "string",
    Schedule = new Aws.Synthetics.Inputs.CanaryScheduleArgs
    {
        Expression = "string",
        DurationInSeconds = 0,
        RetryConfig = new Aws.Synthetics.Inputs.CanaryScheduleRetryConfigArgs
        {
            MaxRetries = 0,
        },
    },
    ExecutionRoleArn = "string",
    RuntimeVersion = "string",
    RunConfig = new Aws.Synthetics.Inputs.CanaryRunConfigArgs
    {
        ActiveTracing = false,
        EnvironmentVariables =
        {
            { "string", "string" },
        },
        EphemeralStorage = 0,
        MemoryInMb = 0,
        TimeoutInSeconds = 0,
    },
    S3Version = "string",
    Region = "string",
    ArtifactConfig = new Aws.Synthetics.Inputs.CanaryArtifactConfigArgs
    {
        S3Encryption = new Aws.Synthetics.Inputs.CanaryArtifactConfigS3EncryptionArgs
        {
            EncryptionMode = "string",
            KmsKeyArn = "string",
        },
    },
    FailureRetentionPeriod = 0,
    S3Bucket = "string",
    S3Key = "string",
    Name = "string",
    DeleteLambda = false,
    StartCanary = false,
    SuccessRetentionPeriod = 0,
    Tags =
    {
        { "string", "string" },
    },
    VpcConfig = new Aws.Synthetics.Inputs.CanaryVpcConfigArgs
    {
        Ipv6AllowedForDualStack = false,
        SecurityGroupIds = new[]
        {
            "string",
        },
        SubnetIds = new[]
        {
            "string",
        },
        VpcId = "string",
    },
    ZipFile = "string",
});

Copy

example, err := synthetics.NewCanary(ctx, "canaryResource", &synthetics.CanaryArgs{
    Handler:            pulumi.String("string"),
    ArtifactS3Location: pulumi.String("string"),
    Schedule: &synthetics.CanaryScheduleArgs{
        Expression:        pulumi.String("string"),
        DurationInSeconds: pulumi.Int(0),
        RetryConfig: &synthetics.CanaryScheduleRetryConfigArgs{
            MaxRetries: pulumi.Int(0),
        },
    },
    ExecutionRoleArn: pulumi.String("string"),
    RuntimeVersion:   pulumi.String("string"),
    RunConfig: &synthetics.CanaryRunConfigArgs{
        ActiveTracing: pulumi.Bool(false),
        EnvironmentVariables: pulumi.StringMap{
            "string": pulumi.String("string"),
        },
        EphemeralStorage: pulumi.Int(0),
        MemoryInMb:       pulumi.Int(0),
        TimeoutInSeconds: pulumi.Int(0),
    },
    S3Version: pulumi.String("string"),
    Region:    pulumi.String("string"),
    ArtifactConfig: &synthetics.CanaryArtifactConfigArgs{
        S3Encryption: &synthetics.CanaryArtifactConfigS3EncryptionArgs{
            EncryptionMode: pulumi.String("string"),
            KmsKeyArn:      pulumi.String("string"),
        },
    },
    FailureRetentionPeriod: pulumi.Int(0),
    S3Bucket:               pulumi.String("string"),
    S3Key:                  pulumi.String("string"),
    Name:                   pulumi.String("string"),
    DeleteLambda:           pulumi.Bool(false),
    StartCanary:            pulumi.Bool(false),
    SuccessRetentionPeriod: pulumi.Int(0),
    Tags: pulumi.StringMap{
        "string": pulumi.String("string"),
    },
    VpcConfig: &synthetics.CanaryVpcConfigArgs{
        Ipv6AllowedForDualStack: pulumi.Bool(false),
        SecurityGroupIds: pulumi.StringArray{
            pulumi.String("string"),
        },
        SubnetIds: pulumi.StringArray{
            pulumi.String("string"),
        },
        VpcId: pulumi.String("string"),
    },
    ZipFile: pulumi.String("string"),
})

Copy

resource "aws_synthetics_canary" "canaryResource" {
  handler              = "string"
  artifact_s3_location = "string"
  schedule = {
    expression          = "string"
    duration_in_seconds = 0
    retry_config = {
      max_retries = 0
    }
  }
  execution_role_arn = "string"
  runtime_version    = "string"
  run_config = {
    active_tracing = false
    environment_variables = {
      "string" = "string"
    }
    ephemeral_storage  = 0
    memory_in_mb       = 0
    timeout_in_seconds = 0
  }
  s3_version = "string"
  region     = "string"
  artifact_config = {
    s3_encryption = {
      encryption_mode = "string"
      kms_key_arn     = "string"
    }
  }
  failure_retention_period = 0
  s3_bucket                = "string"
  s3_key                   = "string"
  name                     = "string"
  delete_lambda            = false
  start_canary             = false
  success_retention_period = 0
  tags = {
    "string" = "string"
  }
  vpc_config = {
    ipv6_allowed_for_dual_stack = false
    security_group_ids          = ["string"]
    subnet_ids                  = ["string"]
    vpc_id                      = "string"
  }
  zip_file = "string"
}

Copy

var canaryResource = new Canary("canaryResource", CanaryArgs.builder()
    .handler("string")
    .artifactS3Location("string")
    .schedule(CanaryScheduleArgs.builder()
        .expression("string")
        .durationInSeconds(0)
        .retryConfig(CanaryScheduleRetryConfigArgs.builder()
            .maxRetries(0)
            .build())
        .build())
    .executionRoleArn("string")
    .runtimeVersion("string")
    .runConfig(CanaryRunConfigArgs.builder()
        .activeTracing(false)
        .environmentVariables(Map.of("string", "string"))
        .ephemeralStorage(0)
        .memoryInMb(0)
        .timeoutInSeconds(0)
        .build())
    .s3Version("string")
    .region("string")
    .artifactConfig(CanaryArtifactConfigArgs.builder()
        .s3Encryption(CanaryArtifactConfigS3EncryptionArgs.builder()
            .encryptionMode("string")
            .kmsKeyArn("string")
            .build())
        .build())
    .failureRetentionPeriod(0)
    .s3Bucket("string")
    .s3Key("string")
    .name("string")
    .deleteLambda(false)
    .startCanary(false)
    .successRetentionPeriod(0)
    .tags(Map.of("string", "string"))
    .vpcConfig(CanaryVpcConfigArgs.builder()
        .ipv6AllowedForDualStack(false)
        .securityGroupIds("string")
        .subnetIds("string")
        .vpcId("string")
        .build())
    .zipFile("string")
    .build());

Copy

canary_resource = aws.synthetics.Canary("canaryResource",
    handler="string",
    artifact_s3_location="string",
    schedule={
        "expression": "string",
        "duration_in_seconds": 0,
        "retry_config": {
            "max_retries": 0,
        },
    },
    execution_role_arn="string",
    runtime_version="string",
    run_config={
        "active_tracing": False,
        "environment_variables": {
            "string": "string",
        },
        "ephemeral_storage": 0,
        "memory_in_mb": 0,
        "timeout_in_seconds": 0,
    },
    s3_version="string",
    region="string",
    artifact_config={
        "s3_encryption": {
            "encryption_mode": "string",
            "kms_key_arn": "string",
        },
    },
    failure_retention_period=0,
    s3_bucket="string",
    s3_key="string",
    name="string",
    delete_lambda=False,
    start_canary=False,
    success_retention_period=0,
    tags={
        "string": "string",
    },
    vpc_config={
        "ipv6_allowed_for_dual_stack": False,
        "security_group_ids": ["string"],
        "subnet_ids": ["string"],
        "vpc_id": "string",
    },
    zip_file="string")

Copy

const canaryResource = new aws.synthetics.Canary("canaryResource", {
    handler: "string",
    artifactS3Location: "string",
    schedule: {
        expression: "string",
        durationInSeconds: 0,
        retryConfig: {
            maxRetries: 0,
        },
    },
    executionRoleArn: "string",
    runtimeVersion: "string",
    runConfig: {
        activeTracing: false,
        environmentVariables: {
            string: "string",
        },
        ephemeralStorage: 0,
        memoryInMb: 0,
        timeoutInSeconds: 0,
    },
    s3Version: "string",
    region: "string",
    artifactConfig: {
        s3Encryption: {
            encryptionMode: "string",
            kmsKeyArn: "string",
        },
    },
    failureRetentionPeriod: 0,
    s3Bucket: "string",
    s3Key: "string",
    name: "string",
    deleteLambda: false,
    startCanary: false,
    successRetentionPeriod: 0,
    tags: {
        string: "string",
    },
    vpcConfig: {
        ipv6AllowedForDualStack: false,
        securityGroupIds: ["string"],
        subnetIds: ["string"],
        vpcId: "string",
    },
    zipFile: "string",
});

Copy

type: aws:synthetics:Canary
properties:
    artifactConfig:
        s3Encryption:
            encryptionMode: string
            kmsKeyArn: string
    artifactS3Location: string
    deleteLambda: false
    executionRoleArn: string
    failureRetentionPeriod: 0
    handler: string
    name: string
    region: string
    runConfig:
        activeTracing: false
        environmentVariables:
            string: string
        ephemeralStorage: 0
        memoryInMb: 0
        timeoutInSeconds: 0
    runtimeVersion: string
    s3Bucket: string
    s3Key: string
    s3Version: string
    schedule:
        durationInSeconds: 0
        expression: string
        retryConfig:
            maxRetries: 0
    startCanary: false
    successRetentionPeriod: 0
    tags:
        string: string
    vpcConfig:
        ipv6AllowedForDualStack: false
        securityGroupIds:
            - string
        subnetIds:
            - string
        vpcId: string
    zipFile: string

Copy

Canary Resource Properties Anchor

To learn more about resource properties and how to use them, see Inputs and Outputs in the Architecture and Concepts docs.

Inputs Anchor

In Python, inputs that are objects can be passed either as argument classes or as dictionary literals.

The Canary resource accepts the following input properties:

ArtifactS3LocationThis property is required.stringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.ExecutionRoleArnThis property is required.stringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.HandlerThis property is required.stringEntry point to use for the source code when running the canary. This value must end with the string .handler .RuntimeVersionThis property is required.stringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.ScheduleThis property is required.CanarySchedule

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:

ArtifactConfig CanaryArtifactConfigconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.DeleteLambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.FailureRetentionPeriodintNumber 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.NameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.RegionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.RunConfig CanaryRunConfigConfiguration block for individual canary runs. Detailed below.S3BucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.S3KeystringS3 key of your script. Conflicts with zipFile.S3VersionstringS3 version ID of your script. Conflicts with zipFile.StartCanaryboolWhether to run or stop the canary.SuccessRetentionPeriodintNumber 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.TagsDictionary<string, string>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.VpcConfig CanaryVpcConfigConfiguration block. Detailed below.ZipFilestringZIP 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.

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:

ArtifactConfig CanaryArtifactConfigArgsconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.DeleteLambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.FailureRetentionPeriodintNumber 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.NameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.RegionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.RunConfig CanaryRunConfigArgsConfiguration block for individual canary runs. Detailed below.S3BucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.S3KeystringS3 key of your script. Conflicts with zipFile.S3VersionstringS3 version ID of your script. Conflicts with zipFile.StartCanaryboolWhether to run or stop the canary.SuccessRetentionPeriodintNumber 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.Tagsmap[string]stringKey-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.VpcConfig CanaryVpcConfigArgsConfiguration block. Detailed below.ZipFilestringZIP 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.

artifact_s3_locationThis property is required.stringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.execution_role_arnThis property is required.stringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.handlerThis property is required.stringEntry point to use for the source code when running the canary. This value must end with the string .handler .runtime_versionThis property is required.stringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.scheduleThis property is required.object

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:

artifact_config objectconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.delete_lambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.failure_retention_periodnumberNumber 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.nameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.run_config objectConfiguration block for individual canary runs. Detailed below.s3_bucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3_keystringS3 key of your script. Conflicts with zipFile.s3_versionstringS3 version ID of your script. Conflicts with zipFile.start_canaryboolWhether to run or stop the canary.success_retention_periodnumberNumber 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.tagsmap(string)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.vpc_config objectConfiguration block. Detailed below.zip_filestringZIP 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.

artifactS3LocationThis property is required.StringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.executionRoleArnThis property is required.StringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.handlerThis property is required.StringEntry point to use for the source code when running the canary. This value must end with the string .handler .runtimeVersionThis property is required.StringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.scheduleThis property is required.CanarySchedule

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:

artifactConfig CanaryArtifactConfigconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.deleteLambdaBooleanSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.failureRetentionPeriodIntegerNumber 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.nameChanges to this property will trigger replacement.StringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionStringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.runConfig CanaryRunConfigConfiguration block for individual canary runs. Detailed below.s3BucketStringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3KeyStringS3 key of your script. Conflicts with zipFile.s3VersionStringS3 version ID of your script. Conflicts with zipFile.startCanaryBooleanWhether to run or stop the canary.successRetentionPeriodIntegerNumber 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.tagsMap<String,String>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.vpcConfig CanaryVpcConfigConfiguration block. Detailed below.zipFileStringZIP 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.

artifactS3LocationThis property is required.stringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.executionRoleArnThis property is required.stringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.handlerThis property is required.stringEntry point to use for the source code when running the canary. This value must end with the string .handler .runtimeVersionThis property is required.stringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.scheduleThis property is required.CanarySchedule

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:

artifactConfig CanaryArtifactConfigconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.deleteLambdabooleanSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.failureRetentionPeriodnumberNumber 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.nameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.runConfig CanaryRunConfigConfiguration block for individual canary runs. Detailed below.s3BucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3KeystringS3 key of your script. Conflicts with zipFile.s3VersionstringS3 version ID of your script. Conflicts with zipFile.startCanarybooleanWhether to run or stop the canary.successRetentionPeriodnumberNumber 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{[key: string]: string}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.vpcConfig CanaryVpcConfigConfiguration block. Detailed below.zipFilestringZIP 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.

artifact_s3_locationThis property is required.strLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.execution_role_arnThis property is required.strARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.handlerThis property is required.strEntry point to use for the source code when running the canary. This value must end with the string .handler .runtime_versionThis property is required.strRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.scheduleThis property is required.CanaryScheduleArgs

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:

artifact_config CanaryArtifactConfigArgsconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.delete_lambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.failure_retention_periodintNumber 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.nameChanges to this property will trigger replacement.strName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionstrRegion where this resource will be managed. Defaults to the Region set in the provider configuration.run_config CanaryRunConfigArgsConfiguration block for individual canary runs. Detailed below.s3_bucketstrFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3_keystrS3 key of your script. Conflicts with zipFile.s3_versionstrS3 version ID of your script. Conflicts with zipFile.start_canaryboolWhether to run or stop the canary.success_retention_periodintNumber 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.tagsMapping[str, str]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.vpc_config CanaryVpcConfigArgsConfiguration block. Detailed below.zip_filestrZIP 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.

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:

artifactConfig Property Mapconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.deleteLambdaBooleanSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.failureRetentionPeriodNumberNumber 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.nameChanges to this property will trigger replacement.StringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionStringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.runConfig Property MapConfiguration block for individual canary runs. Detailed below.s3BucketStringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3KeyStringS3 key of your script. Conflicts with zipFile.s3VersionStringS3 version ID of your script. Conflicts with zipFile.startCanaryBooleanWhether to run or stop the canary.successRetentionPeriodNumberNumber 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.tagsMapKey-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.vpcConfig Property MapConfiguration block. Detailed below.zipFileStringZIP 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.

Outputs Anchor

All input properties are implicitly available as output properties. Additionally, the Canary resource produces the following output properties:

ArnstringAmazon Resource Name (ARN) of the Canary.EngineArnstringARN of the Lambda function that is used as your canary's engine.IdstringThe provider-assigned unique ID for this managed resource.SourceLocationArnstringARN of the Lambda layer where Synthetics stores the canary script code.StatusstringCanary status.TagsAllDictionary<string, string>A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.Timelines ListStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.

ArnstringAmazon Resource Name (ARN) of the Canary.EngineArnstringARN of the Lambda function that is used as your canary's engine.IdstringThe provider-assigned unique ID for this managed resource.SourceLocationArnstringARN of the Lambda layer where Synthetics stores the canary script code.StatusstringCanary status.TagsAllmap[string]stringA map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.Timelines []CanaryTimelineStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.

arnstringAmazon Resource Name (ARN) of the Canary.engine_arnstringARN of the Lambda function that is used as your canary's engine.idstringThe provider-assigned unique ID for this managed resource.source_location_arnstringARN of the Lambda layer where Synthetics stores the canary script code.statusstringCanary status.tags_allmap(string)A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines list(object)Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.

arnStringAmazon Resource Name (ARN) of the Canary.engineArnStringARN of the Lambda function that is used as your canary's engine.idStringThe provider-assigned unique ID for this managed resource.sourceLocationArnStringARN of the Lambda layer where Synthetics stores the canary script code.statusStringCanary status.tagsAllMap<String,String>A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines ListStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.

arnstringAmazon Resource Name (ARN) of the Canary.engineArnstringARN of the Lambda function that is used as your canary's engine.idstringThe provider-assigned unique ID for this managed resource.sourceLocationArnstringARN of the Lambda layer where Synthetics stores the canary script code.statusstringCanary status.tagsAll{[key: string]: string}A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines CanaryTimeline[]Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.

arnstrAmazon Resource Name (ARN) of the Canary.engine_arnstrARN of the Lambda function that is used as your canary's engine.idstrThe provider-assigned unique ID for this managed resource.source_location_arnstrARN of the Lambda layer where Synthetics stores the canary script code.statusstrCanary status.tags_allMapping[str, str]A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines Sequence[CanaryTimeline]Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.

arnStringAmazon Resource Name (ARN) of the Canary.engineArnStringARN of the Lambda function that is used as your canary's engine.idStringThe provider-assigned unique ID for this managed resource.sourceLocationArnStringARN of the Lambda layer where Synthetics stores the canary script code.statusStringCanary status.tagsAllMapA map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines ListStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.

Look up Existing Canary Resource Anchor

Get an existing Canary resource’s state with the given name, ID, and optional extra properties used to qualify the lookup.

TypeScript
Python
Go
C#
Java
YAML
HCL PREVIEW

public static get(name: string, id: Input<ID>, state?: CanaryState, opts?: CustomResourceOptions): Canary

@staticmethod
def get(resource_name: str,
        id: str,
        opts: Optional[ResourceOptions] = None,
        arn: Optional[str] = None,
        artifact_config: Optional[CanaryArtifactConfigArgs] = None,
        artifact_s3_location: Optional[str] = None,
        delete_lambda: Optional[bool] = None,
        engine_arn: Optional[str] = None,
        execution_role_arn: Optional[str] = None,
        failure_retention_period: Optional[int] = None,
        handler: Optional[str] = None,
        name: Optional[str] = None,
        region: Optional[str] = None,
        run_config: Optional[CanaryRunConfigArgs] = None,
        runtime_version: Optional[str] = None,
        s3_bucket: Optional[str] = None,
        s3_key: Optional[str] = None,
        s3_version: Optional[str] = None,
        schedule: Optional[CanaryScheduleArgs] = None,
        source_location_arn: Optional[str] = None,
        start_canary: Optional[bool] = None,
        status: Optional[str] = None,
        success_retention_period: Optional[int] = None,
        tags: Optional[Mapping[str, str]] = None,
        tags_all: Optional[Mapping[str, str]] = None,
        timelines: Optional[Sequence[CanaryTimelineArgs]] = None,
        vpc_config: Optional[CanaryVpcConfigArgs] = None,
        zip_file: Optional[str] = None) -> Canary

func GetCanary(ctx *Context, name string, id IDInput, state *CanaryState, opts ...ResourceOption) (*Canary, error)

public static Canary Get(string name, Input<string> id, CanaryState? state, CustomResourceOptions? opts = null)

public static Canary get(String name, Output<String> id, CanaryState state, CustomResourceOptions options)

resources:  _:    type: aws:synthetics:Canary    get:      id: ${id}

import {
  to = aws_synthetics_canary.example
  id = "${id}"
}

nameThis property is required.The unique name of the resulting resource.idThis property is required.The unique provider ID of the resource to lookup.stateAny extra arguments used during the lookup.optsA bag of options that control this resource's behavior.

resource_nameThis property is required.The unique name of the resulting resource.idThis property is required.The unique provider ID of the resource to lookup.

The following state arguments are supported:

ArnstringAmazon Resource Name (ARN) of the Canary.ArtifactConfig CanaryArtifactConfigconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.ArtifactS3LocationstringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.DeleteLambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.EngineArnstringARN of the Lambda function that is used as your canary's engine.ExecutionRoleArnstringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.FailureRetentionPeriodintNumber 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.HandlerstringEntry point to use for the source code when running the canary. This value must end with the string .handler .NameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.RegionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.RunConfig CanaryRunConfigConfiguration block for individual canary runs. Detailed below.RuntimeVersionstringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.S3BucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.S3KeystringS3 key of your script. Conflicts with zipFile.S3VersionstringS3 version ID of your script. Conflicts with zipFile.Schedule CanarySchedule

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:

SourceLocationArnstringARN of the Lambda layer where Synthetics stores the canary script code.StartCanaryboolWhether to run or stop the canary.StatusstringCanary status.SuccessRetentionPeriodintNumber 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.TagsDictionary<string, string>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.TagsAllDictionary<string, string>A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.Timelines ListStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.VpcConfig CanaryVpcConfigConfiguration block. Detailed below.ZipFilestringZIP 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.

ArnstringAmazon Resource Name (ARN) of the Canary.ArtifactConfig CanaryArtifactConfigArgsconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.ArtifactS3LocationstringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.DeleteLambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.EngineArnstringARN of the Lambda function that is used as your canary's engine.ExecutionRoleArnstringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.FailureRetentionPeriodintNumber 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.HandlerstringEntry point to use for the source code when running the canary. This value must end with the string .handler .NameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.RegionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.RunConfig CanaryRunConfigArgsConfiguration block for individual canary runs. Detailed below.RuntimeVersionstringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.S3BucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.S3KeystringS3 key of your script. Conflicts with zipFile.S3VersionstringS3 version ID of your script. Conflicts with zipFile.Schedule CanaryScheduleArgs

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:

SourceLocationArnstringARN of the Lambda layer where Synthetics stores the canary script code.StartCanaryboolWhether to run or stop the canary.StatusstringCanary status.SuccessRetentionPeriodintNumber 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.Tagsmap[string]stringKey-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.TagsAllmap[string]stringA map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.Timelines []CanaryTimelineArgsStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.VpcConfig CanaryVpcConfigArgsConfiguration block. Detailed below.ZipFilestringZIP 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.

arnstringAmazon Resource Name (ARN) of the Canary.artifact_config objectconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.artifact_s3_locationstringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.delete_lambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.engine_arnstringARN of the Lambda function that is used as your canary's engine.execution_role_arnstringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.failure_retention_periodnumberNumber 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.handlerstringEntry point to use for the source code when running the canary. This value must end with the string .handler .nameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.run_config objectConfiguration block for individual canary runs. Detailed below.runtime_versionstringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.s3_bucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3_keystringS3 key of your script. Conflicts with zipFile.s3_versionstringS3 version ID of your script. Conflicts with zipFile.schedule object

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:

source_location_arnstringARN of the Lambda layer where Synthetics stores the canary script code.start_canaryboolWhether to run or stop the canary.statusstringCanary status.success_retention_periodnumberNumber 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.tagsmap(string)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.tags_allmap(string)A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines list(object)Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.vpc_config objectConfiguration block. Detailed below.zip_filestringZIP 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.

arnStringAmazon Resource Name (ARN) of the Canary.artifactConfig CanaryArtifactConfigconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.artifactS3LocationStringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.deleteLambdaBooleanSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.engineArnStringARN of the Lambda function that is used as your canary's engine.executionRoleArnStringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.failureRetentionPeriodIntegerNumber 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.handlerStringEntry point to use for the source code when running the canary. This value must end with the string .handler .nameChanges to this property will trigger replacement.StringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionStringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.runConfig CanaryRunConfigConfiguration block for individual canary runs. Detailed below.runtimeVersionStringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.s3BucketStringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3KeyStringS3 key of your script. Conflicts with zipFile.s3VersionStringS3 version ID of your script. Conflicts with zipFile.schedule CanarySchedule

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:

sourceLocationArnStringARN of the Lambda layer where Synthetics stores the canary script code.startCanaryBooleanWhether to run or stop the canary.statusStringCanary status.successRetentionPeriodIntegerNumber 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.tagsMap<String,String>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.tagsAllMap<String,String>A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines ListStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.vpcConfig CanaryVpcConfigConfiguration block. Detailed below.zipFileStringZIP 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.

arnstringAmazon Resource Name (ARN) of the Canary.artifactConfig CanaryArtifactConfigconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.artifactS3LocationstringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.deleteLambdabooleanSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.engineArnstringARN of the Lambda function that is used as your canary's engine.executionRoleArnstringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.failureRetentionPeriodnumberNumber 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.handlerstringEntry point to use for the source code when running the canary. This value must end with the string .handler .nameChanges to this property will trigger replacement.stringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionstringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.runConfig CanaryRunConfigConfiguration block for individual canary runs. Detailed below.runtimeVersionstringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.s3BucketstringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3KeystringS3 key of your script. Conflicts with zipFile.s3VersionstringS3 version ID of your script. Conflicts with zipFile.schedule CanarySchedule

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:

sourceLocationArnstringARN of the Lambda layer where Synthetics stores the canary script code.startCanarybooleanWhether to run or stop the canary.statusstringCanary status.successRetentionPeriodnumberNumber 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{[key: string]: string}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.tagsAll{[key: string]: string}A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines CanaryTimeline[]Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.vpcConfig CanaryVpcConfigConfiguration block. Detailed below.zipFilestringZIP 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.

arnstrAmazon Resource Name (ARN) of the Canary.artifact_config CanaryArtifactConfigArgsconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.artifact_s3_locationstrLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.delete_lambdaboolSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.engine_arnstrARN of the Lambda function that is used as your canary's engine.execution_role_arnstrARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.failure_retention_periodintNumber 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.handlerstrEntry point to use for the source code when running the canary. This value must end with the string .handler .nameChanges to this property will trigger replacement.strName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionstrRegion where this resource will be managed. Defaults to the Region set in the provider configuration.run_config CanaryRunConfigArgsConfiguration block for individual canary runs. Detailed below.runtime_versionstrRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.s3_bucketstrFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3_keystrS3 key of your script. Conflicts with zipFile.s3_versionstrS3 version ID of your script. Conflicts with zipFile.schedule CanaryScheduleArgs

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:

source_location_arnstrARN of the Lambda layer where Synthetics stores the canary script code.start_canaryboolWhether to run or stop the canary.statusstrCanary status.success_retention_periodintNumber 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.tagsMapping[str, str]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.tags_allMapping[str, str]A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines Sequence[CanaryTimelineArgs]Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.vpc_config CanaryVpcConfigArgsConfiguration block. Detailed below.zip_filestrZIP 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.

arnStringAmazon Resource Name (ARN) of the Canary.artifactConfig Property Mapconfiguration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.artifactS3LocationStringLocation in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.deleteLambdaBooleanSpecifies whether to also delete the Lambda functions and layers used by this canary. The default is false.engineArnStringARN of the Lambda function that is used as your canary's engine.executionRoleArnStringARN of the IAM role to be used to run the canary. see AWS Docs for permissions needs for IAM Role.failureRetentionPeriodNumberNumber 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.handlerStringEntry point to use for the source code when running the canary. This value must end with the string .handler .nameChanges to this property will trigger replacement.StringName for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.regionStringRegion where this resource will be managed. Defaults to the Region set in the provider configuration.runConfig Property MapConfiguration block for individual canary runs. Detailed below.runtimeVersionStringRuntime version to use for the canary. Versions change often so consult the Amazon CloudWatch documentation for the latest valid versions. Values include syn-python-selenium-1.0, syn-nodejs-puppeteer-3.0, syn-nodejs-2.2, syn-nodejs-2.1, syn-nodejs-2.0, and syn-1.0.s3BucketStringFull bucket name which is used if your canary script is located in S3. The bucket must already exist. Conflicts with zipFile.s3KeyStringS3 key of your script. Conflicts with zipFile.s3VersionStringS3 version ID of your script. Conflicts with zipFile.schedule Property Map

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:

sourceLocationArnStringARN of the Lambda layer where Synthetics stores the canary script code.startCanaryBooleanWhether to run or stop the canary.statusStringCanary status.successRetentionPeriodNumberNumber 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.tagsMapKey-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.tagsAllMapA map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.timelines ListStructure that contains information about when the canary was created, modified, and most recently run. see Timeline.vpcConfig Property MapConfiguration block. Detailed below.zipFileStringZIP 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.

Supporting Types Anchor

CanaryArtifactConfig , CanaryArtifactConfigArgs Anchor

S3Encryption CanaryArtifactConfigS3EncryptionConfiguration of the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See S3 Encryption.

s3_encryption objectConfiguration of the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See S3 Encryption.

s3Encryption CanaryArtifactConfigS3EncryptionConfiguration of the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See S3 Encryption.

s3_encryption CanaryArtifactConfigS3EncryptionConfiguration of the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See S3 Encryption.

s3Encryption Property MapConfiguration of the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See S3 Encryption.

CanaryArtifactConfigS3Encryption , CanaryArtifactConfigS3EncryptionArgs Anchor

EncryptionModestringThe encryption method to use for artifacts created by this canary. Valid values are: SSE_S3 and SSE_KMS.KmsKeyArnstringThe ARN of the customer-managed KMS key to use, if you specify SSE_KMS for encryptionMode.

encryption_modestringThe encryption method to use for artifacts created by this canary. Valid values are: SSE_S3 and SSE_KMS.kms_key_arnstringThe ARN of the customer-managed KMS key to use, if you specify SSE_KMS for encryptionMode.

encryptionModeStringThe encryption method to use for artifacts created by this canary. Valid values are: SSE_S3 and SSE_KMS.kmsKeyArnStringThe ARN of the customer-managed KMS key to use, if you specify SSE_KMS for encryptionMode.

encryptionModestringThe encryption method to use for artifacts created by this canary. Valid values are: SSE_S3 and SSE_KMS.kmsKeyArnstringThe ARN of the customer-managed KMS key to use, if you specify SSE_KMS for encryptionMode.

encryption_modestrThe encryption method to use for artifacts created by this canary. Valid values are: SSE_S3 and SSE_KMS.kms_key_arnstrThe ARN of the customer-managed KMS key to use, if you specify SSE_KMS for encryptionMode.

CanaryRunConfig , CanaryRunConfigArgs Anchor

ActiveTracingboolWhether 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.EnvironmentVariablesDictionary<string, string>Map of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.EphemeralStorageintAmount of ephemeral storage (in MB) allocated for the canary run during execution. Defaults to 1024.MemoryInMbintMaximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.TimeoutInSecondsintNumber 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).

ActiveTracingboolWhether 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.EnvironmentVariablesmap[string]stringMap of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.EphemeralStorageintAmount of ephemeral storage (in MB) allocated for the canary run during execution. Defaults to 1024.MemoryInMbintMaximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.TimeoutInSecondsintNumber 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).

active_tracingboolWhether 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.environment_variablesmap(string)Map of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.ephemeral_storagenumberAmount of ephemeral storage (in MB) allocated for the canary run during execution. Defaults to 1024.memory_in_mbnumberMaximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.timeout_in_secondsnumberNumber 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).

activeTracingBooleanWhether 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.environmentVariablesMap<String,String>Map of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.ephemeralStorageIntegerAmount of ephemeral storage (in MB) allocated for the canary run during execution. Defaults to 1024.memoryInMbIntegerMaximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.timeoutInSecondsIntegerNumber 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).

activeTracingbooleanWhether 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{[key: string]: string}Map of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.ephemeralStoragenumberAmount of ephemeral storage (in MB) allocated for the canary run during execution. Defaults to 1024.memoryInMbnumberMaximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.timeoutInSecondsnumberNumber 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).

active_tracingboolWhether 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.environment_variablesMapping[str, str]Map of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.ephemeral_storageintAmount of ephemeral storage (in MB) allocated for the canary run during execution. Defaults to 1024.memory_in_mbintMaximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.timeout_in_secondsintNumber 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).

activeTracingBooleanWhether 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.environmentVariablesMapMap of environment variables that are accessible from the canary during execution. Please see AWS Docs for variables reserved for Lambda.ephemeralStorageNumberAmount of ephemeral storage (in MB) allocated for the canary run during execution. Defaults to 1024.memoryInMbNumberMaximum amount of memory available to the canary while it is running, in MB. The value you specify must be a multiple of 64.timeoutInSecondsNumberNumber 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).

CanarySchedule , CanaryScheduleArgs Anchor

ExpressionThis property is required.stringRate expression or cron expression that defines how often the canary is to run. For rate expression, the syntax is rate(number unit). 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.DurationInSecondsintDuration in seconds, for the canary to continue making regular runs according to the schedule in the Expression value.RetryConfig CanaryScheduleRetryConfigConfiguration block for canary retries. Detailed below.

expressionThis property is required.stringRate expression or cron expression that defines how often the canary is to run. For rate expression, the syntax is rate(number unit). 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.duration_in_secondsnumberDuration in seconds, for the canary to continue making regular runs according to the schedule in the Expression value.retry_config objectConfiguration block for canary retries. Detailed below.

expressionThis property is required.StringRate expression or cron expression that defines how often the canary is to run. For rate expression, the syntax is rate(number unit). 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.durationInSecondsIntegerDuration in seconds, for the canary to continue making regular runs according to the schedule in the Expression value.retryConfig CanaryScheduleRetryConfigConfiguration block for canary retries. Detailed below.

expressionThis property is required.stringRate expression or cron expression that defines how often the canary is to run. For rate expression, the syntax is rate(number unit). 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.durationInSecondsnumberDuration in seconds, for the canary to continue making regular runs according to the schedule in the Expression value.retryConfig CanaryScheduleRetryConfigConfiguration block for canary retries. Detailed below.

expressionThis property is required.strRate expression or cron expression that defines how often the canary is to run. For rate expression, the syntax is rate(number unit). 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.duration_in_secondsintDuration in seconds, for the canary to continue making regular runs according to the schedule in the Expression value.retry_config CanaryScheduleRetryConfigConfiguration block for canary retries. Detailed below.

expressionThis property is required.StringRate expression or cron expression that defines how often the canary is to run. For rate expression, the syntax is rate(number unit). 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.durationInSecondsNumberDuration in seconds, for the canary to continue making regular runs according to the schedule in the Expression value.retryConfig Property MapConfiguration block for canary retries. Detailed below.

CanaryScheduleRetryConfig , CanaryScheduleRetryConfigArgs Anchor

MaxRetriesThis property is required.intMaximum number of retries. The value must be less than or equal to 2. If maxRetries is 2, run_config.timeout_in_seconds should be less than 600 seconds. Defaults to 0.

max_retriesThis property is required.numberMaximum number of retries. The value must be less than or equal to 2. If maxRetries is 2, run_config.timeout_in_seconds should be less than 600 seconds. Defaults to 0.

maxRetriesThis property is required.IntegerMaximum number of retries. The value must be less than or equal to 2. If maxRetries is 2, run_config.timeout_in_seconds should be less than 600 seconds. Defaults to 0.

maxRetriesThis property is required.numberMaximum number of retries. The value must be less than or equal to 2. If maxRetries is 2, run_config.timeout_in_seconds should be less than 600 seconds. Defaults to 0.

max_retriesThis property is required.intMaximum number of retries. The value must be less than or equal to 2. If maxRetries is 2, run_config.timeout_in_seconds should be less than 600 seconds. Defaults to 0.

maxRetriesThis property is required.NumberMaximum number of retries. The value must be less than or equal to 2. If maxRetries is 2, run_config.timeout_in_seconds should be less than 600 seconds. Defaults to 0.

CanaryTimeline , CanaryTimelineArgs Anchor

CreatedstringDate and time the canary was created.LastModifiedstringDate and time the canary was most recently modified.LastStartedstringDate and time that the canary's most recent run started.LastStoppedstringDate and time that the canary's most recent run ended.

createdstringDate and time the canary was created.last_modifiedstringDate and time the canary was most recently modified.last_startedstringDate and time that the canary's most recent run started.last_stoppedstringDate and time that the canary's most recent run ended.

createdStringDate and time the canary was created.lastModifiedStringDate and time the canary was most recently modified.lastStartedStringDate and time that the canary's most recent run started.lastStoppedStringDate and time that the canary's most recent run ended.

createdstringDate and time the canary was created.lastModifiedstringDate and time the canary was most recently modified.lastStartedstringDate and time that the canary's most recent run started.lastStoppedstringDate and time that the canary's most recent run ended.

createdstrDate and time the canary was created.last_modifiedstrDate and time the canary was most recently modified.last_startedstrDate and time that the canary's most recent run started.last_stoppedstrDate and time that the canary's most recent run ended.

CanaryVpcConfig , CanaryVpcConfigArgs Anchor

Ipv6AllowedForDualStackboolIf true, allow outbound IPv6 traffic on VPC canaries that are connected to dual-stack subnets. The default is false.SecurityGroupIdsListIDs of the security groups for this canary.SubnetIdsListIDs of the subnets where this canary is to run.VpcIdstringID of the VPC where this canary is to run.

Ipv6AllowedForDualStackboolIf true, allow outbound IPv6 traffic on VPC canaries that are connected to dual-stack subnets. The default is false.SecurityGroupIds[]stringIDs of the security groups for this canary.SubnetIds[]stringIDs of the subnets where this canary is to run.VpcIdstringID of the VPC where this canary is to run.

ipv6_allowed_for_dual_stackboolIf true, allow outbound IPv6 traffic on VPC canaries that are connected to dual-stack subnets. The default is false.security_group_idslist(string)IDs of the security groups for this canary.subnet_idslist(string)IDs of the subnets where this canary is to run.vpc_idstringID of the VPC where this canary is to run.

ipv6AllowedForDualStackBooleanIf true, allow outbound IPv6 traffic on VPC canaries that are connected to dual-stack subnets. The default is false.securityGroupIdsListIDs of the security groups for this canary.subnetIdsListIDs of the subnets where this canary is to run.vpcIdStringID of the VPC where this canary is to run.

ipv6AllowedForDualStackbooleanIf true, allow outbound IPv6 traffic on VPC canaries that are connected to dual-stack subnets. The default is false.securityGroupIdsstring[]IDs of the security groups for this canary.subnetIdsstring[]IDs of the subnets where this canary is to run.vpcIdstringID of the VPC where this canary is to run.

ipv6_allowed_for_dual_stackboolIf true, allow outbound IPv6 traffic on VPC canaries that are connected to dual-stack subnets. The default is false.security_group_idsSequence[str]IDs of the security groups for this canary.subnet_idsSequence[str]IDs of the subnets where this canary is to run.vpc_idstrID of the VPC where this canary is to run.

Import Anchor

Using pulumi import, import Synthetics Canaries using the name. For example:

$ pulumi import aws:synthetics/canary:Canary some some-canary

Copy

To learn more about importing existing cloud resources, see Importing resources.

Package Details Anchor

Viewing docs for AWS v7.32.0

published on Friday, May 29, 2026 by Pulumi

Schema (JSON)

pulumi/pulumi-aws

v7.32.0 (7.x, latest)v6.83.1 (6.x)v5.43.0 (5.x)

aws.synthetics.Canary Anchor

On this page

On this page

Example Usage Anchor

Create Canary Resource Anchor

Constructor syntax Anchor

Parameters Anchor

Constructor example Anchor

Canary Resource Properties Anchor

Inputs Anchor

Outputs Anchor

Look up Existing Canary Resource Anchor

Supporting Types Anchor

CanaryArtifactConfig , CanaryArtifactConfigArgs Anchor

CanaryArtifactConfigS3Encryption , CanaryArtifactConfigS3EncryptionArgs Anchor

CanaryRunConfig , CanaryRunConfigArgs Anchor

CanarySchedule , CanaryScheduleArgs Anchor

CanaryScheduleRetryConfig , CanaryScheduleRetryConfigArgs Anchor

CanaryTimeline , CanaryTimelineArgs Anchor

CanaryVpcConfig , CanaryVpcConfigArgs Anchor

Import Anchor

Package Details Anchor

On this page

On this page

Try Pulumi Cloud free. Your team will thank you.