Podos A lightweight container platform Early development · not released

Guides

Domains and HTTPS

Available

This page describes what is in the code on the main branch. Let's Encrypt (tls = "auto") has only been tested against a test ACME server, not yet against the real Let's Encrypt service.

How it works

The daemon contains a reverse proxy that listens on ports 80 and 443. A service with domains and a port receives the traffic for those domains:

TOML
namespace = "shop"

[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com", "www.shop.example.com"]
tls = "auto"
YAML
namespace: shop

service:
  web:
    image: ghcr.io/example/shop:1.4.2
    port: 3000
    domains: [shop.example.com, www.shop.example.com]
    tls: auto

Point the DNS records of the domains at the server and open ports 80 and 443 in its firewall. Deploy, and the proxy serves the service. For routes with TLS, plain HTTP requests are redirected to HTTPS.

The proxy sends the traffic to the container's port. Add a health check and a replica receives traffic only when it is ready.

The proxy is on by default. podos setup --ingress off turns it off, --http-listen and --https-listen change its addresses, and podos setup --reset http-listen goes back to the default. See podos setup.

TLS modes

tls Certificate
auto From Let's Encrypt over ACME. This is the default when tls is not set. Needs podos setup --acme-email EMAIL.
self-signed Issued by the Podos internal CA created by podos setup. Useful for test environments and internal names. Browsers do not trust it by default.
off None: plain HTTP.
cert:<name> A certificate you upload to the environment under <name> with podos cert set.

Private keys are stored encrypted, like secrets, and never appear in manifests, logs or API responses.

Let's Encrypt (auto)

Turn it on once on the server:

sudo podos setup --acme-email admin@example.com

--acme-email saves the contact address and records your agreement to the certificate authority's terms of service (https://letsencrypt.org/repository/). Only this saved setting enables tls = "auto". Without it, a route with auto is reported as broken in podos ps, and every other route keeps working.

Podos has only tested this against a test ACME server, not against the real Let's Encrypt service yet. A wildcard domain such as *.example.com cannot use auto; use an uploaded certificate or self-signed.

Your own certificate (cert:<name>)

Upload the chain (leaf first) and the unencrypted key, for the namespace and environment:

podos cert set shop-cert --cert fullchain.pem --key privkey.pem
podos cert list

Then name it in the manifest:

TOML
namespace = "shop"

[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com"]
tls = "cert:shop-cert"
YAML
namespace: shop

service:
  web:
    image: ghcr.io/example/shop:1.4.2
    port: 3000
    domains: [shop.example.com]
    tls: cert:shop-cert

The certificate must exist and cover the service's domains when you deploy, or the release is refused. podos cert set takes effect at once: upload a renewed certificate under the same name and no redeploy is needed. If you remove a certificate that a service still uses, the HTTPS handshakes of its routes fail and podos ps reports the missing certificate. See podos cert.

Staging or a private CA

Available By default tls = "auto" uses Let's Encrypt production. To test with Let's Encrypt staging, or to use a private ACME CA, start the daemon with --acme-directory URL (https only). With a private CA, --acme-ca-file PATH names the PEM file with the only roots trusted for that connection; the file and its directory must not be writable by group or others. Both are daemon flags, not saved by podos setup. See podos daemon.

Paths

A domain may include a path, example.com/shop. The longest matching path wins. Two services of one environment cannot claim the same domain and path.

One domain, one environment

A domain belongs to one environment. The first claim wins across the whole server: a release that asks for a domain that another namespace holds is refused. Give each environment its own domains, for example with an override:

TOML
namespace = "shop"
environments = ["test", "prod"]

[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com"]

[environment.test.service.web]
domains = ["test.shop.example.com"]
tls = "self-signed"
YAML
namespace: shop
environments: [test, prod]

service:
  web:
    image: ghcr.io/example/shop:1.4.2
    port: 3000
    domains: [shop.example.com]

environment:
  test:
    service:
      web:
        domains: [test.shop.example.com]
        tls: self-signed

podos down removes the environment's domains and its uploaded certificates.

When something is wrong

podos ps prints findings about the namespace's domains below the table: a missing certificate, auto without --acme-email, or a route that could not be set up. A release is refused before anything starts when a domain is claimed by another namespace, a cert: certificate is missing or does not cover the domains, or a wildcard domain uses auto.

See domains and tls in the manifest reference.