# Delegate a domain

Set the platform nameservers at your registrar, and check that public resolvers follow them.

Replace _zone-id_ with the id of your hosted zone. Until the registrar names the platform
nameservers, the zone's records are not answered on the internet.

**Important:**
Add your records, or import them, before you change the nameservers (see
[Import or export a zone file](import-or-export-a-zone-file.md)), and keep the previous DNS host
serving until the check says the domain is delegated: until the registrar publishes the change,
resolvers still ask the old servers.

## Prerequisites

- Permission for `dns:CheckDelegation`. Without it, the console's **Check now** is unavailable,
  with the note "Checking the delegation needs dns:CheckDelegation on this zone. Ask an
  administrator."
- In the console, also `dns:ListZones` to open **Hosted zones** (without it the page shows an
  access-denied notice) and `dns:GetZone` to open the zone (without it the zone's page is not
  found).
- Access to the domain at its registrar.

## Find the nameservers

The platform nameservers are the same for every zone.

**Console**
1. Open **Hosted zones**. The list starts with **Platform nameservers**.
2. Or open the zone and choose the **Delegation** tab: **Nameservers to set at the registrar**.

**CLI**
```sh
dcloud dns zones get zone-id
```

The `nameservers` field lists them.

**API**
```http
GET /dns/api/zones/zone-id
```

The `nameservers` field lists them; `GET /dns/api/zones` returns them beside the zone list.

**Terraform**
```hcl
output "nameservers" {
  value = dcloud_dns_zone.main.nameservers
}
```

## Set them at the registrar

At your registrar, replace the domain's nameservers (its `NS` records) with the platform
nameservers. Keep none of the old ones: a domain whose `NS` records name both is reported as
**Elsewhere**, and resolvers use the old servers part of the time.

## Check the delegation

The check asks public resolvers (1.1.1.1, 9.9.9.9 and 8.8.8.8), not the platform, which `NS`
records the domain has, and stores the result on the zone.

**Console**
1. Open the zone, then choose the **Delegation** tab.
2. Under **Delegation check**, choose **Check now**.

The status, the time of the check and the sentence that explains it appear under **Delegation
check**; "The internet answers:" lists the nameservers the resolvers returned. The zone list shows
the same status under **Delegation**.

**CLI**
```sh
dcloud dns zones check-delegation zone-id
```

**API**
```http
POST /dns/api/zones/zone-id/check-delegation
```

The answer is `{ status, nameservers, expected, detail }`.

**Terraform:** not available. `delegation_status` of `dcloud_dns_zone` shows the result of the last check, but Terraform does not run one.

## Result

| Status      | Meaning                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delegated` | Every `NS` record names a platform nameserver. "Delegated to the platform nameservers."                                                                                   |
| `elsewhere` | Some or all `NS` records name other servers: "Some NS records still name other servers; …" or "The domain is served by other nameservers. Replace them at the registrar." |
| `pending`   | No `NS` records yet, or the lookup failed: "The domain has no NS records yet, or the registrar has not published them." or "Lookup failed (…); try again in a minute."    |

The status is what the last check found; it is not watched continuously. Besides **Check now**, the
CLI and the API, a zone that is not yet `delegated` is checked again when an app's routing or
custom domains are read (as the app's domains panel in the console does) and one of the app's
custom domains is in the zone, for a reader with both `dns:GetZone` and `dns:CheckDelegation`.
Until it is `delegated`, the zone's page shows a banner, "The domain is not delegated here yet." or
"The domain is delegated to other nameservers.", with **Set the nameservers**. How soon the
registrar publishes a change is up to the registrar; resolvers follow within the parent zone's
TTL.

## Related

- [Create a hosted zone](create-a-hosted-zone.md)
- [Troubleshooting](troubleshooting.md)
- `dns.zones.check-delegation` · `dcloud dns zones check-delegation`
