pangea 0.0.47 → 0.0.48

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

@@ -1,321 +0,0 @@
-# Microservice Deployment Component
-
-Production-ready ECS microservice deployment with service discovery, circuit breakers, and distributed tracing.
-
-## Overview
-
-The `microservice_deployment` component creates a complete microservice deployment on AWS ECS with enterprise-grade features including:
-
-- **ECS Fargate Service**: Serverless container execution with automatic scaling
-- **Service Discovery**: AWS Cloud Map integration for service-to-service communication
-- **Circuit Breakers**: Deployment circuit breakers for automatic rollback on failures
-- **Distributed Tracing**: X-Ray, Jaeger, or Zipkin integration for observability
-- **Auto-scaling**: CPU and memory-based automatic scaling policies
-- **Health Checks**: Comprehensive health monitoring with CloudWatch alarms
-- **Blue-Green Deployments**: Support for zero-downtime deployments
-
-## Usage
-
-### Basic Microservice
-
-```ruby
-# Create a simple microservice deployment
-service = microservice_deployment(:user_service, {
-  cluster_ref: ecs_cluster_ref,
-  task_definition_family: "user-service",
-  container_definitions: [{
-    name: "user-api",
-    image: "myapp/user-service:latest",
-    cpu: 512,
-    memory: 1024,
-    port_mappings: [{
-      containerPort: 8080,
-      protocol: "tcp"
-    }],
-    environment: [
-      { name: "NODE_ENV", value: "production" },
-      { name: "PORT", value: "8080" }
-    ]
-  }],
-  vpc_ref: vpc_ref,
-  subnet_refs: [private_subnet_a_ref, private_subnet_b_ref],
-  security_group_refs: [service_sg_ref],
-  target_group_refs: [user_service_tg_ref]
-})
-```
-
-### Microservice with Service Discovery
-
-```ruby
-# Create a microservice with service discovery for internal communication
-order_service = microservice_deployment(:order_service, {
-  cluster_ref: ecs_cluster_ref,
-  task_definition_family: "order-service",
-  container_definitions: [{
-    name: "order-api",
-    image: "myapp/order-service:latest",
-    cpu: 1024,
-    memory: 2048,
-    port_mappings: [{
-      containerPort: 3000,
-      protocol: "tcp"
-    }],
-    environment: [
-      { name: "USER_SERVICE_ENDPOINT", value: "user-service.local:8080" }
-    ],
-    health_check: {
-      command: ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"],
-      interval: 30,
-      timeout: 5,
-      retries: 3,
-      startPeriod: 60
-    }
-  }],
-  vpc_ref: vpc_ref,
-  subnet_refs: [private_subnet_a_ref, private_subnet_b_ref],
-  security_group_refs: [service_sg_ref],
-  
-  # Service discovery configuration
-  service_discovery: {
-    namespace_id: service_discovery_namespace_ref.id,
-    service_name: "order-service",
-    dns_config: {
-      routing_policy: "MULTIVALUE",
-      dns_records: [{
-        type: "A",
-        ttl: 60
-      }]
-    }
-  },
-  
-  # Enable auto-scaling
-  auto_scaling: {
-    enabled: true,
-    min_tasks: 2,
-    max_tasks: 10,
-    target_cpu: 70.0,
-    target_memory: 80.0
-  }
-})
-```
-
-### Event-Driven Microservice with Tracing
-
-```ruby
-# Create an event-driven microservice with distributed tracing
-payment_service = microservice_deployment(:payment_service, {
-  cluster_ref: ecs_cluster_ref,
-  task_definition_family: "payment-service",
-  task_cpu: "1024",
-  task_memory: "2048",
-  
-  container_definitions: [{
-    name: "payment-processor",
-    image: "myapp/payment-service:latest",
-    cpu: 896,  # Leave room for X-Ray sidecar
-    memory: 1792,
-    port_mappings: [{
-      containerPort: 8000,
-      protocol: "tcp"
-    }],
-    environment: [
-      { name: "STRIPE_WEBHOOK_ENDPOINT", value: "/webhooks/stripe" },
-      { name: "SQS_QUEUE_URL", value: payment_queue_ref.id }
-    ],
-    secrets: [
-      { name: "STRIPE_API_KEY", valueFrom: stripe_secret_ref.arn },
-      { name: "DATABASE_URL", valueFrom: db_url_secret_ref.arn }
-    ]
-  }],
-  
-  vpc_ref: vpc_ref,
-  subnet_refs: [private_subnet_a_ref, private_subnet_b_ref],
-  security_group_refs: [service_sg_ref],
-  target_group_refs: [payment_service_tg_ref],
-  
-  # Enable distributed tracing
-  tracing: {
-    enabled: true,
-    sampling_rate: 0.1,  # Sample 10% of requests
-    x_ray: true
-  },
-  
-  # Circuit breaker configuration
-  circuit_breaker: {
-    enabled: true,
-    threshold: 5,
-    timeout: 60,
-    rollback: true
-  },
-  
-  # Health check configuration
-  health_check: {
-    path: "/health",
-    interval: 30,
-    timeout: 5,
-    healthy_threshold: 2,
-    unhealthy_threshold: 3,
-    matcher: "200"
-  }
-})
-```
-
-### Multi-Container Microservice
-
-```ruby
-# Create a microservice with multiple containers (main app + sidecar)
-analytics_service = microservice_deployment(:analytics_service, {
-  cluster_ref: ecs_cluster_ref,
-  task_definition_family: "analytics-service",
-  task_cpu: "2048",
-  task_memory: "4096",
-  
-  container_definitions: [
-    {
-      name: "analytics-api",
-      image: "myapp/analytics-api:latest",
-      cpu: 1536,
-      memory: 3072,
-      essential: true,
-      port_mappings: [{
-        containerPort: 5000,
-        protocol: "tcp"
-      }],
-      depends_on: [{
-        containerName: "envoy-proxy",
-        condition: "HEALTHY"
-      }]
-    },
-    {
-      name: "envoy-proxy",
-      image: "envoyproxy/envoy:latest",
-      cpu: 512,
-      memory: 1024,
-      essential: true,
-      port_mappings: [
-        { containerPort: 9901, protocol: "tcp" },  # Admin
-        { containerPort: 15000, protocol: "tcp" }  # Ingress
-      ],
-      health_check: {
-        command: ["CMD-SHELL", "curl -f http://localhost:9901/clusters || exit 1"],
-        interval: 30,
-        timeout: 5,
-        retries: 3
-      }
-    }
-  ],
-  
-  vpc_ref: vpc_ref,
-  subnet_refs: [private_subnet_a_ref, private_subnet_b_ref],
-  security_group_refs: [service_sg_ref],
-  container_name: "envoy-proxy",  # Route traffic through Envoy
-  container_port: 15000,
-  target_group_refs: [analytics_service_tg_ref],
-  
-  # Enable blue-green deployment
-  enable_blue_green: true,
-  deployment_minimum_healthy_percent: 100,
-  deployment_maximum_percent: 200
-})
-```
-
-## Inputs
-
-### Required Inputs
-
-- `cluster_ref`: Reference to the ECS cluster for deployment
-- `task_definition_family`: Name for the task definition family
-- `container_definitions`: Array of container configurations
-- `vpc_ref`: Reference to the VPC
-- `subnet_refs`: Array of subnet references (minimum 2 for HA)
-
-### Optional Inputs
-
-- `security_group_refs`: Security groups for the service (default: [])
-- `assign_public_ip`: Assign public IPs to tasks (default: false)
-- `desired_count`: Number of tasks to run (default: 2)
-- `launch_type`: ECS launch type - FARGATE or EC2 (default: "FARGATE")
-- `task_cpu`: Task CPU units (default: "256")
-- `task_memory`: Task memory in MB (default: "512")
-- `target_group_refs`: Target groups for load balancing (default: [])
-- `service_discovery`: Service discovery configuration (optional)
-- `circuit_breaker`: Circuit breaker configuration
-- `auto_scaling`: Auto-scaling configuration
-- `tracing`: Distributed tracing configuration
-- `health_check`: Health check configuration
-- `enable_blue_green`: Enable blue-green deployments (default: false)
-- `log_retention_days`: CloudWatch log retention (default: 7)
-
-### Container Definition Structure
-
-```ruby
-{
-  name: "container-name",
-  image: "docker-image:tag",
-  cpu: 256,                    # CPU units
-  memory: 512,                 # Memory in MB
-  essential: true,             # Is this container essential?
-  port_mappings: [...],        # Port mappings
-  environment: [...],          # Environment variables
-  secrets: [...],              # Secrets from Parameter Store/Secrets Manager
-  health_check: {...},         # Container health check
-  depends_on: [...],           # Container dependencies
-  log_configuration: {...}     # Custom logging config (optional)
-}
-```
-
-## Outputs
-
-The component returns a `ComponentReference` with:
-
-- `service_name`: Name of the ECS service
-- `service_arn`: ARN of the ECS service
-- `task_definition_arn`: ARN of the task definition
-- `cluster_name`: Name of the ECS cluster
-- `service_discovery_endpoint`: Service discovery endpoint (if configured)
-- `resilience_features`: List of enabled resilience features
-- `monitoring_features`: List of enabled monitoring features
-- `estimated_monthly_cost`: Estimated AWS costs
-
-## Resources Created
-
-- `aws_cloudwatch_log_group`: CloudWatch log group for container logs
-- `aws_cloudwatch_log_stream`: Log streams for each container
-- `aws_ecs_task_definition`: Task definition with containers
-- `aws_ecs_service`: ECS service with deployment configuration
-- `aws_service_discovery_service`: Service discovery registration (optional)
-- `aws_appautoscaling_target`: Auto-scaling target (optional)
-- `aws_appautoscaling_policy`: CPU and memory scaling policies (optional)
-- `aws_cloudwatch_metric_alarm`: Monitoring alarms
-- `aws_xray_sampling_rule`: X-Ray sampling configuration (optional)
-
-## Best Practices
-
-1. **Container Configuration**
-   - Use specific image tags, not `latest`
-   - Set appropriate CPU and memory limits
-   - Define health checks for all containers
-   - Use secrets for sensitive configuration
-
-2. **Networking**
-   - Deploy across multiple availability zones
-   - Use private subnets for services
-   - Configure security groups with least privilege
-
-3. **Resilience**
-   - Enable circuit breakers for automatic rollback
-   - Configure appropriate health check grace periods
-   - Set deployment percentages for rolling updates
-   - Use auto-scaling for dynamic workloads
-
-4. **Observability**
-   - Enable distributed tracing for debugging
-   - Set appropriate log retention periods
-   - Configure CloudWatch alarms for key metrics
-   - Use structured logging in containers
-
-5. **Cost Optimization**
-   - Right-size CPU and memory allocations
-   - Use Fargate Spot for non-critical workloads
-   - Configure auto-scaling to match demand
-   - Review and adjust log retention policies

