mirror of
https://github.com/tailscale/tailscale.git
synced 2025-02-18 02:48:40 +00:00
api.md: add documentation for new split DNS endpoints (#11922)
Add documentation for GET/PATCH/PUT `api/v2/tailnet/<ID>/dns/split-dns`. These endpoints allow for reading, partially updating, and replacing the split DNS settings for a given tailnet. Updates https://github.com/tailscale/corp/issues/19483 Signed-off-by: Mario Minardi <mario@tailscale.com>
This commit is contained in:
parent
7ba8f03936
commit
ec04c677c0
162
api.md
162
api.md
@ -93,6 +93,10 @@ The Tailscale API does not currently support pagination. All results are returne
|
||||
- **Search paths**
|
||||
- Get search paths: [`GET /api/v2/tailnet/{tailnet}/dns/searchpaths`](#get-search-paths)
|
||||
- Set search paths: [`POST /api/v2/tailnet/{tailnet}/dns/searchpaths`](#set-search-paths)
|
||||
- **Split DNS**
|
||||
- Get split DNS: [`GET /api/v2/tailnet/{tailnet}/dns/split-dns`](#get-split-dns)
|
||||
- Update split DNS: [`PATCH /api/v2/tailnet/{tailnet}/dns/split-dns`](#update-split-dns)
|
||||
- Set split DNS: [`PUT /api/v2/tailnet/{tailnet}/dns/split-dns`](#set-split-dns)
|
||||
|
||||
# Device
|
||||
|
||||
@ -1975,3 +1979,161 @@ The response is a JSON object containing the new list of search paths.
|
||||
"searchPaths": ["user1.example.com", "user2.example.com"],
|
||||
}
|
||||
```
|
||||
|
||||
## Get split DNS
|
||||
|
||||
```http
|
||||
GET /api/v2/tailnet/{tailnet}/dns/split-dns
|
||||
```
|
||||
|
||||
Retrieves the split DNS settings, which is a map from domains to lists of nameservers, that is currently set for the given tailnet.
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `tailnet` (required in URL path)
|
||||
|
||||
The tailnet organization name.
|
||||
|
||||
### Request example
|
||||
|
||||
```sh
|
||||
curl "https://api.tailscale.com/api/v2/tailnet/example.com/dns/split-dns" \
|
||||
-u "tskey-api-xxxxx:"
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"example.com": ["1.1.1.1", "1.2.3.4"],
|
||||
"other.com": ["2.2.2.2"]
|
||||
}
|
||||
```
|
||||
|
||||
## Update split DNS
|
||||
|
||||
```http
|
||||
PATCH /api/v2/tailnet/{tailnet}/dns/split-dns
|
||||
```
|
||||
|
||||
Performs partial updates of the split DNS settings for a given tailnet. Only domains specified in the request map will be modified. Setting the value of a mapping to "null" clears the nameservers for that domain.
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `tailnet` (required in URL path)
|
||||
|
||||
The tailnet organization name.
|
||||
|
||||
#### `PATCH` body format
|
||||
|
||||
Specify mappings from domain name to a list of nameservers in a JSON object:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"example.com": ["1.1.1.1", "1.2.3.4"],
|
||||
"other.com": ["2.2.2.2"]
|
||||
}
|
||||
```
|
||||
|
||||
### Request example: updating split DNS settings for multiple domains
|
||||
|
||||
```sh
|
||||
curl -X PATCH "https://api.tailscale.com/api/v2/tailnet/example.com/dns/split-dns" \
|
||||
-u "tskey-api-xxxxx:" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data-binary '{"example.com": ["1.1.1.1", "1.2.3.4"], "other.com": ["2.2.2.2"]}'
|
||||
```
|
||||
|
||||
### Response: updating split DNS settings for multiple domains
|
||||
|
||||
The response is a JSON object containing the updated map of split DNS settings.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"example.com": ["1.1.1.1", "1.2.3.4"],
|
||||
"other.com": ["2.2.2.2"],
|
||||
<existing unmodified key / value pairs>
|
||||
}
|
||||
```
|
||||
|
||||
### Request example: unsetting nameservers for a domain
|
||||
|
||||
```sh
|
||||
curl -X PATCH "https://api.tailscale.com/api/v2/tailnet/example.com/dns/split-dns" \
|
||||
-u "tskey-api-xxxxx:" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data-binary '{"example.com": null}'
|
||||
```
|
||||
|
||||
### Response: unsetting nameservers for a domain
|
||||
|
||||
The response is a JSON object containing the updated map of split DNS settings.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
<existing unmodified key / value pairs without example.com>
|
||||
}
|
||||
```
|
||||
|
||||
## Set split DNS
|
||||
|
||||
```http
|
||||
PUT /api/v2/tailnet/{tailnet}/dns/split-dns
|
||||
```
|
||||
|
||||
Replaces the split DNS settings for a given tailnet. Setting the value of a mapping to "null" clears the nameservers for that domain. Sending an empty object clears nameservers for all domains.
|
||||
|
||||
### Parameters
|
||||
|
||||
#### `tailnet` (required in URL path)
|
||||
|
||||
The tailnet organization name.
|
||||
|
||||
#### `PUT` body format
|
||||
|
||||
Specify mappings from domain name to a list of nameservers in a JSON object:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"example.com": ["1.2.3.4"],
|
||||
"other.com": ["2.2.2.2"]
|
||||
}
|
||||
```
|
||||
|
||||
### Request example: setting multiple domains
|
||||
|
||||
```sh
|
||||
curl -X PUT "https://api.tailscale.com/api/v2/tailnet/example.com/dns/split-dns" \
|
||||
-u "tskey-api-xxxxx:" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data-binary '{"example.com": ["1.2.3.4"], "other.com": ["2.2.2.2"]}'
|
||||
```
|
||||
|
||||
### Response: unsetting nameservers for a domain
|
||||
|
||||
The response is a JSON object containing the updated map of split DNS settings.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"example.com": ["1.2.3.4"],
|
||||
"other.com": ["2.2.2.2"]
|
||||
}
|
||||
```
|
||||
|
||||
### Request example: unsetting all domains
|
||||
|
||||
```sh
|
||||
curl -X PUT "https://api.tailscale.com/api/v2/tailnet/example.com/dns/split-dns" \
|
||||
-u "tskey-api-xxxxx:" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data-binary '{}'
|
||||
```
|
||||
|
||||
### Response: unsetting nameservers for a domain
|
||||
|
||||
The response is a JSON object containing the updated map of split DNS settings.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
}
|
||||
```
|
Loading…
x
Reference in New Issue
Block a user