Agent Skills: Tailscale Knowledge Patch

Tailscale Knowledge Patch

Use this skill before changing Tailscale client configuration, tailnet policy, Kubernetes Operator resources, containers, Services, routing, identity, or release automation. Start with the quick references below, then read the topic file that matches the work.

Reference index

| Reference | Read when working on | | --- | --- | | CLI and release automation | CLI parsing and inspection, automation, release tracks, and withdrawn or platform-specific builds | | Identity, policy, and trust | Grants, posture, Tailnet Lock, encrypted state, node keys, workload identity, and policy administration | | Integrations and observability | Terraform, APIs, log streaming, metrics, and admin-console integrations | | Kubernetes and containers | Operator CRDs, proxy groups, API proxying, recording, images, authentication, and container behavior | | Managed clients and platforms | System policies, mobile and desktop clients, minimum platforms, UI behavior, and appliance packages | | Networking, routing, and Services | DNS, Serve, Funnel, Services, Peer Relays, DERP, exit nodes, subnet routing, Taildrive, and Tailscale SSH |

Breaking changes and migration checks

Audit repeated flags

CLI commands reject repeated occurrences of the same flag. Check wrappers, shell aliases, container arguments, and generated commands for duplication. In containers, setting --accept-dns through TS_EXTRA_ARGS requires the image containing the compatibility fix described in the CLI reference.

Expect confirmation prompts

Significant CLI actions may prompt for y/n confirmation. Treat unattended jobs as potentially blocking and verify the exact command's non-interactive behavior before deploying automation.

Replace deprecated policy and naming forms

• Use AlwaysOn.Enabled and AlwaysOn.OverrideWithReason instead of the deprecated Apple-platform ForceEnabled policy.
• Use OnboardingFlow instead of the deprecated TailscaleOnboardingSeen macOS policy.
• Store the external GitOps repository URL in the admin console; the older policy-file comment is deprecated and loses when both values exist.
• Replace removed 4via6 MagicDNS name formats with a supported name form.
• On macOS, configure Taildrive shares in the GUI because tailscale drive is no longer available.

Recheck removed and narrowed controls

The Operator no longer uses TS_EXPERIMENTAL_KUBE_API_EVENTS; authorize API event behavior through tailnet policy. The AuthKey system policy applies only while no user is logged in. Do not assume either control has its older, broader effect.

Check platform and release constraints

macOS requires a newer supported floor, and several releases were release candidates, internal-only, delayed, withdrawn, or halted on particular platforms. Consult the release reference before pinning a client version, building a rollout, or treating a same-numbered build as universally available.

Paginate tailnet listings

The list-tailnets API is paginated. Follow returned cursors until empty rather than assuming one response contains the organization, and use totalCount when the complete count matters.

Policy, identity, and trust quick reference

Prefer grants for new policy

New tailnets and never-edited policy files use grants syntax while retaining the same effective permissions. The generally available via field can require traffic to traverse selected exit nodes, subnet routers, or app connectors. Preserve existing semantics when translating ACLs.

Handle key trust deliberately

• Tailnet Lock can require verification of node keys supplied by the coordination server.
• Node-key sealing is enabled by default on major desktop platforms, and existing Linux nodes migrate automatically when upgraded.
• Reauthentication during node-key renewal preserves established connections.
• Use stable JSON forms of Tailnet Lock log and status output when writing parsers.

Select the right workload identity flow

Nodes can authenticate with explicit client and identity tokens, or request identity tokens automatically for a selected audience. The Operator, containers, CI integrations, the API client, and Terraform have related but distinct federation paths. Read both the identity and Kubernetes references before replacing OAuth secrets or auth keys.

Treat state encryption as posture

Use the platform's supported encrypted-state mechanism and validate it with the tsStateEncrypted posture attribute. Linux uses TPM-backed daemon mode, Windows uses a TPM-backed policy, and macOS stores state in Keychain.

Networking and Services quick reference

Account for automatic Service behavior

Tailscale Services are generally available, including hosting from tsnet. Clients accept Service virtual IPs independently of --accept-routes, and Services are advertised automatically at startup unless explicitly disabled. Review route assumptions and duplicate advertisements during migrations.

Preserve source addresses where required

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

Use current relay capabilities

Peer Relays can advertise static endpoints, discover Amazon EC2 addresses, run in Kubernetes, and expose endpoint and traffic metrics. Decide whether endpoint discovery or explicit endpoints are authoritative for the deployment.

Validate exit-node and DNS interactions

auto:any follows the recommended exit node as availability and network conditions change. DNS nameserver configuration can still send all domains to admin-configured resolvers while an exit node is active. Managed clients may permit an enforced exit-node choice with user override.

Test Linux routing health

Linux reports incorrect IP forwarding for subnet routers and exit nodes as a health check. Its firewall setup also uses src_valid_mark with connmark to avoid reverse-path filtering of routed packets. Investigate health warnings before changing firewall rules.

Kubernetes and container quick reference

Use ProxyGroups for shared high availability

Operator-managed Ingresses and Kubernetes Services can share multiple active proxy replicas through a ProxyGroup, multiplex applications, and expose backends across clusters. Preserve cluster-wide EndpointSlice visibility when depending on cross-cluster failover.

Choose API proxy recording deliberately

The Kubernetes API proxy supports high availability, session recording, and audit events. Recording covers exec, attach, and debug sessions; audit logs can supplement or replace full recordings. Configure event authorization in tailnet policy.

Match Recorder replicas to storage

A Recorder defaults to a single-replica StatefulSet with filesystem storage. Multiple replicas require an S3 backend. When using AWS IRSA, set the generated ServiceAccount name and annotations instead of embedding static S3 credentials.

Separate tailnets and namespace authority

Use Tailnet resources for multi-tailnet access and identity configuration, and ProxyGroupPolicy resources to control which namespaces may create ProxyGroups. Reused hostnames are scoped by tailnet, so the same hostname can be valid in separate tailnets.

Verify container compatibility details

Container behavior includes HTTP-only Serve configuration, OAuth and workload identity authentication, Kubernetes startup-state cleanup, automatic Service advertisement, auth keys loaded from files, and fallback to iptables on hosts without nftables. Read the container reference before changing image versions or entrypoint variables.

CLI and observability quick reference

Prefer machine-readable output

Use JSON output for DNS queries and status, and the stable Tailnet Lock JSON forms for automation. Use tailscale wait before binding dependent resources and tailscale ip --assert when a script requires one specific node address.

Inspect the local node directly

Use tailscale get, tailscale whoami, and tailscale service list for preferences, identity, and visible Services. tailscale status --peers=false also reports the current device name.

Monitor the relevant data plane

Available signals include home-DERP selection, Peer Relay packet and byte forwarding, relay endpoint count, Serve traffic for Services, flow-log node details, Kubernetes audit events, and Linux kernel audit messages for successful Tailscale SSH authentication. Choose the metric or log at the layer where failure is expected.