data/lib/pangea/components/microservice_deployment/component/autoscaling.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2025 The Pangea Authors. Licensed under Apache 2.0.
-
-module Pangea
-  module Components
-    module MicroserviceDeploymentComponent
-      module Autoscaling
-        def configure_autoscaling(name, component_attrs, service_ref)
-          return {} unless component_attrs.auto_scaling.enabled
-
-          scalable_target_ref = create_scalable_target(name, component_attrs, service_ref)
-          cpu_policy_ref = create_cpu_scaling_policy(name, component_attrs, scalable_target_ref)
-          memory_policy_ref = create_memory_scaling_policy(name, component_attrs, scalable_target_ref)
-
-          {
-            scalable_target: scalable_target_ref,
-            cpu_scaling_policy: cpu_policy_ref,
-            memory_scaling_policy: memory_policy_ref
-          }
-        end
-
-        private
-
-        def create_scalable_target(name, component_attrs, service_ref)
-          aws_appautoscaling_target(component_resource_name(name, :scalable_target), {
-            service_namespace: 'ecs',
-            resource_id: "service/#{component_attrs.cluster_ref.name}/#{service_ref.name}",
-            scalable_dimension: 'ecs:service:DesiredCount',
-            min_capacity: component_attrs.auto_scaling.min_tasks,
-            max_capacity: component_attrs.auto_scaling.max_tasks
-          })
-        end
-
-        def create_cpu_scaling_policy(name, component_attrs, scalable_target_ref)
-          aws_appautoscaling_policy(component_resource_name(name, :cpu_scaling_policy), {
-            name: "#{name}-cpu-scaling", service_namespace: 'ecs',
-            resource_id: scalable_target_ref.resource_id,
-            scalable_dimension: scalable_target_ref.scalable_dimension,
-            policy_type: 'TargetTrackingScaling',
-            target_tracking_scaling_policy_configuration: {
-              target_value: component_attrs.auto_scaling.target_cpu,
-              predefined_metric_specification: { predefined_metric_type: 'ECSServiceAverageCPUUtilization' },
-              scale_out_cooldown: component_attrs.auto_scaling.scale_out_cooldown,
-              scale_in_cooldown: component_attrs.auto_scaling.scale_in_cooldown
-            }
-          })
-        end
-
-        def create_memory_scaling_policy(name, component_attrs, scalable_target_ref)
-          aws_appautoscaling_policy(component_resource_name(name, :memory_scaling_policy), {
-            name: "#{name}-memory-scaling", service_namespace: 'ecs',
-            resource_id: scalable_target_ref.resource_id,
-            scalable_dimension: scalable_target_ref.scalable_dimension,
-            policy_type: 'TargetTrackingScaling',
-            target_tracking_scaling_policy_configuration: {
-              target_value: component_attrs.auto_scaling.target_memory,
-              predefined_metric_specification: { predefined_metric_type: 'ECSServiceAverageMemoryUtilization' },
-              scale_out_cooldown: component_attrs.auto_scaling.scale_out_cooldown,
-              scale_in_cooldown: component_attrs.auto_scaling.scale_in_cooldown
-            }
-          })
-        end
-      end
-    end
-  end
-end

