Terraform Docker Infrastructure Lab
Modular Terraform infrastructure lab with state-safe refactoring, native IaC tests, CI security gates, observability, and end-to-end failure validation.
View repository01 / Overview
Why it exists
Terraform Docker Infrastructure Lab provisions a local FastAPI, PostgreSQL, Nginx and observability stack through reusable Terraform modules, with native Terraform tests, state-safe moved blocks, CI validation and security scanning.
Explores infrastructure lifecycle and platform engineering beyond basic provisioning by making module boundaries, state migration, configuration-driven replacement, failure testing and infrastructure validation explicit.
02 / Architecture
System architecture
Terraform owns the local Docker network, application layer and observability layer through a root module and three child modules. Browser or curl traffic enters through Nginx, reaches FastAPI and PostgreSQL, while Prometheus, Grafana, Alertmanager and Mailpit provide local monitoring and alert delivery.
Terraform ownership and module boundaries
The root module wires reusable child modules for the network, application and observability layers.
Terraform root module owns modules/network. Terraform root module owns modules/application. Terraform root module owns modules/observability.
- ControlTerraform root moduleproviders · variables · outputs
- Servicemodules/networkDocker network + port checksServicemodules/applicationFastAPI · PostgreSQL · NginxObservabilitymodules/observabilityPrometheus · Grafana · alerts
Application request flow
Only Nginx is the public application entry point; FastAPI and PostgreSQL communicate over the dedicated Docker network.
Browser / curl HTTP Nginx. Nginx proxy FastAPI. FastAPI queries PostgreSQL.
- ClientBrowser / curllocal request
- BoundaryNginxreverse proxy
- ServiceFastAPIAPI + metrics
- PersistencePostgreSQLdatabase + volume
Metrics and alert lifecycle
FastAPI metrics are scraped by Prometheus, visualized in Grafana, and evaluated into alerts delivered through Alertmanager to Mailpit.
FastAPI /metrics queries / alerts Prometheus. FastAPI /metrics visualizes Grafana. Prometheus and Grafana routes Alertmanager. Alertmanager SMTP Mailpit.
- ServiceFastAPI /metricsrequest + latency metrics
- ObservabilityPrometheusscrape + alert rulesObservabilityGrafanaPromQL dashboard
- ControlAlertmanagergroup + route
- OutputMailpitlocal notification sink
Architecture notes
- moved blocks preserve resource identities while the original root resources move into child modules.
- Application and monitoring configuration hashes drive deterministic replacement when meaningful inputs change.
- Native terraform test plans use mocked Docker providers; they do not provision real Docker infrastructure.
- GitHub Actions runs Terraform formatting, initialization, validation and tests, with TFLint, Trivy, Gitleaks and Hadolint security gates; CI does not run terraform apply.
- k6 exercises local load and controlled error, latency and API-down alert lifecycles end to end.
03 / Engineering concepts
System concerns made explicit
04 / Proof & evidence
Measured or reproducible signals
State-safe module refactor
0 add · 0 change · 0 destroy
Verified Terraform migration
The original root resources were reorganized into network, application and observability modules through explicit Terraform moved blocks while preserving managed resource identities and avoiding infrastructure recreation.
Infrastructure validation
Native Terraform tests
Mock-provider test suite
Root and child-module contracts are exercised with terraform test and mocked Docker providers, validating naming, outputs, resource wiring and failure conditions without provisioning real Docker infrastructure.
05 / Technology stack