Apps
Route traffic for chosen domains through tagged app connector nodes: define apps, how learned and static routes and split DNS work, and manage them.
An app is a set of domains reached through app connectors, following
Tailscale’s app connectors.
Instead of routing all Internet traffic through an exit node or advertising
broad subnets, an app connector lets devices on your tailnet reach specific
applications and SaaS domains (such as example.com or *.example.com)
through designated connector nodes in your network.
How it works
- Connector node. A machine runs the app connector service and advertises itself as a connector.
- App definition. An operator defines the app with its domains, static routes, and connector selectors.
- Route learning and approval. The connector resolves the app’s domains, advertises single-address host routes for the learned IPs, and the server approves them automatically.
- DNS. The server sends each machine the policy lets through a connector split DNS for the app’s domains that points at that connector, so queries reach it and it learns the addresses.
Setting up a connector node
A connector node must be a tagged machine because connectors act as shared network infrastructure; user-owned machines cannot serve as connectors.
On the machine, advertise the connector service:
tailscale set --advertise-connector
When registering a new node, pass --advertise-connector to tailscale up
along with the node’s tags:
sudo tailscale up --login-server <YOUR_SLOPSCALE_URL> --auth-key <KEY> \
--advertise-connector
The node reports to the server that it runs the app connector service. The
server sends app definitions to matching connector nodes using the
tailscale.com/app-connectors node capability.
Defining apps
An app has:
- Name: 1 to 63 characters.
- Description: an optional summary.
- Domains: domain names or wildcard domains the connectors watch and
resolve, such as
example.comor*.example.com. - Connectors: node tag selectors (such as
tag:connector) that specify which connector nodes serve the app, or*to select every tagged machine running the connector. If omitted,*is the default. - Routes: optional static CIDR prefixes (such as
198.51.100.0/24) that connectors always advertise. Full internet routes (0.0.0.0/0and::/0) are refused.
Learned and static routes
Connector nodes watch the app’s configured domains and resolve them. Whenever
a connector learns an address for a domain, it advertises a host route
(/32 for IPv4 or /128 for IPv6).
The server approves learned single-address routes automatically. If an app
defines static routes, any prefix within those routes is also approved
automatically for the app’s connectors. Any other advertised routes, such
as broader subnets (10.0.0.0/16) or exit routes, are not covered by the app
and require manual approval by an operator (or policy autoApprovers.routes).
When a domain leaves an app, or the app is deleted, the connector withdraws the routes it learned for it and the server drops their approvals with them, so the connector’s route list only holds what it advertises. Exit routes are left alone, and a plain subnet router keeps its approvals when it stops advertising a route, as before.
DNS
The server sends machines split DNS for the app’s domains, pointing at
the connectors’ DNS endpoints over the tailnet, the way Tailscale’s
control plane does. A query for example.com goes to a connector, and
the connector answers it and learns the addresses in the answer. A
connector is never sent its own apps. A wildcard domain (*.example.com)
routes the base domain too. Nothing has to be configured under
DNS; a split DNS rule for the same domain, if one exists,
comes first.
A connector answers a peer’s query only when the policy lets that peer
send traffic to the internet through it. That is the access the peer
needs for the addresses the connector learns: a rule with the peer as the
source and autogroup:internet, or the addresses themselves, as the
destination. The connector refuses every other peer with a 403, and a
machine whose only resolver for a name refuses it gets no answer at all.
So a machine gets the split DNS toward a connector only when that connector will answer it. The server reads this from the packet filter it sends the connector, which is where the connector’s client looks. Seeing a connector as a peer is not enough. A gateway that reaches a connector through a rule from one node to the other, with nothing through it, gets no split DNS for the app, and the app’s names go to its global nameservers like any other name. Among the connectors that answer a machine, online ones come first.
The client checks TCP port 53, so:
- A rule to
autogroup:internetlimited totcp:53is enough for the app’s DNS. The machine then resolves the app’s names through the connector, and the connector drops the machine’s traffic on other ports. - A rule limited to
udp:53, or to any other UDP port, is not enough. - A rule to the internet on another TCP port,
tcp:443for instance, is enough: the server adds the DNS rule to the connector’s filter for every source the policy lets reach a public address through it.
A machine with only an IPv6 tailnet address gets the split DNS toward a connector only when that connector is also an approved exit node. Over IPv6 the client checks an address that a connector on its own does not answer for.
Machines at the connector’s site
A machine that reaches the internet from the same public address as one of an app’s connectors skips that app. The app already sees the address it allows, so going through a connector would only add a hop. Say the connector sits in the office: a laptop in the office goes out directly, while the same laptop at home still goes through the office connector.
The server compares the public IPv4 address each client reports among its endpoints, the address its NAT shows the internet, so nothing has to be configured. When a machine or a connector moves, its peers get a new netmap. A machine that skips an app does not get these:
- the split DNS for the app’s domains, toward any connector
- the public prefixes inside the app’s static routes, from any connector
- the host routes the connector behind its address learned
The app is skipped on every connector, not only the one behind the machine’s address. With a second connector abroad for failover, the office laptop resolves the app’s names itself and goes out from the office address, instead of sending them abroad. A connector at another site keeps its learned host routes in the laptop’s view, because they cannot be told apart from those of the other apps it serves; with the names resolved locally the laptop rarely meets them.
Private prefixes such as 10.0.0.0/8 in an app’s static routes stay
routed through the connector, since sharing a public address says nothing
about reaching a private network.
Connectors at several sites
An app can list connectors at several sites, for example
tag:office-gateway and tag:eu-gateway. The client sends each DNS query
for the app’s domains to every connector it can reach at once, so each
connector learns the addresses and advertises them. Each machine then goes
through the connector nearest it by the round trips it measured, and
machines equally near several connectors are spread over them; see
regional routing. A machine without
measurements goes through the tailnet-wide primary.
Two things follow from routing by address:
- A service that only lets in the address of one site, an office IP on an allowlist for instance, refuses machines steered to the other site. Keep such a service in an app whose connectors share that address.
- Hosts behind a CDN often share addresses: every proxied hostname in one Cloudflare zone may resolve to the same two. A connector that learned them for one app routes every hostname on them, including hosts in no app. List the CDN’s hostnames in an app whose connectors suit all of them, or keep them out of apps.
Console and API
The admin console has an Apps page under Connectivity (Connectivity › Apps),
listing configured apps, their domains, connector selectors, static routes,
and the connector nodes assigned to each app with counts of learned and pending
routes.
From the CLI:
slopscale apps list
slopscale apps show --id 1
slopscale apps create --name "Internal Tools" \
--domain tools.corp.example.com --domain "*.tools.corp.example.com" \
--connector tag:connector \
--route 192.0.2.0/24
slopscale apps update --id 1 --route 198.51.100.0/24
slopscale apps delete --id 1
Through the API:
GET /api/v1/apps: list all apps (requirespolicy_file:read).POST /api/v1/apps: create an app (requirespolicy_file).GET /api/v1/app/{id}: retrieve an app (requirespolicy_file:read).PUT /api/v1/app/{id}: update an app definition (requirespolicy_file).DELETE /api/v1/app/{id}: delete an app (requirespolicy_file).
Creating, updating and deleting an app are audited as app.create,
app.update and app.delete.