data/lib/pangea/components/microservice_deployment/component/container_definitions.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2025 The Pangea Authors. Licensed under Apache 2.0.
-
-module Pangea
-  module Components
-    module MicroserviceDeploymentComponent
-      module ContainerDefinitions
-        def build_container_definitions(component_attrs, log_group_ref)
-          container_defs = component_attrs.container_definitions.map do |container|
-            build_container_definition(container, component_attrs, log_group_ref)
-          end
-          add_xray_sidecar(container_defs, component_attrs, log_group_ref) if xray_enabled?(component_attrs)
-          container_defs
-        end
-
-        private
-
-        def build_container_definition(container, component_attrs, log_group_ref)
-          definition = {
-            name: container.name, image: container.image, cpu: container.cpu, memory: container.memory,
-            essential: container.essential, portMappings: container.port_mappings, environment: container.environment,
-            secrets: container.secrets, healthCheck: empty_to_nil(container.health_check),
-            dependsOn: empty_to_nil(container.depends_on), ulimits: empty_to_nil(container.ulimits),
-            mountPoints: empty_to_nil(container.mount_points), volumesFrom: empty_to_nil(container.volume_from),
-            logConfiguration: build_log_configuration(container, component_attrs, log_group_ref)
-          }.compact
-          add_xray_env(definition, component_attrs, container)
-          definition
-        end
-
-        def build_log_configuration(container, component_attrs, log_group_ref)
-          return container.log_configuration unless container.log_configuration.empty?
-          {
-            logDriver: 'awslogs',
-            options: {
-              'awslogs-group' => log_group_ref.name, 'awslogs-region' => '${AWS::Region}',
-              'awslogs-stream-prefix' => "#{component_attrs.log_stream_prefix}/#{container.name}"
-            }
-          }
-        end
-
-        def add_xray_env(definition, component_attrs, container)
-          return unless xray_enabled?(component_attrs) && container.essential
-          definition[:environment] ||= []
-          definition[:environment] << { name: 'AWS_XRAY_DAEMON_ADDRESS', value: 'localhost:2000' }
-        end
-
-        def add_xray_sidecar(container_defs, component_attrs, log_group_ref)
-          container_defs << {
-            name: 'xray-daemon', image: 'public.ecr.aws/xray/aws-xray-daemon:latest', cpu: 32, memory: 256,
-            essential: false, portMappings: [{ containerPort: 2000, protocol: 'udp' }],
-            logConfiguration: {
-              logDriver: 'awslogs',
-              options: {
-                'awslogs-group' => log_group_ref.name, 'awslogs-region' => '${AWS::Region}',
-                'awslogs-stream-prefix' => "#{component_attrs.log_stream_prefix}/xray"
-              }
-            }
-          }
-        end
-
-        def xray_enabled?(component_attrs)
-          component_attrs.tracing.enabled && component_attrs.tracing.x_ray
-        end
-
-        def empty_to_nil(value)
-          value.empty? ? nil : value
-        end
-      end
-    end
-  end
-end

