Host DNS zones and records

You create a DNS zone, add a record and verify authoritative and recursive answers.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• Control of example.com and access to its delegation settings. Export DNS_RECORD_NAME with the accepted API representation of www.example.com. The record-name form needs verification below.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
DNS_RECORD_NAME	Your accepted configuration value.
ZONE_ID	Returned resource identifier, or your selected scope identifier.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'ZONE_ID: ' ZONE_ID
export ZONE_ID

Steps

1. Create the zone.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/dns-zones" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"name":"example.com"}'

   API reference: Create a new authoritative DNS zone

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "zoneId": 1
     }
   }

   Set ZONE_ID to the returned zoneId.

2. Read the zone and use its returned delegation information.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/dns-zones/$ZONE_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get DNS zone associated with your account

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "zoneId": 1
     }
   }

   TODO(verify): The precise returned delegation fields and the customer steps for changing delegation.

3. Create an A record.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/dns-zones/$ZONE_ID/records" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'record': {'name': os.environ['DNS_RECORD_NAME'], 'type': 'A', 'ttl': 300, 'content': {'raw': {'value': '192.0.2.10'}}}}))
   PYBODY

   API reference: Create a DNS record inside a zone associated with your account

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "recordId": 1
     }
   }

4. Read the records.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/dns-zones/$ZONE_ID/records" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Returns the DNS records for a specific zone

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200
   }

Verify

Compare the authoritative answer for www.example.com with 192.0.2.10. Then compare recursive answers after the previous TTL expires. A DNS answer does not establish TLS readiness or origin health. TODO(verify): Whether record names must be relative or fully qualified for this create example.

An API mutation saves desired configuration first. Readback and a live traffic check answer different questions. No fixed propagation time is established.

Troubleshooting

Symptom	Cause	Fix
Authoritative answer is missing	Delegation, name or type differs	Check zone delegation and the saved record.
Recursive answer remains old	Previous TTL has not expired	Compare authoritative answers first and wait for the previous TTL.
Record mutation fails	Conflicting records or invalid content	Check the type and supply exactly one content representation.

Limits and defaults

Setting	Limit or default
TTL	Default 300 seconds; 60 to 86400
Record name	Maximum 255 characters
Types	A, AAAA, CAA, CNAME, MX, NS, PTR, SRV or TXT
Content representations	Exactly 1
Disabled and flatten flags	Both default false

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
404	Resource or parent is unavailable.
409	Resource state conflicts with the operation.

Related API operations

• DELETE /dns-zones/{zoneId}
• DELETE /dns-zones/{zoneId}/records/{recordId}
• GET /dns-zones
• GET /dns-zones/{zoneId}
• GET /dns-zones/{zoneId}/records
• GET /dns-zones/{zoneId}/records/{recordId}
• PATCH /dns-zones/{zoneId}/records/{recordId}
• POST /dns-zones
• POST /dns-zones/{zoneId}/records
• PUT /dns-zones/{zoneId}/records/{recordId}

API reference

• Delete a DNS zone and its records

• Delete a DNS record associated with your account

• List DNS zones associated with your account

• Get DNS zone associated with your account

• Returns the DNS records for a specific zone

• Get DNS record associated with your account

• Update a DNS record associated with your account

• Create a new authoritative DNS zone

• Create a DNS record inside a zone associated with your account

• Replace a DNS record associated with your account

• DNS Zones

Need Help?

Contact your account manager or use the Balancer portal.