pangea 0.0.45 → 0.0.47

data/lib/pangea/resources/aws_rds_cluster_endpoint/CLAUDE.md

@@ -1,279 +0,0 @@
-# AWS RDS Cluster Endpoint Implementation
-
-## Resource Overview
-
-The `aws_rds_cluster_endpoint` resource implements Aurora cluster custom endpoints with type-safe attributes and advanced validation. This resource provides fine-grained connection routing capabilities for Aurora clusters.
-
-## Implementation Details
-
-### Type Safety and Validation
-
-**Core Validation Rules:**
-- Endpoint identifier must start with a letter and contain only letters, numbers, and hyphens
-- Maximum endpoint identifier length of 63 characters
-- DB instances cannot appear in both static_members and excluded_members
-- WRITER endpoints cannot use static or excluded member configurations (AWS restriction)
-- Validates custom_endpoint_type enum values (READER, WRITER, ANY)
-
-**Dry-Struct Types:**
-- `ExcludedMember` - Validates excluded cluster member configuration
-- `StaticMember` - Validates static cluster member configuration  
-- `RdsClusterEndpointAttributes` - Main attribute struct with comprehensive validation
-
-### Advanced Features
-
-**Member Selection Logic:**
-- Static members: Always include specific DB instances in routing
-- Excluded members: Never route to specific DB instances
-- Default behavior: Use Aurora's automatic member selection
-- Cross-validation prevents conflicting member configurations
-
-**Endpoint Type Behaviors:**
-- READER: Routes only to read replicas, supports member selection
-- WRITER: Routes only to primary, no member selection allowed
-- ANY: Routes to any available member, supports member selection
-
-**Configuration Intelligence:**
-- Automatic validation of endpoint type and member configuration compatibility
-- DNS name generation for connection string construction
-- Configuration summary generation for documentation and monitoring
-
-### Database-Specific Validations
-
-**Aurora Cluster Integration:**
-- Validates cluster identifier format and requirements
-- Provides method for external DB instance validation (validate_db_instances)
-- Generates cluster-aware DNS names for endpoints
-- Integrates with Aurora cluster member management
-
-**Connection Routing Validation:**
-- Ensures endpoint configuration aligns with Aurora's routing capabilities
-- Validates member selection against Aurora cluster constraints
-- Prevents configuration conflicts that would cause AWS API errors
-
-### Production Database Patterns
-
-**High Availability Support:**
-- Failover endpoint configuration with primary exclusion
-- Regional disaster recovery endpoint patterns
-- Load balancing endpoints for multi-AZ deployments
-- Dedicated instance routing for specialized workloads
-
-**Performance Optimization:**
-- Analytics endpoint patterns for heavy read workloads
-- Static member routing for consistent performance
-- Instance type-aware routing configurations
-- Connection pooling optimization endpoints
-
-**Operational Excellence:**
-- Comprehensive configuration summary for monitoring
-- Cost estimation (endpoints are typically free with Aurora)
-- Tag-based organization and management
-- Integration with cluster lifecycle management
-
-## Architecture Integration
-
-### Multi-Tier Applications
-
-```ruby
-# Example: Three-tier application with dedicated endpoints
-template :multi_tier_endpoints do
-  # Web application endpoint - load balanced across all members
-  web_endpoint = aws_rds_cluster_endpoint(:web_tier, {
-    cluster_identifier: cluster_ref,
-    cluster_endpoint_identifier: "web-tier",
-    custom_endpoint_type: "ANY",
-    tags: { Tier: "web", Purpose: "application" }
-  })
-
-  # Analytics endpoint - dedicated read replicas only
-  analytics_endpoint = aws_rds_cluster_endpoint(:analytics, {
-    cluster_identifier: cluster_ref,
-    cluster_endpoint_identifier: "analytics",
-    custom_endpoint_type: "READER",
-    static_members: analytics_instance_refs,
-    tags: { Tier: "analytics", Purpose: "reporting" }
-  })
-
-  # Admin endpoint - writer access for administration
-  admin_endpoint = aws_rds_cluster_endpoint(:admin, {
-    cluster_identifier: cluster_ref,
-    cluster_endpoint_identifier: "admin",
-    custom_endpoint_type: "WRITER",
-    tags: { Tier: "admin", Purpose: "management" }
-  })
-end
-```
-
-### Disaster Recovery Patterns
-
-```ruby
-# Example: Cross-region disaster recovery endpoint
-template :disaster_recovery_endpoints do
-  # Primary region endpoint excluding DR instances
-  primary_endpoint = aws_rds_cluster_endpoint(:primary, {
-    cluster_identifier: global_cluster_ref,
-    cluster_endpoint_identifier: "primary-region",
-    custom_endpoint_type: "READER",
-    excluded_members: dr_instance_refs,
-    tags: { Region: "primary", Purpose: "active" }
-  })
-
-  # DR endpoint for failover scenarios
-  dr_endpoint = aws_rds_cluster_endpoint(:disaster_recovery, {
-    cluster_identifier: global_cluster_ref,
-    cluster_endpoint_identifier: "dr-region",
-    custom_endpoint_type: "READER",
-    static_members: dr_instance_refs,
-    tags: { Region: "secondary", Purpose: "disaster-recovery" }
-  })
-end
-```
-
-## Testing and Validation
-
-### Type Safety Testing
-
-The implementation provides comprehensive type safety through:
-- Dry-struct validation for all input parameters
-- Custom validation logic for AWS-specific constraints  
-- Runtime type checking with meaningful error messages
-- Integration validation with cluster and instance configurations
-
-### Configuration Validation
-
-**Pre-deployment Validation:**
-- Member selection conflict detection
-- Endpoint type and configuration compatibility checking
-- Cluster identifier and naming convention validation
-- Tag validation for organizational compliance
-
-**Runtime Validation:**
-- DB instance existence validation (when cluster data available)
-- Member selection effectiveness validation
-- Performance impact assessment for endpoint configurations
-
-### Error Handling
-
-**Common Configuration Errors:**
-- Invalid endpoint type and member selection combinations
-- DB instance references that don't exist in the cluster
-- Endpoint identifier naming violations
-- Tag format and compliance issues
-
-**Error Recovery:**
-- Clear error messages with specific validation failures
-- Suggestions for configuration fixes
-- Reference to AWS documentation for complex constraints
-- Integration with Pangea's error reporting system
-
-## Performance Considerations
-
-### Connection Routing Optimization
-
-**Endpoint Selection Strategy:**
-- Use READER endpoints for read-heavy workloads
-- Use WRITER endpoints sparingly for admin operations
-- Use ANY endpoints for balanced mixed workloads
-- Use static members for consistent performance requirements
-
-**Instance Distribution:**
-- Balance static member selection across availability zones
-- Consider instance types when creating static member groups
-- Exclude overloaded instances during peak periods
-- Rotate endpoint usage to prevent hotspots
-
-### Monitoring and Observability
-
-**Endpoint Metrics:**
-- Connection count per endpoint
-- Query performance by endpoint type
-- Instance utilization within endpoint groups
-- Failover behavior and recovery times
-
-**Configuration Tracking:**
-- Endpoint lifecycle management
-- Member selection changes over time
-- Performance impact of routing decisions
-- Cost allocation by endpoint usage
-
-## Security Considerations
-
-### Access Control
-
-**Network Security:**
-- Custom endpoints inherit cluster security group settings
-- Additional security groups can be applied at the cluster level
-- VPC and subnet restrictions apply to all endpoints
-- SSL/TLS settings inherited from cluster configuration
-
-**Authentication and Authorization:**
-- Endpoint-specific user management not supported (cluster-level only)
-- IAM database authentication applies to all endpoints
-- Connection string security for different endpoint types
-- Audit logging includes endpoint-specific connection details
-
-### Compliance Requirements
-
-**Data Protection:**
-- Endpoints inherit cluster encryption settings
-- Audit trail includes endpoint-specific access patterns
-- Compliance reporting includes endpoint usage data
-- Data residency requirements apply to endpoint routing
-
-## Common Pitfalls and Solutions
-
-### Configuration Mistakes
-
-**Pitfall: WRITER endpoints with member selection**
-```ruby
-# INCORRECT - will cause validation error
-aws_rds_cluster_endpoint(:bad_writer, {
-  custom_endpoint_type: "WRITER",
-  static_members: [{ db_instance_identifier: "some-instance" }]  # Not allowed
-})
-
-# CORRECT - WRITER endpoints use default routing
-aws_rds_cluster_endpoint(:good_writer, {
-  custom_endpoint_type: "WRITER"
-})
-```
-
-**Pitfall: Conflicting member configurations**
-```ruby
-# INCORRECT - same instance in both lists
-aws_rds_cluster_endpoint(:conflicted, {
-  custom_endpoint_type: "READER",
-  static_members: [{ db_instance_identifier: "instance-1" }],
-  excluded_members: [{ db_instance_identifier: "instance-1" }]  # Conflict
-})
-```
-
-**Pitfall: Invalid endpoint identifiers**
-```ruby
-# INCORRECT - starts with number
-aws_rds_cluster_endpoint(:bad_name, {
-  cluster_endpoint_identifier: "1-endpoint"  # Invalid
-})
-
-# CORRECT - starts with letter
-aws_rds_cluster_endpoint(:good_name, {
-  cluster_endpoint_identifier: "endpoint-1"
-})
-```
-
-### Performance Issues
-
-**Solution: Instance Type Awareness**
-- Match endpoint routing to instance capabilities
-- Use high-memory instances for analytics endpoints
-- Use general-purpose instances for balanced workloads
-- Consider network performance for distributed applications
-
-**Solution: Connection Pool Management**
-- Configure application connection pools per endpoint
-- Monitor connection distribution across endpoints
-- Implement connection retry logic for endpoint failovers
-- Use appropriate connection pool sizes for endpoint types
-
-This implementation provides a robust, type-safe interface for Aurora cluster endpoints with comprehensive validation, clear error handling, and production-ready patterns for high-availability database architectures.

