cfn-guardian 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4595a270016361e041e9aa0bfc6a4921388036bc224152e63b4d71fa3c0f3c8
-  data.tar.gz: 0fc14a5114332c794335432edfc28907d5080a5faeab449118da714b17b1b54f
+  metadata.gz: 97db5ada9a8fd070dbc9cbb851b3d0f1b0352db96014d9f29883c359a47b92a4
+  data.tar.gz: 8ce062a52661342ab8c78e0adccb357887234384e4ff2e1cd4307cb3066bd41b
 SHA512:
-  metadata.gz: 053dc2627f05cfda432920324f0b7c5b171fe9121b6d46f528c99c3c6042eb1660d508c41ba65f00cd38a67befdea8936a7ceb9bedc96e8ab83ea02a7bea2c60
-  data.tar.gz: 31ad2da72a21a7952b93934f1b67dd8e3f78849dd1957355efb799b796eda2d69ee7e270abee63aa64140db940c16f5c607ca06316b361bfb719f68c7f3662f9
+  metadata.gz: b58d879093561d7f836e73b02aaceb6f3499209907ec0aaf4e66e272398ac53756b51d0820ef319cf89b7bfdeedd2fb44f57d7aee1ddcec904122af523a2ca64
+  data.tar.gz: 0e582fcd0bda145414d31888bde92e0b866a895c82e45841760085ee2ca9466281776750787c0d7c9973a96b227e69e200c79891d9246b4bd294f7b118155fab

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cfn-guardian (0.14.0)
+    cfn-guardian (0.15.0)
       aws-sdk-cloudformation (~> 1.76, < 2)
       aws-sdk-cloudwatch (~> 1.72, < 2)
       aws-sdk-codecommit (~> 1.53, < 2)

data/README.md

@@ -34,6 +34,7 @@ CfnGuardian is a AWS monitoring tool with a few capabilities:
 - EC2 Instances
 - ECS Clusters
 - ECS Services
+- ECS Scheduled Tasks
 - EFS
 - Classic LoadBalancers
 - Lambda Functions

data/docs/ecs_scheduled_tasks.md

