ansible-playbooks/roles/nginx

Nginx Role

Installs and configures Nginx as a reverse proxy for web applications with modular vhost management.

Features

• Modular vhost configuration via /etc/nginx/conf.d/
• Zero-downtime reloads
• Configurable logging backend (journald or traditional files)
• Automatic logrotate for file-based logging
• SSL/TLS configuration
• Native ACME/Let's Encrypt support (Nginx 1.25.0+)
• Transparent proxy forwarding (HTTP/HTTPS to other hosts)

Service Integration Pattern

Each service role should deploy its own vhost config:

In service role tasks:

- name: Deploy nginx vhost
  ansible.builtin.template:
    src: nginx-vhost.conf.j2
    dest: /etc/nginx/conf.d/myservice.conf
    validate: nginx -t
  when: myservice_nginx_enabled
  notify: Reload nginx

- name: Remove nginx vhost when disabled
  ansible.builtin.file:
    path: /etc/nginx/conf.d/myservice.conf
    state: absent
  when: not myservice_nginx_enabled
  notify: Reload nginx

Transparent Proxy Forwarding

Forward TCP traffic from this Nginx instance to services on other hosts using the stream module (layer 4 proxy).

Configuration:

nginx_forwarder:
  "blog.hello.com":
    forward_to: "my.host.lan"
    http: true    # Forward port 80 (default: true)
    https: true   # Forward port 443 (default: true)

How it works:

• Stream-based TCP proxy (layer 4, not HTTP layer 7)
• No protocol inspection - just forwards raw TCP packets
• HTTPS passes through encrypted - backend host handles TLS termination
• HTTP also uses stream (simpler, but no HTTP features like headers/logging)

Use case: Omega (gateway) forwards all traffic to Andromeda (internal server) that handles its own TLS certificates.

Important notes:

• Stream configs deployed to /etc/nginx/streams.d/
• No HTTP logging (stream doesn't understand HTTP protocol)
• No X-Forwarded-For headers (transparent TCP forwarding)
• Only ONE domain can use port 443 forwarding (TCP port limitation)

Logging Backends

journald (default):

• Logs sent to systemd journal via syslog
• View: journalctl -u nginx -f

file:

• Traditional /var/log/nginx/*.log files
• Automatic logrotate configuration

Switch via nginx_log_backend variable.

Hands-on Commands

# Test configuration
nginx -t

# Reload (zero downtime)
systemctl reload nginx

# View logs (journald)
journalctl -u nginx -f
journalctl -u nginx -n 100
journalctl -u nginx -p err

# View logs (file)
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

# List loaded vhosts
ls -la /etc/nginx/conf.d/

# List stream forwarders
ls -la /etc/nginx/streams.d/

Configuration Variables

See defaults/main.yml for all available variables.

References

• Nginx Documentation
• Nginx ACME Support
• Nginx Stream Module
• Nginx Logging
• Nginx SSL/TLS