Skip to content
dns-gate

Adopt and transfer

Records created before the gate are foreign: readable, changed by nobody. An administrator adopts them for a team. Later, a team hands records to another team with a transfer, approved by someone allowed to write them for the owner team. Background: Teams and ownership.

Adopt existing records

Two steps: a preview, bound to the exact content it saw, then the adoption, all or nothing, with a mandatory comment. In the Quickstart, admin adopts www CNAME for team web.

ADMIN=$(curl -fsS "http://127.0.0.1:8090/mint?sub=admin")
admin=(-H "Authorization: Bearer $ADMIN" -H "Content-Type: application/json")

PREVIEW=$(curl -fsS "${admin[@]}" -X POST "$GATE/api/v1/zones/example.com/adopt/preview" \
  -d '{"rrsets": [{"host": "www", "type": "CNAME"}], "owner": "web"}')
echo "$PREVIEW" | jq '.candidates[] | {host, type, adoptable, reason}'

curl -fsS "${admin[@]}" -X POST "$GATE/api/v1/zones/example.com/adopt" -d "$(jq -n \
  --arg t "$(echo "$PREVIEW" | jq -r .preview_token)" \
  '{rrsets: [{host: "www", type: "CNAME"}], owner: "web", preview_token: $t,
    comment: "www belongs to the web site"}')"
$Admin = Invoke-RestMethod "http://127.0.0.1:8090/mint?sub=admin"
$AH = @{ Authorization = "Bearer $Admin" }
$Sel = @(@{ host = "www"; type = "CNAME" })

$Preview = Invoke-RestMethod "$Gate/api/v1/zones/example.com/adopt/preview" -Method Post -Headers $AH `
  -ContentType "application/json" -Body (@{ rrsets = $Sel; owner = "web" } | ConvertTo-Json -Depth 4)
$Preview.candidates | Format-Table host, type, adoptable, reason

Invoke-RestMethod "$Gate/api/v1/zones/example.com/adopt" -Method Post -Headers $AH `
  -ContentType "application/json" -Body (@{ rrsets = $Sel; owner = "web"
    preview_token = $Preview.preview_token
    comment = "www belongs to the web site" } | ConvertTo-Json -Depth 4)
admin = requests.Session()
admin.headers["Authorization"] = "Bearer " + requests.get(
    "http://127.0.0.1:8090/mint", params={"sub": "admin"}).text
sel = [{"host": "www", "type": "CNAME"}]

preview = admin.post(f"{GATE}/api/v1/zones/example.com/adopt/preview",
                     json={"rrsets": sel, "owner": "web"}).json()
print([(c["host"], c["type"], c["adoptable"], c.get("reason")) for c in preview["candidates"]])

admin.post(f"{GATE}/api/v1/zones/example.com/adopt", json={
    "rrsets": sel, "owner": "web", "preview_token": preview["preview_token"],
    "comment": "www belongs to the web site",
}).raise_for_status()
const adminToken = await (await fetch("http://127.0.0.1:8090/mint?sub=admin")).text();
const admin = { Authorization: `Bearer ${adminToken}`, "Content-Type": "application/json" };
const sel = [{ host: "www", type: "CNAME" }];

const preview = await (await fetch(`${GATE}/api/v1/zones/example.com/adopt/preview`, {
  method: "POST", headers: admin, body: JSON.stringify({ rrsets: sel, owner: "web" }) })).json();
console.table(preview.candidates);

await fetch(`${GATE}/api/v1/zones/example.com/adopt`, { method: "POST", headers: admin,
  body: JSON.stringify({ rrsets: sel, owner: "web", preview_token: preview.preview_token,
    comment: "www belongs to the web site" }) });

Preview adopting www CNAME in example.com for team web, then adopt it with the comment "www belongs to the web site".

Tools adopt_preview and adopt_apply.

The selection is rrsets, or hosts globs with types. A candidate that is not adoptable says why: protected, owned_by_other_team, reserved_for_other_team, a read-only reason such as server_managed... 409 adopt_conflict means something changed since the preview: preview again.

Once a team owns its records, the gate exports them as Terraform with import blocks: GET /api/v1/zones/example.com/terraform?team=web. The onboarding guide walks a whole zone through.

Transfer records to another team

A member of the owner team (or of the target team) asks; someone allowed to write the records through the owner team approves. With ownership.require_second_approver: true the approver must be another person; the Quickstart keeps the default, so alice may approve her own request (audited as approval: self), or send "apply": true to do both at once.

ID=$(curl -fsS "${auth[@]}" -X POST "$GATE/api/v1/zones/example.com/transfers" \
  -H "Content-Type: application/json" -d '{
    "rrsets": [{"host": "docs", "type": "CNAME"}], "to_team": "shop",
    "comment": "the shop team runs the docs site now"}' | jq -r .id)

curl -fsS "${auth[@]}" -X POST "$GATE/api/v1/transfers/$ID/approve" \
  -H "Content-Type: application/json" -d '{"comment": "ok"}' | jq .status
$Transfer = Invoke-RestMethod "$Gate/api/v1/zones/example.com/transfers" -Method Post -Headers $H `
  -ContentType "application/json" -Body (@{
    rrsets = @(@{ host = "docs"; type = "CNAME" }); to_team = "shop"
    comment = "the shop team runs the docs site now" } | ConvertTo-Json -Depth 4)

(Invoke-RestMethod "$Gate/api/v1/transfers/$($Transfer.id)/approve" -Method Post -Headers $H `
  -ContentType "application/json" -Body '{"comment": "ok"}').status
transfer = s.post(f"{GATE}/api/v1/zones/example.com/transfers", json={
    "rrsets": [{"host": "docs", "type": "CNAME"}], "to_team": "shop",
    "comment": "the shop team runs the docs site now",
}).json()
print(s.post(f"{GATE}/api/v1/transfers/{transfer['id']}/approve",
             json={"comment": "ok"}).json()["status"])
const transfer = await (await fetch(`${GATE}/api/v1/zones/example.com/transfers`, {
  method: "POST", headers: json, body: JSON.stringify({
    rrsets: [{ host: "docs", type: "CNAME" }], to_team: "shop",
    comment: "the shop team runs the docs site now" }) })).json();
const decided = await (await fetch(`${GATE}/api/v1/transfers/${transfer.id}/approve`, {
  method: "POST", headers: json, body: JSON.stringify({ comment: "ok" }) })).json();
console.log(decided.status);

Ask to transfer docs CNAME in example.com to team shop, because the shop team runs the docs site now.

Tools transfer_propose, then transfer_approve (or transfer_list with status: proposed for the inbox).

The answer is the transfer, applied once approved. It fails with 412 precondition if a record changed since the request, and expires after ownership.transfer_ttl (7 days) without a decision. The requester can always withdraw it (POST /api/v1/transfers/{id}/reject). GET /api/v1/transfers?status=proposed is the approver's inbox. Terraform never transfers: changing team on a dnsgate_record_set fails until the transfer is approved.