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.23

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.23"

  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.23

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({ actions_enabled = optional(bool, true) 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) })	{ "actions_enabled": true, "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
policy_json	Policy JSON. If null, default policy granting S3, logging, and XRay will be attached	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