pangea 0.0.45 → 0.0.46

data/lib/pangea/components/global_service_mesh/README.md

@@ -1,438 +0,0 @@
-# Global Service Mesh Component
-
-## Overview
-
-The `global_service_mesh` component creates a multi-region service mesh infrastructure using AWS App Mesh, providing advanced traffic management, security, observability, and resilience patterns for microservices communication across regions. This component enables zero-trust networking, intelligent routing, and comprehensive observability for distributed applications.
-
-## Features
-
-- **Multi-Region Service Mesh**: Seamless service communication across AWS regions
-- **Advanced Traffic Management**: Circuit breakers, retries, timeouts, and canary deployments
-- **Zero-Trust Security**: mTLS, service authentication, and RBAC
-- **Service Discovery**: Cloud Map integration with cross-region discovery
-- **Comprehensive Observability**: X-Ray tracing, CloudWatch metrics, and access logs
-- **Resilience Patterns**: Bulkhead, circuit breaker, outlier detection
-- **Gateway Management**: Ingress and egress gateways with custom domains
-- **Progressive Delivery**: Canary deployments and traffic shifting
-
-## Usage
-
-```ruby
-service_mesh = global_service_mesh(:global_mesh, {
-  mesh_name: "production-mesh",
-  mesh_description: "Global service mesh for production microservices",
-  
-  services: [
-    {
-      name: "user-service",
-      namespace: "production",
-      port: 8080,
-      protocol: "HTTP2",
-      region: "us-east-1",
-      health_check_path: "/api/v1/health",
-      timeout_seconds: 30,
-      retry_attempts: 3,
-      weight: 100
-    },
-    {
-      name: "order-service",
-      namespace: "production",
-      port: 8080,
-      protocol: "GRPC",
-      region: "us-east-1",
-      health_check_path: "/grpc.health.v1.Health/Check",
-      timeout_seconds: 15,
-      weight: 100
-    },
-    {
-      name: "inventory-service",
-      namespace: "production",
-      port: 8080,
-      protocol: "HTTP",
-      region: "eu-west-1",
-      health_check_path: "/health",
-      timeout_seconds: 10,
-      weight: 100
-    },
-    {
-      name: "payment-service",
-      namespace: "production",
-      port: 8443,
-      protocol: "HTTP2",
-      region: "ap-southeast-1",
-      health_check_path: "/status",
-      timeout_seconds: 20,
-      weight: 100
-    }
-  ],
-  
-  regions: ["us-east-1", "eu-west-1", "ap-southeast-1"],
-  
-  virtual_node_config: {
-    service_discovery_type: "CLOUD_MAP",
-    listener_port: 8080,
-    health_check_interval_millis: 30000,
-    health_check_timeout_millis: 5000,
-    healthy_threshold: 2,
-    unhealthy_threshold: 3,
-    backends: ["order-service", "inventory-service", "payment-service"]
-  },
-  
-  traffic_management: {
-    load_balancing_algorithm: "LEAST_REQUEST",
-    circuit_breaker_enabled: true,
-    circuit_breaker_threshold: 5,
-    outlier_detection_enabled: true,
-    outlier_ejection_duration_seconds: 30,
-    max_ejection_percent: 50,
-    canary_deployments_enabled: true
-  },
-  
-  cross_region: {
-    peering_enabled: true,
-    transit_gateway_enabled: true,
-    private_link_enabled: false,
-    inter_region_tls_enabled: true,
-    latency_routing_enabled: true,
-    health_based_routing: true
-  },
-  
-  security: {
-    mtls_enabled: true,
-    tls_mode: "STRICT",
-    service_auth_enabled: true,
-    rbac_enabled: true,
-    encryption_in_transit: true,
-    secrets_manager_integration: true
-  },
-  
-  observability: {
-    xray_enabled: true,
-    cloudwatch_metrics_enabled: true,
-    access_logging_enabled: true,
-    envoy_stats_enabled: true,
-    custom_metrics_enabled: true,
-    distributed_tracing_sampling_rate: 0.1,
-    log_retention_days: 30
-  },
-  
-  service_discovery: {
-    namespace_name: "production.local",
-    namespace_description: "Production service mesh namespace",
-    dns_ttl: 60,
-    health_check_custom_config_enabled: true,
-    routing_policy: "MULTIVALUE",
-    cross_region_discovery: true
-  },
-  
-  resilience: {
-    retry_policy_enabled: true,
-    max_retries: 3,
-    retry_timeout_seconds: 5,
-    bulkhead_enabled: true,
-    max_connections: 100,
-    max_pending_requests: 100,
-    timeout_enabled: true,
-    request_timeout_seconds: 15,
-    chaos_testing_enabled: true
-  },
-  
-  gateway: {
-    ingress_gateway_enabled: true,
-    egress_gateway_enabled: true,
-    gateway_port: 443,
-    gateway_protocol: "HTTPS",
-    custom_domain_enabled: true,
-    waf_enabled: true,
-    rate_limiting_enabled: true
-  },
-  
-  enable_global_load_balancing: true,
-  enable_multi_cluster_routing: true,
-  enable_service_migration: true,
-  enable_progressive_delivery: true
-})
-```
-
-## Configuration Options
-
-### Core Configuration
-
-- `mesh_name` (required): Name for the service mesh
-- `mesh_description`: Description of the mesh purpose
-- `services` (required): Array of service definitions
-- `regions` (required): List of AWS regions for the mesh
-
-### Service Definition
-
-Each service requires:
-
-- `name`: Service name (must be unique)
-- `namespace`: Service namespace
-- `port`: Service port
-- `protocol`: "HTTP", "HTTP2", "GRPC", or "TCP"
-- `region`: AWS region where service runs
-- `cluster_ref`: Optional ECS cluster reference
-- `task_definition_ref`: Optional task definition reference
-- `health_check_path`: Health check endpoint
-- `timeout_seconds`: Request timeout (default: 15)
-- `retry_attempts`: Number of retries (default: 3)
-- `weight`: Traffic weight for routing (default: 100)
-
-### Virtual Node Configuration
-
-- `service_discovery_type`: "DNS", "CLOUD_MAP", or "CLOUD_MAP_WITH_ECS"
-- `listener_port`: Port for the virtual node listener
-- `health_check_interval_millis`: Health check interval (min: 5000)
-- `health_check_timeout_millis`: Health check timeout
-- `healthy_threshold`: Successful checks for healthy status
-- `unhealthy_threshold`: Failed checks for unhealthy status
-- `backends`: List of backend service names
-
-### Traffic Management Configuration
-
-- `load_balancing_algorithm`: "ROUND_ROBIN", "RANDOM", or "LEAST_REQUEST"
-- `circuit_breaker_enabled`: Enable circuit breaker pattern
-- `circuit_breaker_threshold`: Request failures before opening
-- `outlier_detection_enabled`: Enable outlier detection
-- `outlier_ejection_duration_seconds`: Ejection duration
-- `max_ejection_percent`: Maximum percentage of ejected hosts
-- `canary_deployments_enabled`: Enable canary deployments
-
-### Cross-Region Configuration
-
-- `peering_enabled`: Enable VPC peering
-- `transit_gateway_enabled`: Use Transit Gateway
-- `private_link_enabled`: Use PrivateLink
-- `inter_region_tls_enabled`: TLS for cross-region traffic
-- `latency_routing_enabled`: Latency-based routing
-- `health_based_routing`: Health-aware routing
-
-### Security Configuration
-
-- `mtls_enabled`: Enable mutual TLS
-- `tls_mode`: "STRICT", "PERMISSIVE", or "DISABLED"
-- `certificate_authority_arn`: ACM PCA ARN for mTLS
-- `service_auth_enabled`: Service-level authentication
-- `rbac_enabled`: Role-based access control
-- `encryption_in_transit`: Encrypt all traffic
-- `secrets_manager_integration`: Use Secrets Manager
-
-### Observability Configuration
-
-- `xray_enabled`: Enable X-Ray tracing
-- `cloudwatch_metrics_enabled`: CloudWatch metrics
-- `access_logging_enabled`: Access logs
-- `envoy_stats_enabled`: Envoy statistics
-- `custom_metrics_enabled`: Custom metrics
-- `distributed_tracing_sampling_rate`: Trace sampling rate (0-1)
-- `log_retention_days`: Log retention period
-
-### Service Discovery Configuration
-
-- `namespace_name`: Cloud Map namespace name
-- `namespace_description`: Namespace description
-- `dns_ttl`: DNS record TTL
-- `health_check_custom_config_enabled`: Custom health checks
-- `routing_policy`: "MULTIVALUE" or "WEIGHTED"
-- `cross_region_discovery`: Enable cross-region discovery
-
-### Resilience Configuration
-
-- `retry_policy_enabled`: Enable retry policies
-- `max_retries`: Maximum retry attempts (0-10)
-- `retry_timeout_seconds`: Timeout between retries
-- `bulkhead_enabled`: Enable bulkhead pattern
-- `max_connections`: Maximum connections
-- `max_pending_requests`: Maximum pending requests
-- `timeout_enabled`: Enable timeouts
-- `request_timeout_seconds`: Request timeout
-- `chaos_testing_enabled`: Enable chaos experiments
-
-### Gateway Configuration
-
-- `ingress_gateway_enabled`: Create ingress gateway
-- `egress_gateway_enabled`: Create egress gateway
-- `gateway_port`: Gateway port (1-65535)
-- `gateway_protocol`: "HTTP", "HTTPS", "HTTP2", or "GRPC"
-- `custom_domain_enabled`: Use custom domain
-- `waf_enabled`: Enable WAF protection
-- `rate_limiting_enabled`: Enable rate limiting
-
-## Outputs
-
-The component returns:
-
-- `mesh_name`: Name of the service mesh
-- `mesh_arn`: ARN of the App Mesh
-- `service_discovery_namespace`: Cloud Map namespace
-- `regions`: List of mesh regions
-- `services`: Service endpoints and configuration
-- `connectivity_type`: Types of cross-region connectivity
-- `security_features`: Enabled security features
-- `traffic_management_features`: Traffic management capabilities
-- `observability_features`: Monitoring and tracing features
-- `resilience_features`: Resilience patterns enabled
-- `gateway_endpoints`: Gateway DNS names and endpoints
-- `virtual_nodes`: List of virtual nodes
-- `virtual_services`: List of virtual services
-- `virtual_routers`: List of virtual routers
-- `estimated_monthly_cost`: Cost estimate
-
-## Service Communication Patterns
-
-### East-West Traffic (Service-to-Service)
-
-```ruby
-virtual_node_config: {
-  backends: ["order-service", "inventory-service"],
-  service_discovery_type: "CLOUD_MAP"
-}
-```
-
-### North-South Traffic (External to Service)
-
-```ruby
-gateway: {
-  ingress_gateway_enabled: true,
-  gateway_protocol: "HTTPS",
-  custom_domain_enabled: true
-}
-```
-
-### Cross-Region Communication
-
-```ruby
-cross_region: {
-  transit_gateway_enabled: true,
-  inter_region_tls_enabled: true,
-  latency_routing_enabled: true
-}
-```
-
-## Traffic Management Examples
-
-### Canary Deployment
-
-Deploy multiple versions of a service with weighted routing:
-
-```ruby
-services: [
-  { name: "api-v1", weight: 90 },
-  { name: "api-v2", weight: 10 }
-]
-```
-
-### Circuit Breaker
-
-Protect services from cascading failures:
-
-```ruby
-traffic_management: {
-  circuit_breaker_enabled: true,
-  circuit_breaker_threshold: 5,
-  outlier_detection_enabled: true
-}
-```
-
-### Retry Policy
-
-Automatic retries with backoff:
-
-```ruby
-resilience: {
-  retry_policy_enabled: true,
-  max_retries: 3,
-  retry_timeout_seconds: 5
-}
-```
-
-## Security Best Practices
-
-1. **Enable mTLS**: Always use STRICT mode in production
-2. **Service Authentication**: Use IAM roles per service
-3. **Secrets Management**: Store sensitive data in Secrets Manager
-4. **Network Isolation**: Use security groups and NACLs
-5. **Audit Logging**: Enable CloudTrail and access logs
-6. **Certificate Rotation**: Automate certificate lifecycle
-7. **RBAC Policies**: Implement least privilege access
-
-## Observability Guidelines
-
-1. **Distributed Tracing**: Set appropriate sampling rates
-2. **Custom Metrics**: Track business-specific metrics
-3. **Log Aggregation**: Centralize logs for analysis
-4. **Service Map**: Use X-Ray service map for visualization
-5. **Alerting**: Set up proactive alerts
-6. **Dashboards**: Create service-specific dashboards
-7. **Performance Baselines**: Establish normal behavior
-
-## Cost Optimization
-
-### Major Cost Factors
-
-- **App Mesh**: $0.50/virtual node + $0.25/virtual service
-- **Data Processing**: $0.005/GB for mesh traffic
-- **Cloud Map**: $1/namespace + $0.50/service
-- **Transit Gateway**: $0.05/hour + attachment costs
-- **VPC Endpoints**: $7.20/month per endpoint
-- **X-Ray Tracing**: $5/million traces
-- **CloudWatch**: Metrics, logs, and dashboard costs
-
-### Optimization Strategies
-
-1. **Right-size Resources**: Use appropriate instance types
-2. **Traffic Optimization**: Minimize cross-region traffic
-3. **Sampling Rates**: Balance observability with cost
-4. **Log Retention**: Set appropriate retention periods
-5. **Endpoint Consolidation**: Share endpoints where possible
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Service Discovery Failures**
-   - Check Cloud Map registration
-   - Verify DNS resolution
-   - Review security groups
-
-2. **mTLS Errors**
-   - Verify certificate validity
-   - Check TLS mode compatibility
-   - Review trust chains
-
-3. **Circuit Breaker Activation**
-   - Check service health
-   - Review threshold settings
-   - Analyze error patterns
-
-4. **High Latency**
-   - Check cross-region routing
-   - Review retry policies
-   - Analyze network paths
-
-5. **Connection Limits**
-   - Review bulkhead settings
-   - Check connection pools
-   - Monitor resource usage
-
-## Migration Guide
-
-### From Traditional Architecture
-
-1. **Containerize Services**: Package as containers
-2. **Add Sidecars**: Deploy Envoy proxies
-3. **Enable Discovery**: Register with Cloud Map
-4. **Configure Mesh**: Create virtual nodes/services
-5. **Test Communication**: Verify service connectivity
-6. **Enable Features**: Gradually enable advanced features
-7. **Monitor Impact**: Track performance changes
-
-### Progressive Rollout
-
-1. Start with non-critical services
-2. Enable permissive mTLS initially
-3. Gradually tighten security policies
-4. Add traffic management features
-5. Enable full observability
-6. Implement chaos testing