Nat Instance Module

This Terraform module provisions an Amazon Autoscaling group with an EC2 instance running iptables and squid proxy, allowing for a low-cost alternative to a NAT gateway whilst also providing filtering for outbound http/https traffic.

Overview

The module creates:

• An Autoscaling group to maintain EC2 instances in a running state
• A Lambda function to perform various actions in response to metric alarms, S3 triggers and to perform updates to the private route table(s)
• An S3 trigger to detect changes to squid configuration files
• A cloud-init template to configure iptables, squid and Cloudwatch agent on the EC2 instances
• Cloudwatch log groups for the squid proxy cache and access logs, and Lambda invocation logs

The running instances can be accessed via SSM for debugging purposes.

Usage with Terraform

module "nat-instance" {
  source = "[email protected]:<org>/nat-instance.git?ref=v2.3.1"

  additional_egress_rules = {
    mongodb = {
      cidr_ipv4   = "0.0.0.0/0"
      description = "Allow MongoDB connections"
      ip_protocol = "tcp"
      from_port   = 27016
      to_port     = 27017
    }
  }
  allowed_web_domains = [
    ".amazonaws.com",
    "api.sendgrid.com",
  ]
  enable_eip         = true
  name               = "myapp-test-nat"
  private_subnet_ids = ["subnet-10a214dfcd63a97a4", "subnet-c727b18850685046b"]
  public_subnet_ids  = ["subnet-37f911e98a8616eee", "subnet-233bfad11fdd81dfd"]
  vpc_id             = "vpc-1eb7bfbe312f068e1"
}

Notes

• Instance AMI will not be updated automatically (ignored in lifecycle)

Inputs

Name	Description	Type	Default	Required
additional_egress_rules	Additional egress rules to apply to the security group.	map(object({ name = optional(string) cidr_ipv4 = optional(string) cidr_ipv6 = optional(string) description = optional(string) from_port = optional(string) ip_protocol = optional(string, "tcp") prefix_list_id = optional(string) referenced_security_group_id = optional(string) tags = optional(map(string), {}) to_port = optional(string) }))	{}	no
additional_ingress_rules	Additional ingress rules to apply to the security group.	map(object({ name = optional(string) cidr_ipv4 = optional(string) cidr_ipv6 = optional(string) description = optional(string) from_port = optional(string) ip_protocol = optional(string, "tcp") prefix_list_id = optional(string) referenced_security_group_id = optional(string) tags = optional(map(string), {}) to_port = optional(string) }))	{}	no
allowed_web_domains	List of allowed domains.	list(string)	[ ".amazonaws.com", ".amazon.com" ]	no
architectures	Lambda function architecture.	list(string)	[ "arm64" ]	no
detailed_monitoring	Whether or not to enable detailed monitoring for the EC2 instance.	bool	false	no
enable_eip	Whether or not to enable a consistent elastic IP for the EC2 instances.	bool	false	no
enable_spot_instance	Whether or not to use spot instances for the ASG.	bool	false	no
instance_type	The instance type to use for the ASG.	string	"t4g.small"	no
name	The name to use for resources.	string	"nat"	no
private_subnet_ids	List of private subnet ID's in the VPC.	list(string)	n/a	yes
public_subnet_ids	List of public subnet ID's to deploy the ASG to.	list(string)	n/a	yes
tags	Tags to apply to the resources.	map(string)	{}	no
vpc_id	The ID of the VPC to deploy the NAT instance/squid proxy to.	string	n/a	yes

Modules

Name	Source	Version
config_bucket	terraform-aws-modules/s3-bucket/aws	~> 5.0
squid_config	terraform-aws-modules/s3-bucket/aws//modules/object	~> 5.0
whitelist	terraform-aws-modules/s3-bucket/aws//modules/object	~> 5.0

Outputs

Name	Description
public_ip	n/a

Providers

Name	Version
archive	n/a
aws	~> 6.0

Requirements

Name	Version
terraform	>= 1.8
aws	~> 6.0
random	~> 3.6
time	0.13.1

Resources

Name	Type
aws_autoscaling_group.nat	resource
aws_cloudwatch_log_group.access	resource
aws_cloudwatch_log_group.cache	resource
aws_cloudwatch_log_group.iptables	resource
aws_cloudwatch_log_group.lambda	resource
aws_cloudwatch_metric_alarm.squid	resource
aws_eip.nat	resource
aws_iam_instance_profile.instance	resource
aws_iam_policy.instance	resource
aws_iam_policy.lambda	resource
aws_iam_role.asg_lifecycle	resource
aws_iam_role.instance	resource
aws_iam_role.lambda	resource
aws_iam_role_policy.asg_lifecycle	resource
aws_iam_role_policy_attachment.cloudwatch	resource
aws_iam_role_policy_attachment.custom	resource
aws_iam_role_policy_attachment.lambda_custom	resource
aws_iam_role_policy_attachment.lambda_managed	resource
aws_lambda_function.nat	resource
aws_lambda_permission.alarm_sns	resource
aws_lambda_permission.lifecycle_sns	resource
aws_lambda_permission.s3_trigger	resource
aws_launch_template.nat	resource
aws_s3_bucket_notification.bucket_notification	resource
aws_security_group.instance	resource
aws_sns_topic.alarm	resource
aws_sns_topic.asg_lifecycle	resource
aws_sns_topic_subscription.lambda	resource
aws_sns_topic_subscription.lambda_sub	resource
aws_sqs_queue.dlq	resource
aws_vpc_security_group_egress_rule.this	resource
aws_vpc_security_group_ingress_rule.this	resource
archive_file.lambda_source_code	data source
aws_ami.amazon_linux_2	data source
aws_caller_identity.this	data source
aws_ec2_instance_type.this	data source
aws_iam_policy_document.instance	data source
aws_iam_policy_document.lambda	data source
aws_region.current	data source
aws_route_table.private	data source
aws_subnet.private	data source
aws_vpc.this	data source