Add live-safe DNS record lifecycle example

examples/live_safe_dns_record/README.md

@@ -0,0 +1,53 @@
+# Live Safe DNS Record Example
+
+This example is an **opt-in live test** for writable Dynu provider functionality.
+It creates exactly one disposable DNS `A` record under a user-supplied Dynu root domain,
+then you remove it with `terraform destroy`.
+
+## Safety model
+
+- Creates a **new unique subdomain** every run using `random_id`.
+- Hostname format is:
+  - `<test_prefix>-<random_hex>.<dynu_root_domain>`
+- Creates exactly one record:
+  - `A` record, default content `198.51.100.10`, default TTL `300`.
+- Does **not** import, update, replace, or delete existing production hostnames/records.
+- `terraform destroy` removes only the disposable record in this state.
+
+> [!WARNING]
+> Do not repurpose this example to target existing production subdomains.
+> Always provide only a root Dynu-managed domain (for example, `example.com`) via
+> `dynu_root_domain`.
+
+## Prerequisites
+
+- Local provider binary and Terraform `dev_overrides` set up for `dynu/dynu`.
+- `DYNU_API_KEY` exported (or set `dynu_api_key` in `terraform.tfvars`).
+- A Dynu-managed root domain you control.
+
+## Workflow
+
+```bash
+go build -o terraform-provider-dynu
+cd examples/live_safe_dns_record
+cp terraform.tfvars.example terraform.tfvars
+# edit terraform.tfvars and set only dynu_root_domain
+terraform validate
+terraform plan
+terraform apply
+```
+
+After apply, inspect outputs to confirm the generated disposable hostname and record ID,
+then clean up:
+
+```bash
+terraform destroy
+```
+
+## Cleanup guidance
+
+- Always run `terraform destroy` after testing.
+- If apply is interrupted or partially succeeds, rerun `terraform destroy` from this same
+  directory with the same `terraform.tfvars` and state files.
+- If re-running without destroying first, Terraform may keep state for the previous
+  disposable record until it is destroyed.

examples/live_safe_dns_record/main.tf

@@ -0,0 +1,33 @@
+terraform {
+  required_providers {
+    dynu = {
+      source = "dynu/dynu"
+    }
+
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.6.0"
+    }
+  }
+}
+
+provider "dynu" {
+  api_key = var.dynu_api_key
+}
+
+resource "random_id" "suffix" {
+  byte_length = 4
+}
+
+locals {
+  disposable_label    = "${var.test_prefix}-${lower(random_id.suffix.hex)}"
+  disposable_hostname = "${local.disposable_label}.${var.dynu_root_domain}"
+}
+
+resource "dynu_dns_record" "safe_live_test" {
+  hostname    = local.disposable_hostname
+  record_type = "A"
+  content     = var.test_ip
+  ttl         = var.test_ttl
+  state       = true
+}

examples/live_safe_dns_record/outputs.tf

@@ -0,0 +1,19 @@
+output "disposable_hostname" {
+  description = "Generated unique disposable hostname created by this run."
+  value       = local.disposable_hostname
+}
+
+output "disposable_record_id" {
+  description = "Dynu DNS record ID in domain_id/record_id format for the disposable record."
+  value       = dynu_dns_record.safe_live_test.id
+}
+
+output "root_domain" {
+  description = "Dynu root domain used for this live-safe test."
+  value       = var.dynu_root_domain
+}
+
+output "cleanup_reminder" {
+  description = "Reminder to destroy the disposable record after verification."
+  value       = "Run terraform destroy in this same directory/state to remove only this disposable record."
+}

examples/live_safe_dns_record/terraform.tfvars.example

@@ -0,0 +1,13 @@
+# Required: use only a Dynu-managed root domain/zone that you control.
+# Do NOT put an existing full production hostname here.
+dynu_root_domain = "example.com"
+
+# Optional prefix for generated disposable hostname labels.
+# Final hostname format: <test_prefix>-<random_hex>.<dynu_root_domain>
+test_prefix = "tfacc"
+
+# Optional: documentation/test IP for disposable A record content.
+test_ip = "198.51.100.10"
+
+# Optional TTL for disposable A record.
+test_ttl = 300

examples/live_safe_dns_record/variables.tf

@@ -0,0 +1,29 @@
+variable "dynu_api_key" {
+  description = "Dynu API key. Leave null to use DYNU_API_KEY from the environment."
+  type        = string
+  default     = null
+  sensitive   = true
+}
+
+variable "dynu_root_domain" {
+  description = "Dynu-managed root domain for creating a disposable live test subdomain (for example: example.com)."
+  type        = string
+}
+
+variable "test_prefix" {
+  description = "Prefix for the disposable test hostname label."
+  type        = string
+  default     = "tfacc"
+}
+
+variable "test_ip" {
+  description = "Safe documentation/test IPv4 value for the disposable A record."
+  type        = string
+  default     = "198.51.100.10"
+}
+
+variable "test_ttl" {
+  description = "TTL in seconds for the disposable DNS record."
+  type        = number
+  default     = 300
+}