# Create a hosted zone

Create a hosted zone for a domain, and see which names you cannot host because they are taken or belong to the platform.

Replace _example.com_ with your domain. The name is trimmed, lowercased and stored without a
trailing dot, and cannot be changed later.

## Prerequisites

- Permission for `dns:CreateZone`. Without it, the console shows **Create hosted zone** as
  unavailable, with the note "Creating a hosted zone needs dns:CreateZone. 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 new zone (without it the zone's page is not
  found).
- Room in the **Hosted zones** quota (see [Quotas](quotas.md)).
- Tags your organization marks as required.

## Create the zone

Hosted zones are free.

**Console**
1. Open **Hosted zones**, then choose **Create hosted zone**.
2. For **Domain**, enter example.com: the registrable domain, without a scheme or a trailing
   dot.
3. (Optional) Under **Tags**, add tags.
4. Choose **Create**.

The console opens the zone's page. If you leave the dialog before creating, what you typed is kept
for the next time you open it.

**CLI**
```sh
dcloud dns zones create --name example.com --tags env=prod
```

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

The answer is `201` with the zone, its `nameservers`, `delegationStatus` `pending` and
`dnssecStatus` `off`.

**Terraform**
```hcl
resource "dcloud_dns_zone" "main" {
  name = "example.com"
}

output "nameservers" {
  value = dcloud_dns_zone.main.nameservers
}
```

Changing `name` or `tags` replaces the zone, and with it every record.

## Result

The zone exists, with no records of yours. Its apex `SOA` and `NS` sets are the platform's: the
`NS` set lists the platform nameservers and cannot be changed. The zone is answered on the internet
only once you delegate the domain (see [Delegate a domain](delegate-a-domain.md)).

## When creation is refused

A domain is held by one organization on the platform, and a zone holds the whole tree under it.
Nothing checks that you own a domain before its zone is created, so a name is available to whoever
claims it first.

- `400` "name: Use a domain such as example.com" when the name is not a domain.
- `400` "… is the platform's own domain, so a zone cannot be it, sit under it, or enclose it" for
  the platform's own domain, a name under it, or a name above it.
- `409` "example.com is already a hosted zone on this platform, held by another organization", or
  "example.com overlaps shop.example.com, a hosted zone held by another organization", when another
  organization holds the domain, a name above it or a name below it as a hosted zone. The same
  messages say "a custom domain" when the name is an app's custom domain of another organization.
- `409` when the name is inside one of your own zones (`shop.example.com` inside `example.com`);
  the message names that zone and says it is yours. Delegate it from that zone with an `NS` set instead (see
  [Add a record](add-a-record.md)).
- `409` "Quota exceeded: Hosted zones (dns.zones) — …" when the quota is used up.
- `400` when a tag your organization requires is missing.

## Related

- [Delegate a domain](delegate-a-domain.md)
- [Import or export a zone file](import-or-export-a-zone-file.md)
- `dns.zones.create` · `dcloud dns zones create` · `dcloud_dns_zone`
