was-cf/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Infrastructure Management

# Initialize OpenTofu (required after cloning)
tofu init

# Plan changes
tofu plan

# Apply changes
tofu apply

# Destroy infrastructure
tofu destroy

Backend Setup (S3 + CloudFront Logs)

# Set up S3 backend and CloudFront logging buckets
./setup-backend.sh

# Migrate state to S3 backend (one-time operation)
echo "yes" | tofu init -migrate-state

Validation and Formatting

# Validate Terraform configuration
tofu validate

# Format Terraform files
tofu fmt

# Check syntax and validate variables
tofu plan -var-file=terraform.tfvars

AWS Resource Verification

# Check CloudFront distribution status
aws cloudfront get-distribution --id E1XR8P4ENGP8RU --query 'Distribution.Status' --output text

# List all CloudFront distributions
aws cloudfront list-distributions --query 'DistributionList.Items[*].[Id,Status,DistributionConfig.Enabled]' --output table

# Check S3 backend state
aws s3 ls s3://aws-cf-terraform-state-535294143817/aws-cf/

# View CloudFront logs
aws s3 ls s3://aws-cf-cloudfront-logs-535294143817/cloudfront-logs/ --recursive

Architecture Overview

Infrastructure Design

This is an AWS CloudFront CDN deployment using OpenTofu (Terraform fork) with the following key architectural decisions:

Primary Components:

• CloudFront Distribution: Main CDN with custom origin server
• WAF v2 Web ACL: Security layer with rate limiting and AWS managed rules
• S3 Backend: Remote state storage with versioning and encryption
• Optional CloudFormation Stack: VPC and networking resources

Critical Configuration Constraints:

• Origin server (origin.servidor.it.com) only supports HTTP, not HTTPS
• Using CloudFront default certificate (not custom ACM certificate)
• Route53 records disabled due to CAA restrictions
• DynamoDB state locking disabled due to permission constraints

File Structure and Responsibilities

Core Infrastructure:

• main.tf - CloudFront distribution, origin configuration, cache behaviors, and optional CloudFormation stack
• security.tf - WAF Web ACL with rate limiting, managed rule sets, and security groups
• variables.tf - All configurable parameters with validation rules
• outputs.tf - CloudFront URLs, distribution IDs, and resource ARNs

Configuration Management:

• backend.tf - S3 remote state configuration (no DynamoDB locking)
• versions.tf - OpenTofu/Terraform and provider version constraints
• acm.tf - ACM certificate configuration (currently disabled)
• terraform.tfvars.example - Variable configuration template

Operational Scripts:

• setup-backend.sh - Automated S3 backend and logging bucket creation with proper permissions

Key Architectural Patterns

Multi-Environment Design:

• Variables for project_name and environment enable multiple deployments
• Resource naming follows ${project_name}-${environment}-${resource} pattern
• Tags applied consistently across all resources

Security-First Approach:

• WAF protection with AWS managed rules and rate limiting
• S3 buckets with encryption, versioning, and public access blocking
• Security groups with principle of least privilege (when VPC enabled)

Cache Strategy:

• Default behavior uses CachingDisabled policy for dynamic content
• API paths (/api/*) specifically configured with caching disabled
• Static content can be optimized by changing cache policy IDs

Conditional Resource Creation:

• Most resources controlled by boolean variables for flexible deployment
• ACM certificates, Route53 records, and CloudFormation stacks can be toggled
• Allows gradual feature enablement as permissions are acquired

Important Configuration Notes

Critical Settings in terraform.tfvars

• origin_protocol_policy = "http-only" - Do not change to HTTPS (causes 504 errors)
• create_acm_certificate = false - Custom certificates fail due to CAA restrictions
• enable_waf = true - WAF is working and provides important security
• create_route53_records = false - DNS management disabled due to CAA restrictions

State Management

• Backend uses S3 without DynamoDB locking (single developer setup)
• State bucket: aws-cf-terraform-state-535294143817
• Logs bucket: aws-cf-cloudfront-logs-535294143817

Security Considerations

• WAF provides protection against common attacks and rate limiting
• Origin-to-CloudFront traffic is unencrypted (HTTP-only constraint)
• SSH access defaults to 0.0.0.0/0 in variables - restrict in production
• CloudFront logs stored in S3 with 90-day lifecycle policy

Performance Optimization

• Price class set to PriceClass_100 (US, Canada, Europe)
• Compression enabled for all content types
• Custom error pages redirect 404/403 to index.html for SPA support

Working vs Disabled Features

Currently Working:

• CloudFront distribution with HTTP origin
• WAF v2 with managed rules
• S3 logging and state storage
• Custom cache behaviors for API paths

Currently Disabled (can be enabled with proper permissions):

• ACM custom certificates (CAA restrictions)
• Route53 DNS management (CAA restrictions)
• CloudFormation VPC stack (permission constraints)
• DynamoDB state locking (permission constraints)