Skip to content
Flui Documentation

DNS integration

A new DNS name takes about a minute to reach the world’s resolvers. Right after a deploy, that is long enough to wonder whether something went wrong.

A Flui cluster avoids that wait. Every application on a cluster answers at the same addresses, and every application name sits one label under the same subdomain. One record can cover all of them, including the ones that do not exist yet, and that is the record a Flui cluster publishes.

What an endpoint is

An endpoint is the address a browser, a service or a CLI uses to reach an application from outside the cluster. Endpoints are opt-in: an application that nothing outside needs to reach can be deployed without one. When an application does ask to be reachable, Flui handles the rest: hostname, record, certificate and routing. You do not allocate hostnames or edit records by hand.

A certificate that lets the endpoint serve HTTPS is provisioned alongside it, as described in TLS and certificates.

One record for the whole cluster

When a cluster publishes under a zone, every application on it is reachable at <application>.<cluster>.<zone>, and every one of those names resolves to the same addresses: the cluster’s. So Flui publishes a single record, *.<cluster>, pointing there.

example.com your zone, records by Flui *.production A 203.0.113.10A 203.0.113.11 *.internal A 203.0.113.10A 203.0.113.11 shop.production.example.com running api.production.example.com running next-app.production.example.com not deployed yet, already covered shop.internal.example.com behind the sign-in production checked every minute 203.0.113.10 node-1, ready 203.0.113.11 node-2, ready 203.0.113.12 node-3, not ready: left out
One record, *.production, covers every application on the cluster, including the next one you deploy, and points at every node that takes traffic. A node that is not ready is left out. Gated applications sit under a wildcard of their own, *.internal.

As a result:

  • A new application answers immediately. Its name is covered before it is deployed. Nothing has to propagate, because nothing new was published.
  • Removing an application removes nothing from DNS. There is no per-application record to leave behind, so there are no orphans to clean up.

What you choose for an application, when you deploy it or on its endpoint, is its name and its certificate, not this record. An application that keeps the cluster’s naming is covered by it. One given a name of its own, such as shop.example.com, sits outside *.<cluster> and gets its own record.

You never configure this record; Flui derives it. Flui builds the hostname rule itself, so it knows exactly which names it could ever create, and the wildcard is scoped to the cluster’s own subdomain rather than the zone root. A zone you also use for a website and a mailbox is untouched outside *.<cluster>.

Two commands cover it:

  • flui dns wildcard status says whether the record is in place, what it points at, and what the hostname pattern for this cluster is.
  • flui dns wildcard publish writes it.

status reads the provider live instead of trusting a stored value. Otherwise a record someone deleted by hand would keep reporting as fine.

Publishing creates the record and never overwrites one. If a wildcard is already there pointing somewhere else, someone put it there, and taking it over would silently redirect whatever it was serving. Flui reports it and leaves it alone. That state is reported separately from “not published yet”, because one is work waiting to be done and the other is a publish that would be refused.

Every node that takes traffic

The records point at the public address of every node that can take traffic right now: ready, running the cluster’s ingress, and reachable from the internet. An application can run on any of them and still answer at its name.

Flui measures that set every minute. A node that stops being ready, or leaves the cluster, is taken out of the records; a node that joins or comes back is put in. Every record the cluster owns moves together (the wildcard and any per-application record), so they never disagree. While more than one node is listed, the records carry a short time to live of one minute, so a node that drops out stops being handed to visitors quickly. A measurement that finds no node at all is never published: Flui keeps the records it has, because publishing an empty set would take every application offline at once.

This needs a real domain. A nip.io name carries a single address inside it, so it stays tied to the cluster’s master.

When the wildcard does not answer

A per-application record is the fallback.

Every time an endpoint is reconciled, Flui looks in the zone for a wildcard that covers this exact name. It counts as coverage only if both of these hold:

  • One label. A DNS wildcard matches a single label. *.production answers for app.production and not for a.b.production.
  • The same addresses. A wildcard pointing elsewhere gives a different answer, and skipping the per-application record would send visitors to the wrong host.

When both hold, the record would be redundant: with or without it, the name resolves to the same place. So Flui does not write it. When either fails (no wildcard, a foreign one, or a provider that could not be read just then), the application gets its own record and waits its minute.

There is nothing to configure. Publish the wildcard and the per-application records stop being written. Remove it and they come back on the next reconcile.

If you look at your zone, note that an application covered by the wildcard does not own that record. Tearing the application down deletes what it owns, and the shared record is not its to delete.

Zones, and giving one to a cluster

