Tailscale

Deploy Tailscale on Control Plane using the Template Catalog. Covers configuration, scaling, and mesh VPN gateway setup for routing Tailscale clients to GVC workloads.

Overview

Tailscale is a mesh VPN built on WireGuard. This template deploys a Tailscale gateway workload on Control Plane that joins your Tailscale network and advertises internal Control Plane routes, allowing any connected Tailscale client to reach your GVC workloads via their cpln.local internal endpoints.

The gateway runs in a single configured location. Other locations are suspended so only one Tailscale node is active at a time.

The auth key is not a template value. Tailscale reads it from an opaque secret you create before installing, so the key never passes through Helm or lands in the release.

Template version 1.3.0 is a breaking change. AuthKey was removed, and an install or upgrade that still sets it now fails at render. Two defaults also changed: the image tag is pinned, and TS_HOSTNAME no longer defaults to a leftover test name. If you are running 1.2.x, read Upgrading From 1.2.x before you touch the release.

What Gets Created

• Standard Workload — The Tailscale gateway (RELEASE_NAME-tailscale), active in the configured location only. Advertises Control Plane’s internal network CIDRs and the location’s internal DNS server to Tailscale.
• Secret — A dictionary secret storing the Tailscale auth key, injected into the container at startup.
• Identity & Policy — An identity bound to the workload with reveal access to the auth key secret.
• Serverless Workload (optional) — An httpbin test workload (RELEASE_NAME-httpbin) accessible only from the Tailscale workload, useful for verifying connectivity.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

Complete the following in your Tailscale account before installing:

1. Create an Auth Key

In the Tailscale Admin UI → Settings → Keys, create a new auth key with Reusable and Ephemeral enabled. Save the key value, then store it in an opaque secret — it is not a template value:

printf '%s' 'tskey-auth-YOUR-KEY-HERE' | cpln secret create-opaque --name my-tailscale-authkey --encoding plain -f -

Set authKeySecretName to the name you used. Secret names are org-wide, so give each release its own.

If the secret does not exist at install time the deployment wedges silently — cpln logs returns zero lines. Read status.versions[].message via cpln workload get-deployments RELEASE_NAME-tailscale --gvc GVC_NAME -o yaml; plain cpln workload get has no versions key.

2. Update the Tailscale ACL

Add autoApprovers to your Tailscale ACL so that advertised routes are approved automatically:

{
  "autoApprovers": {
    "routes": {
      "192.168.0.0/16": ["autogroup:member"],
      "240.240.0.0/16": ["autogroup:member"],
      "10.0.0.0/16": ["autogroup:member"],
      "172.20.0.10/32": ["autogroup:member"],
      "10.1.0.10/32": ["autogroup:member"],
      "10.194.112.10/32": ["autogroup:member"]
    }
  }
}

If your location uses a DNS IP not listed above, add its /32 entry here as well.

3. Configure Tailscale DNS

In the Tailscale Admin UI → DNS tab, add a custom nameserver scoped to the cpln.local domain. Use the DNS IP for your selected location from the locationDNS map in values (e.g. 172.20.0.10 for most AWS locations).

If you need to reach per-replica stateful workload endpoints, add an additional custom nameserver scoped to <GVC_NAME>.svc.cluster.local using the same DNS IP.

Installation

To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Upgrading From 1.2.x

Version 1.3.0 removes AuthKey and changes two defaults.

	1.2.x	1.3.0
Auth key	AuthKey value, written into a chart-owned secret	authKeySecretName → an opaque secret you create
image.tag	stable — floating	v1.102.3 — pinned
TS_HOSTNAME	cpln-test-new	cpln-tailscale

Carrying AuthKey forward stops the upgrade. It is rejected at render, so cpln helm upgrade fails and your existing gateway is left untouched and running:

Error: execution error at (tailscale/templates/identity.yaml:1:4): tailscale: AuthKey was REMOVED
— it is now an `opaque` secret you create, named by authKeySecretName, whose entire value is the
auth key. Delete AuthKey from your values. See Prerequisites in the README.

Create the secret (Prerequisites), delete AuthKey, and set authKeySecretName. You can reuse the same key or generate a new one — unlike a database password, a Tailscale auth key only authorizes the device at join time, so replacing it is safe for a node that has already joined.

