update docs

Author: bogdan-ts

terraform/aws/QUICKSTART.md

@@ -22,9 +22,17 @@ cp terraform.tfvars.example terraform.tfvars
 vim terraform.tfvars
 ```
 
-Set required parameters:
+Uncomment and set all required parameters:
 - `ssh_key_name` - your AWS SSH key name
-- `grafana_password` - custom password (optional, defaults to "demo")
+- `aws_region` - AWS region
+- `environment` - environment name
+- `instance_type` - EC2 instance type (e.g., t3.medium)
+- `data_volume_size` - data disk size in GiB
+- `data_volume_type` / `root_volume_type` - volume types (gp3, st1, sc1)
+- `allowed_ssh_cidr` / `allowed_cidr_blocks` - CIDR blocks for access
+- `use_elastic_ip` - allocate Elastic IP (true/false)
+- `grafana_password` - Grafana admin password
+- `postgres_ai_version` - git branch/tag (optional, defaults to "main")
 
 ## Add monitoring instances
 
@@ -45,12 +53,14 @@ monitoring_instances = [
 ## Deploy
 
 ```bash
-# Validate
-./validate.sh
-
-# Deploy
+# Initialize and validate
 terraform init
+terraform validate
+
+# Review changes
 terraform plan
+
+# Deploy
 terraform apply
 
 # Get access info
@@ -63,10 +73,10 @@ terraform output ssh_command
 ```bash
 # Grafana dashboard
 open $(terraform output -raw grafana_url)
-# Login: monitor / demo (or your custom password)
+# Login: monitor / <password from terraform.tfvars>
 
 # SSH
-ssh -i ~/.ssh/postgres-ai-key.pem ubuntu@$(terraform output -raw public_ip)
+ssh -i ~/.ssh/postgres-ai-key.pem ubuntu@$(terraform output -raw external_ip)
 ```
 
 ## Operations
@@ -95,3 +105,17 @@ ssh ubuntu@IP "sudo systemctl status postgres-ai"
 ssh ubuntu@IP "sudo docker ps"
 ```
 
+## Security notes
+
+Credentials (passwords, connection strings) are stored in `terraform.tfstate` in plain text. For one-off/dev deployments this is acceptable if you clean up after `terraform destroy`:
+
+```bash
+terraform destroy
+rm -rf .terraform/ terraform.tfstate*
+```
+
+For production deployments, consider:
+- Using environment variables: `export TF_VAR_grafana_password=...`
+- Remote state with encryption (S3 + encryption)
+- Configuring monitoring instances manually after deployment
+

terraform/aws/README.md

@@ -8,98 +8,100 @@ Single EC2 instance with Docker Compose.
 
 Terraform creates:
 - VPC with public subnet
-- EC2 instance (t3.medium, Ubuntu 22.04 LTS)
-- EBS volume (50 GiB gp3, encrypted)
+- EC2 instance (Ubuntu 22.04 LTS)
+- EBS volumes (configurable types: gp3, st1, sc1, encrypted)
 - Security Group (SSH + Grafana ports)
 - Elastic IP (optional)
 
-On first boot, EC2 instance clones this repository and runs `docker-compose up` to start all monitoring services.
+On first boot, EC2 instance clones the specified version of this repository and runs `docker-compose up` to start all monitoring services.
 
 ## Quick start
 
 See [QUICKSTART.md](QUICKSTART.md) for step-by-step guide.
 
-## Configuration
+### Validation
 
-### Minimal setup
+```bash
+# Check prerequisites
+terraform version
+aws sts get-caller-identity
+
+# Validate configuration
+terraform init
+terraform validate
+terraform plan
+```
 
-```hcl
-# terraform.tfvars
-ssh_key_name = "postgres-ai-key"
+## Configuration
 
-# Optional: Set custom Grafana password (defaults to 'demo')
-# grafana_password = "YourSecurePassword123!"
-```
+### Required parameters
 
-### Minimal production setup
+All parameters in `terraform.tfvars` must be explicitly set (uncommented):
 
 ```hcl
 # terraform.tfvars
 
 # REQUIRED PARAMETERS
