terraform-aws-refarch-healthcheck

Introduction

The SourceFuse AWS Reference Architecture (ARC) Terraform module facilitates endpoint health checks using Route53, enabling automated monitoring and management of endpoint health within AWS infrastructures for enhanced reliability and availability.

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:

healthcheck/
|-- 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 "health_check" {
 source  = "sourcefuse/arc-healthcheck/aws"
  version = "0.0.3"

  name              = var.name
  domain_name       = var.domain_name
  resource_path     = var.resource_path
  type              = var.type
  measure_latency   = var.measure_latency
  alarm_prefix      = var.alarm_prefix
  failure_threshold = var.failure_threshold
  request_interval  = var.request_interval
  search_string     = var.search_string
  alarm_endpoint    = var.alarm_endpoint

}

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 "cloudwatch_alarm_arn" {
  value       = aws_cloudwatch_metric_alarm.this.arn
}

output "route53_health_check_arn" {
  value       = aws_route53_health_check.this.arn
}

1. .tfvars

Inside the .tfvars file of the module, you can provide desired values that can be referenced in the main configuration. For example:

Edit the dev.tfvars file and provide desired values.

region      = "us-east-1"
namespace   = "arc"
environment = "dev"

name              = "test-health-check"
domain_name       = "microservices.io"
resource_path     = "/patterns/observability/health-check-api.html"
type              = "HTTPS_STR_MATCH"
measure_latency   = true
alarm_prefix      = "test"
failure_threshold = 2
request_interval  = 10
search_string     = "Health"  // Note:- string with space(eg. "Health API") is not working , it always goes to in-alarm state
alarm_endpoint    = "https://api.opsgenie.com/v1/json/cloudwatch?apiKey=xxxxx-xx-4xxc9c-xx-xxxx"

First Time Usage

uncomment the backend block in main.tf

terraform init -backend-config=config.dev.hcl

If testing locally, terraform init should be fine

Create a dev workspace

terraform workspace new dev

Plan Terraform

terraform plan -var-file dev.tfvars

Apply Terraform

terraform apply -var-file dev.tfvars

Production Setup

terraform init -backend-config=config.prod.hcl

Create a prod workspace

terraform workspace new prod

Plan Terraform

terraform plan -var-file prod.tfvars

Apply Terraform

terraform apply -var-file prod.tfvars  

Cleanup

Destroy Terraform

terraform destroy -var-file dev.tfvars  

Requirements

Name	Version
terraform	>= 1.3.0, < 2.0.0
aws	~> 5.0

Providers

Name	Version
aws	4.67.0

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_metric_alarm.alarm_breaching	resource
aws_cloudwatch_metric_alarm.ok	resource
aws_route53_health_check.this	resource
aws_sns_topic.this	resource
aws_sns_topic_subscription.this	resource

Inputs

Name	Description	Type	Default	Required
alarm_description	Alarm description	string	null	no
alarm_endpoint	Alarm endpoint, this get added as a subcription to SNS	string	""	no
alarm_endpoint_protocol	Protocol to use. Valid values are: sqs, sms, lambda, firehose, and application. Protocols email, email-json, http and https are also valid but partially supported. See details below.	string	"https"	no
alarm_prefix	Prefix for Alarm	string	n/a	yes
comparison_operator	Specifies the arithmetic operation to use when comparing the specified statistic and threshold. The value should indicate the condition under which the alarm is triggered, such as 'GreaterThanThreshold', 'LessThanThreshold', 'GreaterThanOrEqualToThreshold', or 'LessThanOrEqualToThreshold'.	string	"LessThanOrEqualToThreshold"	no
domain_name	Domain name or ip address of checking service.	string	n/a	yes
enable_alarm	Flag to enable or disable the CloudWatch metric alarm.	bool	false	no
evaluation_periods	The number of periods over which data is compared to the specified threshold.	number	2	no
failure_threshold	The number of consecutive health checks that an endpoint must pass or fail.	number	n/a	yes
invert_healthcheck	A boolean value that indicates whether the status of health check should be inverted. For example, if a health check is healthy but Inverted is True , then Route 53 considers the health check to be unhealthy.	bool	false	no
kms_id	KMS id to encrpyt SNS, note : AWS managed keys doesn't work	string	null	no
measure_latency	Indicates whether you want Route 53 to measure the latency between health checkers in multiple AWS regions and your endpoint and to display CloudWatch latency graphs in the Route 53 console.	string	false	no
name	Health check name	string	n/a	yes
ok_alarm_description	OK Alarm description	string	null	no
period	The period in seconds over which the specified statistic is applied. Valid values are 10, 30, or any multiple of 60	number	10	no
port	Port number of checking service.	number	443	no
regions	A list of AWS regions that you want Amazon Route 53 health checkers to check the specified endpoint from.	list(string)	[ "us-east-1", "us-west-2", "us-west-1" ]	no
request_interval	The number of seconds between the time that Amazon Route 53 gets a response from your endpoint and the time that it sends the next health-check request.	number	n/a	yes
resource_path	Resource path eg. /health	string	""	no
routing_control_arn	The Amazon Resource Name (ARN) for the Route 53 Application Recovery Controller routing control. This is used when health check type is RECOVERY_CONTROL	string	""	no
search_string	String searched in the first 5120 bytes of the response body for check to be considered healthy. Only valid with HTTP_STR_MATCH and HTTPS_STR_MATCH	string	null	no
statistic	Specifies the metric statistic to use for the alarm. Common options include 'Average', 'Sum', 'SampleCount', 'Minimum', and 'Maximum'. This determines how the metric data points are aggregated over the specified period.	string	"Average"	no
tags	Tags object.	map(string)	{}	no
threshold	The value against which the specified statistic is compared. This parameter is required for alarms based on static thresholds, but should not be used for alarms based on anomaly detection models.	number	1	no
type	Type of health check. eg. HTTPS_STR_MATCH, HTTPS, HTTP	string	"HTTPS"	no

Outputs

Name	Description
cloudwatch_alarm_arn	Cloudwatch Alarm ARN
route53_health_check_arn	Route53 Health check ARN
sns_arn	SNS ARN

Development

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 dont specify this in your commit message then by default it will consider patch and will bump that accordingly

Prerequisites

• terraform
• terraform-docs
• pre-commit

Configurations

• Configure pre-commit hooks

  pre-commit install
  

• Configure the dependencies

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

• Execute pre-commit

  pre-commit run -a
  

Authors

This project is authored by: - SourceFuse