> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Domains and DNS zones

> Claim custom domains and host DNS zones from an infrastructure link.

Before an app or a bucket can serve a custom domain, your organization has
to claim it and prove it owns it. An infrastructure link declares claims in
two folders:

- `domains/<name>.yaml` claims a domain whose DNS you host elsewhere.
- `dns/<zone>.yaml` hosts a whole DNS zone on A-Line.cloud, with its
  records.

The file name is the domain or zone name and must be a valid DNS name.

## Domains

```yaml title="domains/example.com.yaml" iac tree=domains
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
scope: domain
```

```yaml title="domains/shop.example.net.yaml" iac tree=domains
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
scope: host
```

`scope` is `domain` (the default), which covers the name and every name
under it, or `host`, which covers exactly that name.

## Verifying a claim

A new claim is **pending**. The link's sync lists every pending claim with
the TXT record to publish: its name is `_a-line-verify.<name>`. A pending
zone also lists the nameservers to delegate it to. Once the record is
visible, the claim is verified.

While a claim is pending, nothing uses it: app domains and bucket domains
under it are not set up, and a zone's records are stored but not
published. They take effect after verification.

A claim can be refused:

| Code | Why |
| --- | --- |
| `name_unavailable` | Another organization already holds the name. |
| `claim_rate_limited` | Your organization has too many open claims, or made too many recently. |
| `resource_managed_elsewhere` | Another link of your organization manages the claim. |

## DNS zones

```yaml title="dns/example.net.yaml" iac tree=zone
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
records:
  - name: "@"
    type: A
    values: ["203.0.113.10"]
  - name: www
    type: CNAME
    ttl: 3600
    values: ["example.net."]
  - name: "@"
    type: MX
    values: ["10 mail.example.net."]
  - name: "@"
    type: TXT
    values: ["v=spf1 mx -all"]
```

Each record has:

| Key | Meaning |
| --- | --- |
| `name` | `@` for the zone itself, a name relative to the zone (`www`, `api.eu`), or an absolute name with a trailing dot that lies inside the zone. |
| `type` | `A`, `AAAA`, `CNAME`, `TXT`, `MX`, `NS`, `SRV`, `CAA`, `HTTPS` or `SVCB`. |
| `ttl` | Seconds, default 300. |
| `values` | 1 to 100 values. |

A zone lists at most 500 records, and one name and type appear once: put
several values in one record. Names starting with `_a-line-verify` or
`_acme-challenge` are written by the platform and are refused
(`reserved_record`).

When `records` is present it is the zone's full record list: records not in
it are removed. Leaving `records` out leaves the zone's records as they are.

Zones need platform DNS to be available. Deleting a zone from a file is not
supported (`zone_delete_unsupported`): delete it in the dashboard.

## Existing claims

Declaring a domain or zone your organization already has, and that no link
manages, adopts it.

## Deleting a domain

Keep the file with `delete: true` to delete the domain. The deletion is
[held](/iac/gitops#held) until someone confirms it. A domain the link doesn't
manage yet can't be deleted from a file (`resource_not_managed`).

```yaml title="domains/old.example.com.yaml" iac tree=delete
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
delete: true
```

## Removing a file

Deleting a file from `domains/` or `dns/` never deletes the domain or zone:
it and its records stay as they are. The next sync stops managing it, so it
is editable in the dashboard again, and the plan lists the release. To
delete a domain, keep its file with `delete: true` as shown above. Delete a
zone in the dashboard.

To use a verified domain, list it in an app's
[`domains`](/iac/networking#domains) or a bucket's
[`domains`](/iac/buckets#buckets).
