{"id":15556193,"url":"https://github.com/so0k/aws-nat-router","last_synced_at":"2026-05-01T01:31:10.672Z","repository":{"id":146553507,"uuid":"149649933","full_name":"so0k/aws-nat-router","owner":"so0k","description":"Manage AWS Egress routes using EC2 tag based discovery and TCP HealthChecks of NAT Instances","archived":false,"fork":false,"pushed_at":"2018-10-02T11:48:39.000Z","size":39,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T03:21:16.253Z","etag":null,"topics":["aws","ec2-instance-metadata","nat-instance"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/so0k.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-20T18:02:57.000Z","updated_at":"2020-01-31T08:36:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"3721e92c-ac9e-40ac-a7e1-d26dc00eb360","html_url":"https://github.com/so0k/aws-nat-router","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/so0k/aws-nat-router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/so0k%2Faws-nat-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/so0k%2Faws-nat-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/so0k%2Faws-nat-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/so0k%2Faws-nat-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/so0k","download_url":"https://codeload.github.com/so0k/aws-nat-router/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/so0k%2Faws-nat-router/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32482460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","ec2-instance-metadata","nat-instance"],"created_at":"2024-10-02T15:12:28.227Z","updated_at":"2026-05-01T01:31:10.655Z","avatar_url":"https://github.com/so0k.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS NAT Route Controller\n\nNote: This is alpha software\n\n[![CircleCI](https://circleci.com/gh/so0k/aws-nat-router.svg?style=svg)](https://circleci.com/gh/so0k/aws-nat-router)\n\n## Overview\n\nThis controller will discover tagged NAT Instances and Routing Tables, filter down to healthy NAT Instances and allocate egress routes through the available NAT Instances for each Routing Table. To ensure only 1 router updates the routes, instances are sorted by LaunchDate and the oldest healthy instance will be considered the leader.\n\nFollowing tags are expected on both EC2 Instance and Routing Table resources:\n\n| Key                  | Description                                      | Default |\n|----------------------|--------------------------------------------------|---------|\n|`aws-nat-router/id`   | Multiple controller can watch multiple resources | `squid` |\n|`aws-nat-router/zone` | Used to simplify zone lookup of Instance / rtb   | `-`     |\n\n## Allocation algorithm\n\nCurrently, the router will prefer to allocate the NAT Instance in the same zone as the routing table.\nIf there is no healthy NAT Instance in the same zone, it will allocate to any NAT Instance which has the least routing tables.\nIf there are multiple healthy NAT Instances per zone, it will try to allocate the routing tables equally across all available NAT Instances\n\n# Terraform Instance Profile\n\n`aws-nat-router` should run on each NAT Instance, which requires the following rights:\n\n```hcl\nactions = [\n      \"ec2:DescribeInstances\",\n      \"ec2:DescribeRouteTables\",\n      \"ec2:CreateRoute\",\n      \"ec2:ReplaceRoute\",\n      \"ec2:ModifyInstanceAttribute\", # to disable SourceDestChecks on Instances launched through ASGs\n    ]\n```\n\nA more complete Instance Role setup would look like this:\n\n```hcl\nresource \"aws_iam_instance_profile\" \"router\" {\n  name = \"nat-router-role\"\n  role = \"${aws_iam_role.router.name}\"\n}\n\nresource \"aws_iam_role\" \"router\" {\n  name               = \"nat-router-role\"\n  assume_role_policy = \"${data.aws_iam_policy_document.assume_ec2_role.json}\"\n}\n\ndata \"aws_iam_policy_document\" \"assume_ec2_role\" {\n  statement {\n    actions = [\"sts:AssumeRole\"]\n\n    principals {\n      type        = \"Service\"\n      identifiers = [\"ec2.amazonaws.com\"]\n    }\n  }\n}\n\nresource \"aws_iam_role_policy\" \"ec2_router\" {\n  name   = \"nat-router-role-ec2\"\n  role   = \"${aws_iam_role.squid.name}\"\n  policy = \"${data.aws_iam_policy_document.ec2_router.json}\"\n}\n\ndata \"aws_iam_policy_document\" \"ec2_router\" {\n  statement {\n    sid = \"1\"\n\n    actions = [\n      \"ec2:DescribeInstances\",\n      \"ec2:DescribeRouteTables\",\n      \"ec2:CreateRoute\",\n      \"ec2:ReplaceRoute\",\n      \"ec2:ModifyInstanceAttribute\",\n    ]\n\n    resources = [\n      \"*\",\n    ]\n  }\n}\n```\n\nSystemd Unit\n\n```ini\n[Unit]\nDescription=AWS NAT Router\nDocumentation=https://github.com/so0k/aws-nat-router\nRequires=network-online.target\nAfter=network-online.target\n[Service]\n# -z: request a file modified later than the given filename modification date (mtime)\nExecStartPre=/usr/bin/curl -sLo /usr/local/bin/aws-nat-router /\n  -z /usr/local/bin/aws-nat-router /\n  https://github.com/so0k/aws-nat-router/releases/download/0.1.4/aws-nat-router\nExecStartPre=/usr/bin/chmod +x /usr/local/bin/aws-nat-router\nEnvironment=LOG_LEVEL=INFO\nExecStart=/usr/local/bin/aws-nat-router \\\n  --vpc-id ${vpc_id} \\\n  --cluster-id ${cluster_id} \\\n  --ec2-election \\\n  --timeout 500ms \\\n  --interval 5s\nRestart=always\nRestartSec=10\n# amount of time (seconds) systemd waits after start before marking it as failed\nTimeoutStartSec=20\n```\n\n## Todo\n\n`runOnce` implementation:\n\n- [x] Discover Tagged Instances\n- [x] Discover Tagged Routing Tables\n- [x] Implement TCP HealthCheck\n- [x] Filter down to only Healthy NAT Instances\n- [x] Implement `PreventSourceDestCheck`\n- [x] Allocate Routing Tables to Instances\n- [x] Update Routing Tables with allocations\n- [ ] Implement recovery actions (Restart or Terminate unhealthy nodes)\n\nController implementation:\n\n- [x] Use AWS secrets from commandline args / env vars or ec2 Role\n- [x] Take region / vpc-id / cluster-id arguments for discovery\n- [x] Take interval arguments and loop `runOnce` on interval\n\nDeployment:\n\nThe controller is meant to run on EC2 Instances, prior to k8s bootstrap, thus we can't use Docker / Kubernetes as a deployment mechanism.\n\n- [x] Add GitHub release to CircleCI\n- [x] Add Sample Systemd unit file\n\n## Reference\n\nbased on AWS `nat_monitor.sh`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fso0k%2Faws-nat-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fso0k%2Faws-nat-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fso0k%2Faws-nat-router/lists"}