netbirdio · lixmal · Mar 18, 2026
diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx
@@ -309,6 +309,10 @@ export const docsNavigation = [
           },
           { title: 'DNS Settings', href: '/manage/dns/dns-settings' },
           { title: 'Custom Zones', href: '/manage/dns/custom-zones' },
+          {
+            title: 'Extra DNS Labels',
+            href: '/manage/dns/extra-dns-labels',
+          },
           {
             title: 'DNS Aliases for Routed Networks',
             href: '/manage/dns/dns-aliases-for-routed-networks',

diff --git a/src/pages/get-started/cli.mdx b/src/pages/get-started/cli.mdx
@@ -121,12 +121,11 @@ netbird up --setup-key AAAA-BBB-CCC-DDDDDD
 ```
 You can set extra DNS labels with the `--extra-dns-labels` flag:
 ```shell
-netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,mgmt1 
+netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,mgmt1
 ```
 <Note>
-    This feature requires a setup-key with permissions to add peers with the extra labels.
+    This feature requires a setup key with the **Allow Extra DNS Labels** option enabled. See [Extra DNS Labels](/manage/dns/extra-dns-labels) for full details, including wildcard labels and round-robin load balancing.
 </Note>
-Multiple peers with the same extra labels will generate grouped DNS labels on the client side, and this feature can be used for DNS round-robing load balancing.
 
 ### login
 Command to authenticate the NetBird client to a management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.

diff --git a/src/pages/manage/dns/extra-dns-labels.mdx b/src/pages/manage/dns/extra-dns-labels.mdx
@@ -0,0 +1,79 @@
+export const description = 'Assign extra DNS labels to peers for service discovery and load balancing'
+import {Note} from "@/components/mdx"
+
+# Extra DNS Labels
+
+Extra DNS labels let you assign additional DNS names to peers beyond their default hostname. Other peers in your NetBird network can then reach the labeled peer using these names. When multiple peers share the same label, queries are resolved in round-robin order, providing basic DNS-based load balancing.
+
+## Prerequisites
+
+Extra DNS labels require a [setup key](/manage/peers/register-machines-using-setup-keys) with the **Allow Extra DNS Labels** option enabled. Without this, the management server rejects the labels during registration.
+
+## Assigning Labels
+
+Pass labels as a comma-separated list with the `--extra-dns-labels` flag:
+
+```shell
+netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,api
+```
+
+You can also use the `NB_EXTRA_DNS_LABELS` environment variable, which is useful for containerized deployments:
+
+```yaml {{ title: 'Container environment' }}
+environment:
+  - NB_SETUP_KEY=AAAA-BBB-CCC-DDDDDD
+  - NB_EXTRA_DNS_LABELS=vpc1,api
+```
+
+This creates DNS records `vpc1.netbird.cloud` and `api.netbird.cloud` (or your custom peer DNS domain) pointing to the peer's NetBird IP. All other peers in the account can resolve these names.
+
+To clear previously set labels, pass an empty string:
+
+```shell
+netbird up --extra-dns-labels ""
+```
+
+<Note>
+Labels must be valid DNS names: ASCII alphanumeric characters, hyphens, and underscores. Unicode domain names are not auto-converted to punycode. Maximum 32 labels per peer.
+</Note>
+
+## Wildcard Labels
+
+You can use a wildcard prefix to match any single subdomain level:
+
+```shell
+netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels "*.myserver"
+```
+
+This creates a wildcard DNS record `*.myserver.netbird.cloud`. Any single-level subdomain query resolves to the peer's IP:
+
+- `app1.myserver.netbird.cloud` - resolves
+- `app2.myserver.netbird.cloud` - resolves
+- `anything.myserver.netbird.cloud` - resolves
+
+<Note>
+Wildcard matching follows standard DNS rules ([RFC 4592](https://www.rfc-editor.org/rfc/rfc4592)): only a single subdomain level is matched. `deep.sub.myserver.netbird.cloud` would **not** match `*.myserver.netbird.cloud`.
+</Note>
+
+Wildcard labels are useful when running a reverse proxy on a peer that serves multiple applications on different subdomains. You don't need to add a new label each time you add an application.
+
+## Round-Robin Load Balancing
+
+When multiple peers share the same label, DNS queries for that label rotate through all matching peers' IPs. For example, if three peers all register with the label `api`:
+
+```shell
+# On peer-1, peer-2, and peer-3:
+netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels api
+```
+
+Queries for `api.netbird.cloud` from any other peer cycle through the three IPs, distributing connections across them.
+
+<Note>
+This is DNS-level round-robin only. There is no health checking. If a peer goes offline, its IP may still be returned until the peer is removed from the network.
+</Note>
+
+## Related
+
+- [Setup Keys](/manage/peers/register-machines-using-setup-keys) - Create keys with the **Allow Extra DNS Labels** option
+- [CLI Reference](/get-started/cli) - `--extra-dns-labels` flag documentation
+- [Custom Zones](/manage/dns/custom-zones) - Manage DNS records distributed to peers
diff --git a/src/pages/manage/dns/index.mdx b/src/pages/manage/dns/index.mdx
@@ -140,5 +140,6 @@ You can disable DNS management for specific groups in [DNS Settings](/manage/dns
 - **[Internal DNS Servers](/manage/dns/internal-dns-servers)** - Configure nameservers and work with AD, BIND, and other internal DNS
 - **[DNS Settings](/manage/dns/dns-settings)** - Control DNS management per group
 - **[Custom Zones](/manage/dns/custom-zones)** - Create private DNS records distributed to peers
+- **[Extra DNS Labels](/manage/dns/extra-dns-labels)** - Assign additional DNS names to peers for service discovery and load balancing
 - **[Troubleshooting](/manage/dns/troubleshooting)** - Diagnose DNS issues
 - **[API Reference](/ipa/resources/dns)** - Automate DNS configuration
diff --git a/src/pages/manage/peers/register-machines-using-setup-keys.mdx b/src/pages/manage/peers/register-machines-using-setup-keys.mdx
@@ -50,12 +50,14 @@ You can set expiration when creating a key. When expired, the setup key can't be
 By default, every reusable key has unlimited usage.
 We recommend limiting the number of times the key can be used, e.g., set it to 30 if you need to enroll only 30 machines.
 
-## Allow Extra DNS labels
+## Allow Extra DNS Labels
 
-You can create a setup key with the `Allow Extra DNS labels` option enabled.
-When enabled, peers added using this key will be able to add extra DNS labels and with that other peers in the NetBird network can reach them with these labels.
+You can create a setup key with the **Allow Extra DNS Labels** option enabled.
+When enabled, peers registered with this key can set additional DNS names using the `--extra-dns-labels` flag. Other peers in the network can then reach them by these names.
 
-If you add multiple peers with the same labels, they became part of a DNS round-robin group for the shared label. This is useful to access services running on multiple nodes.
+If multiple peers share the same label, they form a DNS round-robin group for that label, distributing queries across all of them.
+
+See [Extra DNS Labels](/manage/dns/extra-dns-labels) for full details, including wildcard labels and usage examples.
 
 ## Peer Auto-grouping