Add dns-record module + new-vm-with-dns example + ADR (#2)

Adds a thin Terraform module that wraps kenske/technitium's
technitium_dns_zone_record so any consumer's TF root can register a
<name>.lan A record alongside its proxmox-vm call. The zone itself is
intentionally not created here — it remains a singleton owned by
homelab-services/services/dns/terraform-config/.

The reusable provision-vm.yml workflow gains an opt-in input
`create_dns_record: bool` (default false). When true it also loads
/technitium/ from Infisical and forwards TECHNITIUM_HOST /
TECHNITIUM_TOKEN to the terraform apply as TF_VAR_technitium_*. Existing
callers (provision-dns, provision-observability) are unaffected — when
the input is false the new step is skipped and the empty TF_VAR_*
fall-through is ignored by roots that don't declare those vars.

Files:
- terraform/modules/dns-record/ — module + README
- docs/examples/new-vm-with-dns/ — copy-pasteable root + workflow
- docs/decisions/dns-management.md — rationale (why composable, why
  zone lives in services, provider survey, known gaps)
- .github/workflows/provision-vm.yml — opt-in /technitium load
- README.md — module-index rows for both new paths

Co-authored-by: Blake Hastings <blake@example.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.github/workflows/provision-vm.yml

@@ -18,6 +18,8 @@
 #   /terraform/   TF_VAR_PROXMOX_NODE, TF_VAR_TEMPLATE_ID,
 #                 TF_VAR_GATEWAY, TF_VAR_SSH_PUBLIC_KEY
 #   /ansible/     ANSIBLE_PRIVATE_KEY
+#   /technitium/  TECHNITIUM_HOST, TECHNITIUM_TOKEN
+#                 (only required when create_dns_record: true)
 
 name: Provision VM (reusable)
 
@@ -70,6 +72,11 @@ on:
         required: false
         type: string
         default: "http://192.168.0.161"
+      create_dns_record:
+        description: "Also load Technitium creds from Infisical (/technitium/) and expose them to Terraform. Set true if the caller's Terraform root uses the dns-record module from this repo."
+        required: false
+        type: boolean
+        default: false
 
     outputs:
       vm_ip:
@@ -130,6 +137,22 @@ jobs:
           domain:         ${{ inputs.infisical_domain }}
           export-type:    env
 
+      # Opt-in: only loaded when the caller's TF root uses the dns-record module.
+      # When create_dns_record=false (default) this step is skipped and the
+      # TF_VAR_technitium_* env vars below stay empty — Terraform ignores
+      # unused TF_VAR_* inputs, so non-DNS callers see no behaviour change.
+      - name: Load Technitium secrets from Infisical
+        if: ${{ inputs.create_dns_record }}
+        uses: Infisical/secrets-action@v1.0.16
+        with:
+          method: oidc
+          identity-id:    ${{ inputs.infisical_identity_id }}
+          project-slug:   ${{ inputs.infisical_project_slug }}
+          env-slug:       prod
+          secret-path:    /technitium
+          domain:         ${{ inputs.infisical_domain }}
+          export-type:    env
+
       - name: Setup Terraform
         uses: hashicorp/setup-terraform@v3
         with:
@@ -151,6 +174,9 @@ jobs:
           TF_VAR_cpu_cores:      ${{ inputs.cpu_cores }}
           TF_VAR_memory_mb:      ${{ inputs.memory_mb }}
           TF_VAR_disk_gb:        ${{ inputs.disk_gb }}
+          # Empty when create_dns_record=false; ignored by TF roots that don't declare these vars.
+          TF_VAR_technitium_host:  ${{ env.TECHNITIUM_HOST }}
+          TF_VAR_technitium_token: ${{ env.TECHNITIUM_TOKEN }}
         run: terraform plan -input=false -no-color
 
       - name: Terraform Apply
@@ -163,6 +189,9 @@ jobs:
           TF_VAR_cpu_cores:      ${{ inputs.cpu_cores }}
           TF_VAR_memory_mb:      ${{ inputs.memory_mb }}
           TF_VAR_disk_gb:        ${{ inputs.disk_gb }}
+          # Empty when create_dns_record=false; ignored by TF roots that don't declare these vars.
+          TF_VAR_technitium_host:  ${{ env.TECHNITIUM_HOST }}
+          TF_VAR_technitium_token: ${{ env.TECHNITIUM_TOKEN }}
         run: terraform apply -input=false -auto-approve -no-color
 
       - name: Get VM IP

README.md

@@ -12,6 +12,7 @@ For deployed services (observability, DNS, etc.) see [homelab-services](https://
 |------|-----------|
 | `.github/workflows/provision-vm.yml` | Reusable workflow: Terraform + Ansible for any VM |
 | `terraform/modules/proxmox-vm/` | Generic Proxmox VM module (cloud-init, DHCP via MAC) |
+| `terraform/modules/dns-record/` | Single Technitium A record — compose with `proxmox-vm` to register VMs in DNS |
 | `ansible/base-vm.yml` | Configures any service VM: Docker, runner, Node Exporter, Alloy |
 | `ansible/infra-runner.yml` | Configures the terraform-runner VM itself |
 | `ansible/vars/main.yml` | Platform defaults |
@@ -20,6 +21,7 @@ For deployed services (observability, DNS, etc.) see [homelab-services](https://
 | `docs/patterns/runner-tiers.md` | The infra/service runner tier model |
 | `docs/nodes/terraform-runner/` | How to bootstrap the infra runner |
 | `docs/examples/new-node/` | Complete working example for a new VM node |
+| `docs/examples/new-vm-with-dns/` | Same, but also registers a `<name>.lan` A record |
 | `docs/troubleshooting/` | Common Proxmox provisioning and Ansible gotchas |
 | `docs/decisions/` | Architecture decision records |
 | `docs/observability/` | How observability agents work on every node |

docs/decisions/dns-management.md

@@ -0,0 +1,82 @@
+# Decision: DNS Management in Terraform
+
+> Status: Active
+
+## Decision
+
+DNS records are managed in Terraform via the `kenske/technitium` provider.
+Two pieces, split deliberately:
+
+1. **`terraform/modules/dns-record/`** (this repo) — a thin reusable module
+   wrapping the provider's `technitium_dns_zone_record`. Any Terraform root
+   can compose it next to `module "proxmox-vm"`.
+2. **The `lan` primary zone** itself — created once and owned by
+   `homelab-services/services/dns/terraform-config/`, never duplicated.
+
+The reusable `.github/workflows/provision-vm.yml` workflow accepts a
+`create_dns_record: bool` input. When `true`, it loads
+`/technitium/` from Infisical alongside `/proxmox/`, `/terraform/`,
+`/ansible/`, and forwards `TECHNITIUM_HOST` / `TECHNITIUM_TOKEN` to the
+Terraform apply step as `TF_VAR_technitium_*`.
+
+## Why composable, not integrated into `proxmox-vm`
+
+`proxmox-vm` callers aren't all the same. Some VMs are ephemeral
+(test runners, throwaway experiments) and shouldn't pollute the
+authoritative DNS zone. Some homelab installations may not have Technitium
+at all and would still want to use `proxmox-vm`.
+
+Integrating DNS into `proxmox-vm` would force every caller to either
+configure the `technitium` provider or special-case it with `count = 0`
+plumbing — friction for the common case. Keeping the modules separate
+lets callers opt in by writing two `module` blocks instead of one.
+
+The reusable workflow's `create_dns_record` flag is the matching
+opt-in at the CI layer: non-DNS callers don't need `/technitium/` access in
+Infisical.
+
+## Why the zone lives in `homelab-services`, not here
+
+The zone is a singleton — its SOA, refresh interval, allowed-update
+policy, and existence are all single-point-of-truth concerns. If two roots
+declared `technitium_dns_zone "primary"`, the second `terraform apply`
+would fight the first.
+
+`homelab-services` is the natural owner because the DNS *service*
+(Technitium itself) is deployed there. Records, on the other hand, live
+naturally with the thing they describe — the consumer's VM Terraform.
+
+## Why `kenske/technitium`
+
+Surveyed four community Technitium providers in May 2026:
+
+| Provider | Scope | Verdict |
+|----------|-------|---------|
+| `kenske/technitium` | zones, records, DHCP scopes, DHCP reservations | **chosen** — broad enough, room to grow into DHCP |
+| `kevynb/technitium` | records only (no zones) | too narrow |
+| `darkhonor/technitium` | zones, records, block lists, server settings, STIG mode | STIG opinions add overhead a homelab won't use |
+| `chinyongcy/technitium` | zones, records | smaller surface than kenske, similar feature set |
+
+Pinned to `~> 0.2.2` (latest as of Nov 2025). Single-maintainer risk is
+real; fallback if the provider goes unmaintained is direct API calls via
+`null_resource` + `local-exec curl` against
+[Technitium's HTTP API](https://github.com/TechnitiumSoftware/DnsServer/blob/master/APIDOCS.md).
+
+## Known gaps (managed in the UI for now)
+
+`kenske/technitium` v0.2.2 does not model:
+
+- **Forwarders / recursion settings** — Technitium's default (pure
+  recursion to root servers) is what most homelabs want anyway. Set
+  upstream forwarders via the UI if you need to.
+- **Block lists** — UI: DNS → Blocked Zones → Block Lists.
+
+Both change rarely. If they ever need code-management, the
+`null_resource` + Technitium API escape hatch is the path.
+
+## Bootstrap is one-time and manual
+
+Terraform cannot mint its own API token; a human must log in once to the
+Technitium UI to create the `terraform` user and generate a token. The
+runbook lives at
+[`homelab-services/services/dns/BOOTSTRAP.md`](https://github.com/BlakeHastings/homelab-services/blob/main/services/dns/BOOTSTRAP.md).

docs/examples/new-vm-with-dns/README.md

@@ -0,0 +1,34 @@
+# Example: new VM that also registers a DNS A record
+
+Mirrors [`new-node/`](../new-node/) but composes the `proxmox-vm` and
+`dns-record` modules in one Terraform root so a VM and its
+`<name>.lan` A record are created (and destroyed) together.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `versions.tf` | Declares both `bpg/proxmox` and `kenske/technitium` provider requirements |
+| `providers.tf` | Configures both providers (technitium reads creds from variables) |
+| `variables.tf` | All TF_VAR_* inputs, including `technitium_host` / `technitium_token` |
+| `backend.tf` | Local state on terraform-runner |
+| `main.tf` | `module "vm"` then `module "dns"` — wires `module.vm.vm_ip` into the DNS record |
+| `provision.yml` | Example workflow — sets `create_dns_record: true` on the reusable `provision-vm.yml` |
+
+## How it differs from `new-node/`
+
+1. Adds the `kenske/technitium` provider.
+2. Adds a `module "dns"` block alongside `module "vm"`.
+3. Workflow passes `create_dns_record: true`, which tells
+   `provision-vm.yml@main` to also load `/technitium/` from Infisical and
+   expose `TECHNITIUM_HOST` / `TECHNITIUM_TOKEN` to the Terraform apply.
+
+## Prerequisites
+
+- The `lan` zone must already exist in Technitium. It's created and owned
+  by [homelab-services/services/dns/terraform-config/](https://github.com/BlakeHastings/homelab-services/tree/main/services/dns/terraform-config).
+- The Infisical machine identity for the calling repo must have **read**
+  on the `/technitium/` path (one-time grant per repo).
+
+See [`docs/decisions/dns-management.md`](../../decisions/dns-management.md)
+for the design rationale.

docs/examples/new-vm-with-dns/backend.tf

@@ -0,0 +1,6 @@
+terraform {
+  backend "local" {
+    # REPLACE: my-vm with your VM name. State lives on the terraform-runner.
+    path = "/home/ubuntu/terraform-state/my-vm/terraform.tfstate"
+  }
+}

docs/examples/new-vm-with-dns/main.tf

@@ -0,0 +1,48 @@
+# my-vm — example VM that also registers itself in DNS as my-vm.lan
+#
+# REPLACE: vm_name, vm_id, mac_address, dns_hostname for your VM.
+#
+# Lifecycle is unified: `terraform destroy` removes both the VM and its
+# DNS record. The "lan" zone itself is NOT created here — it's owned by
+# homelab-services/services/dns/terraform-config/.
+
+module "vm" {
+  source = "github.com/BlakeHastings/homelab-platform//terraform/modules/proxmox-vm?ref=main"
+
+  vm_name        = "my-vm"            # REPLACE
+  vm_id          = 202                # REPLACE: unique Proxmox VMID
+  target_node    = var.proxmox_node
+  template_id    = var.template_id
+  cpu_cores      = var.cpu_cores
+  memory_mb      = var.memory_mb
+  disk_gb        = var.disk_gb
+  mac_address    = "BC:24:11:00:02:02"  # REPLACE: unique MAC for DHCP reservation
+  dns_servers    = [var.gateway]        # use router for DNS during provisioning
+  ssh_public_key = var.ssh_public_key
+}
+
+module "dns" {
+  source = "github.com/BlakeHastings/homelab-platform//terraform/modules/dns-record?ref=main"
+
+  hostname = module.vm.vm_name      # → my-vm.lan
+  ip       = module.vm.vm_ip
+  zone     = "lan"
+}
+
+output "vm_ip" {
+  description = "VM IP — also reachable as ${module.dns.fqdn} once DNS records propagate."
+  value       = module.vm.vm_ip
+}
+
+output "vm_id" {
+  value = module.vm.vm_id
+}
+
+output "vm_name" {
+  value = module.vm.vm_name
+}
+
+output "fqdn" {
+  description = "DNS name the VM is reachable at on the LAN."
+  value       = module.dns.fqdn
+}

docs/examples/new-vm-with-dns/providers.tf

@@ -0,0 +1,14 @@
+# Proxmox provider — credentials from /proxmox/ in Infisical (loaded by the
+# reusable provision-vm workflow). See env vars: PROXMOX_VE_ENDPOINT etc.
+provider "proxmox" {
+  insecure = true   # homelab self-signed TLS certificate
+}
+
+# Technitium provider — credentials from /technitium/ in Infisical, loaded
+# automatically by provision-vm.yml when create_dns_record: true.
+# Variables are populated via TF_VAR_technitium_host / TF_VAR_technitium_token
+# set by the workflow.
+provider "technitium" {
+  host  = var.technitium_host
+  token = var.technitium_token
+}

docs/examples/new-vm-with-dns/provision.yml

@@ -0,0 +1,39 @@
+# Example: Provision my-vm and register my-vm.lan in one shot.
+#
+# Copy this to your project repo as .github/workflows/provision-my-vm.yml
+# and update the REPLACE values.
+#
+# Prerequisites:
+#   1. Proxmox Ubuntu 24.04 template exists (VMID 9000)
+#   2. terraform-runner VM bootstrapped (see homelab-platform docs)
+#   3. The "lan" zone exists in Technitium (provisioned once by
+#      homelab-services/services/dns/terraform-config/)
+#   4. This repo has GitHub Actions Variables INFISICAL_IDENTITY_ID and
+#      INFISICAL_PROJECT_SLUG set
+#   5. The Infisical machine identity for this repo has read on
+#      /proxmox/, /terraform/, /ansible/, AND /technitium/
+#
+# Trigger manually: Actions → Provision my-vm → Run workflow
+
+name: Provision my-vm    # REPLACE
+
+on:
+  workflow_dispatch:
+
+permissions:
+  id-token: write    # OIDC for Infisical auth
+  contents: read
+
+jobs:
+  provision:
+    uses: BlakeHastings/homelab-platform/.github/workflows/provision-vm.yml@main
+    with:
+      vm_name:               "my-vm"                              # REPLACE
+      cpu_cores:             2                                    # REPLACE if needed
+      memory_mb:             4096                                 # REPLACE if needed
+      disk_gb:               40                                   # REPLACE if needed
+      terraform_working_dir: "terraform/nodes/my-vm"              # REPLACE
+      observability_server_ip: "192.168.0.251"
+      create_dns_record:     true                                 # ← enables /technitium load
+      infisical_identity_id:  ${{ vars.INFISICAL_IDENTITY_ID }}
+      infisical_project_slug: ${{ vars.INFISICAL_PROJECT_SLUG }}

docs/examples/new-vm-with-dns/variables.tf

@@ -0,0 +1,53 @@
+# All variables are supplied via TF_VAR_* environment variables from the
+# reusable provision-vm workflow. Do not commit a .tfvars file.
+
+variable "proxmox_node" {
+  description = "Proxmox node name (e.g., pve)"
+  type        = string
+}
+
+variable "template_id" {
+  description = "VMID of the Ubuntu 24.04 cloud-init template"
+  type        = number
+  default     = 9000
+}
+
+variable "gateway" {
+  description = "Network gateway IP (e.g., 192.168.0.1)"
+  type        = string
+}
+
+variable "ssh_public_key" {
+  description = "SSH public key for VM access"
+  type        = string
+  sensitive   = true
+}
+
+variable "cpu_cores" {
+  type    = number
+  default = 2
+}
+
+variable "memory_mb" {
+  type    = number
+  default = 4096
+}
+
+variable "disk_gb" {
+  type    = number
+  default = 40
+}
+
+# --- Technitium (DNS) credentials ---
+# Populated by provision-vm.yml when create_dns_record: true.
+
+variable "technitium_host" {
+  description = "Technitium DNS server base URL (e.g. http://192.168.0.250:5380)"
+  type        = string
+}
+
+variable "technitium_token" {
+  description = "API token for the 'terraform' Technitium user"
+  type        = string
+  sensitive   = true
+}

docs/examples/new-vm-with-dns/versions.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    proxmox = {
+      source  = "bpg/proxmox"
+      version = "~> 0.99.0"
+    }
+    technitium = {
+      source  = "kenske/technitium"
+      version = "~> 0.2.2"
+    }
+  }
+}