Skip to content
flui.cloud

TLS and certificates

Every Flui cluster runs on HTTPS from the first minute. There is no “now go install cert-manager and configure an issuer” step: certificates are part of the same operation that creates an endpoint, and they renew themselves without the operator having to think about it.

This chapter is about how — which authority signs the certificates, which kind of certificate Flui issues, and the trade-off between modes.

The three issuance modes

Underneath, the cluster has two primitives — Let’s Encrypt production and Let’s Encrypt staging — and exposes three modes that compose them:

  • Production. Certificates are issued by Let’s Encrypt production — real, browser-trusted, valid for every client out of the box. This is the mode for anything that real users reach.
  • Staging. Certificates are issued by Let’s Encrypt staging — same issuance flow, but signed by a non-trusted CA. Browsers will warn, but the staging endpoint has no practical rate limits, so you can re-issue as often as you need while iterating.
  • Preflight. A two-step path: an initial staging certificate is issued first (no rate limit, fast feedback that the whole challenge chain works end-to-end), and once it is valid the cluster auto-promotes the endpoint to a production certificate. This is the safer choice when you are testing a new DNS setup or a new endpoint against a production-quota authority: you burn out the configuration mistakes against staging, then move to production once you know the flow works.

The trade-off and the rate-limit context are introduced in Creating a cluster from zero; this chapter only revisits the consequence: production is the default for real environments, staging is the default for tight iteration loops, preflight is the bridge between the two when the cost of a production rate-limit hit is high.

Preflight is the dashboard’s orchestration over the two primitives — staging then production are real issuances against real Let’s Encrypt endpoints; the “promotion” is the dashboard swapping the issuer once the staging cert is valid. A cluster can also move from staging to production cleanly as a one-shot operation. The other direction is rarely useful and not a supported flow.

The three certificate shapes

Within either mode, the cluster does not always issue the same kind of certificate. The shape is decided by what the cluster knows about DNS:

Per-endpoint certificates

One certificate per FQDN. The cluster proves it controls the name by serving a small challenge file from the application’s address (an HTTP-01 challenge). No DNS provider integration is required.

This is the simplest shape — each endpoint stands on its own and gets its own certificate — but every new endpoint triggers a fresh issuance, so when the cluster adds and removes endpoints often the issuance count adds up against the public authority’s limits.

Wildcard certificate

A single certificate that covers every endpoint under the cluster’s subdomain. The cluster proves it controls the zone by briefly setting a DNS record on it (a DNS-01 challenge), which requires a DNS zone Flui can drive.

This is the preferred shape when the cluster has a managed DNS zone registered — see DNS as part of the deploy contract. The next endpoint added to the cluster is already covered; there is no re-issuance churn as the application list grows.

SAN certificate

A single certificate that lists every endpoint FQDN as an additional name. The proof of control is the same as the per-endpoint case (HTTP-01 per name); what changes is that the cluster keeps one certificate object up to date instead of one per endpoint.

The canonical use of this shape is the bootstrap of the control cluster itself: a single certificate covers the three core control-plane endpoints — the API, the dashboard and the identity provider — under one issuance, instead of paying for three separate HTTP-01 rounds. The certificate is re-issued whenever the list of names changes, so it is the right call for a small, stable set of endpoints known up front and a poor fit for a cluster whose application list moves frequently.

Renewal

In every mode and every shape, certificates renew themselves ahead of expiry. The cluster keeps the certificate material as a secret close to the application; renewal happens before expiration with no operator action.

The renewal path matches the issuance path: a wildcard renews through DNS-01 against the bound zone; SAN and per-endpoint certificates renew through HTTP-01 served from the cluster’s ingress.

Where this chapter goes from here