Tailscale Knowledge Patch

Tailscale Knowledge Patch

Use this skill when planning, configuring, upgrading, automating, or debugging Tailscale clients, services, policy, containers, Terraform resources, or the Kubernetes Operator.

Confirm the versions of the components in the user's deployment before applying version-attributed guidance. A client, container image, Operator, Terraform provider, and integration can have different release versions. Prefer the project's manifests, configuration, observed behavior, and tests when they disagree with general guidance.

Reference index

Start with compatibility hazards

Paginate tailnet-listing clients

The list-tailnets endpoint returns 100 tailnets by default as of 1.102.2. API clients must follow each returned cursor until it is empty. Use totalCount when the overall count is required. Do not assume one response is complete.

Replace removed 4via6 names

Deprecated 4via6 MagicDNS name formats are rejected as of 1.102.2. Locate stored hostnames in application, connector, and egress configuration and move them to a supported name form before upgrading.

Recheck Tailscale SSH identities

As of 1.102.2, Tailscale SSH rejects numeric-only usernames and UIDs. Unix-socket forwarding also honors symlink permissions. Validate account mappings and socket paths instead of relying on earlier permissive behavior.

Account for interactive CLI prompts

Significant CLI actions can request y/n confirmation as of 1.88.1. Automation must not assume every previously non-interactive command still completes without input; inspect the affected command and choose an explicitly supported non-interactive path.

Do not duplicate CLI flags

Commands reject repeated occurrences of the same flag as of 1.84.0. Normalize arguments assembled from wrappers, environment variables, and scripts. Container image 1.84.2 specifically restored using TS_EXTRA_ARGS to set --accept-dns after the stricter parser broke that case.

Update removed or relocated controls

• Operator 1.96.5 removes TS_EXPERIMENTAL_KUBE_API_EVENTS; configure Kubernetes API event capability through Tailscale ACLs.
• On macOS, tailscale drive is unavailable as of 1.90.1; share Taildrive directories through the GUI.
• ForceEnabled is deprecated on macOS and iOS; use AlwaysOn.Enabled and, where appropriate, AlwaysOn.OverrideWithReason.
• TailscaleOnboardingSeen is deprecated on macOS; use OnboardingFlow.
• Store the external GitOps policy URL in the admin console. That value wins over the deprecated policy-file code comment.

Identity and policy quick reference

Prefer grants for new policy

Grants are the default syntax for new tailnets and policy files that have never been edited. The via field can require traffic to pass through selected exit nodes, subnet routers, or app connectors. Existing effective permissions do not change solely because the default authoring syntax changed.

Treat key protection as an upgrade concern

Node-key sealing is enabled by default on Linux, Windows, and macOS as of 1.90.1; existing Linux nodes migrate automatically on upgrade. Encrypted state is a separate control: Linux can use tailscaled --encrypt-state, Windows has the TPM-backed EncryptState policy, and macOS stores state in Keychain.

Choose the current workload-authentication form

For an externally supplied identity token, use:

tailscale up --client-id=<client-id> --id-token=<identity-token>

For automatic workload identity tokens, select the audience:

tailscale up --audience=<audience>

Provider-native identity is also available in the Operator, container image, GitHub Actions, and GitLab CI contexts described in the detailed references.

Parse only stable Tailnet Lock output

Use tailscale lock log --json for stable Authority Update Messages and tailscale lock status -json for stable tailnet key-authority data. Keep the different flag spellings when reproducing these commands.

Services, routing, and DNS quick reference

Expect Service advertisement at startup

Services advertise automatically at startup. Disable this only when needed:

TS_EXPERIMENTAL_SERVICE_AUTO_ADVERTISEMENT=false

Service virtual IPs are accepted on every client platform regardless of --accept-routes; tsnet can host Services, and Operator egress proxies can send traffic to the VIPs.

Preserve source addresses with PROXY protocol

Serve and Funnel can prepend a PROXY protocol header so the destination can receive the original client IP address and port. Enable it only when the destination expects and validates that header.

Diagnose Linux routing before changing firewall rules

Linux reports bad IP-forwarding configuration for subnet routers and exit nodes as a health check. It also sets src_valid_mark with connmark rules to keep reverse-path filtering from dropping routed packets.

Use machine-readable DNS and readiness checks

tailscale dns status --json
tailscale wait
tailscale ip --assert=100.64.0.1

tailscale dns query also accepts --json. tailscale wait waits until resources are available for binding; tailscale ip --assert verifies that a specific address belongs to the node.

Kubernetes Operator quick reference

Select the right high-availability resource

• Use a ProxyGroup to give Operator-managed Ingresses or Kubernetes Services multiple active proxy replicas and to multiplex applications.
• Use a ProxyGroup of type kube-apiserver for a highly available Kubernetes API server proxy.
• A multi-replica Recorder requires S3 storage. The default Recorder is a single-replica StatefulSet backed by the filesystem.
• Use the Tailnet custom resource for multi-tailnet access and ProxyGroupPolicy to control ProxyGroup creation by namespace.

Separate recordings, audit events, and authorization

The API proxy can record kubectl exec, attach, and debug sessions. Beta audit logging can capture proxied API events in addition to, or instead of, full recordings. Configure event capability through ACLs on Operator 1.96.5 and later.

Plan dual-stack egress explicitly

Connector and egress-proxy resources support 4via6 from dual-stack clusters, and egress ProxyGroup resources support IPv6. Do not confuse this transport support with the removed deprecated 4via6 MagicDNS names.

Client and operations quick reference

Use recommended exit-node tracking where desired

tailscale set --exit-node=auto:any

auto:any tracks the recommended exit node as availability and network conditions change. Managed Windows and macOS deployments can combine ExitNodeID=auto:any with ExitNode.AllowOverride to require an exit node while letting the user select another one.

Inspect client state with dedicated commands

tailscale get
tailscale whoami
tailscale service list

These expose preferences, user/device identity, and visible Services. tailscale status --peers=false also includes the current device name.

Opt into the release-candidate track deliberately

tailscale version --track=release-candidate
tailscale update --track=release-candidate

Use this track only where testing prerelease builds is intentional. On macOS, the About view also exposes a Release Channel menu that can keep such builds updated.

Route platform-specific behavior to the references

Managed policies and client behavior vary substantially by operating system. Read the client-platform reference before translating a Windows policy to macOS/iOS, assuming GUI and CLI parity, or applying a mobile routing default.