Configure DNS zones
Automate setting up, deploying, and managing your Edge DNS zones and the record sets of your primary zones. Use them to integrate with your existing DNS infrastructure and manage your DNS namespace more easily.
1. Prep
If using the Edge DNS or GTM subprovider, you may also need to configure Property Manager to serve traffic via Akamai. This mostly applies when configuring an AKAMAICDN
record.
2. Create a DNS zone
Create a DNS zone resource first. It provides an operating context for all other record set resources.
By default, your Edge DNS contracts can have up to 2,000 configured zones, including aliases. Contact your service representative if you need to increase the limit.
Use the akamai_dns_zone
resource to create a new DNS zone:
-
Add your contract ID, domain zone name, and specify the zone type, either
primary
,secondary
, oralias
. Depending on the zone type, provide additional details in the body of the resource declaration.- When there's more than one group available to you, you're required to provide the group ID.
- The
sign_and_serve
argument is required for bothprimary
andsecondary
zones. - The
masters
andtsig_key
arguments are required only forsecondary
zones. - The
target
argument is required only foralias
zones.
resource "akamai_dns_zone" "my-dns-zone" { contract = "C-0N7RAC7" zone = "my-dns-zone.com" type = "primary" comment = "This is my dns zone" group = 123456 sign_and_serve = false }
-
Run
terraform plan
to check syntax andterraform apply
to create a new DNS zone. -
After creating a zone, Terraform doesn't wait for the zone to be fully activated. Instead, it returns with
activation_state
asPENDING
in your state file. Thus, you need to manually update the state:- After 1–2 minutes when the processing finishes, run
terraform plan -refresh-only
to review how Terraform would update your state file. - Then run
terraform apply -refresh-only
to apply the update of the zone'sactivation_state
in your state file.
- After 1–2 minutes when the processing finishes, run
When creating a primary zone, Akamai automatically creates the SOA
(start of authority) and NS
(name server) records for you in the Control Center UI. However, they aren't added to your configuration file. To add them, follow the steps in the Import DNS zone and records section.
Sometimes due to a network error, a primary zone is only partially created without the SOA
and NS
records. As a result, you won't be able to manage the record sets for this zone. To fix this, manually create these records before you manage the zone. See the akamai_dns_record
resource for the examples of setting up the SOA
and NS
records in Terraform.
Terraform doesn't currently support deleting DNS zones. You can do this using the Control Center UI.
3. Create a DNS record
After creating a DNS zone, add records to create record sets. Initially, the record set is empty for secondary
and alias
zones.
Each primary zone record set must contain one start of authority (SOA
) record and at least one name server (NS
) record.
Secondary zones support only AKAMAICDN
and AKAMAITLC
records. Additionally, an AKAMAITLC
record is read-only in Terraform, you can create it only via the Control Center UI. If you try to add other record types to secondary zones, you get an error.
Use the akamai_dns_record
resource to create a new DNS record:
-
Specify your domain zone name, DNS record name, DNS record type, time-to-live (TTL), and other required or optional arguments depending on the record type.
- See the arguments table of the DNS record resource for details of the supported record types and their arguments.
resource "akamai_dns_record" "my-record-type-a" { zone = "my-dns-zone.com" name = "www.my-dns-zone.com" recordtype = "A" ttl = 86400 target = ["123.4.5.67"] }
-
Run
terraform plan
to check syntax andterraform apply
to create a new DNS record. -
After creating a record for a zone, the zone's
activation_state
changes back toPENDING
in the background, but it doesn't get updated in your state file. As a result, itsactivation_state
staysACTIVE
. If you want to keep track of the zone'sactivation_state
, you can update it manually:- Run
terraform plan -refresh-only
to review how Terraform would update your state file. - Then run
terraform apply -refresh-only
to apply the update of the zone'sactivation_state
in your state file.
The DNS record configuration and state files also include a computed
record_sha
attribute that represents the current resource state to compare the local and remote DNS record configuration. When a change happens outside of Terraform, this attribute also gets updated when you refresh your state. - Run
It's recommended that you don't create multiple DNS records with the same values in the
name
andrecordtype
arguments. This is to avoid issues with deleting or updating such records. Otherwise, you'll need to fix them manually to reconcile your state file.
Configure an AKAMAICDN
record
AKAMAICDN
recordYou can set an AKAMAICDN
record for a zone only if an AKAMAITLC
record doesn't already exists for the given zone.
Before you create an AKAMAICDN
record, first configure an edge hostname via a Property Manager subprovider.
When adding this record:
- In the
target
argument, provide a DNS name representing the selected edge hostname and domain. You need to have at least viewer permissions to that hostname to create this record. - The value of the
ttl
argument needs to be20
seconds.
If you don't fulfill these requirements when creating this record, you get an error.
resource "akamai_dns_record" "my-cdn-record" {
zone = "my-cdn-record.org"
name = "www.my-cdn-record.org"
recordtype = "AKAMAICDN"
target = ["www.example.com.edgekey.net"]
ttl = 20
}
Configure an SPF
or TXT
record
SPF
or TXT
recordThe target
argument for the SPF
(sender policy framework) or TXT
(text) record accepts one or more character-strings. You can provide a string using one of these methods:
-
As an adjacent set of characters without interior spaces.
resource "akamai_dns_record" "my-txt-record" { zone = "my-txt-zone.com" name = "my-txt-zone.com" recordtype = "TXT" target = ["\"Ab1cDE2f3G4h5iJKl67MnopQrs8tUwxY9\""] ttl = 3600 }
-
As a string beginning and ending with a double quote (
"
). Inside a double-quote-delimited string, you can add any character, except for a double quote itself, which needs to be quoted using a backslash (\
).resource "akamai_dns_record" "my-txt-record" { zone = "my_txt-zone.com" name = "my-txt-zone.com" recordtype = "TXT" target = ["\"v=spf1 redirect=example1.com\"", "\"v=spf2 redirect=example2.com\""] ttl = 3600 }
If a given SPF
or TXT
record data in the target
argument has multiple strings and exceeds 255 characters, then you can split those strings into sections to avoid any errors with displaying this record on the UI. To do that:
- Contain each section within double quotes and add a space character between them to separate them.
- Also, add a space character before a closing quote of a given section as well as a backslash (
\
) to quote a double quote. - Don't include a space character before the closing quote of the last section.
- Don't separate the sections of such a record with a comma, as the system will process them as two separate records.
resource "akamai_dns_record" "my-spf-record" {
zone = "my-spf-zone.com"
name = "mailhost.my-spf-zone.com"
recordtype = "SPF"
target = ["\"v=spf1 a mx ip4:13.71.20.6 ip4:13.71.25.91 ip4:52.172.143.60 ip4:13.71.19.14 ip4:103.74.181.16 ip4:103.74.181.17 ip4:180.179.158.193 \" \"ip4:180.179.158.196 ip4:180.179.36.129 ip4:180.179.36.130 ip4:123.456.78.90 include:_spf.example.com include:_spf.example2.com include:_spf.example3.com -all\""]
ttl = 1800
}
Configure an MX
record
MX
recordYou can instantiate an MX
(mail exchanger) record configuration using one of these methods:
Method | Description |
---|---|
Couple priority and host |
Include both the priority and host in each resource "akamai_dns_record" "mx-record-self-contained" {
zone = "mx-record-self-contained-example.com"
name = "mailhost.mx-record-self-contained-example.com"
target = [
"0 smtp-0.example.com.",
"10 smtp-1.example.com."
]
recordtype = "MX"
ttl = 300
}
This configuration will generate these record data values: [
"0 smtp-0.example.com.",
"10 smtp-1.example.com."
]
|
Assign priority to hosts via start and increment parameters |
Define a number of hosts in the resource "akamai_dns_record" "mx-record-pri-increment" {
zone = "mx-pri-increment-example.com"
name = "mailhost.mx-pri-increment-example.com"
target = [
"smtp-1.example.com.",
"smtp-2.example.com.",
"smtp-3.example.com."
]
priority = 10
priority_increment = 10
recordtype = "MX"
ttl = 900
}
Edge DNS will generate the record data values by incrementally pairing and incrementing the [
"10 smtp-1.example.com.",
"20 smtp-2.example.com.",
"30 smtp-3.example.com."
]
|
Generate instances |
Generate a number of host instances using Terraform's resource "akamai_dns_record" "mx-record-instances" {
zone = "mx-record-example.com"
name = "mailhost.mx-record-example.com"
recordtype = "MX"
ttl = 500
count = 3
target = ["smtp-${count.index}.example.com."]
priority = count.index * 10
}
This configuration will generate three distinct resource instances, each with a single target and priority, and aggregated record data values. [
"0 smtp-0.example.com.",
"10 smtp-1.example.com.",
"20 smtp-2.example.com."
]
Note: When deleting a record resource with multiple instances or a single instance, it'll remove the entire remote record set resource. |
Import a DNS zone and records
To check what DNS zones are available to you, run the List zones operation.
To check what DNS records are available for your zone, run the Get a zone's record sets operation. It works only for primary
and secondary
zones.
-
Run the export command with the
--resources
flag to create a list of your zone's current record sets.Even if the zone doesn't have any record sets, the
--resources
flag is required in this command to generate a config file. Otherwise, you get an error.akamai terraform export-zone --resources {"your-dns-zone-name"}
The command will generate a JSON file, for example,
my-dns-zone-com_resources.json
.{ "Zone": "my-dns-zone.com", "Recordsets": { "my-dns-zone.com": [ "NS", "SOA" ] } }
-
Then update your configuration file using the generated JSON file as an input.
akamai terraform export-zone --createconfig {"your-dns-zone-name"}
As a result, your configuration file gets updated with the zone and record set resources. For example:
locals { zone = "my-dns-zone.com" } resource "akamai_dns_zone" "my-dns-zone.com" { contract = var.contractid group = var.groupid zone = local.zone type = "PRIMARY" masters = [] comment = "My dns zone" sign_and_serve = false sign_and_serve_algorithm = "" target = "" end_customer_id = "" } resource "akamai_dns_record" "my-dns-zone-com-NS" { zone = local.zone name = "my-dns-zone.com" recordtype = "NS" target = [ "a1-23.akam.net.", "a2-34.akam.net.", "a3-45.akam.net.", "a4-56.akam.net.", "a5-67.akam.net.", "a6-78.akam.net." ] ttl = 86400 } resource "akamai_dns_record" "my-dns-zone-com_SOA" { zone = local.zone email_address = "hostmaster.my-dns-zone.com" expiry = 604800 name = "my-dns-zone.com" name_server = "a1-23.akam.net." nxdomain_ttl = 300 recordtype = "SOA" refresh = 3600 retry = 600 target = [] ttl = 86400 }
-
Generate an import script for the zone's resources using a previously generated output.
akamai terraform export-zone --importscript {"your-dns-zone-name"}
The generated script file contains the import statements for the zone and its records:
terraform init terraform import akamai_dns_zone.{your-dns-zone-resource-name} {your-dns-zone-name} terraform import akamai_dns_record.{your-dns-record-resource-name} {your-dns-zone-name}#{your-dns-recordset-name}#{record-type}
-
If you previously created a primary zone and want to import just its
NS
andSOA
records, then remove theterraform import akamai_dns_zone.{your-dns-zone-resource-name} {your-dns-zone-name}
line from the script file to avoid creating a duplicate. -
Run the generated import script file to populate your Terraform state and prevent Terraform from attempting to recreate your assets.
Terraform doesn't have access to the zone resource configuration when processing the import. Thus, it can't populate the
group
attribute's value for that resource in your state after import. Update thegroup
locally and then runterraform apply
to reconcile your configuration and state.
Updated 17 days ago