podman-quadlet-cookbook/cookbooks/traefik

Podman Quadlet: Traefik

Overview

Traefik is a modern HTTP reverse proxy and load balancer started as a Podman Quadlet. It provides automatic service discovery, SSL termination, and routing.

This cookbook:

• Runs Traefik as a rootless container with minimal privileges.
• Supports automatic HTTPS with Let's Encrypt integration.
• Includes health checks to monitor the service status.
• Stores configuration in /etc/quadlets/traefik/ and state in /var/lib/quadlets/traefik/.
• Supports automatic container image updates via Podman auto-update.

Configuration

The v3 version of Traefik expects the load its configuration from one (and only one) of the following sources:

• A static configuration file (e.g. traefik.yaml) mounted into the /etc/traefik of the container.
• TRAEFIK_* Environment variables.
• Command-line arguments.

If you want to use a static configuration file, you can place it in /etc/quadlets/traefik/traefik.yaml and it will be mounted into the container. Since it is the default location for Traefik's configuration, no additional configuration is needed.

To use the environment variables, you can set them in the override.conf file for the container. That is to say, you can create the file /etc/containers/systemd/traefik.container.d/override.conf with the following content:

Environment=TRAEFIK_FOO=bar TRAEFIK_BAZ=qux ...

Regarding command-line arguments, you can create the file /etc/containers/systemd/traefik.container.d/override.conf with the following content:

EntryPoint=/usr/local/bin/traefik
Exec=--foo=bar --baz=qux ...

Usage

In a separate terminal, follow the logs.

sudo make tail-logs

Install the Podman Quadlets and start Traefik.

sudo make clean install

You should see the traefik.service starting up.

Verify Traefik is running:

curl -sSf -H 'Host: ping' http://127.0.0.1/

Access the Traefik dashboard (if enabled in configuration):

curl http://127.0.0.1:8080/dashboard/

Restart the traefik.target unit.

sudo systemctl restart traefik.target

Finally, remove the quadlets, their configuration and their data.

sudo make uninstall clean

Integration tests

sudo make test

What if I want to use a TLS certificate provided by the "lego" cookbook?

/etc/containers/systemd/traefik.container.d/lego.conf:

[Unit]
# Now, Traefik depends on the lego target, which will ensure that the TLS certificates are generated and available before Traefik starts
After=lego.target
Wants=lego.target

[Container]
# Mount the directory containing the TLS certificates generated by lego into the Traefik container
Volume=/run/quadlets/traefik/tls:/etc/traefik/tls:Z

# Health check on HTTPS
HealthCmd=wget -q -O /dev/null --no-check-certificate --header 'Host: ping' https://127.0.0.1/

[Service]
# Get the TLS certificates in place before starting traefik
ExecStartPre=/bin/sh -c 'install -o 10001 -g 10000 -m 0600 -t /run/quadlets/traefik/tls /var/lib/quadlets/lego/certificates/*.crt /var/lib/quadlets/lego/certificates/*.key'

/etc/quadlets/traefik/conf.d/tls.yaml:

tls:
  certificates:
  - certFile: /etc/traefik/tls/f.q.d.n.crt
    keyFile: /etc/traefik/tls/f.q.d.n.key
  stores:
    default:
      defaultCertificate:
        certFile: /etc/traefik/tls/f.q.d.n.crt
        keyFile: /etc/traefik/tls/f.q.d.n.key

http:
  routers:
    traefik-ping-tls:
      rule: Host(`ping`)
      entryPoints:
      - https
      service: "ping@internal"
      tls: {}
      middlewares:
      - localhost-only
  middlewares:
    localhost-only:
      ipAllowList:
        sourceRange:
          - "127.0.0.1/32"

/etc/quadlets/traefik/traefik.yaml:

entryPoints:
  # <-- no http entrypoint here
  https:
    address: ":443"

/etc/tmpfiles.d/traefik-lego.conf:

d /run/quadlets/traefik 0755 10001 10000 -
d /run/quadlets/traefik/tls 0700 10001 10000 -

/etc/quadlets/traefik/conf.d/$yoursite.yaml:

http:
  routers:
    example:
      rule: "Host(`service.example.test`)"
      entryPoints:
      - https
      service: "example"
      tls: {} # <-- this tells Traefik to enable TLS and find a matching certificate by SNI
  services:
    example:
      loadBalancer:
        servers:
        - url: "http://127.0.0.1:8080"