Catch event when an SSM-agent becomes active

Question

I want to trigger a lambda whenever a new EC2 instance is registred in SSM's Fleet Manager (meaning the instance can be connected to using SSM), however I can't find what pattern to use in EventBridge.

Within EventBridge, I tried using the following pattern I found in the docs (so far its looks like the closest thing to my goal):

{
  "source": ["aws.ssm"],
  "detail-type": ["Inventory Resource State Change"]
}

However when I create a new EC2 and wait for its SSM agent to become active, it still doesn't trigger the above pattern.

Any idea how to catch this kind of event?

Answer 1

I think you have to go through CloudTrail API call. Please find below a CloudFormation template I used in the past that was working. Please note that it just provides the SSM resources. You need to add your own SQS queue as well (see SQS.ARN) and I've used the association with the tag registration set to enabled. So that if you have a lambda function connected, you can set it to false so if the instance connect again, it won't go to the same process again.

AWSTemplateFormatVersion: "2010-09-09"
Description: >
  SSM Registration event

# Description of the resources to be created.
Resources:
  RegistrationDocument:
    Type: AWS::SSM::Document
    Properties:
      DocumentType: Command
      Content:
        schemaVersion: "2.2"
        description: >
          An Automation Document ran by registered instances that gathers their software inventory
          and automatically updates their AWS SSM Agent to the latest version.
        mainSteps:
          - name: GatherSoftware
            action: aws:softwareInventory
          - name: Sleep
            action: aws:runShellScript
            inputs:
              runCommand:
                - sleep 20 || true
          - name: UpdateAgent
            action: aws:updateSsmAgent
            inputs:
              agentName: amazon-ssm-agent
              source: https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json
              allowDowngrade: "false"

  RegistrationDocumentAssociation:
    Type: AWS::SSM::Association
    Properties:
      AssociationName: !Sub registration-association-${AWS::StackName}
      Name: !Ref RegistrationDocument
      Targets:
        - Key: tag:registration
          Values:
            - enabled

  RegistrationEventRule:
    Type: AWS::Events::Rule
    Properties:
      Description: >
        Events Rule that monitors registration of AWS SSM instances
        and logs them to an SQS queue.
      EventPattern:
        source:
          - aws.ssm
        detail-type:
          - AWS API Call via CloudTrail
        detail:
          eventName:
            - UpdateInstanceAssociationStatus
          requestParameters:
            associationId:
              - !Ref RegistrationDocumentAssociation
            executionResult:
              status:
                - Success
      State: ENABLED
      Targets:
        - Arn: SQS.ARN
          Id: SqsRegistrationSubscription
          SqsParameters:
            MessageGroupId: registration.events