TAILSCALE WITH SWAMP

What @swamp/tailscale covers

The behavior types in @swamp/tailscale fall into these groups:

• Access policy: policy-file, whose validate and preview methods check a policy without saving it
• DNS: dns-configuration, dns-nameservers, dns-preferences, dns-search-paths and dns-split-nameservers
• Credentials: tailnet-key for auth keys, oauth-client, oauth-app and federated-identity
• Devices: device, device-authorization, device-key, device-tags, device-subnet-routes, device-posture-attribute, device-invite and posture-integration
• People: user, user-invite and contacts
• Tailnet-wide settings and events: tailnet-settings, service, webhook and log-stream

Every type authenticates the same way. It uses either a Tailscale API access token or an OAuth client ID and secret. These are set as global arguments or read from the TAILSCALE_API_KEY, TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET environment variables. Unless a behavior sets tailnet, it works on the tailnet that the credential belongs to. Tailscale returns some secrets only once: auth keys, OAuth client and OAuth app secrets, and webhook signing secrets. Swamp writes these to a vault, not to plain state.

The getting started tutorial pulls the extension and has Tailscale check an access policy held in a behavior. The how-to guides cover three common jobs: creating a tagged auth key for CI runners or servers, routing an internal domain with split DNS, and sending tailnet events to a Slack webhook. Understanding Tailscale automation in Swamp covers how the behavior types relate to the Tailscale API, and how credentials, state and secrets move between them.

Community extensions

Several community extensions work on hosts instead of the API. @keeb/tailscale installs Tailscale on Alpine VMs over SSH and authenticates them with an auth key. @bitgnome/tailscale joins the hosts of an @swamp/ssh fleet to the tailnet, using an auth key taken from a vault. Both extensions also parse tailscale status JSON into one resource per machine, so other behaviors and workflows can look up nodes by name. @hivemq/tailscale rolls Tailscale out to bare-metal hosts in a sequence that stops at the first failure: first a canary group, then the fleet, then sshd hardening. @josephholsten/tailscale/device manages TCP serve rules on a device over SSH.

Other extensions add checks and safeguards around the tailnet. @bixu/tailscale-community and @sntxrr/tailscale-acl-drift compare the live policy with a policy file kept in version control and propose ACL changes as pull requests. @mgreten/tailscale-oauth-client replaces an OAuth client in stages, with a preview and a confirmation before each irreversible step. @bixu/tailnet-healthcheck reports devices that run outdated Tailscale clients. @sntxrr/tailcat-probe measures reachability and throughput to a tailcat server. The extensions reference lists the behavior types, arguments and methods of each extension.