Tailscale Orb

This orb will allow users to connect the build-host to a Tailscale Tailnet. The build-host will then be able to communicate privately with any Tailscale host in the same Tailnet via a peer-to-peer mesh network.

You can then also use the remote Tailscale host as a bastion/jump host to relay the traffic from your Tailscale network onto your physical subnet.

This is an “executor-agnostic” orb; there is only one set of commands which can be used on any supported executor. The orb’s underlying code handles the OS/platform detection, and runs the appropriate OS-specific bash commands.

---

Executor support

Linux (machine)	Windows	macOS	Docker
✅	✅	✅	✅

Requirements

• You need to have an existing Tailnet with at least one online Tailscale machine.

  • The Tailscale hostname/IP must be referenced via the ts_dst_host parameter of the orb's connect command.

• You must create a Tailscale auth key and store it in an environment variable (either in the project settings or in an organization context).

  • Be mindful of the type of auth key you create.
  • By default, the orb's connect command expects the Tailscale auth key to be stored in an environment variable named TS_AUTH_KEY, however you can opt to store the auth key in a custom-named environment variable; in such case, the environment variable's name must be passed to the orb's connect command via the ts_auth_key parameter.

• If you wish to use the remote Tailscale host as a bastion/jump host:

  • You will need to start (or restart) Tailscale as a subnet router on that Tailscale host in order to expose the physical subnet route(s) to your target(s).
  • However, the orb won't allow you to use the remote Tailscale host an "exit node". (See "Caveats & limitations")

Features

This orb has 3 commands:

• install
• connect
• disconnect

There are no job or executor defined in this orb.

Commands

The install command will:

• Download/Install Tailscale. (note: if the job uses the Docker executor, this command will also install tmux)

The connect command will:

• Start Tailscale on the build-host and connect it to your Tailnet.
• Attempt to establish a direct link to the Tailscale machine referenced in the ts_dst_host parameter.

The disconnect command will:

• Disconnect the build-host from your Tailnet.

Caveats & limitations

• The Tailscale "exit node" feature is not supported. The reason is that the implementation of a VPN in CircleCI builds requires to exclude communications between the build-agent (running in the build-host) and other CircleCI components/services from the VPN tunnel. Doing so necessitates a "split-tunnel" approach which is not possible with exit nodes because, as Tailscale explains:

  When using exit nodes, the split-tunnel workarounds will not work, as Tailscale sets its own aggressive firewall rules to route all traffic to your exit node. Exit nodes only support one VPN at a time.

• There are several types of auth keys. Make sure to select the appropriate type(s) when generating the Tailscale auth key you'll be using in your CircleCI builds.

• A Tailscale auth key will automatically expire after 90 days.

Resources

CircleCI Orb Registry Page - The official registry page of this orb for all versions and commands described.

CircleCI Orb Docs - Docs for using, creating, and publishing CircleCI Orbs.

Important note regarding support

This is an uncertified orb; it is neither tested nor verified by CircleCI. Therefore CircleCI will not be in a position to assist you with using this orb, or troubleshooting /resolving any issues you might encouter while using this orb.

Should you have questions or encounter an issue while using this orb, please:

1. Refer to the "Caveats & limitations" section.
2. Check if there is a similar existing question/issue. If so, you can add details about your instance of the issue.
3. Visit the Orb Category of CircleCI Discuss.
4. If none of the above helps, open your own issue with a detailled description.

Contribute

You are more than welcome to contribute to this orb by adding features/improvements or fixing open issues. To do so, please create pull requests against this repository, and make sure to provide the requested information.