diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..6bbc66c --- /dev/null +++ b/README.md @@ -0,0 +1,111 @@ +# 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. |