TS_HOSTNAME previously defaulted to cpln-test-new, a leftover from testing that became the advertised tailnet name of every install that did not override it. If you see cpln-test-new in your Tailscale admin console, that is a pre-1.3.0 deployment. Changing it renames the device on your tailnet.

Configuration

The default values.yaml for this template:

# The single location where the Tailscale gateway will be active
location: aws-us-east-1

image:
  repository: tailscale/tailscale
  tag: v1.102.3 # pinned: `stable` floats, so installs are not reproducible

resources:
  cpu: 500m
  memory: 128Mi

extraEnv:
  - name: TS_HOSTNAME
    value: cpln-tailscale # the name this device advertises on your tailnet
  # - name: TS_EXTRA_ARGS
  #   value: --advertise-exit-node

# Internal DNS server IPs per location — used to advertise a DNS route to Tailscale clients
locationDNS:
  aws-us-west-2: 172.20.0.10
  aws-us-east-1: 172.20.0.10
  aws-us-east-2: 172.20.0.10
  aws-sa-east-1: 172.20.0.10
  aws-eu-west-2: 172.20.0.10
  aws-eu-central-1: 172.20.0.10
  aws-il-central-1: 172.20.0.10
  gcp-us-west1: 10.67.224.10
  gcp-us-east1: 10.194.112.10
  gcp-us-central1: 10.228.48.10
  gcp-me-west1: 10.110.48.10
  azure-centralus: 10.1.0.10
  azure-eastus2: 10.1.0.10

deployHttpbinExample: true

authKeySecretName: my-tailscale-authkey # see Prerequisites — must exist before install

Auth Key

• authKeySecretName — Name of the opaque secret holding your Tailscale auth key. The key must be created with the Reusable and Ephemeral options enabled. See Prerequisites.

Location

• location — The single Control Plane location where the Tailscale gateway will run. All other locations in the GVC are suspended. Must match one of the locations configured in your GVC.

The Tailscale workload will appear as Partially Suspended in the console — this is expected behavior.

Advertised Routes

The gateway automatically advertises the following routes to Tailscale:

Route	Purpose
192.168.0.0/16	Control Plane internal network
240.240.0.0/16	Control Plane internal network
<locationDNS[location]>/32	Internal DNS server for the selected location

The /32 DNS host route allows Tailscale clients to resolve cpln.local endpoints after configuring a custom nameserver in Tailscale DNS.

Location DNS

• locationDNS — A map of Control Plane location names to their internal DNS server IPs. The IP for the selected location is advertised as a host route (/32) to enable cpln.local name resolution on Tailscale clients.

If your location is not listed, add it to the map with the correct DNS IP for that location.

Resources and Image

• resources.cpu / resources.memory — CPU and memory for the Tailscale gateway container.
• image.repository / image.tag — Tailscale container image. Defaults to tailscale/tailscale:stable.

Extra Environment Variables

• extraEnv — Additional environment variables passed to the Tailscale container. Common options:
  • TS_HOSTNAME — The hostname the gateway registers under in your Tailscale network.
  • TS_EXTRA_ARGS — Additional Tailscale daemon flags, e.g. --advertise-exit-node to use the gateway as an exit node.

Example Workload

• deployHttpbinExample — When true, deploys an httpbin test workload that only accepts internal connections from the Tailscale gateway. Use it to verify connectivity after setup.

Accessing GVC Workloads

Once the gateway is running and connected to Tailscale:

1. Ensure your local machine is connected to the same Tailscale network.
2. Any GVC workload that grants internal access to the Tailscale workload can be reached via its cpln.local address:

WORKLOAD_NAME.GVC_NAME.cpln.local:PORT

To grant access, add the Tailscale workload to a target workload’s internal firewall:

firewallConfig:
  internal:
    inboundAllowType: workload-list
    inboundAllowWorkload:
      - //gvc/GVC_NAME/workload/RELEASE_NAME-tailscale

External References

Tailscale Documentation

Official Tailscale documentation

Tailscale Admin UI

Manage your Tailscale network, keys, ACLs, and DNS

Tailscale Template

View the source files, default values, and chart definition