docs: [#28] add environment vs provider configuration analysis

- Comprehensive analysis of how multiple environments use same provider
- Testing results showing dynamic .auto.tfvars generation prevents conflicts
- Documentation of overwrite behavior and environment isolation
- Test commands and real-world variable differences demonstrated
- Confirms system is safe and conflict-free for staging/production deployments

Author: josecelano

docs/analysis/environment-provider-configuration-analysis.md

@@ -0,0 +1,211 @@
+# Environment vs Provider Configuration Analysis
+
+## Overview
+
+This document analyzes how the Torrust Tracker Demo infrastructure handles multiple
+environments (staging, production) using the same cloud provider (Hetzner) and explains
+why there are no file conflicts in the OpenTofu/Terraform configuration.
+
+## Problem Statement
+
+The user was concerned about potential configuration conflicts when multiple environments
+use the same provider, specifically:
+
+- Why both `staging-hetzner.env` and `production-hetzner.env` can coexist
+- How the system handles generating provider-specific Terraform variables
+- Whether files get overwritten causing conflicts
+
+## Key Findings
+
+### 1. Dynamic Variable Generation (Not Static Files)
+
+**The system does NOT create separate static `.auto.tfvars` files for each environment.**
+Instead, it uses a **dynamic generation approach** where:
+
+- Each deployment generates the `.auto.tfvars` file on-demand
+- The same file (`hetzner.auto.tfvars`) is overwritten with environment-specific values
+- Variables are sourced from the loaded environment configuration
+
+### 2. File Structure Analysis
+
+```text
+infrastructure/
+├── config/
+│   └── environments/
+│       ├── staging-hetzner.env      # Environment-specific config
+│       └── production-hetzner.env   # Environment-specific config
+└── terraform/
+    └── hetzner.auto.tfvars          # Single provider file (overwritten)
+```
+
+### 3. How It Works
+
+1. **Environment Loading**: The system loads one environment at a time:
+
+   ```bash
+   source infrastructure/config/environments/staging-hetzner.env
+   ```
+
+2. **Provider Loading**: The provider interface validates and loads the provider:
+
+   ```bash
+   load_provider hetzner
+   ```
+
+3. **Dynamic Generation**: The provider generates variables into a single file:
+
+   ```bash
+   provider_generate_terraform_vars "${TERRAFORM_DIR}/hetzner.auto.tfvars"
+   ```
+
+4. **Terraform Execution**: OpenTofu/Terraform uses the generated variables for that
+   specific deployment
+
+## Test Results
+
+### Staging Environment Variables
+
+```hcl
+# Generated Hetzner Cloud provider variables
+infrastructure_provider = "hetzner"
+
+# Standard VM configuration
+environment        = "development"
+vm_name           = "torrust-tracker-staging"
+vm_memory         = 4096
+vm_vcpus          = 4
+vm_disk_size      = 30
+ssh_public_key    = "ssh-rsa AAAAB3..."
+use_minimal_config = false
+
+# Hetzner-specific settings
+hetzner_token       = "staging_token_123"
+hetzner_server_type = "cx31"
+hetzner_location    = "nbg1"
+hetzner_image       = "ubuntu-24.04"
+```
+
+### Production Environment Variables
+
+```hcl
+# Generated Hetzner Cloud provider variables
+infrastructure_provider = "hetzner"
+
+# Standard VM configuration
+environment        = "development"
+vm_name           = "torrust-tracker-production"
+vm_memory         = 8192
+vm_vcpus          = 4
+vm_disk_size      = 40
+ssh_public_key    = "ssh-rsa AAAAB3..."
+use_minimal_config = false
+
+# Hetzner-specific settings
+hetzner_token       = "production_token_456"
+hetzner_server_type = "cx41"
+hetzner_location    = "nbg1"
+hetzner_image       = "ubuntu-24.04"
+```
+
+### Key Differences
+
+- **VM Name**: `torrust-tracker-staging` vs `torrust-tracker-production`
+- **Memory**: 4096MB vs 8192MB
+- **Disk Size**: 30GB vs 40GB
+- **Server Type**: cx31 vs cx41 (auto-selected based on memory)
+- **Token**: Different API tokens for each environment
+
+## Overwrite Behavior Demonstration
+
+When switching environments, the system overwrites the same file with new values:
+
+1. **Deploy Staging**: Generates `hetzner.auto.tfvars` with staging values
+2. **Deploy Production**: Overwrites `hetzner.auto.tfvars` with production values
+
+This approach ensures:
+
+- ✅ No file conflicts between environments
+- ✅ Only one set of variables active at a time
+- ✅ Environment-specific configurations are properly isolated
+- ✅ No risk of mixed configurations
+
+## Code Flow
+
+```mermaid
+graph TD
+    A[make infra-apply ENVIRONMENT=staging PROVIDER=hetzner] --> B[Load staging-hetzner.env]
+    B --> C[Load hetzner provider]
+    C --> D[Generate hetzner.auto.tfvars with staging values]
+    D --> E[Run OpenTofu apply with staging configuration]
+
+    F[make infra-apply ENVIRONMENT=production PROVIDER=hetzner] --> G[Load production-hetzner.env]
+    G --> H[Load hetzner provider]
+    H --> I[Overwrite hetzner.auto.tfvars with production values]
+    I --> J[Run OpenTofu apply with production configuration]
+```
+
+## Provider Interface Implementation
+
+### File: `infrastructure/scripts/providers/provider-interface.sh`
+
+- Defines standard interface all providers must implement
+- Validates provider implementations
+- Manages provider loading and variable generation
+
+### File: `infrastructure/scripts/providers/hetzner/provider.sh`
+
+- Implements `provider_generate_terraform_vars()` function
+- Reads environment variables and generates Terraform variables
+- Auto-selects server types based on memory requirements
+- Handles SSH key configuration
+
+### File: `infrastructure/scripts/provision-infrastructure.sh`
+
+- Orchestrates the entire deployment process
+- Loads environment configurations
+- Calls provider variable generation
+- Executes OpenTofu/Terraform operations
+
+## Conclusion
+
+The system design is **safe and conflict-free** because:
+
+1. **Sequential Execution**: Only one environment is deployed at a time
+2. **Dynamic Generation**: Variables are generated fresh for each deployment
+3. **Single File Overwrite**: The same provider file is reused and overwritten
+4. **Environment Isolation**: Each environment has its own configuration file
+
+There is **no risk of file conflicts** because the system intentionally overwrites the
+same file with environment-specific values, ensuring that only the current deployment's
+configuration is active.
+
+This approach follows infrastructure best practices by:
+
+- Maintaining clear separation between environments
+- Preventing configuration drift
+- Ensuring reproducible deployments
+- Following the principle of least surprise
+
+## Testing Commands Used
+
+```bash
+# Load staging environment and generate variables
+source infrastructure/config/environments/staging-hetzner.env
+load_provider hetzner
+export HETZNER_API_TOKEN="staging_token_123"
+provider_generate_terraform_vars "/tmp/staging-test.auto.tfvars"
+
+# Load production environment and generate variables
+source infrastructure/config/environments/production-hetzner.env
+load_provider hetzner
+export HETZNER_API_TOKEN="production_token_456"
+provider_generate_terraform_vars "/tmp/production-test.auto.tfvars"
+
+# Compare the differences
+diff -u /tmp/staging-test.auto.tfvars /tmp/production-test.auto.tfvars
+
+# Test overwrite behavior
+provider_generate_terraform_vars "/tmp/same-file.auto.tfvars"
+# Switch environment and overwrite
+provider_generate_terraform_vars "/tmp/same-file.auto.tfvars"
+```