Namecheap Terraform Provider

A Terraform Provider for Namecheap domain dns configuration.

Prerequisites

First you'll need to apply for API access to Namecheap. You can do that on this API admin page.

Next, find out your IP address and add that IP (or any other IPs accessing this API) to this whitelist admin page on Namecheap.

Once you've done that, make note of the API token, your IP address, and your username to fill into our provider block.

Usage

First you'll need to manually install this Terraform Provider for now until we get this into the official providers.

Note the command below will install the Linux binary, please check releases page for Windows and Mac builds.

Linux

# Download provider
# Terraform Docs: https://www.terraform.io/docs/configuration/providers.html#third-party-plugins

$ mkdir -p ~/.terraform.d/plugins/
$ wget -O ~/.terraform.d/plugins/terraform-provider-namecheap_v1.5.0 https://github.com/adamdecaf/terraform-provider-namecheap/releases/download/1.5.0/terraform-provider-namecheap-linux-amd64

Mac

$ mkdir -p ~/.terraform.d/plugins/
$ curl -L https://github.com/adamdecaf/terraform-provider-namecheap/releases/download/1.5.0/terraform-provider-namecheap-osx-amd64 > ~/.terraform.d/plugins/terraform-provider-namecheap
$ chmod +x ~/.terraform.d/plugins/terraform-provider-namecheap

Then inside a Terraform file within your project (Ex. providers.tf):

# For example, restrict namecheap version to 1.5.0
provider "namecheap" {
  version = "~> 1.5"
}

# Create a DNS A Record for a domain you own
resource "namecheap_record" "www-example-com" {
  name = "www"
  domain = "example.com"
  address = "127.0.0.1"
  mx_pref = 10
  type = "A"
}

Setup terraform and view the plan output.

$ terraform init
Terraform has been successfully initialized!

$ terraform plan
Terraform will perform the following actions:

  + namecheap_record.www-example.com
      id:       <computed>
      address:  "127.0.0.1"
      domain:   "example.com"
      hostname: <computed>
      mx_pref:  "10"
      name:     "www"
      ttl:      "60"
      type:     "A"


Plan: 1 to add, 0 to change, 0 to destroy.

$ terraform apply
...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Building The Provider

Clone repository to: $GOPATH/src/github.com/adamdecaf/terraform-provider-namecheap

$ mkdir -p $GOPATH/src/github.com/adamdecaf ; cd $GOPATH/src/github.com/adamdecaf
$ git clone [email protected]:adamdecaf/terraform-provider-namecheap

Enter the provider directory and build the provider

$ cd $GOPATH/src/github.com/adamdecaf/terraform-provider-namecheap
$ make build

Using the provider

Make sure your API details are correct in the provider block.

provider "namecheap" {
  username = "your_username"
  api_user = "your_username" # Same as username
  token = "your_token"
  ip = "your.ip.address.here"
  use_sandbox = false # Toggle for testing/sandbox mode
}

Developing the Provider

If you wish to work on the provider, you'll first need Go installed on your machine (version 1.13+ is recommended). You'll also need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH.

This project uses Go Modules, added in Go 1.11.

To compile the provider, run make build. This will build the provider and put the provider binary in the $GOPATH/bin directory.

$ make bin
...
$ $GOPATH/bin/terraform-provider-namecheap
...

In order to test the provider, you can simply run make test.

$ make test

In order to run the full suite of Acceptance tests, run make testacc.

Note: Acceptance tests create real resources, and often cost money to run.

$ make testacc

Another good way to test builds is to symlink the binary terraform-provider-namecheap that you are building into the ~/.terraform.d/plugins/ directory.

Troubleshooting the Provider

Problem: Error: Failed to create namecheap Record: Could not find the record with hash Solution: Double check your IP did not change and make sure it is whitelisted with Namecheaps API. Also ensure the domain names you have in your terraform config are still associated with your account (in cases like where you let one expire). In these rare edge-cases, you may have to delete the bad domain records by running terraform state rm namecheap_record.the_tf_name_of_your_record.