sr2c.podman.podman_nginx role – Deploy nginx with Let’s Encrypt certificates using rootless Podman

Note

This role is part of the sr2c.podman collection (version 0.0.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install sr2c.podman.

To use it in a playbook, specify: sr2c.podman.podman_nginx.

Entry point main – Deploy nginx with Let’s Encrypt certificates using rootless Podman

Synopsis

  • Runs nginx as a quadlet container for podman_nginx_podman_rootless_user, and gets a Let’s Encrypt certificate for podman_nginx_primary_hostname and podman_nginx_additional_hostnames with certbot. Run sr2c.podman.podman_host for the user first.

  • nginx reads its configuration from ~/nginx, mounted as /etc/nginx/conf.d. Until a certificate exists, the role writes a temporary nginx.conf there that answers the ACME challenge and redirects everything else to HTTPS. Once the certificate exists, it replaces that with podman_nginx_config.

  • Certificates are kept in ~/certbot/conf, mounted as /etc/letsencrypt, so the certificate is /etc/letsencrypt/live/<primary hostname>/fullchain.pem inside the container. The calling role’s configuration must serve /.well-known/acme-challenge/ on port 80 from /var/www/certbot, for renewals and when the hostnames change.

  • When the hostnames change, the certificate is issued again with the new names. A timer runs certbot renew daily, and nginx restarts weekly to load renewed certificates.

  • Opens the http and https services in the firewalld zone podman_nginx_firewalld_zone.

  • With socket activation, nginx.socket listens on ports 80 and 443 and starts nginx on the first connection. The socket is enabled, so it starts at boot with podman_nginx_systemd_service_target, or with default.target when there is no target.

Parameters

Parameter

Comments

podman_nginx_additional_hostnames

list / elements=string

Other hostnames to include in the certificate.

Default: []

podman_nginx_additional_volumes

list / elements=dictionary

Extra volumes to mount in the nginx container, for example static files the application writes.

Default: []

dest

string / required

The path inside the container.

options

string / required

The mount options, for example ro,z.

src

string / required

The path on the host.

podman_nginx_certbot_image

string

The certbot container image.

Default: "docker.io/certbot/certbot:latest"

podman_nginx_certbot_testing

boolean

Get certificates from the Let’s Encrypt staging environment, which browsers don’t trust but which has much higher rate limits. Use it for testing.

Choices:

  • false ← (default)

  • true

podman_nginx_config

string

The nginx configuration, written to ~/nginx/nginx.conf once the certificate exists. nginx is restarted straight away when it changes.

The calling role renders it, for example with lookup('ansible.builtin.template', 'home/nginx/myapp.conf'). The lookup runs inside this role, which looks in its own templates before the calling role’s, so avoid a template named nginx-acme.conf.

When not set, the calling role must write its own configuration to ~/nginx after this role runs.

podman_nginx_firewalld_zone

string

The firewalld zone to open the http and https services in.

Default: "public"

podman_nginx_frontend_network

string

A network to attach nginx to, by the name of its quadlet without .network, usually one created with sr2c.podman.podman_networks. nginx reaches the application’s containers over it.

podman_nginx_image

string

The nginx container image.

Default: "docker.io/nginx:1"

podman_nginx_podman_rootless_user

string / required

The rootless Podman user that runs nginx. The calling role passes its own *_podman_rootless_user.

podman_nginx_primary_hostname

string / required

The hostname nginx serves, and the name of the certificate.

podman_nginx_socket_activation

boolean

Start nginx with systemd socket activation, from nginx.socket.

false is deprecated, and running without socket activation will be removed in a future release.

Choices:

  • false ← (default)

  • true

podman_nginx_systemd_service_requires

list / elements=string

Units that nginx requires and starts after, for example myapp.service.

A name without a unit suffix is taken as a service, with a deprecation warning. Give the full unit name.

Default: []

podman_nginx_systemd_service_slice

string

The slice to run nginx in, usually the stack’s slice.

podman_nginx_systemd_service_target

string

The stack’s target. nginx and nginx.socket are PartOf= it, so stopping or restarting the target stops or restarts them too, and the socket is wanted by it.

When this is set, the nginx container is also wanted by default.target, so it starts at boot.

Authors