Skip to content

Commit eb1af6b

Browse files
matanbaruchclaude
andcommitted
docs: add App Connector documentation and integration tests
- Add App Connectors section to docs/ref/acls.md with configuration examples - Add App Connectors to feature list in docs/about/features.md - Add CHANGELOG.md entry for App Connector support - Add integration tests for app connector functionality 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 4ca8aae commit eb1af6b

4 files changed

Lines changed: 419 additions & 0 deletions

File tree

CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ sequentially through each stable release, selecting the latest patch version ava
5555

5656
### Changes
5757

58+
- Add App Connector support for domain-based routing through designated connector nodes [#2987](https://github.com/juanfont/headscale/pull/2987)
5859
- Smarter change notifications send partial map updates and node removals instead of full maps [#2961](https://github.com/juanfont/headscale/pull/2961)
5960
- Send lightweight endpoint and DERP region updates instead of full maps [#2856](https://github.com/juanfont/headscale/pull/2856)
6061
- Add `oidc.email_verified_required` config option to control email verification requirement [#2860](https://github.com/juanfont/headscale/pull/2860)

docs/about/features.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ provides on overview of Headscale's feature and compatibility with the Tailscale
3232
- [x] Basic registration
3333
- [x] Update user profile from identity provider
3434
- [ ] OIDC groups cannot be used in ACLs
35+
- [x] [App Connectors](https://tailscale.com/kb/1281/app-connectors) - Route traffic to specific domains through designated connector nodes
3536
- [ ] [Funnel](https://tailscale.com/kb/1223/funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
3637
- [ ] [Serve](https://tailscale.com/kb/1312/serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))
3738
- [ ] [Network flow logs](https://tailscale.com/kb/1219/network-flow-logs) ([#1687](https://github.com/juanfont/headscale/issues/1687))

docs/ref/acls.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,3 +285,65 @@ Used in Tailscale SSH rules to allow access to any user except root. Can only be
285285
"users": ["autogroup:nonroot"]
286286
}
287287
```
288+
289+
## App Connectors
290+
291+
Headscale supports [App Connectors](https://tailscale.com/kb/1281/app-connectors), which allow you to route traffic to specific domains through designated connector nodes. This is useful for accessing internal applications or services that are only reachable from certain nodes in your tailnet.
292+
293+
App connectors are configured in the `appConnectors` field of your ACL policy:
294+
295+
```json
296+
{
297+
"tagOwners": {
298+
"tag:connector": ["admin@"]
299+
},
300+
"appConnectors": [
301+
{
302+
"name": "Internal Apps",
303+
"connectors": ["tag:connector"],
304+
"domains": ["internal.example.com", "*.corp.example.com"],
305+
"routes": ["10.0.0.0/8"]
306+
}
307+
]
308+
}
309+
```
310+
311+
### Configuration Fields
312+
313+
| Field | Required | Description |
314+
|-------|----------|-------------|
315+
| `name` | No | A human-readable name for this app connector configuration |
316+
| `connectors` | Yes | A list of tags (e.g., `tag:connector`) or `*` (all nodes) that identifies which nodes can serve as connectors |
317+
| `domains` | Yes | A list of domain names to route through the connector. Supports wildcards like `*.example.com` |
318+
| `routes` | No | Optional list of IP prefixes to pre-configure as routes (in addition to dynamically discovered routes from DNS) |
319+
320+
### How It Works
321+
322+
1. Configure tagged nodes as app connectors in your ACL policy
323+
2. Nodes with the specified tags that advertise themselves as app connectors will receive the domain configuration
324+
3. When clients query DNS for the configured domains, traffic is automatically routed through the connector nodes
325+
4. The connector nodes resolve the DNS and forward traffic to the destination
326+
327+
### Example: Multiple Connectors
328+
329+
```json
330+
{
331+
"tagOwners": {
332+
"tag:web-connector": ["admin@"],
333+
"tag:db-connector": ["admin@"]
334+
},
335+
"appConnectors": [
336+
{
337+
"name": "Web Applications",
338+
"connectors": ["tag:web-connector"],
339+
"domains": ["*.internal.example.com", "dashboard.corp.example.com"]
340+
},
341+
{
342+
"name": "Database Access",
343+
"connectors": ["tag:db-connector"],
344+
"domains": ["db.internal.example.com"],
345+
"routes": ["10.20.30.0/24"]
346+
}
347+
]
348+
}
349+
```

0 commit comments

Comments
 (0)