config: drop estate-specific defaults and docs

Remove hardcoded internal PuppetDB URLs and site-specific wording so the
project is publishable as-is.

- backends have no default; require config file or PDBMUX_BACKENDS
- primary/prefer default to the first configured backend
- config init writes example.com placeholders
- Load no longer validates, so config init/version work unconfigured
- genericise README, package doc, help text and Dockerfile comment

README.md

@@ -1,21 +1,23 @@
 # pdbmux — merging PuppetDB proxy
 
-`pdbmux` is a small HTTP daemon that fronts **two** PuppetDB backends and serves
-a single, merged PuppetDB v4 query surface on one address. Point `node-lookup`,
-`pblastreport`, or anything else at `pdbmux` instead of a raw PuppetDB and it
-sees one consistent view spanning both.
+`pdbmux` is a small HTTP daemon that fronts **several** PuppetDB backends and
+serves a single, merged PuppetDB v4 query surface on one address. Point any
+PuppetDB API client at `pdbmux` instead of a raw PuppetDB and it sees one
+consistent view spanning all of them.
 
 ## Why
 
-During the VM→k8s Puppet migration there are two PuppetDBs:
+Running more than one PuppetDB — during a migration between two of them, or
+across regions — means a given node's current data lives in exactly one at any
+moment, and consumers have to know which, or query each in turn. Consider two
+backends being merged during a migration:
 
-- **old** — the legacy Consul-registered `http://puppetdbapi.service.consul:8080`
-- **new** — the k8s `https://puppetdb.k8s.syd1.au.unkin.net` (TLS terminated at
-  the gateway; backends are plain PuppetDB on 8080)
+- **old** — the PuppetDB nodes are moving off, e.g. `http://puppetdb1.example.com:8080`
+- **new** — the PuppetDB nodes are moving on to, e.g. `http://puppetdb2.example.com:8080`
 
-Nodes move from old to new as they migrate, so at any moment a given node's
-current data lives in exactly one of them. `pdbmux` merges both so consumers
+Nodes move from old to new as they migrate. `pdbmux` merges both so consumers
 don't have to know (or query twice) which PuppetDB a node currently lives in.
+The backend names are arbitrary labels; there is no fixed number of backends.
 
 ## Endpoints
 
@@ -55,18 +57,22 @@ unknown fields survive untouched.
 
 Precedence (lowest → highest): **defaults < config file < env vars (`PDBMUX_*`) < flags**.
 
-Config file: `$XDG_CONFIG_HOME/pdbmux/config.yaml`. In Kubernetes, configuration
-is supplied entirely via `PDBMUX_*` env vars (no config file), which is the
-supported deployment path — see [Deployment](#deployment).
+Config file: `$XDG_CONFIG_HOME/pdbmux/config.yaml`. In a container, configuration
+is supplied entirely via `PDBMUX_*` env vars (no config file) — see
+[Deployment](#deployment).
+
+**`backends` has no default.** `pdbmux` refuses to start until at least one
+backend is configured, via the config file or `PDBMUX_BACKENDS`. `primary` and
+`prefer` default to the first configured backend.
 
 ```yaml
-# ~/.config/pdbmux/config.yaml  (local dev; in k8s use PDBMUX_* env instead)
+# ~/.config/pdbmux/config.yaml  (local dev; in a container use PDBMUX_* env instead)
 listen: ":8080"
 backends:
   - name: old
-    url: http://puppetdbapi.service.consul:8080
+    url: http://puppetdb1.example.com:8080
   - name: new
-    url: https://puppetdb.k8s.syd1.au.unkin.net
+    url: https://puppetdb2.example.com
 primary: new          # backend used for non-merged /pdb/query/v4/* pass-through
 merge: freshness      # freshness | static
 prefer: new           # winner on ties / static merge / fallback
@@ -94,16 +100,17 @@ Flags: `--listen`, `--primary`, `--merge`.
 ```bash
 pdbmux                 # start the proxy (serve is the default action)
 pdbmux serve           # explicit
-pdbmux config init     # write a default config file
+pdbmux config init     # write an example config file to edit
 pdbmux config show     # print active config after all overrides
 pdbmux version
 ```
 
-Point a consumer at it:
+Point a consumer at it — any PuppetDB v4 client works, it just needs the
+`pdbmux` address in place of a PuppetDB one:
 
 ```bash
-node-lookup --url http://localhost:8080/pdb/query/v4/facts -R
-NODE_LOOKUP_URL=http://localhost:8080/pdb/query/v4/facts pblastreport somehost
+curl -s --get http://localhost:8080/pdb/query/v4/nodes \
+  --data-urlencode 'query=["=","certname","host1.example.com"]'
 ```
 
 ## Build
@@ -119,30 +126,31 @@ Requires Go 1.25+. Dependencies: `github.com/spf13/cobra` (CLI),
 
 ## Deployment
 
-`pdbmux` runs **in Kubernetes** as a container, in line with the all-in-k8s
-estate direction — it is not shipped as a per-VM RPM/systemd service. The image
-is built and pushed on every `v*` tag (`.woodpecker/docker.yaml`) to:
-
-```
-artifactapi.k8s.syd1.au.unkin.net/docker-internal/pdbmux:<tag>
-```
+`pdbmux` is distributed as a container image only — there is no OS package. The
+image is built and pushed on every `v*` tag (`.woodpecker/docker.yaml`); the
+registry and repository are pipeline settings, so point them at your own.
 
 It is a minimal static (`CGO_ENABLED=0`) binary on a distroless base
 (`Dockerfile`), configured entirely via `PDBMUX_*` env vars, with a single HTTP
-listener and `/healthz` for liveness/readiness probes.
+listener and `/healthz` for liveness/readiness probes. It is stateless, so run
+as many replicas as you like behind an ordinary Service/Ingress.
 
-The Deployment/Service/Gateway manifests live in the estate's `argocd-apps` repo
-under `apps/base/pdbmux/` (namespace `pdbmux`, 2 replicas), and it is exposed to
-VM/workstation `node-lookup` consumers over HTTPS at:
+A container needs at minimum `PDBMUX_BACKENDS`; everything else has a default:
 
-```
-https://pdbmux.k8s.syd1.au.unkin.net
+```yaml
+env:
+  - name: PDBMUX_BACKENDS
+    value: "old=http://puppetdb1.example.com:8080,new=http://puppetdb2.example.com:8080"
+  - name: PDBMUX_PRIMARY
+    value: "new"
+  - name: PDBMUX_PREFER
+    value: "new"
 ```
 
-Locally you can still run the binary directly for development:
+Locally you can run the binary directly for development:
 
 ```bash
-PDBMUX_BACKENDS='old=http://puppetdbapi.service.consul:8080,new=http://puppetdb.puppet.svc.cluster.local:8080' \
+PDBMUX_BACKENDS='old=http://puppetdb1.example.com:8080,new=http://puppetdb2.example.com:8080' \
   pdbmux serve
 curl -s localhost:8080/healthz
 ```