data/lib/pangea/components/microservice_deployment/component/logging.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2025 The Pangea Authors. Licensed under Apache 2.0.
-
-module Pangea
-  module Components
-    module MicroserviceDeploymentComponent
-      module Logging
-        def create_log_group(name, component_attrs, component_tag_set)
-          log_group_name = component_attrs.log_group_name || "/ecs/#{component_attrs.task_definition_family}"
-          aws_cloudwatch_log_group(component_resource_name(name, :log_group), {
-            name: log_group_name, retention_in_days: component_attrs.log_retention_days, tags: component_tag_set
-          })
-        end
-
-        def create_log_streams(name, component_attrs, log_group_ref)
-          component_attrs.container_definitions.each_with_object({}) do |container, log_streams|
-            log_stream_ref = aws_cloudwatch_log_stream(
-              component_resource_name(name, :log_stream, container.name.to_sym),
-              { name: "#{component_attrs.log_stream_prefix}/#{container.name}", log_group_name: log_group_ref.name }
-            )
-            log_streams[container.name.to_sym] = log_stream_ref
-          end
-        end
-      end
-    end
-  end
-end

data/lib/pangea/components/microservice_deployment/component/monitoring.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2025 The Pangea Authors. Licensed under Apache 2.0.
-
-module Pangea
-  module Components
-    module MicroserviceDeploymentComponent
-      module Monitoring
-        def create_cloudwatch_alarms(name, component_attrs, service_ref, component_tag_set)
-          {
-            cpu_high: create_cpu_alarm(name, component_attrs, service_ref, component_tag_set),
-            memory_high: create_memory_alarm(name, component_attrs, service_ref, component_tag_set),
-            task_count_low: create_task_count_alarm(name, component_attrs, service_ref, component_tag_set)
-          }
-        end
-
-        def create_xray_sampling_rule(name, component_attrs, component_tag_set)
-          return nil unless component_attrs.tracing.enabled && component_attrs.tracing.x_ray
-          aws_xray_sampling_rule(component_resource_name(name, :xray_sampling_rule), {
-            rule_name: "#{name}-sampling", priority: 9000, version: 1, reservoir_size: 1,
-            fixed_rate: component_attrs.tracing.sampling_rate, url_path: '*', host: '*',
-            http_method: '*', service_type: '*', service_name: component_attrs.task_definition_family,
-            resource_arn: '*', attributes: {}, tags: component_tag_set
-          })
-        end
-
-        private
-
-        def create_cpu_alarm(name, component_attrs, service_ref, component_tag_set)
-          aws_cloudwatch_metric_alarm(component_resource_name(name, :cpu_alarm), {
-            alarm_name: "#{name}-service-cpu-high", comparison_operator: 'GreaterThanThreshold',
-            evaluation_periods: '2', metric_name: 'CPUUtilization', namespace: 'AWS/ECS',
-            period: '300', statistic: 'Average', threshold: '85.0',
-            alarm_description: 'Service CPU utilization is high',
-            dimensions: { ServiceName: service_ref.name, ClusterName: component_attrs.cluster_ref.name },
-            tags: component_tag_set
-          })
-        end
-
-        def create_memory_alarm(name, component_attrs, service_ref, component_tag_set)
-          aws_cloudwatch_metric_alarm(component_resource_name(name, :memory_alarm), {
-            alarm_name: "#{name}-service-memory-high", comparison_operator: 'GreaterThanThreshold',
-            evaluation_periods: '2', metric_name: 'MemoryUtilization', namespace: 'AWS/ECS',
-            period: '300', statistic: 'Average', threshold: '85.0',
-            alarm_description: 'Service memory utilization is high',
-            dimensions: { ServiceName: service_ref.name, ClusterName: component_attrs.cluster_ref.name },
-            tags: component_tag_set
-          })
-        end
-
-        def create_task_count_alarm(name, component_attrs, service_ref, component_tag_set)
-          threshold = component_attrs.auto_scaling.enabled ?
-            component_attrs.auto_scaling.min_tasks.to_s : component_attrs.desired_count.to_s
-          aws_cloudwatch_metric_alarm(component_resource_name(name, :task_count_alarm), {
-            alarm_name: "#{name}-service-tasks-low", comparison_operator: 'LessThanThreshold',
-            evaluation_periods: '2', metric_name: 'RunningTaskCount', namespace: 'AWS/ECS',
-            period: '60', statistic: 'Average', threshold: threshold,
-            alarm_description: 'Service has fewer running tasks than expected',
-            dimensions: { ServiceName: service_ref.name, ClusterName: component_attrs.cluster_ref.name },
-            tags: component_tag_set
-          })
-        end
-      end
-    end
-  end
-end

