DNS Domains¶
A DNS Domain is a zone Muppy builds host names under: example.com, on which an App
Server is served as myapp.example.com. Every domain names the provider that hosts its
zone, and the provider decides what Muppy can do with it.
Find them under Muppy › Network › DNS › DNS Domains. The Muppy DNS Domain Documentation button of the domain form opens this page.
Providers¶
| DNS Provider | Where the zone lives | Muppy writes the zone |
|---|---|---|
| OVH DNS | OVH | Yes, through the OVH API |
| Cloudflare DNS | Cloudflare | Yes, through a Cloudflare API token — see Preparing a Cloudflare Zone for Public URLs |
| Scaleway DNS | Scaleway | Yes, through the Scaleway API |
| Muppy Builtin DNS Server - MBD | A zone of another provider, shared out as sub-domains | Yes, through its backend domain — see Muppy Builtin DNS |
| Muppy Builtin DNS Client - MBD | A sub-domain served by another Muppy instance | Yes, through that instance |
| Tailscale | Your tailnet's MagicDNS name | No |
| Unmanaged | Anywhere: Muppy has no API on it | No — see Unmanaged DNS Domains |
A new domain is Unmanaged until you choose another provider. The provider can be changed only while the domain is New: disconnect it first to change it.
When Muppy cannot write the zone, the form says so with a banner, Muppy has no API on this zone, and hides what depends on a provider API: Sync, Check Connection, the credential expiry, and the Configs, Sync, HTTPRequest and Kubernetes tabs.
Connecting a domain¶
A domain is usable once it is Connected.
Which domains a consumer can use¶
A consumer is an object that publishes its names on a domain: a Traefik server, a Traefik application and its definition, a Kubernetes cluster, a package profile and a Release, and the Install LXD App. Server, Install single node infra package and Release package wizards. App Servers and Code Servers take their domain from these objects.
The domain form and the domain list show Can Serve Consumers: the domain is Connected, and its provider keeps a consumer's records where the consumer finds them again. Every domain selector of a consumer, and the default Traefik domain in the settings, offer only those domains. A connected Unmanaged or Tailscale domain can serve consumers: Muppy records the names there as declarations.
A Muppy Builtin DNS Server cannot serve consumers: it writes the records of its clients in its backend domain, so a consumer would not find its own records there. A consumer refuses it, whatever writes the field, and the message names the server's backend domain to choose instead. A Muppy Builtin DNS Client serves consumers like any other provider.
The selectors filter only what is offered. A consumer whose domain later goes to Connect Failed keeps it; when the credential is fixed and the domain connected again, the domain is offered again. An install wizard whose default domain cannot serve consumers opens without it, and falls back to the default Traefik domain when the cluster's default is refused.
| State | Meaning |
|---|---|
| New | Not connected yet, or disconnected |
| API Connect in Progress | Waiting for the provider to confirm the authorisation (OVH, MBD Client) |
| Connected | Usable |
| Connect Failed | The provider refused the credential |
- Connect obtains the provider's authorisation and checks it. On an Unmanaged domain it only marks the domain as usable.
- Disconnect revokes the authorisation, or, on an Unmanaged domain, marks the domain as unused.
- On a Tailscale domain, Connect and Disconnect are not implemented and say so.
- Check Connection asks the provider whether the credential still works.
When the provider refuses the credential¶
Any call Muppy makes to the zone can meet a refused credential: Sync, Check Connection, or a record an application needs. Muppy then sets the domain to Connect Failed, even when the task that made the call fails and is rolled back.
The form shows the state in red, and an alert says when the credential was refused, during which operation, and what the provider answered. Credential Expiry says Refused. Connect is back in the button box. Fix the credential at the provider, then click Connect.
When a call fails¶
A provider call that fails stops with an error that names the zone and the provider. Sync shows it in a red notification and leaves the records as they were; Check Connection shows it in a dialog; a task writes it in its journal. The error says which of these happened:
| Error | Meaning |
|---|---|
| Credential refused | The provider refused the credential. The domain goes to Connect Failed. |
| Zone not found | The provider does not know the zone. A sync stops and keeps the records Muppy has. |
| Record not found | The record disappeared between two calls. Deleting a record already gone succeeds. |
| Value rejected | The provider refused the value of a record, and says why. |
| Provider unavailable | A timeout, a network error, a server error or a rate limit. Retry later. |
A Muppy Builtin DNS client also says when something between it and its server answered instead: a Sunray page, a Cloudflare block, or a missing route. Nothing of that page is kept but its status, a few headers and its title.
Records¶
When Muppy writes the zone, the domain's records are listed on its Zone Records tab and under Muppy › Network › DNS › Zone Records. Muppy creates them itself — a record for each Traefik application on a server with Create DNS subdomains — and Sync reads back what the provider holds.
The provider holds the truth, and the list reflects it. The list and the record form are read-only: a record changes through an assistant, which writes at the provider first. The line follows only once the provider has accepted the change.
- Add Record — above the Zone Records tab, or at the top of the Zone Records menu, where the assistant asks for the domain — opens the assistant in creation. Its button names the provider: Create at OVH DNS, Create at Cloudflare DNS. On an Unmanaged or Tailscale domain it says Declare: the line is written, and no provider is called.
- Edit, on a line or on the record form, first reads the record again at the provider, then opens the assistant on what the provider holds. The type cannot change, and only the fields you change are sent. When the provider cannot be read, the assistant says so and shows the line as Muppy knows it; when the record no longer exists there, the line is archived and nothing can be changed.
- Delete asks for confirmation, deletes the record at the provider, then removes the line.
When the provider refuses a value, the assistant stays open with the provider's message, and nothing is written. A record has no Duplicate: a line stands for one record at the provider.
A record created or declared through the assistant has you as its Created by. No Traefik application or Kubernetes release changes or deletes it; one that publishes the same name to another address adds its own record beside it. When an application or a release created a record, the assistant names it: that object may write the record again, and undo a change made here. A creator that is archived or deleted no longer protects its records.
On a Cloudflare domain, Proxied sets the orange cloud of an A, AAAA or CNAME record:
- Domain default, in creation, follows Proxied by Default on the domain;
- Proxied or Not proxied sets it for this record. In an edit, the record's current value is shown, and Domain default is refused.
Created by names the object a record belongs to — a Traefik application, a Kubernetes release, an MBD Server for the records it serves. A record found by Sync that nobody created from Muppy has none. A record belongs to one object only: when another object asks for the same name and type, Muppy refuses and names the owner, so that two applications never overwrite each other's record. An object that finds a record nobody claims takes it over.
Sync only reads the provider; it writes nothing there. It adds the records Muppy did not know, updates the ones that changed, and deactivates the ones the provider no longer has: each deactivation is written in the journal. A record whose type changed at the provider is replaced by a new line.
A domain holds one active line per record of its provider: a second line for the same record is refused. A line that Sync deactivated comes back when its record reappears at the provider.
Sync on one record reads that record only, by its id at the provider, and updates its line; a record the provider no longer holds deactivates it. It writes nothing at the provider. On a deactivated line whose record has an active line already, it updates and opens that line. On an Unmanaged or Tailscale domain there is nothing to read: a notification says so.
Batch Sync says how the provider is read:
- checked (Cloudflare, Scaleway, MBD Client): the whole zone is read in a few calls;
- unchecked (OVH): the zone is read one record at a time, one call per record — about 100 seconds for 700 records. A warning says so on the form. Do not use such a provider for zones of thousands of records.
An MBD Server reads its zone from its backend domain: its Sync syncs the backend first.
On an Unmanaged or Tailscale domain, a record listed is a declaration: see Unmanaged DNS Domains.
Certificates¶
A domain whose zone Muppy writes can obtain Let's Encrypt certificates through the DNS-01 challenge: see Let's Encrypt Certificates (DNS-01). A domain Muppy does not write cannot. The Install LXD App. Server wizard installs Traefik on such a domain with Let's Encrypt off, and refuses to launch with it on: see Installing Traefik on an Unmanaged domain.