Package com.pulumi.aws.synthetics

Class Canary

  • public class Canary
extends com.pulumi.resources.CustomResource
    Provides a Synthetics Canary resource. > **NOTE:** When you create a canary, AWS creates supporting implicit resources. See the Amazon CloudWatch Synthetics documentation on [DeleteCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_DeleteCanary.html) 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 
     
 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()
             .schedule(CanaryScheduleArgs.builder()
                 .expression("rate(0 minute)")
                 .build())
             .name("some-canary")
             .artifactS3Location("s3://some-bucket/")
             .executionRoleArn("some-role")
             .handler("exports.handler")
             .zipFile("test-fixtures/lambdatest.zip")
             .runtimeVersion("syn-1.0")
             .build());
 
     }
 }
    ## Import Using `pulumi import`, import Synthetics Canaries using the `name`. For example: ```sh $ pulumi import aws:synthetics/canary:Canary some some-canary ```

    • Nested Class Summary

      • Nested classes/interfaces inherited from class com.pulumi.resources.CustomResource

        com.pulumi.resources.CustomResource.CustomResourceInternal

      • Nested classes/interfaces inherited from class com.pulumi.resources.Resource

        com.pulumi.resources.Resource.LazyField<T extends java.lang.Object>, com.pulumi.resources.Resource.LazyFields, com.pulumi.resources.Resource.ResourceInternal

    • Field Summary

      • Fields inherited from class com.pulumi.resources.Resource

        childResources, remote

    • Constructor Summary

      Constructors 
      Constructor Description
      Canary​(java.lang.String name)  
      Canary​(java.lang.String name, CanaryArgs args)  
      Canary​(java.lang.String name, CanaryArgs args, com.pulumi.resources.CustomResourceOptions options)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      com.pulumi.core.Output<java.lang.String> arn()  
      com.pulumi.core.Output<java.util.Optional<CanaryArtifactConfig>> artifactConfig()  
      com.pulumi.core.Output<java.lang.String> artifactS3Location()  
      com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> deleteLambda()  
      com.pulumi.core.Output<java.lang.String> engineArn()  
      com.pulumi.core.Output<java.lang.String> executionRoleArn()  
      com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> failureRetentionPeriod()  
      static Canary get​(java.lang.String name, com.pulumi.core.Output<java.lang.String> id, CanaryState state, com.pulumi.resources.CustomResourceOptions options)
      Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
      com.pulumi.core.Output<java.lang.String> handler()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> kmsKeyArn()  
      com.pulumi.core.Output<java.lang.String> name()  
      com.pulumi.core.Output<java.lang.String> region()  
      com.pulumi.core.Output<CanaryRunConfig> runConfig()  
      com.pulumi.core.Output<java.lang.String> runtimeVersion()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> s3Bucket()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> s3Key()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> s3Version()  
      com.pulumi.core.Output<CanarySchedule> schedule()  
      com.pulumi.core.Output<java.lang.String> sourceLocationArn()  
      com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> startCanary()  
      com.pulumi.core.Output<java.lang.String> status()  
      com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> successRetentionPeriod()  
      com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()  
      com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()  
      com.pulumi.core.Output<java.util.List<CanaryTimeline>> timelines()  
      com.pulumi.core.Output<java.util.Optional<CanaryVpcConfig>> vpcConfig()  
      com.pulumi.core.Output<java.util.Optional<java.lang.String>> zipFile()  

      • Methods inherited from class com.pulumi.resources.CustomResource

        getId, id, idFuture

      • Methods inherited from class com.pulumi.resources.Resource

        getChildResources, getResourceName, getResourceType, getUrn, pulumiChildResources, pulumiResourceName, pulumiResourceType, urn

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Canary

        public Canary​(java.lang.String name)
        Parameters:
        name - The _unique_ name of the resulting resource.

      • Canary

        public Canary​(java.lang.String name,
              CanaryArgs args)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.

      • Canary

        public Canary​(java.lang.String name,
              CanaryArgs args,
              @Nullable
              com.pulumi.resources.CustomResourceOptions options)
        Parameters:
        name - The _unique_ name of the resulting resource.
        args - The arguments to use to populate this resource's properties.
        options - A bag of options that control this resource's behavior.

    • Method Detail

      • arn

        public com.pulumi.core.Output<java.lang.String> arn()
        Returns:
        ARN of the Canary.

      • artifactConfig

        public com.pulumi.core.Output<java.util.Optional<CanaryArtifactConfig>> artifactConfig()
        Returns:
        configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. See Artifact Config.

      • artifactS3Location

        public com.pulumi.core.Output<java.lang.String> artifactS3Location()
        Returns:
        Location in Amazon S3 where Synthetics stores artifacts from the test runs of this canary.

      • deleteLambda

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> deleteLambda()
        Returns:
        Specifies whether to also delete the Lambda functions and layers used by this canary. The default is `false`.

      • engineArn

        public com.pulumi.core.Output<java.lang.String> engineArn()
        Returns:
        ARN of the Lambda function that is used as your canary's engine.

      • executionRoleArn

        public com.pulumi.core.Output<java.lang.String> executionRoleArn()
        Returns:
        ARN of the IAM role to be used to run the canary. see [AWS Docs](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html#API_CreateCanary_RequestSyntax) for permissions needs for IAM Role.

      • failureRetentionPeriod

        public com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> failureRetentionPeriod()
        Returns:
        Number of days to retain data about failed runs of this canary. If you omit this field, the default of 31 days is used. The valid range is 1 to 455 days.

      • handler

        public com.pulumi.core.Output<java.lang.String> handler()
        Returns:
        Entry point to use for the source code when running the canary. This value must end with the string `.handler` .

      • kmsKeyArn

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> kmsKeyArn()
        Returns:
        ARN of the customer-managed KMS key used to encrypt the environment variables of the canary's Lambda function at rest. If omitted, an AWS owned key is used. Note that this is distinct from `artifact_config.s3_encryption.kms_key_arn`, which encrypts the artifacts the canary uploads to Amazon S3.

      • name

        public com.pulumi.core.Output<java.lang.String> name()
        Returns:
        Name for this canary. Has a maximum length of 255 characters. Valid characters are lowercase alphanumeric, hyphen, or underscore.

      • region

        public com.pulumi.core.Output<java.lang.String> region()
        Returns:
        Region where this resource will be [managed](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints). Defaults to the Region set in the provider configuration.

      • runConfig

        public com.pulumi.core.Output<CanaryRunConfig> runConfig()
        Returns:
        Configuration block for individual canary runs. Detailed below.

      • runtimeVersion

        public com.pulumi.core.Output<java.lang.String> runtimeVersion()
        Returns:
        Runtime version to use for the canary. Versions change often so consult the [Amazon CloudWatch documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html) 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`.

      • s3Bucket

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> s3Bucket()
        Returns:
        Full bucket name which is used if your canary script is located in S3. The bucket must already exist. **Conflicts with `zipFile`.**

      • s3Key

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> s3Key()
        Returns:
        S3 key of your script. **Conflicts with `zipFile`.**

      • s3Version

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> s3Version()
        Returns:
        S3 version ID of your script. **Conflicts with `zipFile`.**

      • schedule

        public com.pulumi.core.Output<CanarySchedule> schedule()
        Returns:
        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:

      • sourceLocationArn

        public com.pulumi.core.Output<java.lang.String> sourceLocationArn()
        Returns:
        ARN of the Lambda layer where Synthetics stores the canary script code.

      • startCanary

        public com.pulumi.core.Output<java.util.Optional<java.lang.Boolean>> startCanary()
        Returns:
        Whether to run or stop the canary.

      • status

        public com.pulumi.core.Output<java.lang.String> status()
        Returns:
        Canary status.

      • successRetentionPeriod

        public com.pulumi.core.Output<java.util.Optional<java.lang.Integer>> successRetentionPeriod()
        Returns:
        Number of days to retain data about successful runs of this canary. If you omit this field, the default of 31 days is used. The valid range is 1 to 455 days.

      • tags

        public com.pulumi.core.Output<java.util.Optional<java.util.Map<java.lang.String,​java.lang.String>>> tags()
        Returns:
        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

        public com.pulumi.core.Output<java.util.Map<java.lang.String,​java.lang.String>> tagsAll()
        Returns:
        A map of tags assigned to the resource, including those inherited from the provider `defaultTags` configuration block.

      • timelines

        public com.pulumi.core.Output<java.util.List<CanaryTimeline>> timelines()
        Returns:
        Structure that contains information about when the canary was created, modified, and most recently run. see Timeline.

      • vpcConfig

        public com.pulumi.core.Output<java.util.Optional<CanaryVpcConfig>> vpcConfig()
        Returns:
        Configuration block. Detailed below.

      • zipFile

        public com.pulumi.core.Output<java.util.Optional<java.lang.String>> zipFile()
        Returns:
        ZIP file that contains the script, if you input your canary script directly into the canary instead of referring to an S3 location. It can be up to 225KB. **Conflicts with `s3Bucket`, `s3Key`, and `s3Version`.**

      • get

        public static Canary get​(java.lang.String name,
                         com.pulumi.core.Output<java.lang.String> id,
                         @Nullable
                         CanaryState state,
                         @Nullable
                         com.pulumi.resources.CustomResourceOptions options)
        Get an existing Host resource's state with the given name, ID, and optional extra properties used to qualify the lookup.
        Parameters:
        name - The _unique_ name of the resulting resource.
        id - The _unique_ provider ID of the resource to lookup.
        state -
        options - Optional settings to control the behavior of the CustomResource.