-ssh_key_name = "your-key-name"
-
-# AWS SETTINGS
-aws_region = "us-east-1"
-environment = "production"
-instance_type = "t3.medium"
-
-# STORAGE
-data_volume_size = 50 # GiB
+ssh_key_name         = "your-key-name"
+aws_region           = "us-east-1"
+environment          = "production"
+instance_type        = "t3.medium"
+data_volume_size     = 50
+data_volume_type     = "gp3"  # gp3 (SSD), st1 (HDD), sc1 (HDD)
+root_volume_type     = "gp3"
+allowed_ssh_cidr     = ["203.0.113.0/24"]
+allowed_cidr_blocks  = ["203.0.113.0/24"]
+use_elastic_ip       = true
+grafana_password     = "YourSecurePassword123!"
+```
 
-# SECURITY (restrict access!)
-allowed_ssh_cidr = ["0.0.0.0/0"] # WARNING: Allows access from anywhere
-allowed_cidr_blocks = ["0.0.0.0/0"] # WARNING: Allows access from anywhere
+### Optional parameters
 
-# OPTIONAL PARAMETERS
-# grafana_password = "YourSecurePassword123!" # Defaults to 'demo'
-# postgres_ai_api_key = "your-api-key" # For uploading reports
-# enable_demo_db = false # true for testing
-# use_elastic_ip = true # Stable IP address
+```hcl
+# OPTIONAL (have defaults)
+postgres_ai_api_key = "your-api-key"  # For uploading reports
+enable_demo_db      = false           # Demo database (default: true)
+postgres_ai_version = "main"          # Git branch/tag (default: "main")
 
 monitoring_instances = [
   {
-    name = "main-db"
-    conn_str = "postgresql://monitor:pass@db.example.com:5432/postgres"
+    name        = "main-db"
+    conn_str    = "postgresql://monitor:pass@db.example.com:5432/postgres"
     environment = "production"
-    cluster = "main"
-    node_name = "primary"
+    cluster     = "main"
+    node_name   = "primary"
   }
 ]
 ```
 
-### Full configuration
+### Full example
 
 ```hcl
-# AWS
-aws_region = "us-east-1"
-environment = "production"
-instance_type = "t3.medium"
-
-# Storage
-data_volume_size = 50
-
-# Security (restrict access in production)
-allowed_ssh_cidr = ["203.0.113.0/24"]
-allowed_cidr_blocks = ["203.0.113.0/24"]
-
-# Required
-ssh_key_name = "ssh-key"
-
-# Optional
-grafana_password = "SecurePassword123!" # Defaults to 'demo'
-postgres_ai_api_key = "your-api-key"
-enable_demo_db = false
-use_elastic_ip = true
+# REQUIRED
+ssh_key_name         = "postgres-ai-key"
+aws_region           = "us-east-1"
+environment          = "production"
+instance_type        = "t3.medium"
+data_volume_size     = 100
+data_volume_type     = "gp3"
+root_volume_type     = "gp3"
+allowed_ssh_cidr     = ["203.0.113.0/24"]
+allowed_cidr_blocks  = ["203.0.113.0/24"]
+use_elastic_ip       = true
+grafana_password     = "SecurePassword123!"
+
+# OPTIONAL
+postgres_ai_api_key  = "your-api-key"
+enable_demo_db       = false
+postgres_ai_version  = "v0.9"
 
-# Monitoring instances
 monitoring_instances = [
   {
-    name = "prod-db"
-    conn_str = "postgresql://monitor:pass@db.example.com:5432/postgres"
+    name        = "prod-db"
+    conn_str    = "postgresql://monitor:pass@db.example.com:5432/postgres"
     environment = "production"
-    cluster = "main"
-    node_name = "primary"
+    cluster     = "main"
+    node_name   = "primary"
   }
 ]
 ```
@@ -111,7 +113,7 @@ monitoring_instances = [
 ```bash
 terraform output ssh_command
 # Or directly:
