Tailscale

Overview

Tailscale is a mesh VPN built on WireGuard. This template runs a Tailscale subnet router inside your GVC: it joins your tailnet, advertises Control Plane’s internal network routes plus the internal DNS server of one location, and lets any device on your tailnet reach GVC workloads by their cpln.local addresses without giving those workloads a public endpoint. The gateway runs in exactly one location, set by location. The auth key is not a template value; the gateway reads it from a secret you create before installing, so the key never passes through Helm or lands in the release.

This template does not create a GVC. It deploys into an existing GVC that you already have, and the location named by location must already be one of that GVC’s locations. Every other location on the GVC runs nothing for this workload.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-tailscale`	Tailscale subnet router (standard, 1 replica, active only in `location`)	—
Identity	`RELEASE_NAME-tailscale-identity`	Identity bound to the gateway workload	—
Policy	`RELEASE_NAME-tailscale-policy`	Grants the identity `reveal` on your auth key secret only	—
Workload	`RELEASE_NAME-httpbin`	Example target that accepts internal traffic only from the gateway	`deployHttpbinExample: true` (default)

The template creates no secret of its own. The auth key lives only in the prerequisite secret described below.

Prerequisites

You need a Tailscale account with admin access to its tailnet, plus one secret in your Control Plane org. Secrets are org-level, so no GVC flag is involved.

Generate a Tailscale auth key

In the Tailscale admin console, open Settings then Keys and select Generate auth key. Enable both Reusable and Ephemeral.The gateway keeps no Tailscale state on disk, so it joins the tailnet with this key every time its container starts. A reusable key lets it rejoin after a restart; an ephemeral key makes Tailscale remove the old device entry once it goes offline. The chart applies no ACL tags of its own, and the route approval example in the next step assumes an untagged key.

Store the auth key in an opaque secret

Paste your key in place of the placeholder. The whole value of the secret is the key:

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

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

Let Tailscale approve the advertised routes

The gateway advertises three routes: 192.168.0.0/16, 240.240.0.0/16, and a /32 host route to the internal DNS server of the selected location (looked up in locationDNS). Add an autoApprovers block to your tailnet policy file so they are approved automatically. This example covers the default aws-us-east-1 location, whose DNS server is 172.20.0.10:

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

For another location, replace 172.20.0.10/32 with that location’s entry from locationDNS. Without autoApprovers you can still approve the routes by hand after install (see Connecting).

Add split DNS for cpln.local

In the Tailscale admin console DNS page, add a custom nameserver, restrict it to the domain cpln.local, and set its address to the locationDNS IP of your selected location (172.20.0.10 for the default aws-us-east-1).

Create the secret before installing, or the deployment wedges silently. A name that points at a secret which does not exist installs successfully and then never starts. The container never runs, so cpln logs returns zero lines. The one place the reason appears is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-tailscale --gvc GVC_NAME -o yaml

Plain cpln workload get has no versions key. Once the secret exists, the deployment recovers on its own after a few minutes, or immediately with cpln workload force-redeployment RELEASE_NAME-tailscale --gvc GVC_NAME.

Installation

Install with the secret name from Prerequisites. Add --set location=... if the gateway should run somewhere other than aws-us-east-1:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/tailscale \
  --version 1.3.0 --gvc GVC_NAME \
  --set authKeySecretName=SECRET_NAME

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

Configuration

Auth Key

authKeySecretName: my-tailscale-authkey

Location

# Set this to a single location in your gvc
location: aws-us-east-1

The gateway runs in this location only and is suspended everywhere else, so the console shows the workload as Partially Suspended. The location must already be on your GVC and must have an entry in locationDNS.

Location DNS

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

Maps each location to its internal DNS server. The entry for location becomes the advertised /32 route and is the address you give Tailscale split DNS. Leave the map as shipped unless your location is missing from it.

Image and Resources

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

resources:
  cpu: 500m
  memory: 128Mi

Extra Environment Variables

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

Each entry is passed to the Tailscale container as an environment variable. Give each release a distinct TS_HOSTNAME so gateways are easy to tell apart in the Tailscale admin console. The commented exit-node example is not part of the default install and has not been verified with this template.

Example Workload

deployHttpbinExample: true

Creates RELEASE_NAME-httpbin, a small HTTP service that only the gateway may reach. Use it to prove the tailnet path works, then set it to false.

Connecting

What	Address	Notes
Any workload in the GVC	`WORKLOAD_NAME.GVC_NAME.cpln.local:PORT`	From a device on your tailnet, once the routes are approved, split DNS is set, and the target allows the gateway (below)
Example workload	`RELEASE_NAME-httpbin.GVC_NAME.cpln.local:80`	Created when `deployHttpbinExample: true`; already allows the gateway
Gateway on your tailnet	`cpln-tailscale`	The `TS_HOSTNAME` value, listed on the Machines page
Auth key	`cpln secret reveal SECRET_NAME -o yaml`	Your prerequisite secret

Approve the routes. If you did not set up autoApprovers, open the gateway on the Machines page, choose Edit route settings, and approve all three advertised routes. Until they are approved, the gateway shows as connected but carries no traffic to the GVC. Allow the gateway on each target workload. Traffic from tailnet devices reaches a workload from the gateway, so the target’s internal firewall must admit RELEASE_NAME-tailscale. For example:

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

Verify from a laptop or other device that is connected to the same tailnet:

curl http://RELEASE_NAME-httpbin.GVC_NAME.cpln.local/headers

A JSON response proves the routes, split DNS and gateway are all working. Check the gateway’s own output with:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-tailscale"}' --limit 50 --since 10m

Operations

Upgrading from 1.2.x

Version 1.3.0 removes the AuthKey value and changes two defaults.

	1.2.x	1.3.0
Auth key	`AuthKey` value, written into a chart-owned secret `RELEASE_NAME-tailscale`	`authKeySecretName` names an opaque secret you create; the chart creates no secret
`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 auth key secret

