Menu
Amazon EC2 Systems Manager
User Guide

Systems Manager Inventory Manager Walkthrough

Use the following walkthrough to collect and manage inventory in a test environment.

Launch a New Instance

Instances require an AWS Identity and Access Management (IAM) role that enables the instance to communicate with Amazon EC2 Systems Manager (SSM). You can attach an IAM role when you create a new instance, or you can attach it to an existing instance.

To create an SSM-supported IAM role

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, Create New Role.

  3. In Step 1: Set Role Name, enter a name that identifies this role as a Run Command role.

  4. In Step 2: Select Role Type, choose Amazon EC2 Role for Simple Systems Manager. The system skips Step 3: Establish Trust because this is a managed policy.

  5. In Step 4: Attach Policy, choose AmazonEC2RoleforSSM.

  6. Choose Next Step, and then choose Create Role.

The following procedure describes how to attach the role you've created to a new instance. For more information about attaching a role to an existing instance, see Attaching an IAM Role to an Instance in the Amazon EC2 User Guide.

To create an instance that uses an SSM-supported role

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. Select a supported region.

  3. Choose Launch Instance and select an Amazon Machine Image (AMI).

  4. Choose your instance type and then choose Next: Configure Instance Details.

  5. In Auto-assign Public IP, choose Enable.

  6. From IAM role, choose the role you created earlier.

  7. Complete the wizard to launch the new instance. Make a note of the instance ID. You will need to specify this ID later in this tutorial.

Important

On Linux instances, you must install the SSM Agent on the instance you just created. For more information, see Installing SSM Agent on Linux.

Grant Your User Account Access to SSM

Your user account must be configured to communicate with the SSM API. Use the following procedure to attach a managed IAM policy to your user account that grants you full access to SSM API actions.

To create the IAM policy for your user account

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Policies. (If this is your first time using IAM, choose Get Started, and then choose Create Policy.)

  3. In the Filter field, type AmazonSSMFullAccess and press Enter.

  4. Select the check box next to AmazonSSMFullAccess and then choose Policy Actions, Attach.

  5. On the Attach Policy page, choose your user account and then choose Attach Policy.

Inventory Manager CLI Walkthrough

The following procedure walks you through the process of using Inventory to collect metadata from the test instance you created earlier.

To gather inventory from an instance

  1. Execute the following command to create a State Manager association that runs Inventory on the instance you created earlier. This command configures the service to run every six hours and to collect network configuration, Windows Update, and application metadata on the test instance you created earlier.

    Copy
    aws ssm create-association --name "AWS-GatherSoftwareInventory" --targets "Key=instanceids,Values=ID of the instance you created earlier" --schedule-expression "cron(0 0/30 * 1/1 * ? *)" --output-location "{ \"S3Location\": { \"OutputS3Region\": \"us-east-1\", \"OutputS3BucketName\": \"Test bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" --parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"

    The system responds with information like the following.

    Copy
    { "AssociationDescription": { "ScheduleExpression": "cron(0 0/30 * 1/1 * ? *)", "OutputLocation": { "S3Location": { "OutputS3KeyPrefix": "Test", "OutputS3BucketName": "Test bucket", "OutputS3Region": "us-east-1" } }, "Name": "The name you specified", "Parameters": { "applications": [ "Enabled" ], "networkConfig": [ "Enabled" ], "windowsUpdates": [ "Enabled" ] }, "Overview": { "Status": "Pending", "DetailedStatus": "Creating" }, "AssociationId": "1a2b3c4d5e6f7g-1a2b3c-1a2b3c-1a2b3c-1a2b3c4d5e6f7g", "DocumentVersion": "$DEFAULT", "LastUpdateAssociationDate": 1480544990.06, "Date": 1480544990.06, "Targets": [ { "Values": [ "i-1a2b3c4d5e6f7g" ], "Key": "InstanceIds" } ] } }

    You can target large groups of instances by using the Targets parameter with EC2 tags.

    Copy
    aws ssm create-association --name "AWS-GatherSoftwareInventory" --targets "Key=tag:Environment,Values=Production" --schedule-expression "cron(0 0/30 * 1/1 * ? *)" --output-location "{ \"S3Location\": { \"OutputS3Region\": \"us-east-1\", \"OutputS3BucketName\": \"Test bucket\", \"OutputS3KeyPrefix\": \"Test\" } }" --parameters "networkConfig=Enabled,windowsUpdates=Enabled,applications=Enabled"
  2. Execute the following command to view the association status.

    Copy
    aws ssm describe-instance-associations-status --instance-id ID of the instance you created earlier

    The system responds with information like the following.

    Copy
    { "InstanceAssociationStatusInfos": [ { "Status": "Pending", "DetailedStatus": "Associated", "Name": "reInvent2016PolicyDocumentTest", "InstanceId": "i-1a2b3c4d5e6f7g", "AssociationId": "1a2b3c4d5e6f7g-1a2b3c-1a2b3c-1a2b3c-1a2b3c4d5e6f7g", "DocumentVersion": "1" } ] }

The following procedure walks you through the process of using the PutInventory API to assign custom metadata to the test instance you created earlier. This example assigns rack location information to a managed instance.

To assign custom metadata to an instance for Inventory

  1. Execute the following command to assign rack location information to the test instance you created earlier.

    Copy
    aws ssm put-inventory --instance-id "ID" --items '[{"CaptureTime": "2016-08-22T10:01:01Z", "TypeName": "Custom:RackInfo", "Content":[{"RackLocation": "Bay B/Row C/Rack D/Shelf E"}], "SchemaVersion": "1.0"}]'
  2. Execute the following command to view custom inventory entries for this instance.

    Copy
    aws ssm list-inventory-entries --instance-id ID --type-name "Custom:RackInfo"

    The system responds with information like the following.

    Copy
    { "InstanceId": "ID", "TypeName": "Custom:RackInfo", "Entries": [ { "RackLocation": "Bay B/Row C/Rack D/Shelf E" } ], "SchemaVersion": "1.0", "CaptureTime": "2016-08-22T10:01:01Z" }
  3. Execute the following command to view the custom metadata.

    Copy
    aws ssm get-inventory

    The system responds with information like the following.

    Copy
    { "Entities": [ { "Data": { "AWS:InstanceInformation": { "Content": [ { "ComputerName": "WIN-9JHCEPEGORG.WORKGROUP", "InstanceId": "ID", "ResourceType": "EC2Instance", "AgentVersion": "3.19.1153", "PlatformVersion": "6.3.9600", "PlatformName": "Windows Server 2012 R2 Standard", "PlatformType": "Windows" } ], "TypeName": "AWS:InstanceInformation", "SchemaVersion": "1.0" } }, "Id": "ID" } ] }