artis3n.tailscale

This role installs and sets up Tailscale on a Linux system.

Supported operating systems:

• Debian / Ubuntu
• CentOS / RedHat
• Rocky Linux / AlmaLinux
• Amazon Linux 2023 / Amazon Linux 2
• Fedora
• Arch Linux
• OpenSUSE
• Oracle Linux
• Raspbian

Check the CI workflow for the versions actively tested in each pull request.

Tip: This role requires Ansible 2.11 or newer. Ansible 2.12 is the recommended minimum version as it has been tested for compatibility.

If you find this role useful, please consider giving a one-time or recurring sponsorship.

Table of Contents

• Role Outputs
• Role Variables
  • Required
  • Optional
• Dependencies
• Example Playbook
• State Tracking
• License
• Author Information
• Development and Contributing

This role captures any error messages from the Tailscale binary to help identify issues with your configuration when using the tailscale up command. The --authkey= will be hidden unless insecurely_log_authkey is set to true.

Role Outputs

This role provides the IPv4 and IPv6 addresses of the Tailscale node, along with tailscale whois output as facts. Important data from whois is included directly, while the rest is stored as a JSON fact for convenience.

Outputted facts:

tailscale_node_ipv4           (string): The IPv4 address of the Tailscale node.
tailscale_node_ipv6           (string): The IPv6 address of the Tailscale node.
tailscale_node_hostname_full  (string): The full hostname of the Tailscale node.
tailscale_node_hostname_short (string): The short hostname of the Tailscale node.
tailscale_node_created_at     (string): The timestamp indicating when the Tailscale node was created.
tailscale_node_tags           (list):   The tags assigned to the Tailscale node.
tailscale_node_services       (list):   The services running on the Tailscale node.
tailscale_node_whois          (dict):   The full output of `tailscale whois`.

Role Variables

Required

You must have either tailscale_authkey or tailscale_up_skip. In most cases, you will use tailscale_authkey.

If you are uninstalling Tailscale (state: absent), neither tailscale_authkey nor tailscale_up_skip is needed.

tailscale_authkey

This is needed unless tailscale_up_skip is set to true.

A Tailscale Authorization key that you can generate from your Tailscale account. There are two types of keys:

• Auth key (tskey-auth-XXX-YYYYY)
• OAuth key (tskey-client-XXX-YYYY)

Important: Using an OAuth key requires additional settings:

• tailscale_tags (must be provided),
• tailscale_oauth_ephemeral (defaults to true),
• tailscale_oauth_preauthorized (defaults to false).

Auth keys expire in a maximum of 90 days after creation. OAuth tokens expire after 1 hour unless revoked.

For more details, refer to Tailscale's OAuth clients page.

tailscale_tags

Default: []

These tags will be assigned to the Tailscale nodes configured by this role (using --advertise-tags with tailscale up). For more information, see What are tags?.

Note: Tags are required for OAuth clients (tailscale_authkey OAuth key).

Do not prefix entries with tag:. For example, tailscale_tags: ['worker'] translates to --advertise-tags=tag:worker.

tailscale_up_skip

If set to true, tailscale_authkey is not needed.

Default: false

This controls whether to install and configure Tailscale as a service but skip executing tailscale up. Useful for creating builds where Tailscale shouldn't authenticate yet.

Optional

state

Default: latest

Specifies if Tailscale should be installed or uninstalled. If specified, state must be latest, present, or absent.

The default latest helps keep your software updated with the latest features and security updates. To avoid updates if Tailscale is already installed, use present.

If absent, this role will remove the Tailscale node and clean up any added artifacts.

tailscale_args

Use this to pass command-line arguments to tailscale up.

Note that traditional command functions are used, and shell operations like $() are not supported. You can only pass tailscale up arguments.

Caution:

• Do not use for --authkey, --advertise-tags, or --timeout.
• Use appropriate variables for those settings.

tailscale_oauth_ephemeral

Note: Used only when tailscale_authkey is an OAuth key.

Default: true

Whether to register as an ephemeral node.

tailscale_oauth_preauthorized

Note: Used only when tailscale_authkey is an OAuth key.

Default: false

Whether to skip manual device approval.

insecurely_log_authkey

Default: false

If set to true, logs the raw value of the Tailscale auth key when errors are encountered. By default, the auth key is not logged during successful task completions and is hidden if an error occurs.

release_stability

Default: stable

Whether to use the stable or unstable Tailscale track.

• stable: Reliable releases.
• unstable: Latest changes, may have issues.

tailscale_up_timeout

Default: 120

Sets the timeout duration for the tailscale up command in seconds.

verbose

Default: false

Controls whether to output more details during execution. This is helpful for debugging and reporting issues.

Dependencies

Collections

• community.general

Example Playbook

- name: Setup Tailscale
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Enable Tailscale SSH:

- name: Setup Tailscale with SSH
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"
        tailscale_args: "--ssh"

Passing custom command-line arguments:

- name: Setup Tailscale with Custom Args
  hosts: all
  tasks:
    - name: Use Headscale
      include_role:
        name: artis3n.tailscale
      vars:
        tailscale_args: "--login-server='http://localhost:8080'"
        tailscale_authkey: "{{ lookup('env', 'HEADSCALE_KEY') }}"

Enable verbose output:

- name: Setup Tailscale Verbosely
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_KEY') }}"

Connect using an OAuth client secret:

- name: Setup Tailscale with OAuth
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        tailscale_authkey: "{{ lookup('env', 'TAILSCALE_OAUTH_CLIENT_SECRET') }}"
        tailscale_tags:
          - "oauth"

Install Tailscale without authenticating:

- name: Install Tailscale without Auth
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        tailscale_up_skip: true

Uninstall a Tailscale node:

- name: Uninstall Tailscale
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        state: absent

State Tracking

This role will create a directory called artis3n-tailscale in the target's default state directory to keep track of the configuration.

This allows it to update the Tailscale configuration accurately when needed. If you delete this directory, the role will reconfigure Tailscale unnecessarily, but it won’t cause any damage.

It is recommended to let this Ansible role manage this directory.

Keep in mind:

Flags are not saved between runs; you need to specify all flags each time.

License

MIT License

Author Information

Ari Kalfus (@artis3n) dev@artis3nal.com

Development and Contribution

This repository uses a test Tailscale account for authentication during CI runs. New authorized machines are created in the test account each time a Docker container is set up.

A special auth key (TAILSCALE_CI_KEY) is stored as a secret in GitHub Actions.

For local testing, store the Tailscale ephemeral auth key in the TAILSCALE_CI_KEY variable and, if testing with OAuth, also use the TAILSCALE_OAUTH_CLIENT_SECRET variable.

Alternatively, you can use a Headscale container for testing with Molecule by setting USE_HEADSCALE to true.

USE_HEADSCALE=true molecule test