terraform-aws-arc-synthetic-monitoring

Overview

SourceFuse AWS Reference Architecture (ARC) Terraform module for managing synthetic canaries.

Features

• Allows creation of AWS Synthetics canaries with VPC configurations.
• Supports custom IAM roles and policies.
• Flexible configuration options for canaries.

Introduction

SourceFuse's AWS Reference Architecture (ARC) Terraform module for Synthetics Canaries centralizes and automates the monitoring of your applications and APIs. By leveraging AWS CloudWatch Synthetics, this module allows you to create and manage canary scripts that continuously check the availability and performance of your endpoints. It provides a comprehensive solution to detect anomalies, pinpoint performance issues, and ensure that your applications are functioning as expected. The module also supports scheduling canary runs, capturing and analyzing logs and metrics, and integrating with other AWS services for alerting and reporting. With cross-region and cross-account capabilities, it enhances monitoring coverage and resilience for your applications.

Prerequisites

Before using this module, ensure you have the following:

• AWS credentials configured.
• Terraform installed.
• A working knowledge of Terraform.

Getting Started

1. Define the Module

Initially, it's essential to define a Terraform module, which is organized as a distinct directory encompassing Terraform configuration files. Within this module directory, input variables and output values must be defined in the variables.tf and outputs.tf files, respectively. The following illustrates an example directory structure:

synthetics/
|-- main.tf
|-- variables.tf
|-- outputs.tf

1. Define Input Variables

Inside the variables.tf or in *.tfvars file, you should define values for the variables that the module requires.

1. Use the Module in Your Main Configuration In your main Terraform configuration file (e.g., main.tf), you can use the module. Specify the source of the module, and version, For Example

module "synthetic-monitoring" {
  source            = "sourcefuse/arc-synthetic-monitoring/aws"
  version           = "0.0.1"
  sns_topic_name    = var.sns_topic_name
  endpoint          = var.endpoint
  kms_key_alias     = var.kms_key_alias
  canaries_with_vpc = local.canaries_with_vpc
  bucket_name       = var.bucket_name
  tags              = module.tags.tags
}

1. Output Values

Inside the outputs.tf file of the module, you can define output values that can be referenced in the main configuration. For example:

output "canary_arns" {
  value = module.synthetic-monitoring.canary_arns
}

Usage

To see a full example, check out the main.tf file in the example folder.

Requirements

Name	Version
terraform	~> 1.7
archive	2.4.2
aws	>= 4.0, < 6.0
random	3.6.2

Providers

Name	Version
aws	4.67.0
random	3.6.2

Modules

Name	Source	Version
kms	sourcefuse/arc-kms/aws	0.0.4

Resources

Name	Type
aws_cloudwatch_metric_alarm.fail_alarm	resource
aws_cloudwatch_metric_alarm.success_alarm	resource
aws_iam_policy.canary_execution_policy	resource
aws_iam_role.canary_execution_role	resource
aws_iam_role_policy_attachment.canary_execution_attachment	resource
aws_s3_bucket.artifcats_bucket	resource
aws_s3_bucket_cors_configuration.cors	resource
aws_s3_bucket_public_access_block.public_access_block	resource
aws_s3_bucket_server_side_encryption_configuration.ssm	resource
aws_s3_bucket_versioning.versioning	resource
aws_sns_topic.this	resource
aws_sns_topic_policy.this	resource
aws_sns_topic_subscription.this	resource
aws_synthetics_canary.dynamic_canaries_with_vpc	resource
random_pet.iam_role_name	resource
aws_caller_identity.current	data source
aws_iam_policy_document.sns_topic_policy	data source
aws_iam_role.execution_role	data source

Inputs

Name	Description	Type	Default	Required
block_public_acls	Whether Amazon S3 should block public ACLs for this bucket.	bool	true	no
block_public_policy	Whether Amazon S3 should block public bucket policies for this bucket.	bool	true	no
bucket_key_enabled	Specifies whether bucket key is enabled.	bool	false	no
bucket_name	The name of the S3 bucket.	string	n/a	yes
canaries_with_vpc	List of canaries with VPC configuration	map(object({ name = string handler = string zip_file = string s3_details = optional(object({ s3_bucket = string s3_key = string s3_version = string }), null) runtime_version = string start_canary = bool failure_retention_period = number success_retention_period = number schedule_expression = string environment_variables = map(string) }))	n/a	yes
cloudwatch_metric_alarms_enabled	Boolean flag to enable/disable CloudWatch metrics alarms	bool	false	no
cors_configuration	The CORS configuration for the S3 bucket.	list(object({ allowed_headers = list(string) allowed_methods = list(string) allowed_origins = list(string) expose_headers = list(string) max_age_seconds = number }))	[ { "allowed_headers": [ "Authorization" ], "allowed_methods": [ "GET", "POST" ], "allowed_origins": [ "*" ], "expose_headers": [ "x-amz-server-side-encryption" ], "max_age_seconds": 3000 } ]	no
custom_kms_policy	Custom KMS policy to apply if enabled. If not provided, a default policy will be used.	string	""	no
deletion_window_in_days	Duration in days after which the key is deleted after destruction of the resource	number	10	no
enable_key_rotation	Specifies whether key rotation is enabled	bool	true	no
enabled	Whether the KMS module is enabled. If true, a custom KMS key will be used for encryption. If false, the default AWS managed KMS key will be used.	bool	true	no
endpoint	The endpoint for the SNS subscription.	string	n/a	yes
force_destroy	Specifies whether to force destroy the bucket (and all objects) when the bucket is removed.	bool	true	no
ignore_public_acls	Whether Amazon S3 should ignore public ACLs for this bucket.	bool	true	no
kms_key_alias	Alias for the custom KMS key (if enabled).	string	n/a	yes
protocol	The protocol for the SNS subscription endpoint.	string	"email"	no
region	AWS region	string	"us-east-1"	no
restrict_public_buckets	Whether Amazon S3 should restrict public bucket policies for this bucket.	bool	true	no
security_group_ids	List of security group IDs for the canary	list(string)	[ "" ]	no
sns_topic_name	Name for the SNS topic.	string	n/a	yes
sse_algorithm	The server-side encryption algorithm to use. Valid values are AES256 and aws:kms	string	"aws:kms"	no
subnet_ids	List of subnet IDs where the canary will run	list(string)	[ "" ]	no
tags	Tags to apply to the canary	map(string)	n/a	yes
versioning_enabled	Enable versioning for the S3 bucket.	bool	false	no

Outputs

Name	Description
canary_arns	ARNs of all canaries created

Versioning

This project uses a .version file at the root of the repo which the pipeline reads from and does a git tag.

When you intend to commit to main, you will need to increment this version. Once the project is merged, the pipeline will kick off and tag the latest git commit.

Development

Prerequisites

• terraform
• terraform-docs
• pre-commit
• golang
• golint

Configurations

• Configure pre-commit hooks

  pre-commit install
  

Versioning

while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch

For Example

git commit -m "your commit message #major"

By specifying this , it will bump the version and if you don't specify this in your commit message then by default it will consider patch and will bump that accordingly

Tests

• Tests are available in test directory
• Configure the dependencies

  cd test/
  go mod init github.com/sourcefuse/terraform-aws-refarch-<module_name>
  go get github.com/gruntwork-io/terratest/modules/terraform
  

• Now execute the test
  

  go test -timeout  30m
  

Authors

This project is authored by: - SourceFuse ARC Team

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Mayank Sharma 💻 📖 🚇 🚧 🧑‍🏫

This project follows the all-contributors specification. Contributions of any kind welcome!