112 lines
3.1 KiB
Markdown
112 lines
3.1 KiB
Markdown
# 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:**
|
|
```yaml
|
|
- 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:**
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
# 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](defaults/main.yml) for all available variables.
|
|
|
|
## References
|
|
|
|
- [Nginx Documentation](https://nginx.org/en/docs/)
|
|
- [Nginx ACME Support](https://blog.nginx.org/blog/native-support-for-acme-protocol)
|
|
- [Nginx Stream Module](https://nginx.org/en/docs/stream/ngx_stream_core_module.html)
|
|
- [Nginx Logging](https://nginx.org/en/docs/syslog.html)
|
|
- [Nginx SSL/TLS](https://nginx.org/en/docs/http/configuring_https_servers.html)
|