Menu
Amazon EC2 Systems Manager
User Guide

Systems Manager Inventory

When you configure Systems Manager Inventory, you specify the type of metadata to collect, the instances from where the metadata should be collected, and a schedule for metadata collection. These configurations are saved with your AWS account as a State Manager association.

Note

Inventory only collects metadata. It does not collect any personal or proprietary data.

The following table describes the different parts of inventory collection in more detail.

Part Details

Type of information to collect

  • Instance details, including system name, OS name, OS version, last boot, DNS, domain, workgroup, OS architecture, etc.

  • Network configuration details, including IP address, MAC address, DNS, gateway, and subnet mask.

  • Application details, including application names, publishers, and versions

  • AWS component details, including EC2 driver, agents, and versions.

  • Windows Server Update history.

  • Custom inventory details. Custom inventory is described in more detail later in this section.

Instances to collect information from

You can individually select instances or target groups of instances using EC2 tag.

When to collect information

You can specify a collection interval in terms of minutes, hours, days, and weeks. The shortest collection interval is every 30 minutes.

Depending on the amount of data collected, the system can take several minutes to report the data to the output you specified. After the information is collected, the metadata is sent over a secure HTTPS channel to a plain-text AWS store that is accessible only from your AWS account. You can view the data in the Amazon S3 bucket you specified, or in the Amazon EC2 console on the Inventory tab for your managed instance. The Inventory tab includes several predefined filters to help you query the data.

To start collecting inventory on your managed instance, see Configuring Inventory Collection. To view samples of how to set up inventory collection using the Amazon EC2 console and the AWS CLI, see Systems Manager Inventory Manager Walkthrough.

Custom Inventory

You can use custom inventory to attach any metadata you want to your instances. For example, let's say you manage a large number of servers in racks in your data center, and these servers have been configured as Systems Manager managed instances. You store information about server location in the racks in a spreadsheet. With custom inventory, you could assign rack location metadata to each instance. When you perform inventory tasks with Systems Manager, the metadata would be combined with other inventory metadata to help you understand the contents of your data center.

To record custom inventory, you can either use the Systems Manager PutInventory API action, or use the SSM Agent to upload custom inventory directly from the instance. For more information about the PutInventory API action, see the Amazon EC2 Systems Manager API Reference.

To upload custom data using SSM Agent, you must create custom inventory JSON files, as shown in the following example.

Note

You must save the file with the following extension: .json.

Copy
{ "SchemaVersion": "1.0", "TypeName": "Custom:RackInformation", "Content": { "Location": "US-EAST-01.DC.RACK1", "InstalledTime": "2016-01-01T01:01:01Z", "vendor": "DELL", "Zone" : "BJS12", "TimeZone": "UTC-8" } }

You can also specify multiple items in the file, as shown in the following example.

Copy
{ "SchemaVersion": "1.0", "TypeName": "Custom:PuppetModuleInfo", "Content": [{ "Name": "puppetlabs/aws", "Version": "1.0" }, { "Name": "puppetlabs/dsc", "Version": "2.0" } ] }

The JSON schema for custom inventory requires SchemaVersion, TypeName, and Content sections, but you can define the information in those sections.

Copy
{ "SchemaVersion": "user_defined", "TypeName": "Custom:user_defined", "Content": { "user_defined_attribute1": "user_defined_value1", "user_defined_attribute2": "user_defined_value2", "user_defined_attribute3": "user_defined_value3", "user_defined_attribute4": "user_defined_value4" } }

TypeName is limited to 100 characters. Also, the TypeName section must start with Custom. For example, Custom:PuppetModuleInfo. Both Custom and the Data you specify must begin with a capital letter. The following examples would cause an exception: "CUSTOM:RackInformation", "custom:rackinformation".

The Content section includes attributes and data. These items are not case-sensitive. However, if you define an attribute (for example: "Vendor": "DELL"), then you must consistently reference this attribute in your custom inventory files. If you specify "Vendor": "DELL" (using a capital “V” in vendor) in one file, and then you specify "vendor": "DELL" (using a lowercase “v” in vendor) in another file, the system returns an error.

The following table shows the location where custom inventory JSON files must be stored on the instance:

Operating System Path

Windows

%SystemDrive%\ProgramData\Amazon\SSM\InstanceData\<instance-id>\inventory\custom

Linux

/var/lib/amazon/ssm/<instance-id>/inventory/custom

Related AWS Services

Systems Manager Inventory provides a snapshot of your current inventory to help you manage software policy and improve the security posture of your entire fleet. You can extend your inventory management and migration capabilities using the following AWS services.

  • AWS Config provides a historical record of changes to your inventory, along with the ability to create rules to generate notifications when a configuration item is changed. For more information, see, Recording Amazon EC2 managed instance inventory in the AWS Config Developer Guide.

  • AWS Application Discovery Service is designed to collect inventory on OS type, application inventory, processes, connections, and server performance metrics from your on-premises VMs to support a successful migration to AWS. For more information, see the Application Discovery Service User Guide.