Menu
AWS Systems Manager
User Guide

Systems Manager Inventory Manager Walkthroughs

Use the following walkthroughs to collect and manage Inventory data. We recommend that you initially perform these walkthroughs with managed instances in a test environment.

Before You Begin

Before you start these walkthroughs, complete the following tasks.

  • Update SSM Agent on the instances you want to inventory. By running the latest version of SSM Agent, you ensure that you can collect metadata for all supported inventory types. For information about how to update SSM Agent by using State Manager, see Walkthrough: Automatically Update the SSM Agent.

  • Verify that your instances meet Systems Manager prerequisites. For more information, see Systems Manager Prerequisites.

  • (Optional) Create a JSON file to collect custom inventory. For more information, see Working with Custom Inventory.

Assigning Custom Inventory Metadata to an Instance

The following procedure walks you through the process of using the PutInventory API action to assign custom Inventory metadata to a managed instance. This example assigns rack location information to an instance. For more information about custom Inventory, see Working with Custom Inventory.

To assign custom Inventory metadata to an instance

  1. Download the latest version of the AWS CLI to your local machine.

  2. Open the AWS CLI and run the following command to specify your credentials and a Region. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM).

    Copy
    aws configure

    The system prompts you to specify the following.

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  3. Execute the following command to assign rack location information to an instance.

    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"}]'
  4. 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" }
  5. 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" } ] }

Collecting Inventory by Using the AWS CLI

The following procedure walks you through the process of using Inventory to collect metadata from an Amazon EC2 instance. When you configure Inventory collection, you start by creating a Systems Manager State Manager association. Systems Manager collects the Inventory data when the association is run. If you don't create the association first, and attempt to invoke the aws:softwareInventory plugin by using, for example, Run Command, the system returns the following error:

The aws:softwareInventory plugin can only be invoked via ssm-associate.

Note

An instance can have only have one Inventory association configured at a time. If you configure an instance with two or more Inventory associations, the association doesn't run and no inventory data is collected.

To gather inventory from an instance

  1. Download the latest version of the AWS CLI to your local machine.

  2. Open the AWS CLI and run the following command to specify your credentials and a Region. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM).

    Copy
    aws configure

    The system prompts you to specify the following.

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  3. Execute the following command to create a State Manager association that runs Inventory on the instance. This command configures the service to run every six hours and to collect network configuration, Windows Update, and application metadata from an instance.

    Copy
    aws ssm create-association --name "AWS-GatherSoftwareInventory" --targets "Key=instanceids,Values=an instance ID" --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"

    You can also inventory files and Windows Registry keys on a Windows instance by using the files and windowsRegistry inventory types with expressions. For more information about these inventory types, see Working with File and Windows Registry Inventory.

    Copy
    aws ssm create-association --name "AWS-GatherSoftwareInventory" --targets "Key=instanceids,Values=i-0704358e3a3da9eb1" --schedule-expression "cron(0 0/30 * 1/1 * ? *)" --parameters '{"files":["[{\"Path\": \"C:\\Program Files\", \"Pattern\": [\"*.exe\"], \"Recursive\": true}]"], "windowsRegistry": ["[{\"Path\":\"HKEY_LOCAL_MACHINE\\Software\\Amazon\", \"Recursive\":true}]"]}' --profile dev-pdx
  4. Execute the following command to view the association status.

    Copy
    aws ssm describe-instance-associations-status --instance-id an instance ID

    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" } ] }

Using Resource Data Sync to Aggregate Inventory Data

The following walkthrough describes how to create a Resource Data Sync configuration by using the AWS CLI. A Resource Data Sync automatically ports Inventory data from all of your managed instances to a central Amazon S3 bucket. The sync automatically updates the data in the central Amazon S3 bucket whenever new Inventory data is discovered. This walkthrough also describes how to use Amazon Athena and Amazon QuickSight to query and analyze the aggregated data. For information about creating a Resource Data Sync by using the Amazon EC2 console, see Configuring Resource Data Sync for Inventory.

Note

This walkthrough includes information about how to encrypt the sync by using AWS Key Management Service (AWS KMS). Inventory does not collect any user-specific, proprietary, or sensitive data so encryption is optional. For more information about AWS KMS, see AWS Key Management Service Developer Guide.

Before You Begin

Before you start this walkthrough, you must collect Inventory metadata from your managed instances. For the purpose of the Amazon Athena and Amazon QuickSight sections in this walkthrough, we recommend that you collect Application metadata. For more information about how to collect Inventory data, see Collecting Inventory by Using the AWS CLI.

(Optional) If you want to encrypt the sync by using AWS KMS, then you must either create a new key that includes the following policy, or you must update an existing key and add this policy to it.

Copy
{ "Version":"2012-10-17", "Id":"ssm-access-policy", "Statement":[ { "Sid":"ssm-access-policy-statement", "Action":[ "kms:GenerateDataKey" ], "Effect":"Allow", "Principal":{ "Service":"ssm.amazonaws.com" }, "Resource":"arn:aws:kms:region:AWS-account-ID:key/KMS-key-id" } ] }

