Connecting through Tailscale

Tailscale is a managed virtual private network (VPN). It creates a private mesh network called a tailnet.

Each device on the Tailscale network receives a stable private IP address, and can communicate directly with other devices on the tailnet, without the need to open ports to the public internet or to configure VPN gateways.

Tonic Structural can join your corporate tailnet as a node. It can then reach database servers that are on the same tailnet, even if those servers are in a private network and have no public IP address.

Overview of the steps to enable the connection

To allow Tonic Structural to reach a database through Tailscale, you:

1. Allow connections from the tailnet to your database server.
2. Add your database server to the tailnet - Install the Tailscale agent on the server, or configure a subnet router.
3. Declare an access control list (ACL) tag - Register the tag in the tailnet policy that Structural uses to identify itself.
4. Create an OAuth credential - Generate the client secret that Structural uses to authenticate to your tailnet.
5. Configure the Structural workspace - Enable the Tailscale tunnel and provide the connection details.

Allowing connections to the database server from the tailnet

Connections from Structural arrive at the server's Tailscale IP address, not the server's actual IP address.

You must configure your database server to allow connections from your tailnet's IP address range.

By default, the range is 100.64.0.0/10, although it can be customized.

For a PostgreSQL database server, you add an entry for the subnet in pg_hba.conf.

Adding your database server to the tailnet

To make your database server reachable through Tailscale, you can either:

• Install Tailscale directly on the database server.
• Use a subnet router.

Installing Tailscale directly on the database server

If you have shell access to the database server, then this is the simplest approach.

1. Install Tailscale on the server. For platform-specific instructions, go to tailscale.com/download.
2. If a browser is available:

   1. Run sudo tailscale up. This returns a link that looks like:

      https://login.tailscale.com/a/0123456789abcdef

   2. Open the URL in a browser. Tailscale prompts for authentication and then adds the server to your tailnet.
3. For headless servers where no browser is available, use the --auth-key flag instead:

   1. To generate an auth key, go to https://login.tailscale.com/admin/settings/keys .
   2. Click Generate auth key, then indicate whether the key is:

      • A one-off key - single use, for a single server.
      • A reusable key - for multiple servers.

      The generated key starts with tskey-.
   3. After you generate the key, run:

      sudo tailscale up --auth-key=<key>

4. Retrieve the server's Tailscale IP address:

   tailscale ip -4

5. Verify that the device appears at https://login.tailscale.com/admin/machines.

The server now has a stable Tailscale IP address, which is by default in the 100.x.x.x range.

You use the Tailscale IP address as the value of Server in the workspace data connection settings.

Using a subnet router

If you cannot install Tailscale on the database server itself, for example because it is a managed database service, you can instead:

1. Install Tailscale on any other machine that is on the same private network as the database server.
2. Configure the machine as a subnet router.

A subnet router advertises a CIDR range to your tailnet. Other nodes such as Structural can then use regular IP addresses to reach the devices on that subnet. Tailscale does not need to be installed on those devices.

To configure a subnet router:

1. Install Tailscale on a machine that can reach the database server.
2. Start Tailscale with the --advertise-routes flag, which specifies the subnet that your database is on:

   sudo tailscale up --advertise-routes=10.0.1.0/24

3. Approve the advertised route:

   1. Go to https://login.tailscale.com/admin/machines.
   2. Click the machine.
   3. Click Edit route settings.
   4. Enable the route.

When you use a subnet router, then in Structural, you set the value of Server to the database server's regular private IP address - for example, 10.0.1.50 - instead of a Tailscale IP address.

Declaring an ACL tag

Tailscale uses ACL tags to control the devices that a given credential can authenticate to.

Before you create an OAuth credential, you must declare the tag that you intend to use in your tailnet's ACL policy.

1. Go to https://login.tailscale.com/admin/acls.
2. Edit the policy JSON.
3. If the policy does not already contain a tagOwners section, then add the section.
4. Add the tag to tagOwners. For example, to create a tag called tag:tonic:

"tagOwners": {
    "tag:tonic": ["[e-mail]"],
},

1. Save the policy.

Creating an OAuth credential

Structural authenticates to your tailnet using an OAuth client credential. You create this from the Tailscale admin console under Trust credentials.

1. Go to https://login.tailscale.com/admin/settings/trust-credentials.
2. Click + Credential.
3. Select OAuth as the credential type.

New Tailscale credential with OAuth selected as the credential type

1. Add a description, then click Next.
2. To set the credential scope:

   1. From the Scopes dropdown, select Custom scopes.
   2. Under Keys, for Auth Keys, check the Write checkbox.
   3. In the Tags field, provide the ACL tag that you created.
3. Click Generate credential. Tailscale displays the Credential created panel with the client ID and the client secret.

Credential created panel with the client ID and client secret for the Tailscale OAuth credential

1. Copy the Client secret immediately. It is only shown once. The client secret starts with tskey-client-. In the Structural workspace configuration, you paste this value into the Tailscale Auth Key field. Structural does not use the client ID.

Configuring a workspace to use Tailscale tunneling

After you complete the setup in Tailscale, you can configure a Structural workspace to connect through Tailscale.

Setting the database connection server value

When you connect through Tailscale, in the database connection fields, to set the value of Server:

• If you installed Tailscale on the database server, set Server to the Tailscale IP address, which is the stable address that is assigned to the device on your tailnet. By default, the address in the 100.x.x.x range.
• If you use a subnet router, then in Structural, set Server to the database server's regular private IP address - for example, 10.0.1.50.

Enabling and configuring the Tailscale connection

To enable and configure the Tailscale connection:

1. If the connector supports multiple tunneling options:

   1. Toggle Enable Connection Tunnel to the on position.
   2. From the Tunnel type dropdown list, select Tailscale Tunnel.

   If the data connector only supports Tailscale tunneling, then it is selected automatically.
2. In the Tags field, provide a comma-separated list of ACL tags to use to join the tailnet. For example, tag:tonic-worker. Each tag name must exactly match the tag name that you configured in Tailscale, and must include the tag: prefix. If the tags don't match, then when Structural tries to connect, Tailscale returns an authentication error.
3. Optionally, in the Control Server URL field, provide the URL. This is intended for customers who use Headscale or a self-hosted Tailscale control plane.
4. In the Tailscale Auth Key field, you can either:

   • Provide the Tailscale OAuth client credential (value starting with tskey-client-) that you generated and copied from Tailscale. Structural does not support other types of Tailscale keys, such as user auth keys.
   • If secrets managers are available, select a secret name from a secrets manager.

How the connection works

When Structural uses Tailscale tunneling to establish a connection:

1. Structural uses the provided credential (OAuth credential or secrets manager secret) to authenticate as a new ephemeral node on your tailnet.
2. The node is tagged with the specified ACL tags. The tags control what the node can reach based on your tailnet policy.
3. Structural uses its Tailscale IP address to connect to the database server. Traffic flows through the encrypted tailnet mesh, not the public internet.
4. When the connection is torn down, the ephemeral node is removed from your tailnet.

Troubleshooting the connection

Here are some errors that might occur during the connection:

Error	Likely cause
Tailscale authentication failed	Either: The tag in the Tags field does not match the tag on the OAuth credential's auth_keys scope. The tag is not declared in tagOwners in your ACL policy.
Connection times out	Either: The database server is not on the tailnet. The ACL policy does not permit the tagged node to reach it.
Invalid auth key type	You used a user auth key or a pre-auth key instead of an OAuth client secret.