A zone is a domain you already own, registered with Flui, on a DNS provider Flui can talk to. You create the domain at the provider; Flui detects it and registers it. Registering a zone is done from the dashboard or the API. flui dns zone list shows the zones an installation knows about, with each one’s provider and TTL.

Assigning a zone to a cluster moves that cluster’s applications off a nip.io name and onto the domain:

Terminal window
flui dns zone assign example.com --cluster production

You do it once per cluster, and again after a rebuild, which is why it is available as a command and not only on a screen. Useful flags: --acme-email for the address registered with the certificate authority, --certificate-provider to choose between Let’s Encrypt and its staging service, and --no-wildcard-certificate if you want a certificate per application instead of one covering them all.

A cluster can publish under more than one zone. When an application’s hostname could belong to several, the longest match wins.

The command answers immediately. The work behind it (the credentials the certificate flow needs, the issuers, the wildcard record) runs in the background.

Keeping the zone in line

Flui keeps a view of what a zone should contain. The provider holds what it actually contains. The two can drift: someone edits a record in the provider’s console, a delete the provider accepted gets lost, a cluster is rebuilt at a new address.

flui dns zone status shows where each assignment stands (in sync, reconciling, drifted, pending, or in error), with the reason when there is one, and how long ago it last settled.

flui dns zone reconcile re-applies what the assignment needs. Add --wait when a script needs the outcome rather than the acknowledgement; it polls, with --timeout in seconds, and the work carries on whether or not you are still watching.

A second provider for the same zone

A DNS provider is a single point of failure you do not control. If it stops answering, every application under that zone becomes unreachable, however healthy the cluster is.

A replica is the same zone, carried on a second provider. The primary is untouched; a replica only adds coverage. Flui writes each record to the replica as well as the primary, and a scheduled pass brings the replica back in line if a write was missed.

  • flui dns replica add --zone <id> --provider <name> registers one. It must be a different provider from the primary, and one this installation is configured for. Pass --provider-zone-id to adopt a zone you already created there instead of having Flui create one.
  • flui dns replica populate copies every record across and applies the changes.
  • flui dns replica verify runs the same comparison without writing anything: it reports what it would create, update and remove.
  • flui dns replica list shows each replica’s state: pending, populating, active, degraded or disabled. A write Flui could not make marks the replica degraded rather than failing your deploy.
  • flui dns replica disable and enable pause and resume the copying without unregistering anything.
  • flui dns replica remove removes Flui’s registration only. Records already written at the provider stay where they are.

Plan for two consequences. Registering the first replica lowers the zone’s TTL from five minutes to one, because a long TTL is what makes a failover slow; removing the last one restores it. And Flui does not make the second provider authoritative for you. Adding its nameservers at your registrar is your step, and you should confirm the replica answers correctly before you take it.

Names without a domain: nip.io

When a cluster has no zone assigned, Flui builds the hostname from the cluster’s address, through a public service (nip.io) that resolves a name back to the address written inside it. No record exists anywhere; resolution happens at the resolver.

This lets the first cluster of a new installation come up without DNS as a prerequisite. You get a working URL the moment the cluster is ready. It is also fine for development and staging, where the hostname does not have to be presentable.

Do not use it for production. It puts a third party in your request path, it shares rate limits with everyone else using it, and your cluster’s address is written in every URL.

Moving to a real domain later is one operation: register the zone and assign it to the cluster. The wildcard is published as part of the assignment. New endpoints use the new names, and existing ones are reconciled across without redeploying the application.

Public and gated endpoints

An application can be published for the public or kept behind the installation’s sign-in:

  • <application>.<cluster>.<zone>: the public address, covered by the cluster’s wildcard.
  • <application>.internal.<zone>: the same application, behind the sign-in gate described in The control cluster. This name sits directly under the zone, not under the cluster’s subdomain, and is covered by its own wildcard, *.internal.<zone>.

Apart from the pattern, its wildcard and the gate in the request path, the two work the same way.

An application’s URL is published only once the endpoint serves. A hostname is decided when the endpoint is created, minutes before anything answers on it, and if that work then fails, the name never resolves. So the URL is withheld until the record and the routing are in place. It is withheld a little longer while the certificate is being issued, because an https:// link in that window would show a browser security warning.

While the URL is withheld, the endpoint’s state and its reason are shown instead.

What Flui DNS does not do

Buying a domain, and moving its authoritative DNS to a provider Flui integrates with, are steps you take at the registrar. Flui does not act at the registrar level: it works on a zone you have already created at a supported provider.

Where this chapter goes from here