pulumi-namecheap/README.md

A Pulumi provider for managing Namecheap domain records and DNS configuration, dynamically bridged from the Terraform Namecheap provider with support for A, AAAA, CNAME, MX, TXT records and email services.

# Pulumi Namecheap Provider

A Pulumi provider for managing Namecheap resources, dynamically bridged from the [Terraform Namecheap Provider](https://github.com/namecheap/terraform-provider-namecheap).

## Introduction

This package provides a Pulumi provider that enables you to manage your Namecheap domain records and DNS configuration using TypeScript, JavaScript, Python, Go, or C#. The provider is automatically generated from the Terraform Namecheap provider, giving you access to all its functionality within the Pulumi ecosystem.

### Features

- **Domain Record Management**: Create and manage DNS records (A, AAAA, CNAME, MX, TXT, etc.) for your Namecheap domains
- **Multiple Record Types**: Support for A, AAAA, ALIAS, CAA, CNAME, MX, MXE, NS, TXT, URL, URL301, and FRAME records
- **Email Configuration**: Configure email services with support for NONE, MXE, MX, FWD, OX, and GMAIL
- **Sandbox Support**: Test your configurations in Namecheap's sandbox environment
- **TypeScript Support**: Full type safety with comprehensive TypeScript definitions

## Installation

### npm

```bash
npm install pulumi-namecheap
```

### yarn

```bash
yarn add pulumi-namecheap
```

### pnpm

```bash
pnpm add pulumi-namecheap
```

### bun

```bash
bun add pulumi-namecheap
```

## Configuration

Before using the provider, you need to configure authentication with your Namecheap API credentials.

### Required Configuration

- **API Key**: Your Namecheap API key
- **API User**: Your Namecheap API username
- **Username**: Your Namecheap account username
- **Client IP**: The IP address from which you're making API calls (must be whitelisted in Namecheap)

### Optional Configuration

- **Use Sandbox**: Set to `true` to use Namecheap's sandbox environment for testing

### Setting Configuration

You can configure the provider in several ways:

#### 1. Using Pulumi Config

```bash
pulumi config set namecheap:apiKey your-api-key
pulumi config set namecheap:apiUser your-api-user
pulumi config set namecheap:userName your-username
pulumi config set namecheap:clientIp your-client-ip
pulumi config set namecheap:useSandbox false  # optional
```

#### 2. Using Environment Variables

```bash
export NAMECHEAP_API_KEY="your-api-key"
export NAMECHEAP_API_USER="your-api-user"
export NAMECHEAP_USER_NAME="your-username"
export NAMECHEAP_CLIENT_IP="your-client-ip"
export NAMECHEAP_USE_SANDBOX="false"  # optional
```

#### 3. Provider Constructor

```typescript
import * as namecheap from 'pulumi-namecheap'

const provider = new namecheap.Provider('namecheap-provider', {
  apiKey: 'your-api-key',
  apiUser: 'your-api-user',
  userName: 'your-username',
  clientIp: 'your-client-ip',
  useSandbox: false, // optional
})
```

## Usage

### Basic Domain Records Management

```typescript
import * as namecheap from 'pulumi-namecheap'

// Create DNS records for your domain
const records = new namecheap.DomainRecords('my-domain-records', {
  domain: 'example.com',
  mode: 'OVERWRITE', // MERGE (default) or OVERWRITE
  records: [
    {
      hostname: '@',
      type: 'A',
      address: '192.168.1.100',
      ttl: 300,
    },
    {
      hostname: 'www',
      type: 'CNAME',
      address: 'example.com',
      ttl: 300,
    },
    {
      hostname: '@',
      type: 'MX',
      address: 'mail.example.com',
      mxPref: 10,
      ttl: 300,
    },
    {
      hostname: '@',
      type: 'TXT',
      address: 'v=spf1 include:_spf.google.com ~all',
      ttl: 300,
    },
  ],
})
```

### Advanced Configuration with Email Setup

```typescript
import * as namecheap from 'pulumi-namecheap'

const domainRecords = new namecheap.DomainRecords('example-domain', {
  domain: 'example.com',
  emailType: 'GMAIL', // Configure Gmail for email
  mode: 'MERGE',
  records: [
    // A record for root domain
    {
      hostname: '@',
      type: 'A',
      address: '203.0.113.1',
      ttl: 1800,
    },
    // CNAME for www subdomain
    {
      hostname: 'www',
      type: 'CNAME',
      address: 'example.com',
      ttl: 1800,
    },
    // Multiple MX records for redundancy
    {
      hostname: '@',
      type: 'MX',
      address: 'aspmx.l.google.com',
      mxPref: 1,
      ttl: 3600,
    },
    {
      hostname: '@',
      type: 'MX',
      address: 'alt1.aspmx.l.google.com',
      mxPref: 5,
      ttl: 3600,
    },
    // TXT record for domain verification
    {
      hostname: '@',
      type: 'TXT',
      address: 'google-site-verification=your-verification-string',
      ttl: 3600,
    },
  ],
})

// Export the domain records ID
export const domainRecordsId = domainRecords.domainRecordsId
```

### Using Custom Provider Instance

```typescript
import * as namecheap from 'pulumi-namecheap'

// Create a custom provider for sandbox testing
const sandboxProvider = new namecheap.Provider('sandbox-provider', {
  apiKey: 'your-sandbox-api-key',
  apiUser: 'your-api-user',
  userName: 'your-username',
  clientIp: 'your-client-ip',
  useSandbox: true,
})

// Use the custom provider
const testRecords = new namecheap.DomainRecords(
  'test-records',
  {
    domain: 'test-domain.com',
    records: [
      {
        hostname: 'test',
        type: 'A',
        address: '192.168.1.1',
        ttl: 300,
      },
    ],
  },
  { provider: sandboxProvider },
)
```

## Resources

### DomainRecords

Manages DNS records for a Namecheap domain.

#### Properties

- **domain** (Required): The domain name to manage records for
- **records** (Optional): Array of DNS record configurations
- **emailType** (Optional): Email service configuration (`NONE`, `MXE`, `MX`, `FWD`, `OX`, `GMAIL`)
- **mode** (Optional): How to handle existing records (`MERGE` or `OVERWRITE`)
- **nameservers** (Optional): Custom nameservers for the domain

#### Record Types

Each record in the `records` array supports:

- **hostname** (Required): The subdomain/hostname for the record
- **type** (Required): Record type (`A`, `AAAA`, `ALIAS`, `CAA`, `CNAME`, `MX`, `MXE`, `NS`, `TXT`, `URL`, `URL301`, `FRAME`)
- **address** (Required): The target IP address or hostname
- **ttl** (Optional): Time to live (60-60000 seconds)
- **mxPref** (Optional): MX record priority (required for MX records)

## API Reference

For detailed API documentation, see the generated documentation in your IDE or visit the [Pulumi Registry](https://www.pulumi.com/registry/).

## Authentication Setup

### Getting Your API Credentials

1. **Log in to Namecheap**: Go to your Namecheap account dashboard
2. **Enable API Access**: Navigate to Profile → Tools → Namecheap API Access
3. **Generate API Key**: Create a new API key for your application
4. **Whitelist IP**: Add your client IP address to the whitelist
5. **Note Your Details**: Save your API key, username, and API user name

### Testing in Sandbox

Namecheap provides a sandbox environment for testing. Set `useSandbox: true` in your provider configuration to use the sandbox API endpoints.

## Examples

You can find more examples in the [examples directory](./examples) or check out these common use cases:

- [Basic A/CNAME Records](./examples/basic-records)
- [Email Configuration](./examples/email-setup)
- [Multi-domain Management](./examples/multiple-domains)
- [Sandbox Testing](./examples/sandbox-testing)

## Support

This provider is a derived work of the [Terraform Provider](https://github.com/namecheap/terraform-provider-namecheap) distributed under [MPL 2.0](https://www.mozilla.org/en-US/MPL/2.0/).

If you encounter a bug or missing feature, please consult the source [`terraform-provider-namecheap` repo](https://github.com/namecheap/terraform-provider-namecheap/issues).

For Pulumi-specific issues, please open an issue in the [pulumi-any-terraform repository](https://github.com/hckhanh/pulumi-any-terraform).

## License

This package is distributed under the MIT License. The underlying Terraform provider is distributed under MPL 2.0.