cdk-tailscale-bastion

This packages creates an AWS EC2 (Bastion) configured for Tailscale. This covers the Tailscale AWS VPC guide as well as most of the Tailscale RDS guide.

Using Tailscale to access your VPC permits high performance connectivity whilst avoiding SSH or the overhead & limitations of Session Manager.

Installation

JS/TS: npm i cdk-tailscale-bastion -D

C#: dotnet add package CDK.Tailscale.Bastion

Instructions

The Tailscale Auth key should be passed in via secrets manager and NOT hardcoded in your application.

import { TailscaleBastion } from 'cdk-tailscale-bastion';

// Secrets Manager
const secret = Secret.fromSecretNameV2(stack, 'ApiSecrets', 'tailscale');

const bastion = new TailscaleBastion(stack, 'Sample-Bastion', {
  vpc,
  tailscaleCredentials: {
    secretsManager: {
      secret: secret,
      key: 'AUTH_KEY',
    },
  },
});

Whatever resource you intend to reach should permit connections from the bastion on the relevant port, naturally.

Tailscale Auth Key

I recommend generating an Ephemeral key that includes the bastion as a tag for ease of teardown and tracking:

Tailscale Configuration

Once deployed, unless you have auto approval enabled, you'll need to manually enable the subnet routes in the tailscale console.

You'll also need to setup the nameserver. The bastion construct conveniently outputs the settings you require for Tailscale's DNS configuration:

Given your configuration is correct, a direct connection to your internal resources should now be possible.

4via6 Support

If you wish to use 4via6 subnet routers, you can pass the IPv6 address via the advertiseRoute property:

new TailscaleBastion(stack, 'Cdk-Sample-Lib', {
  vpc,
  tailscaleCredentials: ...,
  advertiseRoute: 'fd7a:115c:a1e0:b1a:0:7:a01:100/120',
});

Incoming routes

If you have other subnet routers configured in Tailscale, you can use the incomingRoutes property to configure VPC route table entries for all private subnets.

new TailscaleBastion(stack, 'Sample-Bastion', {
  vpc,
  tailscaleCredentials: ...,
  incomingRoutes: [
    '192.168.1.0/24',
  ],
});

API Reference

Constructs

TailscaleBastion

Initializers

import { TailscaleBastion } from 'cdk-tailscale-bastion'

new TailscaleBastion(scope: Construct, id: string, props: TailscaleBastionProps)

Name	Type	Description
`scope`	`constructs.Construct`	No description.
`id`	`string`	No description.
`props`	`TailscaleBastionProps`	No description.

`scope`^Required

Type: constructs.Construct

`id`^Required

Type: string

`props`^Required

Type: TailscaleBastionProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.

`toString`

public toString(): string

Returns a string representation of this construct.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.

`isConstruct`

import { TailscaleBastion } from 'cdk-tailscale-bastion'

TailscaleBastion.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

`x`^Required

Type: any

Any object.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`bastion`	`aws-cdk-lib.aws_ec2.BastionHostLinux`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`bastion`^Required

public readonly bastion: BastionHostLinux;

Type: aws-cdk-lib.aws_ec2.BastionHostLinux

Structs

SecretsManagerAuthKey

Initializer

import { SecretsManagerAuthKey } from 'cdk-tailscale-bastion'

const secretsManagerAuthKey: SecretsManagerAuthKey = { ... }

Properties

Name	Type	Description
`key`	`string`	The key of the auth key value located within the provided secret.
`secret`	`aws-cdk-lib.aws_secretsmanager.ISecret`	Secret manager location where the tailscale auth key is stored.

`key`^Required

public readonly key: string;

Type: string

The key of the auth key value located within the provided secret.

`secret`^Required

public readonly secret: ISecret;

Type: aws-cdk-lib.aws_secretsmanager.ISecret

Secret manager location where the tailscale auth key is stored.

Must be in the standard key/value JSON format.

TailscaleBastionProps

Initializer

import { TailscaleBastionProps } from 'cdk-tailscale-bastion'

const tailscaleBastionProps: TailscaleBastionProps = { ... }

Properties

Name	Type	Description
`tailscaleCredentials`	`TailscaleCredentials`	Credential settings for the tailscale auth key.
`vpc`	`aws-cdk-lib.aws_ec2.IVpc`	VPC to launch the instance in.
`additionalInit`	`aws-cdk-lib.aws_ec2.InitElement[]`	Additional cloudformation init actions to perform during startup.
`advertiseRoute`	`string`	Advertise a custom route instead of using the VPC CIDR, used for Tailscale 4via6 support.
`availabilityZone`	`string`	In which AZ to place the instance within the VPC.
`cpuType`	`aws-cdk-lib.aws_ec2.AmazonLinuxCpuType`	CPU Type of the instance.
`incomingRoutes`	`string[]`	List of incoming routes from Tailscale network.
`instanceName`	`string`	The name of the instance.
`instanceType`	`aws-cdk-lib.aws_ec2.InstanceType`	Type of instance to launch.
`securityGroup`	`aws-cdk-lib.aws_ec2.ISecurityGroup`	Security Group to assign to this instance.
`subnetSelection`	`aws-cdk-lib.aws_ec2.SubnetSelection`	Select the subnets to run the bastion host in.