To create a Resource Data Sync for Inventory

  1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. Create a bucket to store your aggregated Inventory data. For more information, see Create a Bucket in the Amazon Simple Storage Service Getting Started Guide. Make a note of the bucket name and the AWS Region where you created it.

  3. After you create the bucket, choose the Permissions tab, and then choose Bucket Policy.

  4. Copy and paste the following bucket policy into the policy editor. Replace Bucket-Name and Account-ID with the name of the Amazon S3 bucket you created and a valid AWS account ID. Optionally, replace Bucket-Prefix with the name of an Amazon S3 prefix (subdirectory). If you did not created a prefix, remove Bucket-Prefix/ from the ARN in the policy.

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "SSMBucketPermissionsCheck", "Effect": "Allow", "Principal": { "Service": "ssm.amazonaws.com" }, "Action": "s3:GetBucketAcl", "Resource": "arn:aws:s3:::Bucket-Name" }, { "Sid": " SSMBucketDelivery", "Effect": "Allow", "Principal": { "Service": "ssm.amazonaws.com" }, "Action": "s3:PutObject", "Resource": ["arn:aws:s3:::Bucket-Name/Bucket-Prefix/*/accountid=Account-ID/*"], "Condition": { "StringEquals": { "s3:x-amz-acl": "bucket-owner-full-control" } } } ] }
  5. (Optional) If you want to encrypt the sync, then you must add the following policy to the bucket. Repeat the previous step to add the following policy to the bucket.

    Copy
    { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"ssm.amazonaws.com" }, "Action":"s3:PutObject", "Resource":"arn:aws:s3:::bucket-name/prefix/*", "Condition":{ "StringEquals":{ "s3:x-amz-server-side-encryption":"aws:kms", "s3:x-amz-server-side-encryption-aws-kms-key-id":"arn:aws:kms:region:AWS-account-ID:key/KMS-key-ID" } } } ] }
  6. Download the latest version of the AWS CLI to your local machine.

  7. Open the AWS CLI and run the following command to specify your credentials and a Region. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM).

    Copy
    aws configure

    The system prompts you to specify the following.

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  8. (Optional) If you want to encrypt the sync, execute the following command to verify that the bucket policy is enforcing the KMS key requirement.

    Copy
    aws s3 cp ./A file in the bucket s3://bucket-name/prefix/ --sse aws:kms --sse-kms-key-id "arn:aws:kms:region:AWS-account-ID:key/KMS-key-id" --region region
  9. Execute the following command to create a Resource Data Sync configuration with the Amazon S3 bucket you created at the start of this procedure. This command creates a sync from the AWS Region you are currently logged into.

    Note

    If the sync and the target Amazon S3 bucket are located in different regions, you may be subject to data transfer pricing. For more information, see Amazon S3 Pricing.

    Copy
    aws ssm create-resource-data-sync --sync-name a name --s3-destination "BucketName=the name of the S3 bucket,Prefix=the name of the prefix, if specified,SyncFormat=JsonSerDe,Region=the region where the S3 bucket was created"

    You can use the region parameter to specify where the sync configuration should be created. In the following example, Inventory data from the us-west-1 Region, will be synchronized in the Amazon S3 bucket in the us-west-2 Region.

    Copy
    aws ssm create-resource-data-sync --sync-name InventoryDataWest --s3-destination "BucketName=InventoryData,Prefix=HybridEnv,SyncFormat=JsonSerDe,Region=us-west-2" --region us-west-1

    (Optional) If you want to encrypt the sync by using AWS KMS, execute the following command to create the sync. If you encrypt the sync, then the AWS KMS key and the Amazon S3 bucket must be in the same Region.

    Copy
    aws ssm create-resource-data-sync --sync-name sync-name --s3-destination "BucketName=bucket-name,Prefix=prefix,SyncFormat=JsonSerDe,AWSKMSKeyARN=arn:aws:kms:region:AWS-account-ID:key/KMS-key-id,Region=bucket-region" --region region
  10. Execute the following command to view the status of sync configuration.

    Copy
    aws ssm list-resource-data-sync

    If you created the sync configuration in a different Region, then you must specify the region parameter, as shown in the following example.

    Copy
    aws ssm list-resource-data-sync --region us-west-1
  11. After the sync configuration is created successfully, browse the target bucket in Amazon S3. Inventory data should appear within a few minutes.

Working with the Data in Amazon Athena

The following section describes how to view and query the data in Amazon Athena.