-ssh -i ~/.ssh/postgres-ai-key.pem ubuntu@$(terraform output -raw public_ip)
+ssh -i ~/.ssh/postgres-ai-key.pem ubuntu@$(terraform output -raw external_ip)
 ```
 
 ### Service management
@@ -132,14 +134,19 @@ sudo systemctl restart postgres-ai
 
 ### Add monitoring instance
 
-Method 1: Update terraform.tfvars and run `terraform apply`
+Method 1: Update `terraform.tfvars` and apply changes:
+```bash
+# Edit terraform.tfvars, add to monitoring_instances array
+terraform apply
+# Automatically updates instances.yml and restarts pgwatch services
+```
 
-Method 2: Manual configuration on server:
+Method 2: Manual configuration (avoids credentials in state):
 ```bash
 ssh ubuntu@your-ip
 cd /home/postgres_ai/postgres_ai
 sudo -u postgres_ai vim instances.yml
-sudo docker-compose restart
+sudo -u postgres_ai ./postgres_ai update-config
 ```
 
 ### Backup
@@ -247,16 +254,16 @@ ssh ubuntu@your-ip "sudo resize2fs /dev/nvme1n1"
 Choose instance type based on monitoring workload:
 
 ```hcl
-instance_type = "t3.medium"  # 2 vCPU, 4 GiB RAM
+instance_type = "t3.small"  # 2 vCPU, 2 GiB RAM
 ```
 
 Suitable for:
-- Monitoring 1-3 small databases
+- Monitoring 1-2 small databases
 - Dev/test environments
 - Proof of concept
 
 ```hcl
-instance_type = "t3.medium"  # 2 vCPU, 8 GiB RAM (default)
+instance_type = "t3.medium"  # 2 vCPU, 4 GiB RAM
 ```
 
 Suitable for:
@@ -271,6 +278,28 @@ Suitable for:
 - Monitoring 10+ databases
 - High-frequency metric collection
 
+## Storage options
+
+### Volume types
+
+```hcl
+# SSD (recommended for production)
+data_volume_type = "gp3"  # General Purpose SSD
+root_volume_type = "gp3"
+
+# HDD (lower cost for testing)
+data_volume_type = "st1"  # Throughput Optimized HDD (min 125 GiB)
+data_volume_type = "sc1"  # Cold HDD (min 125 GiB)
+```
+
+### Volume sizing
+
+```hcl
+data_volume_size = 50   # Small deployments
+data_volume_size = 100  # Medium deployments
+data_volume_size = 500  # Large deployments
+```
+
 ## Custom domain
 
 ```bash
@@ -284,7 +313,7 @@ aws route53 change-resource-record-sets \
         "Name": "monitoring.example.com",
         "Type": "A",
         "TTL": 300,
-        "ResourceRecords": [{"Value": "'"$(terraform output -raw public_ip)"'"}]
+        "ResourceRecords": [{"Value": "'"$(terraform output -raw external_ip)"'"}]
       }
     }]
   }'
@@ -315,3 +344,30 @@ This deployment is appropriate for:
 - Teams with Linux administration skills
 
 For production-critical systems requiring high availability, consider managed services (RDS, ECS Fargate) instead.
+
+## Security considerations
+
+### Credentials in Terraform state
+
+All credentials (passwords, connection strings) are stored in plain text in `terraform.tfstate`. This is acceptable for:
+- Development and testing
+- One-off monitoring deployments
+- When state files are properly secured
+
+For production deployments:
+- Use remote state with encryption (S3 + KMS)
+- Use environment variables: `export TF_VAR_grafana_password=...`
+- Configure monitoring instances manually after deployment (Method 2)
+- Store state in private repositories only
+
+### IMDSv2
+
+EC2 instances are configured to require IMDSv2 (Instance Metadata Service v2) for enhanced security against SSRF attacks.
+
+### Cleanup
+
+After destroying infrastructure, remove local state files:
+```bash
+terraform destroy
+rm -rf .terraform/ terraform.tfstate*
+```