data/lib/pangea/resources/aws_rds_cluster_instance/CLAUDE.md

@@ -1,378 +0,0 @@
-# AWS RDS Cluster Instance Implementation
-
-## Resource Overview
-
-The `aws_rds_cluster_instance` resource creates and manages AWS Aurora RDS Cluster Instances, which serve as the compute nodes within Aurora clusters. Each instance handles database operations and can be configured as writers or readers with specific performance characteristics and failover priorities.
-
-## Implementation Architecture
-
-### Type Safety Structure
-```
-RdsClusterInstanceAttributes (Dry::Struct)
-├── identifier: String (optional)
-├── identifier_prefix: String (optional)
-├── cluster_identifier: String (required)
-├── instance_class: String (enum of Aurora instance types, required)
-├── engine: String (optional, inherited from cluster)
-├── engine_version: String (optional, inherited from cluster)
-├── availability_zone: String (optional)
-├── db_parameter_group_name: String (optional)
-├── publicly_accessible: Bool (default: false)
-├── monitoring_interval: Integer (0-60, default: 0)
-├── monitoring_role_arn: String (optional)
-├── performance_insights_enabled: Bool (default: false)
-├── performance_insights_kms_key_id: String (optional)
-├── performance_insights_retention_period: Integer (7-731, default: 7)
-├── preferred_backup_window: String (optional)
-├── preferred_maintenance_window: String (optional)
-├── auto_minor_version_upgrade: Bool (default: true)
-├── apply_immediately: Bool (default: false)
-├── copy_tags_to_snapshot: Bool (default: true)
-├── ca_cert_identifier: String (optional)
-├── promotion_tier: Integer (0-15, default: 1)
-└── tags: Hash[String, String] (default: {})
-```
-
-### Core Validations
-
-1. **Identifier Validation**
-   - Cannot specify both identifier and identifier_prefix
-   - AWS will generate identifier if neither provided
-
-2. **Instance Class Validation**
-   - Comprehensive enum of Aurora-supported instance types
-   - Includes burstable (t3, t4g), memory-optimized (r5, r6g, r6i, x2g)
-   - Special handling for "serverless" instance class
-
-3. **Promotion Tier Validation**
-   - Must be between 0-15 (0 = highest priority for writer role)
-   - Determines failover order and instance role
-
-4. **Monitoring Configuration Validation**
-   - monitoring_role_arn required when monitoring_interval > 0
-   - Performance Insights retention period must be >= 7 days when enabled
-   - Serverless instances don't support enhanced monitoring
-
-5. **Performance Insights Validation**
-   - Retention period validation (7-731 days)
-   - KMS key validation when encryption is enabled
-   - Feature availability by instance type
-
-6. **Serverless Instance Validation**
-   - Enhanced monitoring not supported
-   - Different constraint validation for serverless vs. provisioned
-
-### Resource Function Signature
-```ruby
-def aws_rds_cluster_instance(name, attributes = {})
-  # Returns ResourceReference with:
-  # - Comprehensive Terraform outputs
-  # - Performance characteristics analysis  
-  # - Role and tier information
-  # - Cost and scaling insights
-end
-```
-
-## Terraform Resource Mapping
-
-### Generated Terraform JSON Structure
-```json
-{
-  "resource": {
-    "aws_rds_cluster_instance": {
-      "resource_name": {
-        "identifier": "aurora-instance-name",
-        "cluster_identifier": "aurora-cluster-name",
-        "instance_class": "db.r5.large",
-        "promotion_tier": 0,
-        "performance_insights_enabled": true,
-        "performance_insights_retention_period": 93,
-        "monitoring_interval": 60,
-        "monitoring_role_arn": "arn:aws:iam::account:role/rds-monitoring-role",
-        "preferred_maintenance_window": "sun:04:00-sun:05:00",
-        "tags": {
-          "Role": "writer",
-          "Environment": "production"
-        }
-      }
-    }
-  }
-}
-```
-
-### Available Outputs
-Comprehensive output coverage including:
-- Instance identifiers and ARN
-- Cluster association information
-- Network endpoint details
-- Performance and monitoring configuration
-- Instance characteristics and status
-- Database parameter configuration
-
-## Design Patterns
-
-### Instance Classification System
-```ruby
-def instance_family
-  case instance_class
-  when /^db\.t3/ then "t3"
-  when /^db\.t4g/ then "t4g"
-  when /^db\.r5/ then "r5"
-  when /^db\.r6g/ then "r6g"
-  when /^db\.r6i/ then "r6i"
-  when /^db\.x2g/ then "x2g"
-  when "serverless" then "serverless"
-  end
-end
-```
-
-### Role-Based Configuration
-```ruby
-def role_description
-  case promotion_tier
-  when 0 then "Primary writer instance"
-  when 1 then "Primary failover target"
-  else "Reader instance (tier #{promotion_tier})"
-  end
-end
-
-def can_be_writer?
-  promotion_tier == 0
-end
-```
-
-### Performance Characteristics Analysis
-```ruby
-def performance_characteristics
-  {
-    vcpus: estimated_vcpus,
-    memory_gb: estimated_memory_gb,
-    instance_family: instance_family,
-    is_burstable: is_burstable?,
-    is_memory_optimized: is_memory_optimized?,
-    is_graviton: is_graviton?
-  }
-end
-```
-
-### Cost Estimation System
-```ruby
-def estimated_monthly_cost
-  return "Variable based on Aurora Capacity Units" if is_serverless?
-  
-  hourly_rate = calculate_hourly_rate(instance_class)
-  monthly_cost = hourly_rate * 730
-  "~$#{monthly_cost.round(2)}/month"
-end
-```
-
-### Pre-configured Instance Templates
-```ruby
-module AuroraInstanceConfigs
-  def self.production_writer
-    # Returns production-optimized writer configuration
-  end
-  
-  def self.graviton_writer
-    # Returns Graviton2-based cost-optimized configuration
-  end
-  
-  def self.multi_az_deployment
-    # Returns multi-AZ deployment pattern
-  end
-end
-```
-
-## Integration Patterns
-
-### Cluster Relationship Management
-- Required cluster_identifier for cluster association
-- Engine and version inheritance from parent cluster
-- Coordinated backup and maintenance window scheduling
-- Automatic cluster membership registration
-
-### Parameter Group Integration
-- Instance-level parameter groups through db_parameter_group_name
-- Parameter validation against engine family
-- Performance tuning through parameter optimization
-- Engine-specific parameter support
-
-### Monitoring Integration
-- CloudWatch enhanced monitoring configuration
-- Performance Insights with configurable retention
-- Custom metrics and alarm integration
-- Role-based monitoring strategies
-
-### Network and Security Integration
-- VPC placement through cluster subnet group
-- Security group inheritance from cluster
-- Availability zone distribution for high availability
-- Cross-AZ failover coordination
-
-## Operational Considerations
-
-### High Availability Architecture
-- **Promotion Tiers**: 0-15 priority system for failover order
-- **Multi-AZ Deployment**: Instance distribution across availability zones
-- **Failover Management**: Automatic promotion based on tier hierarchy
-- **Reader Endpoint**: Load balancing across reader instances
-
-### Instance Role Management
-- **Writer Instances**: Tier 0 for primary write operations
-- **Primary Failover**: Tier 1 for immediate failover capability
-- **Reader Instances**: Tier 2+ for read scaling and secondary failover
-- **Role Flexibility**: Dynamic role assignment through promotion
-
-### Performance Optimization
-- **Instance Sizing**: Memory and CPU optimization by workload
-- **Burstable Performance**: T3/T4g for variable workloads
-- **Memory Optimized**: R5/R6 series for consistent high performance
-- **Graviton2 Processors**: ARM-based cost optimization
-
-### Cost Management
-- **Instance Type Selection**: Balanced performance vs. cost
-- **Graviton2 Adoption**: ~20% cost savings with ARM architecture
-- **Right-sizing**: Monitoring-driven instance optimization
-- **Auto-scaling**: Reader instance scaling based on load
-
-## Error Handling
-
-### Validation Errors
-```ruby
-# Conflicting identifier specifications
-raise Dry::Struct::Error, "Cannot specify both 'identifier' and 'identifier_prefix'"
-
-# Monitoring configuration errors
-raise Dry::Struct::Error, "monitoring_role_arn is required when monitoring_interval > 0"
-
-# Performance Insights configuration errors  
-raise Dry::Struct::Error, "performance_insights_retention_period must be at least 7 days when Performance Insights is enabled"
-
-# Promotion tier validation
-raise Dry::Struct::Error, "promotion_tier must be between 0 and 15"
-
-# Serverless limitations
-raise Dry::Struct::Error, "Enhanced monitoring is not supported for serverless instances"
-```
-
-### Runtime Validation
-- AWS service-level validation for instance configuration
-- Cluster membership validation
-- Instance class availability by region
-- Parameter group compatibility validation
-
-## Testing Considerations
-
-### Unit Testing
-- Dry::Struct validation for all attribute combinations
-- Instance classification and role determination testing
-- Performance characteristics calculation testing
-- Cost estimation accuracy testing
-
-### Integration Testing
-- Cluster association and dependency testing
-- Cross-AZ deployment validation
-- Monitoring configuration testing
-- Parameter group integration testing
-
-### Performance Testing
-- Instance performance validation
-- Failover testing and timing
-- Load balancing effectiveness
-- Monitoring data accuracy
-
-## Performance Characteristics
-
-### Instance Provisioning
-- Fast instance creation within existing cluster
-- Automatic cluster membership registration
-- Parameter group application
-- Monitoring configuration activation
-
-### Scaling Capabilities
-- **Vertical Scaling**: Instance class modification
-- **Horizontal Scaling**: Reader instance addition/removal
-- **Cross-AZ Scaling**: Multi-region read replica support
-- **Automated Scaling**: Auto Scaling Group integration
-
-### Monitoring Performance
-- Real-time performance metrics through CloudWatch
-- Performance Insights for query-level analysis
-- Enhanced monitoring for OS-level metrics
-- Custom metrics for application-specific monitoring
-
-## Advanced Features
-
-### Graviton2 Processor Support
-```ruby
-def is_graviton?
-  instance_class.include?("t4g") || 
-  instance_class.include?("r6g") || 
-  instance_class.include?("x2g")
-end
-```
-
-### Performance Insights Integration
-```ruby
-def has_performance_insights?
-  performance_insights_enabled
-end
-
-def supports_performance_insights?
-  !is_serverless?
-end
-```
-
-### Multi-tier Failover Architecture
-```ruby
-def is_likely_reader?
-  promotion_tier > 0
-end
-
-def failover_priority
-  15 - promotion_tier  # Higher number = higher priority
-end
-```
-
-### Cost Optimization Features
-```ruby
-def estimated_vcpus
-  # Detailed vCPU calculation by instance class
-end
-
-def estimated_memory_gb  
-  # Detailed memory calculation by instance class
-end
-```
-
-## Future Extensibility
-
-### Enhanced Instance Management
-- Intelligent instance sizing recommendations
-- Automated right-sizing based on performance metrics
-- Predictive scaling for reader instances
-- Cross-region read replica automation
-
-### Advanced Monitoring
-- Machine learning-based performance insights
-- Automated anomaly detection
-- Predictive maintenance scheduling
-- Cost optimization recommendations
-
-### Operational Enhancements
-- Blue/green deployment support for instances
-- Automated failover testing
-- Instance lifecycle management
-- Configuration drift detection
-
-### Performance Optimization
-- Query-level performance analysis
-- Automatic parameter tuning
-- Workload-specific instance recommendations
-- Multi-dimensional cost optimization
-
-### Security Enhancements
-- Instance-level encryption key management
-- Fine-grained access control
-- Security compliance monitoring
-- Audit trail automation