Skip to main content
Private DNS publishes Instance names for you. This page covers the names you manage yourself: records in a network’s datum.internal zone, private zones of your own, and which networks can resolve them. Create private zones and associations with datumctl apply, and read and delete them with datumctl get and datumctl delete. You can add and change records with either datumctl apply or datumctl dns record. Your account needs the DNS Admin role to change them, and DNS Viewer to read them.

How the pieces fit

A private zone resolves only from the networks it’s associated with. Two networks can each have a zone with the same domain, and each gets its own answers.

Find a network’s DNS context and zone

To list each network’s DNS context and managed zone, run:
The output is similar to the following:
Use CONTEXT when you associate a zone with the network, and ZONE when you add records to the network’s datum.internal zone.

Add a record to datum.internal

To add a name to one network without creating a zone, add a record set to the network’s managed zone. Replace MANAGED_ZONE with the ZONE from the previous section:
db.datum.internal now resolves on that network only. You can’t add records at or below instances.datum.internal, which Compute owns. You can also use the datumctl dns plugin, which needs DNS enabled in the project. See Troubleshooting. Every network has its own datum.internal zone. If your project has more than one network, add --vpc with the network’s name to say which zone you mean:

Create a private zone

Create a zone when you want a namespace of your own, or one that several networks share:
Keep the following points in mind:
  • You can’t change a zone’s domain or visibility after you create it. Create a new zone instead.
  • A private zone resolves nowhere until you associate it with a network.
  • Prefer a domain you control, or one under .internal. If you create a private zone for a public domain, such as example.com, associated networks get your private answers instead of the public ones for every name in that domain.

Choose which networks resolve a zone

Associate the zone with each network that should resolve it:
To share the zone with another network, create another association that names that network’s context. To stop a network from resolving the zone, delete its association. The zone and its records stay. An association can’t be edited to point at a different zone or network. Delete it and create a new one. If you delete and recreate a zone with the same name, also recreate its associations. A network can’t have two associated zones with the same domain. A zone can sit below another associated zone, such as db.corp.internal below corp.internal. Lookups use the zone with the longest matching domain.

Add records to a private zone

Records in a private zone use the same DNSRecordSet resource as public DNS:
To use datumctl dns record instead, pass the zone’s domain, such as corp.internal. If more than one network has a zone with that domain, the command stops and asks for --vpc with the name of the network you mean, as in datumctl dns record list corp.internal --vpc default. Private zones support A, AAAA, CNAME, TXT, MX, SRV, CAA, NS, PTR, TLSA, HTTPS, and SVCB records. For the rules that apply, see Private DNS limits and behavior.
Instances have IPv6 addresses only. Use AAAA records for addresses on your network.

Find services by name

Use one of the following, depending on what you need:
  • One Instance: use its Compute name, such as web-default-us-central-1-0.instances.datum.internal. Read it from the Instance’s status.dns. See Private DNS for Compute.
  • A stable name for a service: add a CNAME to the network’s datum.internal zone that points at an Instance name, such as api.datum.internal → web-default-us-central-1-0.instances.datum.internal.. Update the CNAME when you replace the Instance.
  • Several Instances behind one name: create AAAA records for each address under one name, as in the example above. Clients pick an address from the answer. DNS doesn’t check whether each address is healthy.

Check status

A change goes through two steps. First the record set or association is accepted. Then the zone is programmed, and the name resolves.
For what each reason means, see Troubleshooting.

Delete names and zones

  • Delete a record set to remove its names. Clients can keep an old answer until its TTL expires.
  • Delete a zone association to stop one network from resolving the zone.
  • Delete a zone to remove it from every network. Delete its record sets and associations too.
  • Don’t delete a network’s managed zone or its association. Instance names on that network stop resolving. If you deleted one by mistake, contact support@datum.net.
Last modified on November 18, 2026