gbrindisi / ansible-role-tailscale

Ansible role to install and enable a Tailscale node.

artis3n.tailscale

This role initializes a Tailscale node. If Tailscale is already installed, this role will update Tailscale to the latest version.

Supported operating systems:

• Debian
• Ubuntu
• CentOS / RedHat
• Amazon Linux
• Oracle Linux
• Fedora
• Arch Linux
• Raspbian (untested but should work)

See the CI worfklow for the list of distribution versions actively tested in each pull request.

This role does not re-apply the up command if Tailscale is already logged in. This will be supported in a future release.

Requirements

You must supply a tailscale_auth_key variable, which can be generated under your Tailscale account at https://login.tailscale.com/admin/authkeys.

Role Variables

Required

One of tailscale_auth_key or tailscale_up_skip must be present. In most cases you will use tailscale_auth_key.

tailscale_auth_key

Is not required if tailscale_up_skip is set to true.

A Tailscale Node Authorization auth key.

A Node Authorization auth key can be generated under your Tailscale account at https://login.tailscale.com/admin/authkeys. Note that reusable authorization keys now expire 90 days after they are generated.

This value should be treated as a sensitive secret. You are encouraged to use ansible-vault to encrypt this value in your playbook.

tailscale_up_skip

If set to true, tailscale_auth_key is not required.

Default: false

Whether to install and configure Tailscale as a service but skip running tailscale up. Helpful when packaging up a Tailscale installation into a build process such as AMI creation when the server should not yet authenticate to your Tailscale network.

Optional

force

Default: false

If set to true, tailscale up will always run. This can be beneficial if tailscale has already been configured on a host but you want to re-run up with different arguments.

release_stability

Default: stable

Whether to use the Tailscale stable or unstable track.

stable:

Stable releases. If you're not sure which track to use, pick this one.

unstable:

The bleeding edge. Pushed early and often. Expect rough edges!

tailscale_args

Pass any additional command-line arguments to tailscale up.

Note that this parameter does not support bash piping or command extensions like & or ;. Only tailscale up arguments can be passed.

Do not use this for --authkey. Use the tailscale_auth_key variable instead.

In the future, this parameter will be replaced with a map of supported command-line arguments. Since Tailscale is still undergoing rapid development, we are holding off on creating such an argument map until features are more stable.

verbose

Default: false

Whether to output additional information during role execution. Helpful for debugging and collecting information to submit in a GitHub issue on this repository.

Dependencies

None

Example Playbook

- name: Servers
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        # Fake example encrypted by ansible-vault
        tailscale_auth_key: !vault |
          $ANSIBLE_VAULT;1.2;AES256;tailscale
          32616238303134343065613038383933333733383765653166346564363332343761653761646363
          6637666565626333333664363739613366363461313063640a613330393062323161636235383936
          37373734653036613133613533376139383138613164323661386362376335316364653037353631
          6539646561373535610a643334396234396332376431326565383432626232383131303131363362
          3537

Pass arbitrary command-line arguments:

- name: Servers
  hosts: all
  tasks:
    - name: Get AZ subnets
      ec2_vpc_subnet_facts:
        region: "{{ placement.region }}"
        filters:
          vpc-id: "{{ vpc_id }}"
          availability-zone: "{{ placement.availability_zone }}"
      register: subnet_info

    - name: Set Subnet list
      set_fact:
        subnet_blocks: "{{ subnet_info.subnets | map(attribute='cidr_block') | list  }}"

    - name: Configure Sysctl
      sysctl:
        name: net.ipv4.ip_forward
        value: 1
        state: present
        ignoreerrors: true
        sysctl_set: true

    - name: Iptables Masquerade
      iptables:
        table: nat
        chain: POSTROUTING
        jump: MASQUERADE

    - name: Configure Tailscale
      include_role:
        name: artis3n.tailscale
      vars:
        tailscale_args: "--accept-routes=false --advertise-routes={{ subnet_blocks | join(',') }}"
        # Fake example encrypted by ansible-vault
        tailscale_auth_key: !vault |
          $ANSIBLE_VAULT;1.2;AES256;tailscale
          32616238303134343065613038383933333733383765653166346564363332343761653761646363
          6637666565626333333664363739613366363461313063640a613330393062323161636235383936
          37373734653036613133613533376139383138613164323661386362376335316364653037353631
          6539646561373535610a643334396234396332376431326565383432626232383131303131363362
          3537

Get verbose output:

- name: Servers
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        verbose: true
        # Fake example encrypted by ansible-vault
        tailscale_auth_key: !vault |
          $ANSIBLE_VAULT;1.2;AES256;tailscale
          32616238303134343065613038383933333733383765653166346564363332343761653761646363
          6637666565626333333664363739613366363461313063640a613330393062323161636235383936
          37373734653036613133613533376139383138613164323661386362376335316364653037353631
          6539646561373535610a643334396234396332376431326565383432626232383131303131363362
          3537

Install Tailscale, but don't authenticate to the network:

- name: Servers
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        tailscale_up_skip: true

Run tailscale up on a host that has been previously configured:

- name: Servers
  hosts: all
  roles:
    - role: artis3n.tailscale
      vars:
        force: true
        # Fake example encrypted by ansible-vault
        tailscale_auth_key: !vault |
          $ANSIBLE_VAULT;1.2;AES256;tailscale
          32616238303134343065613038383933333733383765653166346564363332343761653761646363
          6637666565626333333664363739613366363461313063640a613330393062323161636235383936
          37373734653036613133613533376139383138613164323661386362376335316364653037353631
          6539646561373535610a643334396234396332376431326565383432626232383131303131363362
          3537

License

MIT

Author Information

Ari Kalfus (@artis3n) [e-mail]

Development and Contributing

This GitHub repository uses a dedicated "test" Tailscale account to authenticate Tailscale during CI runs. Each Docker container creates a new authorized machine in that test account. The machines are authorized with ephemeral auth keys and are automatically cleaned up within 48 hours.

This value is stored in a GitHub Action secret with the name TAILSCALE_CI_KEY. If you are interested in contributing to this repository, you must create a Tailscale account and generate a Node Authorization ephemeral auth key. Fork this repo and add your ephemeral auth key to the fork's secrets under the name TAILSCALE_CI_KEY.

To test this role locally, store the Tailscale ephemeral auth key in a TAILSCALE_CI_KEY env var.

If you are a Collaborator on this repository, you can open a GitHub Codespace and the TAILSCALE_CI_KEY will be populated for you.