Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/int128/terraform-aws-nat-instance
Terraform module to provision a NAT Instance using an Auto Scaling Group and Spot Instance from $1/month
https://github.com/int128/terraform-aws-nat-instance
terraform terraform-aws terraform-modules
Last synced: about 1 month ago
JSON representation
Terraform module to provision a NAT Instance using an Auto Scaling Group and Spot Instance from $1/month
- Host: GitHub
- URL: https://github.com/int128/terraform-aws-nat-instance
- Owner: int128
- License: apache-2.0
- Archived: true
- Created: 2019-09-12T03:11:16.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-10T21:30:46.000Z (5 months ago)
- Last Synced: 2024-09-22T04:30:52.642Z (about 1 month ago)
- Topics: terraform, terraform-aws, terraform-modules
- Language: HCL
- Homepage: https://registry.terraform.io/modules/int128/nat-instance/aws/
- Size: 80.1 KB
- Stars: 175
- Watchers: 6
- Forks: 90
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# terraform-aws-nat-instance [](https://circleci.com/gh/int128/terraform-aws-nat-instance)
This is a Terraform module which provisions a NAT instance.
Features:
- Providing NAT for private subnet(s)
- Auto healing using an auto scaling group
- Saving cost using a spot instance (from $1/month)
- Fixed source IP address by reattaching ENI
- Supporting Systems Manager Session Manager
- Compatible with workspaces
Terraform 0.12 or later is required.
**Warning**: Generally you should use a NAT gateway. This module provides a very low cost solution for testing purpose.
## Getting Started
You can use this module with [terraform-aws-modules/vpc/aws](https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws) module as follows:
```tf
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
name = "main"
cidr = "172.18.0.0/16"
azs = ["us-west-2a", "us-west-2b", "us-west-2c"]
private_subnets = ["172.18.64.0/20", "172.18.80.0/20", "172.18.96.0/20"]
public_subnets = ["172.18.128.0/20", "172.18.144.0/20", "172.18.160.0/20"]
enable_dns_hostnames = true
}
module "nat" {
source = "int128/nat-instance/aws"
name = "main"
vpc_id = module.vpc.vpc_id
public_subnet = module.vpc.public_subnets[0]
private_subnets_cidr_blocks = module.vpc.private_subnets_cidr_blocks
private_route_table_ids = module.vpc.private_route_table_ids
}
resource "aws_eip" "nat" {
network_interface = module.nat.eni_id
tags = {
"Name" = "nat-instance-main"
}
}
```
Now create an EC2 instance in the private subnet to verify the NAT configuration.
Open the [AWS Systems Manager Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html), log in to the instance and make sure you have external access from the instance.
See also the [example](example/).
## How it works
This module provisions the following resources:
- Auto Scaling Group with mixed instances policy
- Launch Template
- Elastic Network Interface
- Security Group
- IAM Role for SSM and ENI attachment
- VPC Route (optional)
You need to attach your elastic IP to the ENI.
Take a look at the diagram:
By default the latest Amazon Linux 2 image is used.
You can set `image_id` for a custom image.
The instance will execute [`runonce.sh`](runonce.sh) and [`snat.sh`](snat.sh) to enable NAT as follows:
1. Attach the ENI to `eth1`.
1. Set the kernel parameters for IP forwarding and masquerade.
1. Switch the default route to `eth1`.
## Configuration
### User data
You can set additional `write_files` and `runcmd` section. For example,
```tf
module "nat" {
user_data_write_files = [
{
path : "/opt/nat/run.sh",
content : file("./run.sh"),
permissions : "0755",
},
]
user_data_runcmd = [
["/opt/nat/run.sh"],
]
}
```
See also [cloud-init modules](https://cloudinit.readthedocs.io/en/latest/topics/modules.html) and the [example](example/) for more.
### SSH access
You can enable SSH access by setting `key_name` option and opening the security group. For example,
```tf
module "nat" {
key_name = "YOUR_KEY_PAIR"
}
resource "aws_security_group_rule" "nat_ssh" {
security_group_id = module.nat.sg_id
type = "ingress"
cidr_blocks = ["0.0.0.0/0"]
from_port = 22
to_port = 22
protocol = "tcp"
}
```
## Migration guide
### Upgrade to v2 from v1
This module no longer creates an EIP since v2.
To keep your EIP when you migrate to module v2, rename the EIP in the state as follows:
```console
% terraform state mv -dry-run module.nat.aws_eip.this aws_eip.nat
Would move "module.nat.aws_eip.this" to "aws_eip.nat"
% terraform state mv module.nat.aws_eip.this aws_eip.nat
Move "module.nat.aws_eip.this" to "aws_eip.nat"
Successfully moved 1 object(s).
```
## Contributions
This is an open source software. Feel free to open issues and pull requests.
## Requirements
| Name | Version |
|------|---------|
| [terraform](#requirement\_terraform) | >= 0.12.0 |
## Providers
| Name | Version |
|------|---------|
| [aws](#provider\_aws) | n/a |
## Modules
No modules.
## Resources
| Name | Type |
|------|------|
| [aws_autoscaling_group.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/autoscaling_group) | resource |
| [aws_iam_instance_profile.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_instance_profile) | resource |
| [aws_iam_role.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
| [aws_iam_role_policy.eni](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy) | resource |
| [aws_iam_role_policy_attachment.ssm](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
| [aws_launch_template.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/launch_template) | resource |
| [aws_network_interface.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/network_interface) | resource |
| [aws_route.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route) | resource |
| [aws_security_group.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group) | resource |
| [aws_security_group_rule.egress](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group_rule) | resource |
| [aws_security_group_rule.ingress_any](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group_rule) | resource |
| [aws_ami.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ami) | data source |
## Inputs
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| [enabled](#input\_enabled) | Enable or not costly resources | `bool` | `true` | no |
| [image\_id](#input\_image\_id) | AMI of the NAT instance. Default to the latest Amazon Linux 2 | `string` | `""` | no |
| [instance\_types](#input\_instance\_types) | Candidates of spot instance type for the NAT instance. This is used in the mixed instances policy | `list(string)` |
[
"t3.nano",
"t3a.nano"
]
| no |
| [key\_name](#input\_key\_name) | Name of the key pair for the NAT instance. You can set this to assign the key pair to the NAT instance | `string` | `""` | no |
| [name](#input\_name) | Name for all the resources as identifier | `string` | n/a | yes |
| [private\_route\_table\_ids](#input\_private\_route\_table\_ids) | List of ID of the route tables for the private subnets. You can set this to assign the each default route to the NAT instance | `list(string)` | `[]` | no |
| [private\_subnets\_cidr\_blocks](#input\_private\_subnets\_cidr\_blocks) | List of CIDR blocks of the private subnets. The NAT instance accepts connections from this subnets | `list(string)` | n/a | yes |
| [public\_subnet](#input\_public\_subnet) | ID of the public subnet to place the NAT instance | `string` | n/a | yes |
| [ssm\_policy\_arn](#input\_ssm\_policy\_arn) | SSM Policy to be attached to instance profile | `string` | `"arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"` | no |
| [tags](#input\_tags) | Tags applied to resources created with this module | `map(string)` | `{}` | no |
| [use\_spot\_instance](#input\_use\_spot\_instance) | Whether to use spot or on-demand EC2 instance | `bool` | `true` | no |
| [user\_data\_runcmd](#input\_user\_data\_runcmd) | Additional runcmd section of cloud-init | `list(list(string))` | `[]` | no |
| [user\_data\_write\_files](#input\_user\_data\_write\_files) | Additional write\_files section of cloud-init | `list(any)` | `[]` | no |
| [vpc\_id](#input\_vpc\_id) | ID of the VPC | `string` | n/a | yes |
## Outputs
| Name | Description |
|------|-------------|
| [eni\_id](#output\_eni\_id) | ID of the ENI for the NAT instance |
| [eni\_private\_ip](#output\_eni\_private\_ip) | Private IP of the ENI for the NAT instance |
| [iam\_role\_name](#output\_iam\_role\_name) | Name of the IAM role for the NAT instance |
| [sg\_id](#output\_sg\_id) | ID of the security group of the NAT instance |