Add container deployment model (ADR-020) and fix review issues
- ADR-020: Document defense-in-depth rationale for running in a minimal Docker container (memory-safe language + container isolation), flexible upstream addressing (Docker DNS, loopback, LAN, tunnel endpoints), file-primary logging for fail2ban, and volume mount strategy - ADR-016: Add allow_wildcard_bind override for container deployments where 0.0.0.0 is correct inside the container network namespace - operations.md: Add container deployment section with Docker Compose example, networking table, volume mounts, and health check integration; flip logging to file-primary for fail2ban reliability; note systemd as alternative to container deployment - config.md: Restructure logging fields into nested LoggingConfig (matching TOML [logging] section), add allow_wildcard_bind, shutdown_timeout_secs, and log_file_path fields; clarify upstream addressing supports Docker DNS and tunnel endpoints; update validation rule for 0.0.0.0 override - overview.md: Update architecture diagram for container model with Docker networking and volume mounts; add ADR-020 reference - proxy.md: Clarify X-Forwarded-Proto is determined by listener port, not hardcoded 80/443 - ADR-013: Fix health_check_port default contradiction (default is 9900, not 0/disabled as previously stated)
This commit is contained in:
@@ -19,8 +19,15 @@ deployment.
|
||||
## Decision
|
||||
|
||||
The `bind_addr` field on each `[[listeners]]` entry must be an explicit IP
|
||||
address. `0.0.0.0` is rejected during config validation. The proxy will not
|
||||
start if any listener's `bind_addr` is `0.0.0.0`.
|
||||
address. `0.0.0.0` is rejected during config validation unless explicitly
|
||||
overridden. The proxy will not start if any listener's `bind_addr` is
|
||||
`0.0.0.0` and the override is not enabled.
|
||||
|
||||
**Override mechanism**: `allow_wildcard_bind = true` in the config file, or
|
||||
`--allow-wildcard-bind` on the command line. This flag permits `0.0.0.0` as a
|
||||
valid bind address. It is intended for container deployments where the
|
||||
container's network namespace is isolated and `0.0.0.0` is the correct address
|
||||
(Docker publishes only the explicitly mapped ports).
|
||||
|
||||
## Rationale
|
||||
|
||||
@@ -31,24 +38,31 @@ start if any listener's `bind_addr` is `0.0.0.0`.
|
||||
- `0.0.0.0` is often a default in example configurations and can be deployed
|
||||
without the operator realizing the service is accessible on all interfaces
|
||||
- Rejecting it at validation time prevents this common mistake
|
||||
- If a deployment genuinely needs to bind all interfaces, `0.0.0.0` can be
|
||||
overridden with an explicit flag, but this should be a deliberate choice
|
||||
- In a container, `0.0.0.0` is correct and safe because the container's
|
||||
network namespace isolates it — only Docker-published ports are reachable
|
||||
from outside the container
|
||||
- The override is opt-in so it must be a deliberate choice, not an accident
|
||||
- This matches the principle of explicit over implicit for security-sensitive
|
||||
configuration
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
- Prevents accidental exposure on unintended network interfaces
|
||||
- Prevents accidental exposure on unintended network interfaces in bare-metal
|
||||
deployments
|
||||
- Forces operators to be deliberate about which interface the proxy serves
|
||||
- Config validation catches the mistake before deployment
|
||||
- Container deployments work correctly with `0.0.0.0` when the override is
|
||||
explicitly enabled
|
||||
|
||||
**Negative:**
|
||||
- Not suitable for deployments that genuinely need to bind all interfaces
|
||||
(mitigated by explicit override if needed in the future)
|
||||
- Slightly more configuration required (operator must know their public IP)
|
||||
- Container deployments require one extra config flag (`allow_wildcard_bind =
|
||||
true`) — a minor operational step
|
||||
- Slightly more configuration required for bare-metal (operator must know
|
||||
their public IP)
|
||||
|
||||
## References
|
||||
|
||||
- [ADR-020: Container Deployment Model](020-container-deployment.md)
|
||||
- [config.md](../config.md)
|
||||
- [overview.md](../overview.md)
|
||||
Reference in New Issue
Block a user