search

pbs / terraform-aws-synthetics-module

Standard PBS TF CloudWatch Synthetics Module
MIT License
0 stars 0 forks source link

readme

PBS TF Synthetics Module

Installation

Using the Repo Source

Use this URL for the source of the module. See the usage examples below for more details.

github.com/pbs/terraform-aws-synthetics-module?ref=2.0.21

Alternative Installation Methods

More information can be found on these install methods and more in the documentation here.

Usage

Creates a basic CloudWatch Synthetics Canary, along with the accoutrement to utilize it effectively.

Integrate this module like so:

module "synthetics" {
  source = "github.com/pbs/terraform-aws-synthetics-module?ref=2.0.21"

  zip_file = "path/to/file.zip"

  # Tagging Parameters
  organization = var.organization
  environment  = var.environment
  product      = var.product
  repo         = var.repo

  # Optional Parameters
}

Note that either a zip_file or a canary_script_s3_location must be provided to provide code for the canary to run.

An example showing how to use Terraform to generate a canary can be found in the basic example.

Note that this is not advised for most use-cases. data resources in Terraform are assumed to have no side effects (like creating a zip file), and you will run into trouble if you use this approach for frequent canary adjustments.

The recommended workaround for this is to use something external to Terraform (like a bash script or Terragrunt) to handle the zip file creation, and then use Terraform to deploy the canary.

Adding This Version of the Module

If this repo is added as a subtree, then the version of the module should be close to the version shown here:

2.0.21

Note, however that subtrees can be altered as desired within repositories.

Further documentation on usage can be found here.

Below is automatically generated documentation on this Terraform module using terraform-docs

Requirements

Name Version
terraform >= 1.3.2
aws >= 4.5.0

Providers

Name Version
aws 5.38.0

Modules

Name Source Version
role github.com/pbs/terraform-aws-iam-role-module.git 0.2.4
s3 github.com/pbs/terraform-aws-s3-module 4.0.13

Resources

Name Type
aws_cloudwatch_metric_alarm.alarm resource
aws_synthetics_canary.canary resource
aws_caller_identity.current data source
aws_default_tags.common_tags data source
aws_region.current data source

Inputs

Name Description Type Default Required
environment Environment (sharedtools, dev, staging, qa, prod) string n/a yes
organization Organization using this module. Used to prefix tags so that they are easily identified as being from your organization string n/a yes
product Tag used to group resources according to product string n/a yes
repo Tag used to point to the repo using this module string n/a yes
alarm_config Configurations for the alarm 
object({
    comparison_operator       = optional(string, "LessThanThreshold")
    period                    = optional(number, 300)
    evaluation_periods        = optional(number, 1)
    metric_name               = optional(string, "SuccessPercent")
    namespace                 = optional(string, "CloudWatchSynthetics")
    statistic                 = optional(string, "Sum")
    datapoints_to_alarm       = optional(number, 1)
    threshold                 = optional(string, "90")
    alarm_actions             = optional(list(string), [])
    ok_actions                = optional(list(string), [])
    insufficient_data_actions = optional(list(string), [])
    treat_missing_data        = optional(string, "missing")
    description               = optional(string)
  })
 
{
  "alarm_actions": [],
  "comparison_operator": "LessThanThreshold",
  "datapoints_to_alarm": 1,
  "description": null,
  "evaluation_periods": 1,
  "insufficient_data_actions": [],
  "metric_name": "SuccessPercent",
  "namespace": "CloudWatchSynthetics",
  "ok_actions": [],
  "period": 300,
  "statistic": "Sum",
  "threshold": "90",
  "treat_missing_data": "missing"
}
 no
artifact_config Configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3. 
object({
    s3_encryption = optional(object({
      encryption_mode = optional(string)
      kms_key_arn     = optional(string)
    }))
  })
 null no
canary_script_s3_location Location in Amazon S3 where Synthetics stores the canary script for a canary. Conflicts with zip_file. 
object({
    bucket  = optional(string)
    key     = optional(string)
    version = optional(string)
  })
 {} no
delete_lambda Specifies whether to also delete the Lambda functions and layers used by this canary. bool false no
execution_role_arn ARN of the IAM role to be used to run the canary. string null no
execution_role_name Name of the execution role created by this module, if one is created. If null, will default to name. string null no
failure_retention_period Number of days to retain data about failed runs of this canary. number 31 no
force_destroy Specifies whether to force destroy the bucket containing the canary artifacts. This is required when the bucket contains objects. The default value is false. bool false no
handler Entry point to use for the source code when running the canary. This value must end with the string .handler. string "canary.handler" no
name Name of the synthetics module. If null, will default to product. string null no
run_config Configuration block for individual canary runs. 
object({
    timeout_in_seconds    = optional(number)
    memory_in_mb          = optional(number)
    active_tracing        = optional(bool)
    environment_variables = optional(map(string))
  })
 null no
runtime_version Specifies the runtime version to use for the canary. For a list of valid runtime versions, see Canary Runtime Versions. string "syn-nodejs-puppeteer-7.0" no
schedule Schedule for how often the canary is to run and when these test runs are to stop. 
object({
    expression          = string
    duration_in_seconds = optional(number)
  })
 
{
  "expression": "rate(5 minutes)"
}
 no
snapshot_bucket_name Name of the bucket to store snapshots in. If null, will default to name. string null no
start_canary Specifies whether this canary is to run after it is created. bool true no
success_retention_period Number of days to retain data about successful runs of this canary. The valid range is 1 to 455 days. number 31 no
tags Extra tags map(string) {} no
vpc_config Specifies the VPC settings of the canary. 
object({
    subnet_ids         = list(string)
    security_group_ids = list(string)
  })
 null no
zip_file 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 canary_script_s3_location. string null no

Outputs

Name Description
arn ARN of the canary
engine_arn ARN of the Lambda function that is used as your canary's engine
execution_role_name Name of the IAM role used to run the canary
id Name of the canary
name Name of the canary
source_location_arn ARN of the Lambda layer where Synthetics stores the canary script code
status Status of the canary
timeline Timeline of the canary