`tailscaleCredentials`^Required

public readonly tailscaleCredentials: TailscaleCredentials;

Type: TailscaleCredentials

Credential settings for the tailscale auth key.

One type must be used. Ephemeral keys are recommended.

`vpc`^Required

public readonly vpc: IVpc;

Type: aws-cdk-lib.aws_ec2.IVpc

VPC to launch the instance in.

`additionalInit`^Optional

public readonly additionalInit: InitElement[];

Type: aws-cdk-lib.aws_ec2.InitElement[]

Additional cloudformation init actions to perform during startup.

`advertiseRoute`^Optional

public readonly advertiseRoute: string;

Type: string

Advertise a custom route instead of using the VPC CIDR, used for Tailscale 4via6 support.

`availabilityZone`^Optional

public readonly availabilityZone: string;

Type: string
Default: Random zone.

In which AZ to place the instance within the VPC.

`cpuType`^Optional

public readonly cpuType: AmazonLinuxCpuType;

Type: aws-cdk-lib.aws_ec2.AmazonLinuxCpuType
Default: AmazonLinuxCpuType.X86_64

CPU Type of the instance.

`incomingRoutes`^Optional

public readonly incomingRoutes: string[];

Type: string[]
Default: none

List of incoming routes from Tailscale network.

VPC route table will get these targets added.

`instanceName`^Optional

public readonly instanceName: string;

Type: string
Default: 'BastionHostTailscale'

The name of the instance.

`instanceType`^Optional

public readonly instanceType: InstanceType;

Type: aws-cdk-lib.aws_ec2.InstanceType
Default: 't3.nano'

Type of instance to launch.

`securityGroup`^Optional

public readonly securityGroup: ISecurityGroup;

Type: aws-cdk-lib.aws_ec2.ISecurityGroup
Default: create new security group with no inbound and all outbound traffic allowed

Security Group to assign to this instance.

`subnetSelection`^Optional

public readonly subnetSelection: SubnetSelection;

Type: aws-cdk-lib.aws_ec2.SubnetSelection
Default: PUBLIC subnets of the supplied VPC

Select the subnets to run the bastion host in.

PUBLIC subnets are used by default to allow for a direct Tailscale connection. DERP nodes will be used in a private subnet.

TailscaleCredentials

Initializer

import { TailscaleCredentials } from 'cdk-tailscale-bastion'

const tailscaleCredentials: TailscaleCredentials = { ... }

Properties

Name	Type	Description
`secretsManager`	`SecretsManagerAuthKey`	Fetches the Auth Key from secrets manager.
`unsafeString`	`string`	Provides an auth key as a plaintext string.

`secretsManager`^Optional

public readonly secretsManager: SecretsManagerAuthKey;

Type: SecretsManagerAuthKey

Fetches the Auth Key from secrets manager.

This value will be fetched during bastion startup.

`unsafeString`^Optional

public readonly unsafeString: string;

Type: string

Provides an auth key as a plaintext string.

This option will expose the auth key in your CDK template and should only be used with non-reusable keys. Potentially useful for DevOps runbooks and temporary instances.

Files

API.md

Latest commit

History

API.md

File metadata and controls

cdk-tailscale-bastion

Installation

Instructions

Tailscale Auth Key

Tailscale Configuration

4via6 Support

Incoming routes

API Reference

Constructs

TailscaleBastion

Initializers

scopeRequired

idRequired

propsRequired

Methods

toString

Static Functions

isConstruct

xRequired

Properties

nodeRequired

bastionRequired

Structs

SecretsManagerAuthKey

Initializer

Properties

keyRequired

secretRequired

TailscaleBastionProps

Initializer

Properties

tailscaleCredentialsRequired

vpcRequired

additionalInitOptional

advertiseRouteOptional

availabilityZoneOptional

cpuTypeOptional

incomingRoutesOptional

instanceNameOptional

instanceTypeOptional

securityGroupOptional

subnetSelectionOptional

TailscaleCredentials

Initializer

Properties

secretsManagerOptional

unsafeStringOptional

`scope`^Required

`id`^Required

`props`^Required

`toString`

`isConstruct`

`x`^Required

`node`^Required

`bastion`^Required

`key`^Required

`secret`^Required

`tailscaleCredentials`^Required

`vpc`^Required

`additionalInit`^Optional

`advertiseRoute`^Optional

`availabilityZone`^Optional

`cpuType`^Optional

`incomingRoutes`^Optional

`instanceName`^Optional

`instanceType`^Optional

`securityGroup`^Optional

`subnetSelection`^Optional

`secretsManager`^Optional

`unsafeString`^Optional