# Pulumi Porkbun Provider

A native [Pulumi](https://www.pulumi.com/) provider for managing DNS records on
[Porkbun](https://porkbun.com/), built with the
[pulumi-go-provider](https://github.com/pulumi/pulumi-go-provider) framework.

NOTE: This is currently pretty incomplete. I only built up what I need for
my use-case, which is controlling DNS records.

## Resources

| Resource | Description |
| --- | --- |
| `porkbun:index:DnsRecord` | A DNS record on a domain using Porkbun's nameservers. |

### `DnsRecord`

| Input | Type | Description |
| --- | --- | --- |
| `domain` (required) | string | The domain the record belongs to, e.g. `example.com`. Changing it replaces the record. |
| `name` | string | The subdomain, e.g. `www`. Empty for the root domain, `*` for a wildcard. Changing it replaces the record. |
| `type` (required) | string | One of `A`, `AAAA`, `ALIAS`, `CAA`, `CNAME`, `HTTPS`, `MX`, `NS`, `SRV`, `SSHFP`, `SVCB`, `TLSA`, `TXT`. |
| `content` (required) | string | The record's answer, e.g. an IP address for an `A` record. |
| `ttl` | int | Time to live in seconds. Defaults to `600`. |
| `prio` | int | Priority, for record types that support it (`MX`, `SRV`). Defaults to `0`. |

Outputs: all inputs, plus `fqdn` (the fully qualified record name) and `id`
(the Porkbun record ID).

Changes to `content`, `ttl`, `prio`, and `type` are applied in place through
Porkbun's edit endpoint; changes to `domain` or `name` replace the record.

## Configuration

Credentials come from Pulumi config or the environment. Create an API key pair
at <https://porkbun.com/account/api> and enable API access for each domain you
want to manage.

```sh
pulumi config set porkbun:apiKey --secret pk1_...
pulumi config set porkbun:secretApiKey --secret sk1_...
```

or:

```sh
export PORKBUN_API_KEY=pk1_...
export PORKBUN_SECRET_API_KEY=sk1_...
```

| Config key | Env var | Description |
| --- | --- | --- |
| `porkbun:apiKey` (secret) | `PORKBUN_API_KEY` | The Porkbun API key. |
| `porkbun:secretApiKey` (secret) | `PORKBUN_SECRET_API_KEY` | The Porkbun secret API key. |
| `porkbun:baseUrl` | — | Override the API endpoint (mainly for testing). |

## Usage

YAML:

```yaml
resources:
  www:
    type: porkbun:DnsRecord
    properties:
      domain: example.com
      name: www
      type: A
      content: 192.0.2.1
```

TypeScript (after `make gen-sdks`):

```typescript
import * as porkbun from "@pulumi/porkbun";

const www = new porkbun.DnsRecord("www", {
    domain: "example.com",
    name: "www",
    type: "A",
    content: "192.0.2.1",
});
```

### Importing existing records

Use an ID of the form `<domain>/<recordId>`:

```sh
pulumi import porkbun:index:DnsRecord www example.com/106926652
```

The record ID is visible in the Porkbun DNS dashboard or via the API's
retrieve endpoint.

## Development

```sh
make build      # build bin/pulumi-resource-porkbun
make test       # run unit + provider integration tests
make schema     # regenerate schema.json
make gen-sdks   # generate TypeScript/Python/Go SDKs into sdk/
make install    # install the built provider as a local Pulumi plugin
```

Tests run entirely against an in-memory fake of the Porkbun API; no
credentials or network access are required.

A runnable example lives in [`examples/yaml`](examples/yaml). It references
the locally built provider via `plugins.providers`, so `make build` first,
then run `pulumi up` inside the example directory.