Namecheap Provider - Khanh Docs

The Namecheap provider allows you to manage DNS records and domain configurations on Namecheap through Pulumi's infrastructure as code approach.

Overview#

The Namecheap provider bridges the Terraform Namecheap provider to Pulumi, enabling you to:

Manage DNS records for your domains
Configure email forwarding and MX records
Use custom nameservers
Automate domain configuration

Installation#

Install the Namecheap provider package using your preferred package manager:

bun add @pulumi-any-terraform/namecheap

pnpm add @pulumi-any-terraform/namecheap

yarn add @pulumi-any-terraform/namecheap

npm install @pulumi-any-terraform/namecheap

Configuration#

The provider requires authentication with Namecheap's API. You need:

API Key: Your Namecheap API key
API User: Your API username (often same as your account username)
Username: Your Namecheap account username
Client IP (optional): Your whitelisted IP address for API access

Getting API Credentials#

Log in to your Namecheap account
Navigate to Profile → Tools → API Access
Enable API access and whitelist your IP address
Generate an API key

Configuration Options#

Configure the provider using one of these methods:

Method 1: Configuration Block#

import * as namecheap from "@pulumi-any-terraform/namecheap";const provider = new namecheap.Provider("namecheap-provider", {    apiKey: "your-api-key",    apiUser: "your-api-username",    userName: "your-username",    clientIp: "your-ip-address", // Optional    useSandbox: false, // Set to true for testing});

Method 2: Environment Variables#

export NAMECHEAP_API_KEY="your-api-key"export NAMECHEAP_API_USER="your-api-username"export NAMECHEAP_USER_NAME="your-username"export NAMECHEAP_CLIENT_IP="your-ip-address"export NAMECHEAP_USE_SANDBOX="false"

Method 3: Pulumi Configuration#

pulumi config set namecheap:apiKey "your-api-key" --secretpulumi config set namecheap:apiUser "your-api-username"pulumi config set namecheap:userName "your-username"pulumi config set namecheap:clientIp "your-ip-address"pulumi config set namecheap:useSandbox false

Quick Start#

Here's a simple example to create DNS records for a domain:

import * as namecheap from "@pulumi-any-terraform/namecheap";// Create DNS records for example.comconst dnsRecords = new namecheap.DomainRecords("example-dns", {    domain: "example.com",    mode: "OVERWRITE", // or "MERGE" to merge with existing records    emailType: "MX",    records: [        {            hostname: "@",            type: "A",            address: "192.0.2.1",            ttl: 300,        },        {            hostname: "www",            type: "A",            address: "192.0.2.1",            ttl: 300,        },        {            hostname: "@",            type: "MX",            address: "mail.example.com",            mxPref: 10,            ttl: 300,        },    ],});export const domainRecordsId = dnsRecords.domainRecordsId;

Sandbox Mode#

For testing and development, enable sandbox mode to use Namecheap's sandbox environment:

const provider = new namecheap.Provider("namecheap-sandbox", {    apiKey: "sandbox-api-key",    apiUser: "sandbox-username",    userName: "sandbox-username",    useSandbox: true,});

Resources#

The Namecheap provider includes the following resources:

DomainRecords - Manage DNS records for a domain

Best Practices#

Security#

Never commit API keys to source control
Use Pulumi secrets for sensitive configuration
Whitelist only necessary IP addresses for API access
Use separate API keys for different environments

DNS Management#

Use TTL wisely: Lower TTL (300-600 seconds) for frequently changing records, higher TTL (3600+ seconds) for stable records
OVERWRITE vs MERGE mode: Use OVERWRITE for full control, MERGE to preserve existing records
Test in sandbox: Always test configuration changes in sandbox mode first

Example Project Structure#

import * as pulumi from "@pulumi/pulumi";import * as namecheap from "@pulumi-any-terraform/namecheap";const config = new pulumi.Config();const domain = config.require("domain");// Production DNS configurationconst prodDns = new namecheap.DomainRecords("production-dns", {    domain: domain,    mode: "OVERWRITE",    records: [        // Web server        { hostname: "@", type: "A", address: "203.0.113.1", ttl: 3600 },        { hostname: "www", type: "A", address: "203.0.113.1", ttl: 3600 },                // Mail server        { hostname: "@", type: "MX", address: "mail.example.com", mxPref: 10, ttl: 3600 },                // API subdomain        { hostname: "api", type: "A", address: "203.0.113.2", ttl: 1800 },                // TXT records for verification        { hostname: "@", type: "TXT", address: "v=spf1 include:_spf.example.com ~all", ttl: 3600 },    ],});

Troubleshooting#

API Access Issues#

Error: Invalid API credentials

Verify API key, API user, and username are correct
Ensure your IP address is whitelisted in Namecheap settings

Error: Domain not found

Confirm the domain is purchased and active in your Namecheap account
Check for typos in the domain name

DNS Propagation#

DNS changes may take time to propagate:

TTL determines cache time: If previous TTL was 3600 seconds, changes may take up to 1 hour to fully propagate
Use DNS tools: Check propagation with tools like dig or online DNS checkers
Lower TTL before changes: If planning major DNS changes, lower TTL 24-48 hours in advance