Derive hostname from compose service label for scaled services (round-robin)

[maxfield-allison]

Problem statement

When a compose-managed workload has no explicit dnsweaver.hostname, dnsweaver currently derives the hostname from the instance/container name plus the domain suffix. For scaled services this produces per-replica names: deploy.replicas: 3 yields proxy-1, proxy-2, proxy-3, so with a lan suffix you get proxy-1.lan, proxy-2.lan, proxy-3.lan.

Requested by @jochumdev in #132 (review of PR #133). Both incus-compose and Docker Compose expose a stable service label:

• incus-compose: incus-compose.service (surfaced de-prefixed from user.label.incus-compose.service after [Feature]: add support for incus-compose #131)
• Docker Compose: com.docker.compose.service

Proposed solution

Add an opt-in mode that derives the hostname from the compose service label when no explicit hostname is set, so all replicas of a service share one round-robin name:

proxy-1, proxy-2, proxy-3  ->  proxy.lan  (3 A records, round-robin)

This is a behavior change with a deliberate semantic difference from the current per-replica naming, so it must be opt-in with clear precedence, not a silent default.

Design questions to settle

1. Opt-in switch: a per-source or global toggle (e.g. DNSWEAVER_..._SERVICE_HOSTNAME=true)? Default off.
2. Precedence: explicit dnsweaver.hostname > service-label-derived > instance-name-derived. Confirm ordering.
3. Round-robin semantics: multiple instances sharing a name emit multiple A records to the same hostname. Confirm the reconciler/providers handle N records per name cleanly (ownership, updates, orphan cleanup).
4. Cross-platform: implement once, keyed off both incus-compose.service and com.docker.compose.service, so Docker Compose users benefit too.
5. Domain suffix: service-derived names still get the domain suffix appended the same way.

Scope

• Applies to both Incus and Docker sources (label-driven).
• Builds on [Feature]: add support for incus-compose #131 (label de-prefixing) which is already merged/in-review as PR feat(incus): support incus-compose labels (#131) #133.
• Independent of [Feature]: Use the events api in an incus source #132 (event watcher).

[jochumdev]

Yes, this is a breaking change and yes I wouldn't default this without a Major release.

[jochumdev]

Hmm if we have both proxy-1.home.example.com and proxy.example.com set we don't need _SERVICE_HOSTNAME=true it is maybe just another A entry for free?

[maxfield-allison]

Picking up your second point, because it reframes this nicely and I want to be honest about where the real work is.

You're right that if we emit both proxy-1.home.example.com and proxy.example.com, the service name is additive rather than a replacement, and that dissolves the breaking-change problem: nothing existing gets renamed or removed, so it wouldn't need a major release on compatibility grounds. That's a better shape than the opt-in toggle I first proposed.

The catch is that "just another A entry for free" isn't free yet, and it's worth being precise about why. The blocker isn't the naming, it's the reconciler's current data model.

Right now desired state is keyed one hostname to one workload. When two workloads resolve to the same name, the second is dropped as a duplicate (first workload wins, logged as duplicate hostname found in multiple workloads). So today, even setting the same explicit dnsweaver.hostname on three replicas yields a single A record, not a round-robin set. The service-label idea inherits that limitation: to get proxy.example.com pointing at all three replica IPs, the reconciler first has to learn to hold a set of A records per hostname (hostname to a set of targets) instead of collapsing to one.

That reconciler change is the actual work item, and it's valuable on its own because it also fixes the explicit-shared-hostname case. Once it exists, your additive framing is exactly right and the service name becomes a small derivation layer on top, no toggle required.

Two things that then need a decision:

1. Ownership and orphan cleanup are currently keyed by hostname alone (one ownership marker per name). With N A records under one name, removing a single replica has to delete just that replica's A record, not the whole name's set. So partial membership needs to be represented in ownership, not just presence/absence of the name.
2. Cross-project collisions, now that multi-project support landed ([Feature]: Multi project support in incus #137). Two compose projects each with a proxy service would both contribute to proxy.example.com. We should decide whether that's an intentional merged round-robin or should be disambiguated (project-scoped name, or only emit when unambiguous).

So I'd sequence it as: first teach the reconciler to manage multiple A records per hostname (helps explicit shared hostnames immediately), then layer the compose-service-derived name on top as an additive record. Curious whether that matches how you'd expect it to behave, especially the collision question.

[jochumdev]

Great question!

About collisions:

yes, I would by default - with an opt-out - add the project.name to such generated hostnames, I recommend that for docker as well but have to say I have not much docker-compose knowledge.

This is especially important for multi-tendant hosting suppliers but also for homelab users that will host for example immich with 2 different project names.

The immich example:

server.immich.home.example.com
server.immich2.home.example.com

Both works with project in between.

Users then might set CNAME's.

immich.a-domain.org. CNAME server.immich.home.example.com.
immich.b-dolmain.org. CNAME server.immich2.home.example.com.

[maxfield-allison]

Your multi-tenant framing settled the collision question, and thinking it through changed how I'd scope this. The short version: this is less a compose feature and more a reconciler capability, and treating it that way makes it better for everyone, not just compose users.

Two things I want to get right before writing code:

1. This is a reconciler change first, a compose change second. The "multiple A records per one hostname" behavior lives entirely at the reconciler's desired-state layer, above any source. If I fix it there, then explicit shared hostnames start working as round-robin for every source (Docker, Kubernetes, Proxmox, file-based), not only incus-compose. The compose service name then becomes a thin derivation on top of a capability that already stands on its own. That ordering also means the feature earns its keep even for people who never touch compose.

2. "project" is an overloaded word here, and I don't want to bake the ambiguity into config. dnsweaver already has an Incus project concept (the multi-project support from #137: DNSWEAVER_INCUS_PROJECTS, the project field on events). That's an infrastructure namespace. The compose project name you're describing (server.immich.home vs server.immich2.home) is a different axis, and a single instance has both. So the derived name needs to say explicitly which one it means. I'm inclined toward the compose project name for the segment you described, since that's what maps to "two deployments of the same app," but the docs and env var have to name it unambiguously (something like a compose-project segment, distinct from the Incus project scope) so nobody has to guess.

There's also one honest constraint on the provider side worth surfacing early: creating N records for a name is safe across providers, but removing one member is not uniform. Some backends write a whole record set at once (PowerDNS rrsets, for example), so dropping one replica has to be a read-modify-write that preserves its siblings rather than a delete-by-name. That's the part that makes this a real design item rather than a quick patch, and it's why per-member ownership (so we know exactly which A record belongs to which instance) matters more than I first gave it credit for.

So the shape I'd propose:

1. Reconciler learns to hold a set of A records per hostname, with per-member ownership. Immediately fixes explicit shared hostnames for all sources.
2. Provider delete paths audited so removing one member never clobbers the set.
3. Compose-service-derived name layered on top, <service>.<compose-project>.<suffix>, project segment on by default with an opt-out, and clearly distinct from the Incus project scope.

I think steps 1-2 deserve a short design note of their own since they touch every provider, and the compose naming rides on top once they land. Does splitting it that way sit right with you, and do you agree the compose-project segment should be named distinctly from the Incus project so the two never blur?