data/lib/pangea/components/microservice_deployment/component/outputs.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright 2025 The Pangea Authors. Licensed under Apache 2.0.
-
-module Pangea
-  module Components
-    module MicroserviceDeploymentComponent
-      module Outputs
-        def calculate_outputs(service_ref, task_def_ref, log_group_ref, component_attrs, load_balancers)
-          {
-            service_name: service_ref.name, service_arn: service_ref.id, task_definition_arn: task_def_ref.arn,
-            task_definition_family: component_attrs.task_definition_family,
-            cluster_name: component_attrs.cluster_ref.name, desired_count: component_attrs.desired_count,
-            launch_type: component_attrs.launch_type, log_group_name: log_group_ref.name,
-            service_discovery_endpoint: service_discovery_endpoint(component_attrs),
-            resilience_features: resilience_features(component_attrs, load_balancers),
-            monitoring_features: monitoring_features(component_attrs),
-            estimated_monthly_cost: estimate_microservice_cost(component_attrs)
-          }
-        end
-
-        private
-
-        def service_discovery_endpoint(component_attrs)
-          return nil unless component_attrs.service_discovery
-          "#{component_attrs.service_discovery.service_name}.#{component_attrs.service_discovery.namespace_id}"
-        end
-
-        def resilience_features(component_attrs, load_balancers)
-          [
-            ('Circuit Breaker' if component_attrs.circuit_breaker.enabled),
-            ('Auto Scaling' if component_attrs.auto_scaling.enabled),
-            ('Health Checks' if load_balancers.any?),
-            ('Service Discovery' if component_attrs.service_discovery),
-            ('Distributed Tracing' if component_attrs.tracing.enabled),
-            ('Blue-Green Deployment' if component_attrs.enable_blue_green)
-          ].compact
-        end
-
-        def monitoring_features(component_attrs)
-          [
-            'CloudWatch Logs', 'CloudWatch Alarms',
-            ('X-Ray Tracing' if component_attrs.tracing.x_ray),
-            ('Jaeger Tracing' if component_attrs.tracing.jaeger),
-            ('Zipkin Tracing' if component_attrs.tracing.zipkin)
-          ].compact
-        end
-
-        def estimate_microservice_cost(attrs)
-          vcpu_hour_cost = 0.04048
-          gb_hour_cost = 0.004445
-          vcpus = attrs.task_cpu.to_f / 1024
-          memory_gb = attrs.task_memory.to_f / 1024
-          hourly_cost_per_task = (vcpus * vcpu_hour_cost) + (memory_gb * gb_hour_cost)
-          task_count = attrs.auto_scaling.enabled ? attrs.auto_scaling.min_tasks : attrs.desired_count
-          cost = hourly_cost_per_task * task_count * 730
-          cost += 5.0 # CloudWatch Logs
-          cost += 22.0 if attrs.target_group_refs.any? # Load Balancer
-          cost += 1.0 if attrs.service_discovery # Service Discovery
-          cost += 5.0 if attrs.tracing.enabled && attrs.tracing.x_ray # X-Ray
-          cost.round(2)
-        end
-      end
-    end
-  end
-end