Follow Prerequisites. Use a new name, not RELEASE_NAME-tailscale, because the upgrade removes that chart-owned secret. You can reuse your current key or generate a new one.

Update your values

Delete AuthKey and set authKeySecretName. If you relied on the old cpln-test-new device name, set TS_HOSTNAME in extraEnv explicitly; otherwise the device appears on your tailnet as cpln-tailscale.

Upgrade

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/tailscale \
  --version 1.3.0 --gvc GVC_NAME \
  --set authKeySecretName=SECRET_NAME

Rotating the Auth Key

An auth key only authorizes the device when it joins, but the gateway rejoins with the key on every container start, so keep a valid key in the secret. To replace it, apply the whole secret with the new value:

cat > rotate.yaml <<'EOF'
kind: secret
name: SECRET_NAME
type: opaque
data:
  encoding: plain
  payload: NEW-VALUE
EOF
cpln apply -f rotate.yaml
cpln secret reveal SECRET_NAME -o yaml

A running gateway does not pick up the new value by itself. Force a redeployment so it rejoins with the new key:

cpln workload force-redeployment RELEASE_NAME-tailscale --gvc GVC_NAME

Scaling and Availability

The gateway is a single replica in a single location. Do not run it in several locations: a subnet router advertising the same routes from several places gives Tailscale competing paths. If that location is unavailable, tailnet access to the GVC stops until it returns. The workloads themselves are unaffected.

Troubleshooting

The gateway never starts and cpln logs returns nothing

Cause: the secret named by authKeySecretName does not exist, so the deployment is paused before the container starts.Fix: read status.versions[].message with cpln workload get-deployments RELEASE_NAME-tailscale --gvc GVC_NAME -o yaml. It names the missing secret, for example

The secret SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Create the secret as in Prerequisites.

The gateway is online in Tailscale but workloads are unreachable

Cause: the advertised routes are not approved, or the target workload’s internal firewall does not admit the gateway.Fix: approve the routes under Edit route settings on the Machines page, or add autoApprovers as in Prerequisites. Then allow //gvc/GVC_NAME/workload/RELEASE_NAME-tailscale in the target’s firewallConfig.internal, as shown in Connecting. Test against RELEASE_NAME-httpbin first, since it already allows the gateway.

cpln.local names do not resolve on a tailnet device

Cause: split DNS for cpln.local is missing, points at the wrong address, or the /32 DNS route is not approved.Fix: set the custom nameserver for cpln.local to the locationDNS entry for your location, and confirm that same address appears as an approved /32 route on the gateway.

The advertised routes end in a bare /32 with no address

Cause: location has no entry in locationDNS, so TS_ROUTES renders as 192.168.0.0/16,240.240.0.0/16,/32.Fix: add your location and its internal DNS server address to locationDNS, then upgrade the release.

No replica runs in any location

Cause: location names a location that is not on your GVC. The workload is suspended everywhere else, so nothing runs.Fix: compare location with spec.staticPlacement.locationLinks from cpln gvc get GVC_NAME -o yaml, set it to one of those locations, and upgrade.

The gateway dropped off the tailnet after running fine for weeks

Cause: the auth key expired. The gateway rejoins with the key whenever its container restarts, and an expired key can no longer join.Fix: generate a new reusable, ephemeral key and follow Rotating the Auth Key.

Important Notes

Create the auth key secret before installing; a missing secret wedges the deployment with no logs.
Generate the key as Reusable and Ephemeral, and replace it before it expires.
Approve the three advertised routes and add cpln.local split DNS, or tailnet devices cannot reach anything.
Every workload you want to reach must allow RELEASE_NAME-tailscale in its internal firewall.
After rotating the key in the secret, force a redeployment of RELEASE_NAME-tailscale.
Never upgrade from 1.2.x with AuthKey still in your values; follow Upgrading from 1.2.x.

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Auth Key

Location

Location DNS

Image and Resources

Extra Environment Variables

Example Workload

Connecting

Operations

Upgrading from 1.2.x

Rotating the Auth Key

Scaling and Availability

Troubleshooting

Important Notes

External References

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Auth Key

​Location

​Location DNS

​Image and Resources

​Extra Environment Variables

​Example Workload

​Connecting

​Operations

​Upgrading from 1.2.x

​Rotating the Auth Key

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Overview

What Gets Created

Prerequisites

Installation

Configuration

Auth Key

Location

Location DNS

Image and Resources

Extra Environment Variables

Example Workload

Connecting

Operations

Upgrading from 1.2.x

Rotating the Auth Key

Scaling and Availability

Troubleshooting

Important Notes

External References