diff --git a/docs/reference/services/ci-cd-pipeline/tailscale-subnet-router.md b/docs/reference/services/ci-cd-pipeline/tailscale-subnet-router.md deleted file mode 100644 index fd7ffeb0b8..0000000000 --- a/docs/reference/services/ci-cd-pipeline/tailscale-subnet-router.md +++ /dev/null @@ -1,514 +0,0 @@ ---- -type: "service" -name: "Tailscale Subnet Router" -description: "Deploy a Tailscale Subnet Router on AWS." -category: "remote-access" -cloud: "aws" -tags: ["vpn","ec2","ssh","security"] -license: "gruntwork" -built-with: "terraform, bash, packer" -title: "Tailscale Subnet Router" -hide_title: true ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import VersionBadge from '../../../../src/components/VersionBadge.tsx'; -import { HclListItem, HclListItemDescription, HclListItemTypeDetails, HclListItemDefaultValue } from '../../../../src/components/HclListItem.tsx'; - - - -# Tailscale Subnet Router - - -View Source - -Release Notes - -## Overview - -This service contains [Terraform](https://www.terraform.io) code to deploy a production-grade server that can act as a -[Tailscale](https://tailscale.com/) [subnet router](https://tailscale.com/kb/1019/subnets/) for a VPC on -[AWS](https://aws.amazon.com). - -Under the hood this module launches an EC2 instance (backed by an ASG) with Tailscale running in subnet router mode to -expose the VPC network to the [tailnet](https://tailscale.com/kb/1136/tailnet/). - -:::note - -This module depends on a [Tailscale](https://tailscale.com/) account. You must be signed up for the service to use -this VPN. The number of instances of this module you can deploy is dependent on how many subnet routers are -available on your plan. Refer to the [Tailscale pricing page](https://tailscale.com/pricing/) for more details on -available subnet routers for each plan. - -::: - -![Tailscale Subnet Router architecture](/img/reference/services/ci-cd-pipeline/tailscale-subnet-router-architecture.png) - -## Features - -* VPN without inbound security group rules. -* Authenticate to tailscale using auth keys stored in Secrets Manager -* Built in fault tolerance with Auto Scaling Group. -* Rolling deployment support with [Instance Refresh](https://docs.aws.amazon.com/autoscaling/ec2/userguide/asg-instance-refresh.html). -* Support for customizable IAM role. -* Support for customizable security groups. - -## Learn - -:::note - -This repo is a part of the [Gruntwork Service Catalog](https://github.com/gruntwork-io/terraform-aws-service-catalog/), -a collection of reusable, battle-tested, production ready infrastructure code. -If you’ve never used the Service Catalog before, make sure to read -[How to use the Gruntwork Service Catalog](https://docs.gruntwork.io/reference/services/intro/overview)! - -::: - -### Core concepts - -* [What is Tailscale?](https://tailscale.com/kb/1151/what-is-tailscale/) -* [What is a Tailscale subnet router?](https://tailscale.com/kb/1019/subnets/) -* [How does Tailscale work?](https://tailscale.com/blog/how-tailscale-works/) -* [How does Tailscale avoid inbound Security Group rules?](https://tailscale.com/blog/how-nat-traversal-works/) - -## Deploy - -### Non-production deployment (quick start for learning) - -If you just want to try this repo out for experimenting and learning, check out the following resources: - -* [examples/for-learning-and-testing folder](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/v0.90.6/examples/for-learning-and-testing): The - `examples/for-learning-and-testing` folder contains standalone sample code optimized for learning, experimenting, and - testing (but not direct production usage). - -## Manage - -### What ports should I expose on the Security Group to connect to the tailnet? - -You do not need to expose any inbound ports on the Security Group to access the VPC network through the subnet router. -[Tailnet solely depends on outbound stateful connections to manage network -access](https://tailscale.com/blog/how-nat-traversal-works/). - -However, you will need to create inbound security group rules that allow access from the Tailscale subnet router to -access services within your VPC through the tailnet. - -### What AMI should I use? - -Any AMI can be used with this module, provided that the [install-tailscale](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/v0.90.6/modules/mgmt/tailscale-subnet-router/scripts/install-tailscale.sh) script is installed -into the AMI. The `install-tailscale` script ensures that Tailscale is installed with the `init-tailscale-subnet-router` boot -script, which can be used to load the auth key from AWS Secrets Manager to authenticate to Tailscale at boot time. - -### How do I authenticate the server to Tailscale? - -This module expects the server to authenticate to Tailscale using [an auth -key](https://tailscale.com/kb/1085/auth-keys/) that is stored in AWS Secrets Manager. The auth key must be **Reusable** -to allow the server to automatically rejoin the network when recovering from a failure. - -We also recommend using a unique auth key for each subnet router instance, and to tag each key so that you can -differentiate between the different VPC networks in your [Tailscale ACL rules](https://tailscale.com/kb/1018/acls/). - -### How do I add IAM policies to the Tailscale subnet router IAM role? - -This module creates an IAM role that is assigned to the EC2 instance acting as the Tailscale subnet router. You can attach -custom policies to the IAM role directly by using the `aws_iam_role_policy` resource (for inline policies), or -the `aws_iam_role_policy_attachment` resource (for attaching dedicated IAM policies). - -For example: - -```hcl -module "tailscale" { - source = "git::git@github.com:gruntwork-io/terraform-aws-openvpn.git//modules/tailscale-subnet-router?ref=v1.0.8" - - # (... options omitted...) -} - -resource "aws_iam_policy" "my_custom_policy" { - name = "my-custom-policy" - policy = " (... omitted ...) " -} - -resource "aws_iam_role_policy_attachment" "attachment" { - role = module.tailscale.iam_role_id - policy_arn = aws_iam_policy.my_custom_policy.arn -} -``` - -## Reference - - - - -### Required - - - - -The AMI to run on the Tailscale subnet router. This should be built from the Packer template under tailscale-subnet-router-ubuntu.json. One of ami or ami_filters is required. Set to null if looking up the ami with filters. - - - - - - - -Properties on the AMI that can be used to lookup a prebuilt AMI for use with the Tailscale subnet router. You can build the AMI using the Packer template tailscale-subnet-router-ubuntu.json. Only used if ami is null. One of ami or ami_filters is required. Set to null if passing the ami ID directly. - - - - -```hcl -object({ - # List of owners to limit the search. Set to null if you do not wish to limit the search by AMI owners. - owners = list(string) - - # Name/Value pairs to filter the AMI off of. There are several valid keys, for a full reference, check out the - # documentation for describe-images in the AWS CLI reference - # (https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html). - filters = list(object({ - name = string - values = list(string) - })) - }) -``` - - - - - - - -The ARN of a Secrets Manager entry containing the Tailscale auth key to use for authenticating the server. - - - - - - - -The name of the server. This will be used to namespace all resources created by this module. - - - - - - - -The ids of the subnets where this server should be deployed. - - - - - - - -The id of the VPC where this server should be deployed. - - - - -### Optional - - - - -List of IDs of AWS Security Groups that should be attached to the tailscale relay server. - - - - - - - - -The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and disk space usage) should send notifications. - - - - - - - - -Cloud init scripts to run on the Tailscale subnet router while it boots. See the part blocks in https://www.terraform.io/docs/providers/template/d/cloudinit_config.html for syntax. - - - - -```hcl -map(object({ - filename = string - content_type = string - content = string - })) -``` - - - - - - - - -The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for encrypting log data. - - - - - - - - -The number of days to retain log events in the log group. Refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group#retention_in_days for all the valid values. When null, the log events are retained forever. - - - - - - - - -Tags to apply on the CloudWatch Log Group, encoded as a map where the keys are tag keys and values are tag values. - - - - - - - - -The default OS user for the Tailscale subnet router AMI. For AWS Ubuntu AMIs, which is what the Packer template in tailscale-subnet-router-ubuntu.json uses, the default OS user is 'ubuntu'. - - - - - - - - -If true, the launched EC2 instance will be EBS-optimized. Note that for most instance types, EBS optimization does not incur additional cost, and that many newer EC2 instance types have EBS optimization enabled by default. However, if you are running previous generation instances, there may be an additional cost per hour to run your instances with EBS optimization enabled. Please see: https://aws.amazon.com/ec2/pricing/on-demand/#EBS-Optimized_Instances - - - - - - - - -Set to true to enable several basic CloudWatch alarms around CPU usage, memory usage, and disk space usage. If set to true, make sure to specify SNS topics to send notifications to using alarms_sns_topic_arn. - - - - - - - - -Set to true to send logs to CloudWatch. This is useful in combination with https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/logs/cloudwatch-log-aggregation-scripts to do log aggregation in CloudWatch. - - - - - - - - -Set to true to add IAM permissions to send custom metrics to CloudWatch. This is useful in combination with https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/agents/cloudwatch-agent to get memory and disk metrics in CloudWatch for your Tailscale subnet router. - - - - - - - - -Enable fail2ban to block brute force log in attempts. Defaults to true. - - - - - - - - -Set this variable to true to enable the Instance Metadata Service (IMDS) endpoint, which is used to fetch information such as user-data scripts, instance IP address and region, etc. Set this variable to false if you do not want the IMDS endpoint enabled for instances launched into the Auto Scaling Group. - - - - - - - - -Enable ip-lockdown to block access to the instance metadata. Defaults to true. - - - - - - - - -Set to true to add IAM permissions for ssh-grunt (https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/ssh-grunt), which will allow you to manage SSH access via IAM groups. - - - - - - - - -Whether to configure DNS to Tailscale on the EC2 instance. By default we disable the tailnet DNS as it is generally best to let Amazon handle the DNS configuration on EC2 instances. This is most useful when the subnet router needs to communicate with other services on your tailnet. - - - - - - - - -If you are using ssh-grunt and your IAM users / groups are defined in a separate AWS account, you can use this variable to specify the ARN of an IAM role that ssh-grunt can assume to retrieve IAM group and public SSH key info from that account. To omit this variable, set it to an empty string (do NOT use null, or Terraform will complain). - - - - - - - - -The type of EC2 instance to run (e.g. t2.micro) - - - - - - - - -The number of seconds until a newly launched instance is configured and ready to use. - - - - - - - - -The name of a Key Pair that can be used to SSH to this instance. Leave blank if you don't want to enable Key Pair auth. - - - - - - - - -List of CIDR blocks to expose as routes on the tailnet through this server. If null, defaults to the entire VPC CIDR block. - - - - - - - - -When true, precreate the CloudWatch Log Group to use for log aggregation from the EC2 instances. This is useful if you wish to customize the CloudWatch Log Group with various settings such as retention periods and KMS encryption. When false, the CloudWatch agent will automatically create a basic log group to use. - - - - - - - - -If you are using ssh-grunt, this is the name of the IAM group from which users will be allowed to SSH to this Tailscale subnet router. This value is only used if enable_ssh_grunt=true. - - - - - - - - -If you are using ssh-grunt, this is the name of the IAM group from which users will be allowed to SSH to this Tailscale subnet router with sudo permissions. This value is only used if enable_ssh_grunt=true. - - - - - - - - -Advertised hostname of the server on the tailnet. If null, defaults to the name input value. - - - - - - - - -Set this variable to true to enable the use of Instance Metadata Service Version 1 in this module's aws_launch_configuration. Note that while IMDsv2 is preferred due to its special security hardening, we allow this in order to support the use case of AMIs built outside of these modules that depend on IMDSv1. - - - - - - - - - - - -The ARN of the ASG managing the Tailscale relay server. - - - - - - - -The name of the ASG managing the Tailscale relay server. - - - - - - - -ARN of the IAM role attached to the Tailscale relay server. - - - - - - - -ID of the IAM role attached to the Tailscale relay server. - - - - - - - -ID of the primary security group attached to the Tailscale relay server. - - - - - - - - - diff --git a/package.json b/package.json index 75f624824a..1e040d2eb9 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,7 @@ "yargs": "^17.4.0" }, "optionalDependencies": { - "docs-sourcer": "git+ssh://git@github.com/gruntwork-io/docs-sourcer.git#v0.0.27" + "docs-sourcer": "git+ssh://git@github.com/gruntwork-io/docs-sourcer.git#v0.0.29" }, "browserslist": { "production": [ diff --git a/static/img/reference/services/ci-cd-pipeline/tailscale-subnet-router-architecture.png b/static/img/reference/services/security/tailscale-subnet-router-architecture.png similarity index 100% rename from static/img/reference/services/ci-cd-pipeline/tailscale-subnet-router-architecture.png rename to static/img/reference/services/security/tailscale-subnet-router-architecture.png diff --git a/yarn.lock b/yarn.lock index 9dea47e28a..e3c69e06a7 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5436,9 +5436,9 @@ dns-txt@^2.0.2: dependencies: buffer-indexof "^1.0.0" -"docs-sourcer@git+ssh://git@github.com/gruntwork-io/docs-sourcer.git#v0.0.27": +"docs-sourcer@git+ssh://git@github.com/gruntwork-io/docs-sourcer.git#v0.0.29": version "0.0.1" - resolved "git+ssh://git@github.com/gruntwork-io/docs-sourcer.git#11f327f296a93c753b3a1a9adbd4bedb17a7ec69" + resolved "git+ssh://git@github.com/gruntwork-io/docs-sourcer.git#fd669b06af28f8f4cacf236914051bafb9fcc773" dependencies: "@octokit/auth-app" "^3.6.1" "@octokit/plugin-retry" "^3.0.9"