@@ -0,0 +1,99 @@
+# ECS Scheduled Tasks
+
+`ECSScheduledTask` monitors ECS tasks that run outside of an ECS service, for example tasks launched on a schedule by an EventBridge rule or EventBridge Scheduler. These tasks have no service to attach `ECSService` alarms to, so Guardian watches the `ECS Task State Change` events for the cluster instead and notifies when a task fails.
+
+## Configuration
+
+```yaml
+Resources:
+  ECSScheduledTask:
+  # Id is the ECS cluster name. Monitors every standalone task in the cluster.
+  - Id: batch-jobs
+  # Optionally narrow to a single task definition family.
+  - Id: shared-cluster
+    TaskDefinitionFamily: report-export
+```
+
+| Key | Required | Description |
+|---|---|---|
+| `Id` | yes | ECS cluster name |
+| `TaskDefinitionFamily` | no | Only match tasks from this task definition family, matched on the task definition ARN |
+
+Every event subscription in this group, including custom ones, is scoped to:
+
+- the cluster in `Id`
+- tasks not started by an ECS service (the task's `group` doesn't start with `service:`), so service deployments don't trigger alerts
+- the `TaskDefinitionFamily`, if set
+
+If a scheduled task is launched with a custom `group` starting with `service:`, it won't be matched.
+
+## Default Event Subscriptions
+
+Both are sent to the `Events` topic by default.
+
+| Name | Fires when |
+|---|---|
+| `TaskFailed` | A task stops and any of its containers has a non-zero exit code |
+| `TaskFailedToStart` | A task stops with stop code `TaskFailedToStart`, e.g. the image can't be pulled or a secret can't be fetched |
+
+A container with no exit code (null or missing, e.g. one that never started) doesn't match. EventBridge matches `exitCode` against every container in the task, so a sidecar (such as a log router) that exits non-zero will also trigger `TaskFailed`.
+
+## Overriding Defaults
+
+Event subscriptions are configured under the `EventSubscriptions` key. See [event subscriptions](event_subscriptions.md).
+
+```yaml
+EventSubscriptions:
+  ECSScheduledTask:
+    # page on failed runs instead of sending to the Events topic
+    TaskFailed:
+      Topic: Critical
+    # disable the failed-to-start notification
+    TaskFailedToStart: false
+    # custom subscriptions default to the ECS Task State Change detail type
+    # and are scoped to the cluster and family like the defaults
+    TaskStoppedBySpot:
+      Detail:
+        stopCode: [SpotInterruption]
+```
+
+## Alarms
+
+There are no default alarms, as scheduled tasks only publish metrics while they run. If [Container Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContainerInsights.html) is enabled on the cluster, alarms can be added under `Templates`. They use the `ECS/ContainerInsights` namespace with the `ClusterName` dimension, plus `TaskDefinitionFamily` if set, and treat missing data as not breaching.
+
+Alarms are named `guardian-ECSScheduledTask-<Id>-<AlarmName>`, or `guardian-ECSScheduledTask-<Id>:<TaskDefinitionFamily>-<AlarmName>` when a family is set, so a cluster-wide entry and family entries on the same cluster each get their own alarm.
+
+```yaml
+Templates:
+  ECSScheduledTask:
+    MemoryUtilizedHigh:
+      MetricName: MemoryUtilized
+      Statistic: Maximum
+      Threshold: 1800 # MiB
+      AlarmAction: Warning
+```
+
+## Missed Runs
+
+The event subscriptions only fire when a task runs and fails. They won't fire if the schedule never launches a task. If `RunTask` itself fails (for example on a bad network configuration), ECS creates no task and emits no events. That shows up in the launcher's own metrics instead: `FailedInvocations` in the `AWS/Events` namespace for an EventBridge rule, or `TargetErrorCount` and `InvocationDroppedCount` in the `AWS/Scheduler` namespace for EventBridge Scheduler (Scheduler doesn't publish `FailedInvocations`).
+
+To catch a missed run, add a `LogGroup` metric filter that counts a line the task logs on success, and alarm when the count is below 1 over the schedule interval. A metric filter with no matches publishes no data, so the alarm must treat missing data as breaching. See [log group metric filters](custom_checks/log_group_metric_filters.md).
+
+```yaml
+Resources:
+  LogGroup:
+  - Id: batch-jobs
+    MetricFilters:
+    - MetricName: ReportExportSucceeded
+      Pattern: '"export complete"'
+
+Templates:
+  LogGroup:
+    ReportExportSucceeded:
+      ComparisonOperator: LessThanThreshold
+      Threshold: 1
+      Period: 86400 # the schedule interval, here daily
+      EvaluationPeriods: 1
+      TreatMissingData: breaching
+      AlarmAction: Warning
+```

data/docs/overview.md

@@ -24,4 +24,5 @@
 10. [Dimension Variables](variables.md)
 11. [Search Expression Alarms](search_expressions.md)
 12. [Alarm Tags](alarm_tags.md)
-13. [Anomaly Detection Alarms](anomaly_detection.md)
+13. [Anomaly Detection Alarms](anomaly_detection.md)
+14. [ECS Scheduled Tasks](ecs_scheduled_tasks.md)

data/lib/cfnguardian/compile.rb

@@ -20,6 +20,7 @@ require 'cfnguardian/resources/dynamodb_table'
 require 'cfnguardian/resources/ec2_instance'
 require 'cfnguardian/resources/ecs_cluster'
 require 'cfnguardian/resources/ecs_service'
+require 'cfnguardian/resources/ecs_scheduled_task'
 require 'cfnguardian/resources/eks_container_insights'
 require 'cfnguardian/resources/elastic_file_system'
 require 'cfnguardian/resources/elasticache_replication_group'

data/lib/cfnguardian/models/alarm.rb

@@ -271,6 +271,25 @@ module CfnGuardian
       end
     end
 
+    class ECSScheduledTaskAlarm < BaseAlarm
+      def initialize(resource)
+        super(resource)
+        @group = 'ECSScheduledTask'
+        @namespace = 'ECS/ContainerInsights'
+        @dimensions = { ClusterName: resource['Id'] }
+        if resource.has_key?('TaskDefinitionFamily')
+          @dimensions[:TaskDefinitionFamily] = resource['TaskDefinitionFamily']
+          # keep family alarms distinct from the cluster-wide and other family alarms on the same cluster.
+          # ECS cluster and family names can't contain a colon, so cluster `a` with family `b`
+          # can't share an alarm name with a cluster called `a-b`
+          @resource_hash = Digest::MD5.hexdigest [resource['Id'], resource['TaskDefinitionFamily']].to_json
+          @resource_name = "#{resource['Id']}:#{resource['TaskDefinitionFamily']}" if @resource_name.nil?
+        end
+        # scheduled tasks only publish metrics while they are running
+        @treat_missing_data = 'notBreaching'
+      end
+    end
+
     class EKSContainerInsightsClusterAlarm < BaseAlarm
       def initialize(resource)
         super(resource)

data/lib/cfnguardian/models/event_subscription.rb

@@ -95,6 +95,30 @@ module CfnGuardian
       end
     end
 
+    class ECSScheduledTaskEventSubscription < BaseEventSubscription
+      def initialize(resource)
+        super(resource)
+        @source = 'aws.ecs'
+        @detail_type = 'ECS Task State Change'
+        @hash = Digest::MD5.hexdigest [resource['Id'], resource['TaskDefinitionFamily']].to_json
+        @scope = {
+          'clusterArn' => ["arn:aws:ecs:${AWS::Region}:${AWS::AccountId}:cluster/#{resource['Id']}"],
+          # tasks started by an ECS service have a group of service:<name>
+          'group' => [{ 'anything-but' => { 'prefix' => 'service:' } }]
+        }
+        if resource.has_key?('TaskDefinitionFamily')
+          # the trailing colon stops family `app` matching `app-v2`
+          @scope['taskDefinitionArn'] = [{ 'prefix' => "arn:aws:ecs:${AWS::Region}:${AWS::AccountId}:task-definition/#{resource['TaskDefinitionFamily']}:" }]
+        end
+      end
+
+      # Always scope to the resource's cluster and family, including custom and
+      # inherited subscriptions that set their own Detail.
+      def detail
+        return @detail.merge(@scope)
+      end
+    end
+
     class AcmEventSubscription < BaseEventSubscription; end
     class ApiGatewayEventSubscription < BaseEventSubscription; end
     class ApplicationTargetGroupEventSubscription < BaseEventSubscription; end

data/lib/cfnguardian/resources/ecs_scheduled_task.rb

@@ -0,0 +1,30 @@
+module CfnGuardian::Resource
+  # Monitors ECS tasks that run outside of an ECS service, such as tasks launched
+  # by an EventBridge rule or EventBridge Scheduler. These tasks have no service
+  # metrics, so failures are detected from the ECS Task State Change events.
+  # The cluster and task definition family scope is applied by
+  # ECSScheduledTaskEventSubscription, so custom subscriptions get it too.
+  class ECSScheduledTask < Base
+
+    def default_event_subscriptions()
+      event_subscription = CfnGuardian::Models::ECSScheduledTaskEventSubscription.new(@resource)
+      event_subscription.name = 'TaskFailed'
+      event_subscription.detail = {
+        'lastStatus' => ['STOPPED'],
+        # numeric matching skips containers with a null or missing exit code,
+        # which `anything-but: 0` would match
+        'containers' => { 'exitCode' => [{ 'numeric' => ['>', 0] }] }
+      }
+      @event_subscriptions.push(event_subscription)
+
+      event_subscription = CfnGuardian::Models::ECSScheduledTaskEventSubscription.new(@resource)
+      event_subscription.name = 'TaskFailedToStart'
+      event_subscription.detail = {
+        'lastStatus' => ['STOPPED'],
+        'stopCode' => ['TaskFailedToStart']
+      }
+      @event_subscriptions.push(event_subscription)
+    end
+
+  end
+end

data/lib/cfnguardian/version.rb

@@ -1,4 +1,4 @@
 module CfnGuardian
-  VERSION = "0.14.0"
+  VERSION = "0.15.0"
   CHANGE_SET_VERSION = VERSION.gsub('.', '-').freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cfn-guardian
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Guslington
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -327,6 +327,7 @@ files:
 - docs/custom_checks/tls.md
 - docs/custom_checks/websocket.md
 - docs/custom_metrics.md
+- docs/ecs_scheduled_tasks.md
 - docs/event_subscriptions.md
 - docs/maintenance_mode.md
 - docs/notifiers.md
@@ -369,6 +370,7 @@ files:
 - lib/cfnguardian/resources/dynamodb_table.rb
 - lib/cfnguardian/resources/ec2_instance.rb
 - lib/cfnguardian/resources/ecs_cluster.rb
+- lib/cfnguardian/resources/ecs_scheduled_task.rb
 - lib/cfnguardian/resources/ecs_service.rb
 - lib/cfnguardian/resources/eks_container_insights.rb
 - lib/cfnguardian/resources/elastic_file_system.rb