https://github.com/masterpointio/terraform-aws-tailscale

Terraform module to provision a Tailscale Subnet Router into your AWS VPC
https://github.com/masterpointio/terraform-aws-tailscale

opentofu opentofu-module tailscale terraform terraform-module

Last synced: 3 months ago
JSON representation

Terraform module to provision a Tailscale Subnet Router into your AWS VPC

Host: GitHub
URL: https://github.com/masterpointio/terraform-aws-tailscale
Owner: masterpointio
License: apache-2.0
Created: 2020-12-01T12:19:56.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2025-04-01T09:40:30.000Z (3 months ago)
Last Synced: 2025-04-10T09:14:58.261Z (3 months ago)
Topics: opentofu, opentofu-module, tailscale, terraform, terraform-module
Language: HCL
Homepage:
Size: 154 KB
Stars: 46
Watchers: 4
Forks: 9
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

[![Masterpoint Logo](https://i.imgur.com/RDLnuQO.png)](https://masterpoint.io)

# terraform-aws-tailscale [![Latest Release](https://img.shields.io/github/release/masterpointio/terraform-aws-tailscale.svg)](https://github.com/masterpointio/terraform-aws-tailscale/releases/latest)

This is a Terraform Module to create a simple, autoscaled [Tailscale Subnet Router](https://tailscale.com/kb/1019/subnets/) on EC2 instance along with generated auth key, and its corresponding IAM resources. The instance should cycle itself on a schedule.

It's 100% Open Source and licensed under the [APACHE2](LICENSE).

## Usage

Here's how to invoke this example module in your projects

```hcl
module "vpc" {
source = "cloudposse/vpc/aws"
version = "2.1.1"

namespace = "eg"
stage = "test"
name = "tailscale"

ipv4_primary_cidr_block = "172.16.0.0/16"
}

module "subnets" {
source = "cloudposse/dynamic-subnets/aws"
version = "2.4.1"

namespace = "eg"
stage = "test"
name = "tailscale"

availability_zones = ["us-east-1a", "us-east-1b"]

vpc_id = module.vpc.vpc_id
igw_id = [module.vpc.igw_id]
ipv4_cidr_block = [module.vpc.vpc_cidr_block]
}

module "tailscale" {
source = "masterpointio/tailscale/aws"
version = "X.X.X"

namespace = "eg"
stage = "test"
name = "tailscale"

vpc_id = module.vpc.vpc_id
subnet_ids = module.subnets.private_subnet_ids
advertise_routes = [module.vpc.vpc_cidr_block]

ephemeral = true
}
```

## Examples

Here is an example of using this module:

- [`examples/complete`](https://github.com/masterpointio/terraform-aws-tailscale/) - complete example of using this module

## System Logging and Monitoring Setup

On Linux and other Unix-like systems, Tailscale typically runs as a systemd service, which by default does not rotate logs - potentially allowing system logs to grow until the disk fills.

To address this, our user data script configures both a maximum journal size and a retention period to ensure logs are periodically purged. We also install the [CloudWatch Agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) with its default configuration so that filesystem usage metrics are reported to AWS.

👀 To view these metrics, navigate in the AWS Console to “CWAgent” → “AutoScalingGroupName, ImageId, InstanceId, InstanceType, device, fstype, path” → “disk_used_percent” for the root path “/”.

## Direct and Relayed Connections

Tailscale supports two primary types of [connection types](https://tailscale.com/kb/1257/connection-types) for subnet routers:

- **Direct (peer-to-peer)**: Nodes communicate directly with each other when possible, offering better performance and reliability.
- **Relayed**: Traffic is routed through Tailscale's DERP (Designated Encrypted Relay for Packets) servers when direct connectivity isn't possible (e.g. when the subnet router is in a private VPC subnet).

### Addressing Connection Stability Issues

We've been using relayed connections for our subnet routers, but we've observed that relayed connections can sometimes cause intermittent connectivity issues, particularly when working with database connections through the Tailscale proxy (see [this issue](https://github.com/cyrilgdn/terraform-provider-postgresql/issues/495) for an example).

These issues appear as connection timeouts or SOCKS server errors:

```sh
│ Error: Error connecting to PostgreSQL server dev.example.com (scheme: postgres): socks connect tcp localhost:1055->dev.example.com:5432: unknown error general SOCKS server failure
│
│ with data.postgresql_schemas.schemas["example"],
│ on main.tf line 65, in data "postgresql_schemas" "schemas":
│ 65: data "postgresql_schemas" "schemas" {
│
╵
netstack: decrementing connsInFlightByClient[100.0.108.92] because the packet was not handled; new value is 0
[RATELIMIT] format("netstack: decrementing connsInFlightByClient[%v] because the packet was not handled; new value is %d")
```

### Configuring Direct Connections

To optimize for direct connections in your Tailscale subnet router, follow this example:

```hcl
locals {
public_subnets = ["subnet-1234567890", "subnet-0987654321"]
vpc_id = "vpc-1234567890"
direct_port = "41641"
}

module "tailscale" {
source = "masterpointio/tailscale/aws"
version = "1.6.0" # Or later
...
# Direct connection configuration
subnet_ids = local.public_subnets # Ensure subnet router is in a public subnet

additional_security_group_ids = [module.direct_sg.id] # Attach the security group to the subnet router
tailscaled_extra_flags = ["--port=${local.direct_port}"] # Ensure `tailscaled` listens on the same port as the security group is configured

context = module.this.context
}

module "direct_sg" {
source = "cloudposse/security-group/aws"
version = "2.2.0"
enabled = true

vpc_id = local.vpc_id
attributes = ["tailscale", "direct"]

rules = [{
key = "direct_ingress"
type = "ingress"
from_port = local.direct_port
to_port = local.direct_port
protocol = "udp"
cidr_blocks = ["0.0.0.0/0"]
description = "Allow a direct Tailscale connection from any peer."
}]

context = module.this.context
}
```

The above configuration ensures that the subnet router can establish direct connections with other Tailscale nodes:

1. It is in a public subnet and gets a public IP address.
2. The security group is attached and configured to listen on a fixed port.
3. The `tailscaled` daemon is configured to listen on the same port as the security group is configured to listen on.
4. The outgoing UDP and TCP packets on port `443` are permitted. In our example, [`cloudposse/security-group/aws`](https://github.com/cloudposse/terraform-aws-security-group) module allows all egress.

## Requirements

| Name | Version |
| ------------------------------------------------------------------------ | --------- |
| [terraform](#requirement_terraform) | >= 1.0 |
| [aws](#requirement_aws) | >= 4.0 |
| [tailscale](#requirement_tailscale) | >= 0.13.7 |

## Providers

| Name | Version |
| ------------------------------------------------------------------ | --------- |
| [aws](#provider_aws) | >= 4.0 |
| [tailscale](#provider_tailscale) | >= 0.13.7 |

## Modules

| Name | Source | Version |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------- |
| [ssm_policy](#module_ssm_policy) | cloudposse/iam-policy/aws | 2.0.1 |
| [ssm_state](#module_ssm_state) | cloudposse/ssm-parameter-store/aws | 0.13.0 |
| [tailscale_subnet_router](#module_tailscale_subnet_router) | masterpointio/ssm-agent/aws | 1.3.0 |
| [this](#module_this) | cloudposse/label/null | 0.25.0 |

## Resources

| Name | Type |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| [aws_iam_role_policy_attachment.cw_agent](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
| [aws_iam_role_policy_attachment.default](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
| [tailscale_tailnet_key.default](https://registry.terraform.io/providers/tailscale/tailscale/latest/docs/resources/tailnet_key) | resource |

## Inputs

| Name | Description | Type | Default | Required |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: |
| [additional_security_group_ids](#input_additional_security_group_ids) | Additional Security Group IDs to associate with the Tailscale Subnet Router EC2 instance. | `list(string)` | `[]` | no |
| [additional_tag_map](#input_additional_tag_map) | Additional key-value pairs to add to each map in `tags_as_list_of_maps`. Not added to `tags` or `id`.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration. | `map(string)` | `{}` | no |
| [additional_tags](#input_additional_tags) | Additional Tailscale tags to apply to the Tailscale Subnet Router machine in addition to `primary_tag`. These should not include the `tag:` prefix. | `list(string)` | `[]` | no |
| [advertise_routes](#input_advertise_routes) | The routes (expressed as CIDRs) to advertise as part of the Tailscale Subnet Router.
Example: ["10.0.2.0/24", "0.0.1.0/24"] | `list(string)` | `[]` | no |
| [ami](#input_ami) | The AMI to use for the Tailscale Subnet Router EC2 instance.
If not provided, the latest Amazon Linux 2 AMI will be used.
Note: This will update periodically as AWS releases updates to their AL2 AMI.
Pin to a specific AMI if you would like to avoid these updates. | `string` | `""` | no |
| [associate_public_ip_address](#input_associate_public_ip_address) | Associate public IP address with subnet router | `bool` | `null` | no |
| [attributes](#input_attributes) | ID element. Additional attributes (e.g. `workers` or `cluster`) to add to `id`,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the `delimiter`
and treated as a single ID element. | `list(string)` | `[]` | no |
| [context](#input_context) | Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as `null` to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged. | `any` |

{
 "additional_tag_map": {},
 "attributes": [],
 "delimiter": null,
 "descriptor_formats": {},
 "enabled": true,
 "environment": null,
 "id_length_limit": null,
 "label_key_case": null,
 "label_order": [],
 "label_value_case": null,
 "labels_as_tags": [
 "unset"
 ],
 "name": null,
 "namespace": null,
 "regex_replace_chars": null,
 "stage": null,
 "tags": {},
 "tenant": null
}

| no |
| [create_run_shell_document](#input_create_run_shell_document) | Whether or not to create the SSM-SessionManagerRunShell SSM Document. | `bool` | `true` | no |
| [delimiter](#input_delimiter) | Delimiter to be used between ID elements.
Defaults to `-` (hyphen). Set to `""` to use no delimiter at all. | `string` | `null` | no |
| [descriptor_formats](#input_descriptor_formats) | Describe additional descriptors to be output in the `descriptors` output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
`{
format = string
labels = list(string)
}`
(Type is `any` so the map values can later be enhanced to provide additional options.)
`format` is a Terraform format string to be passed to the `format()` function.
`labels` is a list of labels, in order, to pass to `format()` function.
Label values will be normalized before being passed to `format()` so they will be
identical to how they appear in `id`.
Default is `{}` (`descriptors` output will be empty). | `any` | `{}` | no |
| [desired_capacity](#input_desired_capacity) | Desired number of instances in the Auto Scaling Group | `number` | `1` | no |
| [enabled](#input_enabled) | Set to false to prevent the module from creating any resources | `bool` | `null` | no |
| [environment](#input_environment) | ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' | `string` | `null` | no |
| [ephemeral](#input_ephemeral) | Indicates if the key is ephemeral. | `bool` | `false` | no |
| [exit_node_enabled](#input_exit_node_enabled) | Advertise Tailscale Subnet Router EC2 instance as exit node. Defaults to false. | `bool` | `false` | no |
| [expiry](#input_expiry) | The expiry of the auth key in seconds. | `number` | `7776000` | no |
| [id_length_limit](#input_id_length_limit) | Limit `id` to this many characters (minimum 6).
Set to `0` for unlimited length.
Set to `null` for keep the existing setting, which defaults to `0`.
Does not affect `id_full`. | `number` | `null` | no |
| [instance_type](#input_instance_type) | The instance type to use for the Tailscale Subnet Router EC2 instance. | `string` | `"t4g.nano"` | no |
| [journald_max_retention_sec](#input_journald_max_retention_sec) | The maximum time to store journal entries. | `string` | `"7d"` | no |
| [journald_system_max_use](#input_journald_system_max_use) | Disk space the journald may use up at most | `string` | `"200M"` | no |
| [key_pair_name](#input_key_pair_name) | The name of the key-pair to associate with the Tailscale Subnet Router EC2 instance. | `string` | `null` | no |
| [label_key_case](#input_label_key_case) | Controls the letter case of the `tags` keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the `tags` input.
Possible values: `lower`, `title`, `upper`.
Default value: `title`. | `string` | `null` | no |
| [label_order](#input_label_order) | The order in which the labels (ID elements) appear in the `id`.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present. | `list(string)` | `null` | no |
| [label_value_case](#input_label_value_case) | Controls the letter case of ID elements (labels) as included in `id`,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the `tags` input.
Possible values: `lower`, `title`, `upper` and `none` (no transformation).
Set this to `title` and set `delimiter` to `""` to yield Pascal Case IDs.
Default value: `lower`. | `string` | `null` | no |
| [labels_as_tags](#input_labels_as_tags) | Set of labels (ID elements) to include as tags in the `tags` output.
Default is to include all labels.
Tags with empty values will not be included in the `tags` output.
Set to `[]` to suppress all generated tags.
**Notes:**
The value of the `name` tag, if included, will be the `id`, not the `name`.
Unlike other `null-label` inputs, the initial setting of `labels_as_tags` cannot be
changed in later chained modules. Attempts to change it will be silently ignored. | `set(string)` |

[
 "default"
]

| no |
| [max_size](#input_max_size) | Maximum number of instances in the Auto Scaling Group. Must be >= desired_capacity. | `number` | `2` | no |
| [min_size](#input_min_size) | Minimum number of instances in the Auto Scaling Group | `number` | `1` | no |
| [monitoring_enabled](#input_monitoring_enabled) | Enable detailed monitoring of instances | `bool` | `true` | no |
| [name](#input_name) | ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a `tag`.
The "name" tag is set to the full `id` string. There is no tag with the value of the `name` input. | `string` | `null` | no |
| [namespace](#input_namespace) | ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique | `string` | `null` | no |
| [preauthorized](#input_preauthorized) | Determines whether or not the machines authenticated by the key will be authorized for the tailnet by default. | `bool` | `true` | no |
| [primary_tag](#input_primary_tag) | The primary tag to apply to the Tailscale Subnet Router machine. Do not include the `tag:` prefix. This must match the OAuth client's tag. If not provided, the module will use the module's ID as the primary tag, which is configured in context.tf | `string` | `null` | no |
| [regex_replace_chars](#input_regex_replace_chars) | Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, `"/[^a-zA-Z0-9-]/"` is used to remove all characters other than hyphens, letters and digits. | `string` | `null` | no |
| [reusable](#input_reusable) | Indicates if the key is reusable or single-use. | `bool` | `true` | no |
| [session_logging_enabled](#input_session_logging_enabled) | To enable CloudWatch and S3 session logging or not.
Note this does not apply to SSH sessions as AWS cannot log those sessions. | `bool` | `true` | no |
| [session_logging_kms_key_alias](#input_session_logging_kms_key_alias) | Alias name for `session_logging` KMS Key.
This is only applied if 2 conditions are met: (1) `session_logging_kms_key_arn` is unset,
(2) `session_logging_encryption_enabled` = true. | `string` | `"alias/session_logging"` | no |
| [session_logging_ssm_document_name](#input_session_logging_ssm_document_name) | Name for `session_logging` SSM document.
This is only applied if 2 conditions are met: (1) `session_logging_enabled` = true,
(2) `create_run_shell_document` = true. | `string` | `"SSM-SessionManagerRunShell-Tailscale"` | no |
| [ssh_enabled](#input_ssh_enabled) | Enable SSH access to the Tailscale Subnet Router EC2 instance. Defaults to true. | `bool` | `true` | no |
| [ssm_state_enabled](#input_ssm_state_enabled) | Control if tailscaled state is stored in AWS SSM (including preferences and keys).
This tells the Tailscale daemon to write + read state from SSM,
which unlocks important features like retaining the existing tailscale machine name.
See more in the [docs](https://tailscale.com/kb/1278/tailscaled#flags-to-tailscaled). | `bool` | `false` | no |
| [stage](#input_stage) | ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release' | `string` | `null` | no |
| [subnet_ids](#input_subnet_ids) | The Subnet IDs which the Tailscale Subnet Router EC2 instance will run in. These _should_ be private subnets. | `list(string)` | n/a | yes |
| [tags](#input_tags) | Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`).
Neither the tag keys nor the tag values will be modified by this module. | `map(string)` | `{}` | no |
| [tailscale_up_extra_flags](#input_tailscale_up_extra_flags) | Extra flags to pass to `tailscale up` for advanced configuration.
See more in the [docs](https://tailscale.com/kb/1241/tailscale-up). | `list(string)` | `[]` | no |
| [tailscaled_extra_flags](#input_tailscaled_extra_flags) | Extra flags to pass to Tailscale daemon for advanced configuration. Example: ["--state=mem:"]
See more in the [docs](https://tailscale.com/kb/1278/tailscaled#flags-to-tailscaled). | `list(string)` | `[]` | no |
| [tenant](#input_tenant) | ID element \_(Rarely used, not included by default)\_. A customer identifier, indicating who this instance of a resource is for | `string` | `null` | no |
| [user_data](#input_user_data) | The user_data to use for the Tailscale Subnet Router EC2 instance.
You can use this to automate installation of all the required command line tools. | `string` | `""` | no |
| [vpc_id](#input_vpc_id) | The ID of the VPC which the Tailscale Subnet Router EC2 instance will run in. | `string` | n/a | yes |

## Outputs

| Name | Description |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [autoscaling_group_id](#output_autoscaling_group_id) | The ID of the Tailscale Subnet Router EC2 instance Autoscaling Group. |
| [instance_name](#output_instance_name) | The name tag value of the Tailscale Subnet Router EC2 instance. |
| [launch_template_id](#output_launch_template_id) | The ID of the Tailscale Subnet Router EC2 instance Launch Template. |
| [security_group_id](#output_security_group_id) | The ID of the Tailscale Subnet Router EC2 instance Security Group. |

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/masterpointio/terraform-aws-tailscale

Awesome Lists containing this project

README