How app connectors work

This topic provides an overview for how app connectors work.

This feature is currently in beta. To try it, follow the steps below to enable it for your network using Tailscale v1.54 or later.

App connectors are available for all plans.

When you use an app connector, you specify which applications you wish to make accessible over your Tailscale network (known as a tailnet), and the domains for those applications. Any traffic for that application is then forced over the tailnet to a node running an app connector before egressing to the target domains. This is useful for cases where the application has an allowlist of IP addresses which can connect to it: the IP address of the node running the app connector can be added to the allowlist, and all nodes on the tailnet will use that IP address for their traffic egress.

App connectors work by proxying DNS for the target domains and advertising the subnet routes for the observed DNS results. Upon each query to a configured domain, the returned routes for that domain are advertised as routes via the app connector. In a similar manner to a subnet router, the app connector is then used to connect to any IP addresses advertised by the target domain. These requests then egress the tailnet through the appropriate app connector. In simplified terms, an app connector could be considered an automatic subnet router that is configured by domains instead of addresses.

App connectors are an always-on feature. Domains configured to route through an app connector will always route through an available app connector from all clients on the tailnet, unless that client has disabled accept routes. App connectors will be used even when an exit node is enabled on a client's device.

Configure apps for route discovery

You can configure apps for route discovery using domains, CNAME records, or wildcards.

Domains

You can configure apps with a list of domains. Domains must be valid, fully-qualified domain names. Tailscale routes DNS routing records like A and AAAA through app connectors.

After you add a domain, configured app connectors begin route discovery. If no routes are pre-configured, app connectors effectively start a "learning" period. During the learning period, as end users make requests to configured domains, the app connector proxies DNS requests, identifies routing records, and adds those as advertised routes to each app connector. When auto approval is enabled, the discovered routes are immediately advertised and updated on all connected clients on the tailnet. This automatically routes traffic through the app connector (for the local region if using regional routing). The learning period continues until the app connector discovers all routes. For smaller domains, this takes minimal time. It might take longer for larger domains or domains with wildcards. See connecting large SaaS services.

DNS lookups

App connectors work by acting as the authoritative nameserver for the domains configured on an app. For example, when an app is configured for *.example.com, a split DNS entry is created. Any subsequent DNS lookups from the client for *.example.com are sent to the appropriate app connectors. Each app connector itself performs the DNS lookup, and if the lookup succeeds then a new subnet route is introduced for the resolved IP address before returning the response to the client.

CNAMEs

For CNAMEs, which are not routing records, app connectors will follow the CNAME chain and automatically advertise the resulting routes. To check if your domain is using a CNAME, use a command like dig app.acme.com. The output will look similar to:

.1. app.acme.com IN CNAME acme.backend.com
.2. acme.backend.com A ...

In the above example, the target of the CNAME chain, acme.backend.com, will be used for route advertisement instead of app.acme.com.

In some cases, CNAME records return different results in different geographies, as web services use geographic DNS load balancing. In these cases, it is recommended that your app connectors be deployed in locations that closely mirror your organization's global footprint.

Wildcards

Wildcards (*) are supported. Wildcard behavior is non-inclusive of the parent domain. For example, to include all of acme.com and its subdomains, enter both acme.com and *.acme.com. To only include the top-level domain, include acme.com and omit *.acme.com. To include only subdomains, include *.acme.com and omit acme.com.

ACL driven route configuration

You can manually preconfigure routes in the access control lists (ACLs) section of your tailnet policy file alongside the domains configuration. For example:

{
    "name": "myapp",
    "connectors": ["tag:connector"],
    "domains": ["example.com"],
    "routes": ["192.0.0.0/24"],
}

Effective with Tailscale v1.60.0 for stable tracks and v1.59.43 for unstable tracks, app connector nodes will automatically advertise these routes as soon as the ACL change is applied to the tailnet policy file. App connectors added to this app will also immediately advertise these routes. Additionally, routes added via the ACL are implicitly approved and do not require a sibling autoApprovers entry.

This maintains strict routing control as part of the ACL and approval process. In many instances this also removes the need for users to build up large -–advertise-routes arguments for node configurations in order to avoid lengthy discovery periods with disruptive routing changes.

Route coalescing

Routes populated by ACL driven route configuration will coalesce or replace routes that are a sub-route of the new advertisemen. For example, if the connector had previously discovered 192.0.0.1/32 and 192.0.0.2/32, and the routes ACL is adjusted to cover 192.0.0.0/24, the route table exposed by the connector will settle to 192.0.0.0/24 only, in order to minimize routing table length and complexity.