# Add a record

Add a record set to a hosted zone, or replace the set at the same name and type.

Replace _zone-id_ with the id of your hosted zone and _www_ with the name of the record. For the
value formats, see [Record sets](record-sets.md). An `ALIAS` record has its own page:
[Point a name at a resource](point-a-name-at-a-resource.md).

**Important:**
Adding a set where one with the same name and type exists replaces that set completely, and its
TTL becomes what this request says: 300 in the API, CLI and Terraform when you give none.

## Prerequisites

- Permission for `dns:ChangeRecords` on the zone. Without it, the console shows **Add record** as
  unavailable, with the note "Adding, editing or deleting a record set needs dns:ChangeRecords 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), `dns:GetZone` to open the zone (without it the zone's page is not found)
  and `dns:ListRecords` to see the zone's records.
- (Optional) For the console's address picker on `A` and `AAAA` records:
  `ec2:DescribeInstances`, `ec2:DescribeAddresses` or `lb:DescribeLoadBalancers`.
- Room in the zone's **Record sets per zone** quota when the set is new (see
  [Quotas](quotas.md)).

## Add the record set

**Console**
1. Open the zone. On the **Records** tab, choose **Add record**.
2. For **Name**, enter www, or `@` for the apex.
3. For **Type**, choose the record type.
4. For **Values, one per line**, enter the values. For `A`, you can instead choose an instance,
   Elastic IP or load balancer under **Address of one of your resources**, and for `AAAA` an
   Elastic IP or load balancer; the console adds its address to the values.
5. (Optional) Change **TTL (seconds)**. The form starts at 3600.
6. Choose **Add**.

The set appears in the table. If you close the dialog before adding, what you typed is kept for
the next **Add record**; **Start over** clears it.

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

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

An `MX` set with two mail hosts:

```http
POST /dns/api/zones/zone-id/records
{ "name": "@", "type": "MX", "values": ["10 mail.example.com", "20 mail2.example.com"], "ttl": 3600 }
```

The answer is `201` with the set as stored: the name fully qualified, host names lowercase.

**Terraform**
```hcl
resource "dcloud_dns_record" "www" {
  zone_id = dcloud_dns_zone.main.id
  name    = "www"
  type    = "A"
  ttl     = 3600
  values  = ["192.0.2.10", "192.0.2.11"]
}
```

Changing `name`, `type` or `zone_id` replaces the record.

## Delegate a name below the zone

To hand `shop.example.com` to other nameservers, add an `NS` set at `shop` with their names. The
platform then answers every name at and under `shop.example.com` with a referral to them. The
apex `NS` set is the platform's and cannot be changed.

## Result

The nameservers answer the new set from their next pull of the zone data. Resolvers that
cached the previous answer keep it until its TTL runs out.

## When the record is refused

A set the checks refuse is answered `400` with the reason, the quota `409`, and a zone that does
not exist `404` "Zone not found":

- ""-www" is not a valid name in example.com", with the name you entered in quotes.
- "The apex NS records are the platform nameservers and cannot be changed".
- "A CNAME cannot sit at the zone apex; use ALIAS for an app or A for an address".
- "www.example.com already has other records; a CNAME must be the only record at its name", also
  when the other record is a `CNAME`: to change a `CNAME`, edit it (see
  [Edit or delete a record](edit-or-delete-a-record.md)).
- "www.example.com is a CNAME; remove it before adding other records".
- "At least one value is required", or "A CNAME has exactly one value".
- A value in the wrong format, for example "192.0.2.300 is not an IPv4 address" or "mail.example.com
  is not "<priority> <mail host>"".
- `409` "A zone holds at most 10000 record sets; this one has 10000 and the change would add 1"
  when a new set does not fit in the zone's quota. Replacing a set always fits.

In the console, the dialog also refuses an empty value list ("Add at least one value, one per
line.") and a TTL that is not a whole number of at least 1 ("TTL is a whole number of seconds, at
least 1.").

## Related

- [Record sets](record-sets.md)
- [Edit or delete a record](edit-or-delete-a-record.md)
- `dns.records.set` · `dcloud dns records set` · `dcloud_dns_record`
