SSL/TLS Certificates

Technical details. wbsp-platform up sets certificates up for you, and every application gets trusted HTTPS with no action from you or its developer. This page explains how. Developers who want an application on a domain of their own should read Custom domains.

Two front doors

A request reaches an application through one of two load balancers, depending on the name it uses.

Names under the platform's domain (<app>.<domain>, api.<domain>, …)
  Browser → application load balancer (TLS ends here: AWS wildcard certificate, firewall inspects)
          → re-encrypted → Traefik (in the cluster) → the application

Custom domains (shop.example.org, CNAME'd to the platform)
  Browser → network load balancer (passes the encrypted traffic straight through)
          → Traefik (TLS ends here: Let's Encrypt certificate for that domain) → the application

Names under the platform's domain are covered by one wildcard certificate, *.<domain>, issued by AWS Certificate Manager when the platform is built. It lives on the application load balancer, where the firewall (WAF) inspects the decrypted traffic. Nothing is issued per application, and a new application serves trusted HTTPS on its first request. AWS renews the certificate automatically.

Custom domains don't match that wildcard, so they use the second door. The developer points the domain at the platform with a CNAME record. Traefik, the in-cluster router, then asks Let's Encrypt for a certificate for that exact name the first time it's needed, proving control of the domain over plain HTTP (port 80). Traefik renews each certificate about 30 days before it expires. Developers need the second door's address for their CNAME record; you can find it with kubectl -n traefik get svc traefik (see "Looking inside the cluster" in Platform technical details).

Plain HTTP is redirected to HTTPS at both doors.

Practice and real certificates

Let's Encrypt has two issuers:

Issuer	Browsers trust it	Rate limits
Practice (staging)	No	very generous, for testing
Real (production)	Yes	strict (below)

A new platform is built on the practice issuer, so a mistake during the build can't use up the real issuer's limits. wbsp-platform up finishes with cutover, which switches to the real issuer. cutover --keep-practice-certificates holds back, and cutover --undo goes back to practice. The setting is WBSP_ACME_STAGING in the install's .env.

This applies to custom domains only. The wildcard certificate for the platform's own domain comes from AWS and is always trusted.

Let's Encrypt rate limits

Limit	Value	Notes
Certificates per registered domain	50 per week	e.g. 50 subdomains of `example.org` per week
Duplicate certificates	5 per week	the same exact set of names issued again
New orders per account	300 per 3 hours	across all domains
Failed validations	5 per hour per domain	the CNAME must be correct before the first request

Under normal use (fewer than 50 new custom domains a week), these limits don't matter.

Where certificates are kept

Traefik keeps its Let's Encrypt certificates and account key on a persistent disk, so they survive restarts and aren't requested again. When an application is removed, its route is deleted and Traefik stops renewing its certificate. The old certificate stays on the disk, where it takes negligible space and does no harm.

Limitations

A custom domain must point at the platform before its first request. If the CNAME hasn't propagated, issuance fails and is retried automatically, but repeated failures count against the rate limit above.
No wildcard certificates for custom domains. The HTTP proof can't issue them, so each custom name gets its own certificate.
Local deployments are HTTP only. Certificates apply to aws destinations.