A Tailscale Library for Elixir

This library is a work in progress, but will soon be used in a production cluster.

This library helps you automatically build an Elixir cluster using Tailscale. The library also helps in interacting with the general state of your Tailnet, so you can lookup nodes by tags and hostnames, and subscribe to various events. The library requires that tailscale is connected and running on the host.

Notes

This library uses the tailscale status --json command, which Tailscale has marked experimental. So if Tailscale updates their JSON response, this library may temporarily break. The status is diffed for changes, which is subscribed by the Cluster module to watch for any changes.

Work-In-Progress {: .warning}

I haven't throughly tested the library yet so there could be cluster-killing bugs.

Don't use it for anything critical yet.

I'll improve the library soon and test it.

Installation

Add the library to your dependencies:

def deps do
  [
    {:tailscale, "~> 0.1.0"}
  ]
end

Docs are available here.

Build a Cluster

The simplest way to get started with this library is to add a few nodes to Tailscale with the beam tag, drop in this library in your application.ex, and everything should just work.

1. [On Tailscale] Create a "beam" tag:

In the Access Controls tab add the line in the tagOwners object:

// Define the tags which can be applied to devices and by which users.
"tagOwners": {
  "tag:beam":     ["autogroup:admin"],
  // ...
},

2. [On Tailscale] Create an auth-key with the "beam" tag.

• On Tailscale -> Settings -> Keys (in Personal Settings) -> Generate auth key
• You could choose the Reusable option to use the same auth-key on many VMs.
• Enable the Tags option and select the "tag:beam" tag from the Add Tags option.
• Click Generate Key and copy the key.

3. [On VM] Install and authenticate Tailscale on every server

tailscale up --auth-key <your-tailscale-auth-key>

In a few seconds, you should see the node show up on Tailscale, with the "beam" tag on it.

Confirm that Tailscale is working by running:

tailscale status

4. [In Elixir] Just drop in the library in your Application Supervisor

defmodule YourApp.Application do
  @moduledoc false
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      Tailscale,
      ...
    ]

    opts = [strategy: :one_for_one, name: YourApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

And that's all. Starting the app will first find all nodes with the beam tag and connect to them automatically. As usual, just ensure that the same cookie is set on all nodes. The library will automatically start the Erlang distribution, so don't start it yourself.

To do something different, look through the code and the docs for the modules. I'll document the library further soon.