PlusClouds pdns-agent

A lightweight daemon that manages self-hosted PowerDNS zones/records on behalf of the PlusClouds platform. It connects to the platform over NATS (forked from vm.agent's transport/protocol layer - same command/event model, agent_type = "dns" instead of "vm"), and turns zone/record commands into calls against PowerDNS's own local REST API - it never touches PowerDNS's backend database directly, so PowerDNS keeps owning its own consistency, AXFR, and notify mechanics.

No REST API of its own. No open inbound ports. Outbound-only NATS connection.

---

What it does

Capability	Description
Zone/record management	zone.create/zone.delete/zone.sync, record.create/record.update/record.delete - see internal/modules/powerdns
System metrics	CPU, memory, disk, network - for basic host monitoring of the PowerDNS server itself
Service management	start/stop/restart/enable/disable systemd services (e.g. the local pdns service)
Capability discovery	On boot the agent publishes its full operation schema, so the platform knows what it can do
Heartbeat	Keeps DnsServers.agent_status/agent_last_seen_at current on the platform

Architecture

Communicates exclusively over NATS:

agent.dns.{server_uuid}.cmd   ←  platform sends zone/record commands
agent.dns.{server_uuid}.evt   →  agent sends telemetry, heartbeat, capabilities, results
dns.{server_uuid}.telemetry   →  client-facing telemetry stream

internal/modules/powerdns is the only genuinely new piece versus vm.agent

• it builds PowerDNS REST API calls (POST/PATCH/DELETE /servers/{id}/zones/...) from the command params sent by NextDeveloper\DNS\Services\DnsProviders\PowerDns\PowerDnsProviderService on the PHP side (see the nextdeveloper/dns package).

v1 limitation: each PlusClouds DnsRecords row is treated as the entire rrset for its (name, type) pair — round-robin/multi-value records sharing a name+type are not yet merged (would require fetching PowerDNS's existing rrset before REPLACE). Noted in internal/modules/powerdns/powerdns.go.

Configuration

See configs/pdns-agent.yaml for the full annotated sample. Key settings:

• nats.agent_uuid / nats.api_key — must match the platform's DnsServers row for this PowerDNS instance.
• powerdns.api_url / powerdns.api_key — PowerDNS's local REST API (pdns.conf: api=yes, api-key=...).

Build

make build          # dev build for current OS/arch → bin/pdns-agent
make build-linux     # production build → bin/pdns-agent.linux
make install         # install binary + systemd unit + default config (requires root)

Origin

Forked from plusclouds/vm.agent - internal/nats, internal/protocol, internal/executor, internal/modules/system, and internal/modules/services are reused as-is (or with only VM-specific identity fields removed); internal/modules/powerdns and the dispatcher's zone.*/record.* operations are new. This is a deliberate copy, not a shared-library extraction — vm.agent, backup.agent, s3.agent, and now pdns-agent each maintain their own independent copy of the same core today.