Terraform Provider

Table of Contents

• Video walk-through
• Before starting
• Configure the provider
• Manage DNS records
• Add or register a domain
• Manage email forwards
• Request a Let’s Encrypt certificate
• Bring existing resources under Terraform
• Troubleshooting
• Have more questions?

DNSimple’s Terraform provider lets you manage DNS records, domains, email forwards, Let’s Encrypt certificates, and other DNSimple resources with Terraform. You configure the provider with an API access token and your account ID, describe the resources in Terraform configuration files, and run terraform apply. The provider is published as dnsimple/dnsimple in the Terraform Registry. If you use HashiCorp Consul, see Consul Integration.

Video walk-through

Before starting

You need:

• Terraform installed
• An API access token. An account token is recommended. A scoped token needs permissions for the resources you manage, such as Zones for records.
• Your account ID. The API & Access page in your account settings shows it, as in Getting to the API & Access page.

Configure the provider

Declare the provider and pass it your token and account ID:

terraform {
  required_providers {
    dnsimple = {
      source  = "dnsimple/dnsimple"
      version = "~> 2.2"
    }
  }
}

provider "dnsimple" {
  token   = var.dnsimple_token
  account = var.dnsimple_account
}

variable "dnsimple_token" {
  type      = string
  sensitive = true
}

variable "dnsimple_account" {
  type = string
}

Run terraform init to download the provider. To keep the token out of your files, set it in the DNSIMPLE_TOKEN environment variable instead. The account ID can come from DNSIMPLE_ACCOUNT in the same way, and then the provider block can be empty.

Optional settings:

• sandbox = true connects to the DNSimple Sandbox, a separate test environment with its own accounts and tokens. Try new configurations there first.
• prefetch = true lists each zone’s records once and reads them from that list, instead of fetching every record with its own request. Use it for large configurations that hit the API rate limit.

Manage DNS records

Use dnsimple_zone_record. Use an empty name for the domain apex, and write the record type in uppercase:

resource "dnsimple_zone_record" "apex" {
  zone_name = "example.com"
  name      = ""
  value     = "192.0.2.1"
  type      = "A"
  ttl       = 3600
}

resource "dnsimple_zone_record" "mx" {
  zone_name = "example.com"
  name      = ""
  value     = "mail.example.com"
  type      = "MX"
  priority  = 10
  ttl       = 3600
}

priority applies only to MX and SRV records. ttl defaults to 3600. See supported DNS record types for the record types DNSimple supports.

Add or register a domain

dnsimple_domain adds a domain to your account so you can manage its DNS. It does not register the domain:

resource "dnsimple_domain" "example" {
  name = "example.com"
}

To register a domain, use dnsimple_registered_domain with a registrant contact, which you can manage with dnsimple_contact. Registration is charged like any other domain registration. Some TLDs need extended attributes; the provider documentation shows how to pass them.

Manage email forwards

resource "dnsimple_email_forward" "sales" {
  domain            = "example.com"
  alias_name        = "sales"
  destination_email = "alice@example.net"
}

This forwards sales@example.com to alice@example.net. See Email Forwarding.

Request a Let’s Encrypt certificate

resource "dnsimple_lets_encrypt_certificate" "www" {
  domain_id  = "example.com"
  name       = "www"
  auto_renew = true
}

Use name = "" for the domain apex. The domain must resolve with DNSimple for the certificate to be issued.

To read an issued certificate into your configuration, for example to install it elsewhere, use the dnsimple_certificate data source with the certificate ID:

data "dnsimple_certificate" "www" {
  domain         = "example.com"
  certificate_id = 1234
}

Bring existing resources under Terraform

Resources you created in DNSimple can be imported, so Terraform manages them without recreating them. For example, to import record 1234 in example.com:

terraform import dnsimple_zone_record.www example.com_1234

Each resource’s page in the provider documentation shows its import format. The provider also manages zones, contacts, DS records, and name server delegation.

Troubleshooting

• 429 errors on large configurations. Each record is read with its own API request, which can exceed the rate limit. Set prefetch = true.
• A record is rejected during validation. Check that type is uppercase, and that priority is set only for MX and SRV records.
• “The zone example.com does not resolve with DNSimple”. A Let’s Encrypt certificate can only be issued while the domain uses DNSimple’s name servers. The order stays open after this error, so a new terraform apply fails with “There is already an open order for www.example.com”. Contact support to clear it once the domain resolves with DNSimple.
• A domain registration fails. Check whether the TLD needs extended attributes, as in Add or register a domain.

Have more questions?

If you have additional questions or need any assistance with our Terraform provider, contact support, and we will be happy to help. You can also read more about DNSimple integrations.