To view and query the data in Amazon Athena

  1. In the Amazon Athena console, copy and paste the following statement into the query editor and then choose Run Query.

    Copy
    CREATE DATABASE ssminventory

    The system creates a database called ssminventory.

  2. Copy and paste the following statement into the query editor and then choose Run Query. Replace Bucket-Name and Bucket-Prefix with the name and prefix of the Amazon S3 target.

    Copy
    CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_Application ( `ResourceId` string, `Name` string, `ApplicationType` string, `Publisher` string, `Version` string, `InstalledTime` string, `Architecture` string, `URL` string ) PARTITIONED BY (AccountId string, Region string, ResourceType string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1' ) LOCATION 's3://Bucket-Name/Bucket-Prefix/AWS:Application/'

    The system creates a table with partitioning information for the Application inventory type.

  3. Copy and paste the following statement into the query editor and then choose Run Query.

    Copy
    MSCK REPAIR TABLE ssminventory.AWS_Application

    The system partitions the table.

    Note

    If you create Resource Data Syncs from additional AWS Regions or accounts, then you must run this command again to update the partitions. You may also need to update your Amazon S3 bucket policy.

  4. To preview your data, choose the view icon next to the AWS_Application table.

    
                            alt-text
  5. Copy and paste the following statement into the query editor and then choose Run Query.

    Copy
    SELECT a.name, a.version, count( a.version) frequency from aws_application a where a.name = 'aws-cfn-bootstrap' group by a.name, a.version order by frequency desc

    The query returns a count of different versions of aws-cfn-bootstrap, which is an AWS application present on Amazon EC2 Linux and Windows instances.

  6. Individually copy and paste the following statements into the query editor, replace Bucket-Name and Bucket-Prefix with information for Amazon S3, and then choose Run Query. These statements set up additional Inventory tables in Athena.

    Copy
    CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_AWSComponent ( `ResourceId` string, `Name` string, `ApplicationType` string, `Publisher` string, `Version` string, `InstalledTime` string, `Architecture` string, `URL` string ) PARTITIONED BY (AccountId string, Region string, ResourceType string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1' ) LOCATION 's3://Bucket-Name/Bucket-Prefix/AWS:AWSComponent/' MSCK REPAIR TABLE ssminventory.AWS_AWSComponent
    Copy
    CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_WindowsUpdate ( `ResourceId` string, `HotFixId` string, `Description` string, `InstalledTime` string, `InstalledBy` string ) PARTITIONED BY (AccountId string, Region string, ResourceType string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1' ) LOCATION 's3://Bucket-Name/Bucket-Prefix/AWS:WindowsUpdate/' MSCK REPAIR TABLE ssminventory.AWS_WindowsUpdate
    Copy
    CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_InstanceInformation ( `AgentType` string, `AgentVersion` string, `ComputerName` string, `IamRole` string, `InstanceId` string, `IpAddress` string, `PlatformName` string, `PlatformType` string, `PlatformVersion` string ) PARTITIONED BY (AccountId string, Region string, ResourceType string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1' ) LOCATION 's3://Bucket-Name/Bucket-Prefix/AWS:InstanceInformation/' MSCK REPAIR TABLE ssminventory.AWS_InstanceInformation
    Copy
    CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_Network ( `ResourceId` string, `Name` string, `SubnetMask` string, `Gateway` string, `DHCPServer` string, `DNSServer` string, `MacAddress` string, `IPV4` string, `IPV6` string ) PARTITIONED BY (AccountId string, Region string, ResourceType string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1' ) LOCATION 's3://Bucket-Name/Bucket-Prefix/AWS:Network/' MSCK REPAIR TABLE ssminventory.AWS_Network
    Copy
    CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_PatchCompliance ( `ResourceId` string, `Title` string, `KBId` string, `Classification` string, `Severity` string, `State` string, `InstalledTime` string ) PARTITIONED BY (AccountId string, Region string, ResourceType string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1' ) LOCATION 's3://Bucket-Name/Bucket-Prefix/AWS:PatchCompliance/' MSCK REPAIR TABLE ssminventory.AWS_PatchCompliance
    Copy
    CREATE EXTERNAL TABLE IF NOT EXISTS ssminventory.AWS_PatchSummary ( `ResourceId` string, `PatchGroup` string, `BaselineId` string, `SnapshotId` string, `OwnerInformation` string, `InstalledCount` int, `InstalledOtherCount` int, `NotApplicableCount` int, `MissingCount` int, `FailedCount` int, `OperationType` string, `OperationStartTime` string, `OperationEndTime` string ) PARTITIONED BY (AccountId string, Region string, ResourceType string) ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe' WITH SERDEPROPERTIES ( 'serialization.format' = '1' ) LOCATION 's3://Bucket-Name/Bucket-Prefix/AWS:PatchSummary/' MSCK REPAIR TABLE ssminventory.AWS_PatchSummary

Working with the Data in Amazon QuickSight

The following section provides an overview with links for building a visualization in Amazon QuickSight.

To build a visualization in Amazon QuickSight

  1. Sign up for Amazon QuickSight and then log in to the QuickSight console.

  2. Create a data set from the AWS_Application table and any other tables you created. For more information, see Creating a Data Set Using Amazon Athena Data.

  3. Join tables. For example, you could join the instanceid column from AWS_InstanceInformation because it matches the resourceid column in other inventory tables. For more information about joining tables, see Joining Tables.

  4. Build a visualization. For more information, see Working with Amazon QuickSight Visuals.