# Get started with DNS

Create a hosted zone, add a record, see what the zone needs at the registrar, and delete the zone again, in about ten minutes.

Replace _example.com_ with a domain you own, and _zone-id_ with the id of the zone you create in
step 1. Nothing in this tutorial changes your registrar, so the domain keeps resolving where it does
today.

## Prerequisites

- Permission for `dns:CreateZone`, `dns:ChangeRecords`, `dns:CheckDelegation` and
  `dns:DeleteZone`.
- In the console, also `dns:ListZones` to open **Hosted zones** (without it the page shows an
  access-denied notice), `dns:GetZone` to open the zone (without it the zone's page is not found)
  and `dns:ListRecords` to see its records.
- For the CLI steps, the dcloud CLI, signed in. For the API steps, an access key (see
  [Security](security.md)).

## Step 1: Create a hosted zone

Hosted zones are free.

**Console**
1. Open **Hosted zones**, then choose **Create hosted zone**.
2. For **Domain**, enter example.com.
3. Choose **Create**.

The console opens the zone. The banner says "The domain is not delegated here yet.", and the header
lists the **Nameservers**.

**CLI**
```sh
dcloud dns zones create --name example.com
```

**API**
```http
POST /dns/api/zones
{ "name": "example.com" }
```

The answer holds the zone's `id` and `nameservers`, the platform nameservers. If the domain, a name
above it or a name below it is already held by another organization, the create is refused with
`409` (see [Create a hosted zone](create-a-hosted-zone.md)).

## Step 2: Add a record

Add an `A` record that answers `www.example.com` with a documentation address.

**Console**
1. On the zone's **Records** tab, choose **Add record**.
2. For **Name**, enter www.
3. For **Type**, keep **A**.
4. For **Values, one per line**, enter `192.0.2.10`.
5. Keep **TTL (seconds)** at 3600, and choose **Add**.

The record appears in the table, under the platform's `NS` row.

**CLI**
```sh
dcloud dns records set zone-id --name www --type A --values 192.0.2.10 --ttl 3600
```

**API**
```http
POST /dns/api/zones/zone-id/records
{ "name": "www", "type": "A", "values": ["192.0.2.10"], "ttl": 3600 }
```

## Step 3: Check the delegation

The zone is answered on the internet only once the registrar names the platform nameservers. Ask
public resolvers where the domain points today.

**Console**
1. Choose the **Delegation** tab.
2. Under **Delegation check**, choose **Check now**.

The status reads **Elsewhere** while your registrar names other nameservers, and **Pending** when
the domain has no `NS` records; the sentence under it says why.

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

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

To serve the domain from here, you would now set the nameservers at the registrar (see
[Delegate a domain](delegate-a-domain.md)). This tutorial stops before that.

## Clean up

Delete the zone. Its records go with it.

**Console**
1. Choose the **Danger zone** tab, then choose **Delete zone**.
2. In the dialog, enter the domain name and choose **Delete**.

The console returns to **Hosted zones**.

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

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

## Next steps

- [Delegate a domain](delegate-a-domain.md)
- [Import or export a zone file](import-or-export-a-zone-file.md)
- [Point a name at a resource](point-a-name-at-a-resource.md)
