AWS Systems Manager
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用自定义清单

您可以通过创建自定义清单将所需的任何元数据分配给您的实例。例如,假如您负责管理数据中心多个机架中的大量服务器,而且这些服务器已配置为 Systems Manager 托管实例。目前,您在电子表格中存储服务器机架位置的相关信息。借助自定义清单,您可以指定每个实例的机架位置作为实例上的元数据。当您使用 Systems Manager 收集清单时,该元数据与其他清单元数据一起收集。随后您可以使用资源数据同步将所有清单元数据传输到中央 Amazon S3 存储桶并查询数据。

注意

对于每个 AWS 账户,Systems Manager 最多支持 20 个自定义清单类型。

要将自定义清单分配给实例,可以使用 Systems Manager PutInventory API 操作,如演练:将自定义清单元数据分配给某个实例中所述。或者,您可以创建自定义清单 JSON 文件并将其上传到实例。本部分描述了如何创建 JSON 文件。

以下包含自定义清单的示例 JSON 文件指定有关本地服务器的机架信息。此示例指定一种类型的自定义清单数据 ("TypeName": "Custom:RackInformation"),在描述数据的 Content 下有多个条目。

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

您也可以在 Content 部分指定不同条目,如以下示例所示。

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

自定义清单的 JSON 架构需要 SchemaVersion、TypeName 和 Content 部分,但您可以定义这些部分的信息。

{ "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 最长为 100 个字符。此外,TypeName 部分必须以 Custom 开头。例如,Custom:PuppetModuleInfo。Custom 和您指定的数据必须以一个大写字母开头。以下示例可能会引起异常:“CUSTOM:RackInformation”、“custom:rackinformation”。

Content 部分包括属性和数据。这些项目不区分大小写。但是,如果您定义了属性 (例如“Vendor”: “DELL”),在自定义清单文件中必须一致地引用此属性。如果您在一个文件中指定“Vendor”: “DELL”(vendor 使用大写字母“V”),在另一个文件中指定“vendor”: “DELL”(vendor 使用小写字母“v”),系统会返回错误。

注意

您必须使用 .json 扩展名保存文件。

创建文件之后,您必须在实例上保存文件。下表说明了自定义清单 JSON 文件必须存储在实例中的哪个位置:

操作系统 路径

Windows

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

Linux

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

有关如何使用自定义清单的示例,请参阅使用 EC2 Systems Manager 自定义清单类型获取队列的磁盘利用率

删除自定义清单

您可以使用 DeleteInventory API 操作来删除自定义清单类型以及与该类型关联的数据。您可以使用 AWS CLI 调用 delete-inventory 命令来删除某个清单类型的所有数据。您可以使用 SchemaDeleteOption 调用 delete-inventory 命令来删除自定义清单类型。

注意

清单类型也称为清单架构。

SchemaDeleteOption 参数包括以下选项:

  • DeleteSchema:此选项删除指定的自定义类型和与之关联的所有数据。如果需要,可以稍后重新创建架构。

  • DisableSchema:如果您选择此选项,系统将禁用当前版本,删除其所有数据,并在版本早于或等于所禁用版本时忽略所有新数据。您可以通过对高于已禁用版本的版本调用 PutInventory 操作来重新启用此清单类型。

使用 AWS CLI 删除或禁用自定义清单

  1. Install and configure the AWS CLI, if you have not already.

    For information, see Install or Upgrade and then Configure the AWS CLI.

  2. 运行以下命令来使用 dry-run 选项查看将从系统中删除哪些数据。此命令不会删除任何数据。

    aws ssm delete-inventory --type-name "Custom:custom_type_name" --dry-run

    系统将返回类似于以下内容的信息。

    {
       "DeletionSummary":{
          "RemainingCount":3,
          "SummaryItems":[
             {
                "Count":2,
                "RemainingCount":2,
                "Version":"1.0"
             },
             {
                "Count":1,
                "RemainingCount":1,
                "Version":"2.0"
             }
          ],
          "TotalCount":3
       },
       "TypeName":"Custom:custom_type_name"
    }

    有关如何了解和删除清单摘要的信息,请参阅了解删除清单摘要

  3. 运行以下命令来删除自定义清单类型的所有数据。

    aws ssm delete-inventory --type-name "Custom:custom_type_name"

    注意

    此命令的输出未显示删除进度。因此,TotalCount 和 Remaining Count 始终相同,因为系统尚未删除任何数据。您可以使用 describe-inventory-deletions 命令来显示删除进度,如本主题的下文所述。

    系统将返回类似于以下内容的信息。

    {
       "DeletionId":"system_generated_deletion_ID",
       "DeletionSummary":{
          "RemainingCount":3,
          "SummaryItems":[
             {
                "Count":2,
                "RemainingCount":2,
                "Version":"1.0"
             },
             {
                "Count":1,
                "RemainingCount":1,
                "Version":"2.0"
             }
          ],
          "TotalCount":3
       },
       "TypeName":"custom_type_name"
    }

    系统将从 Systems Manager Inventory 服务中删除指定的自定义清单类型的所有数据。

  4. 运行以下命令。此命令对清单类型的当前版本执行以下操作:禁用当前版本、删除它的所有数据并忽略所有新数据 (如果版本低于或等于已禁用版本)。

    aws ssm delete-inventory --type-name "Custom:custom_type_name" --schema-delete-option "DisableSchema"

    系统将返回类似于以下内容的信息。

    {
       "DeletionId":"system_generated_deletion_ID",
       "DeletionSummary":{
          "RemainingCount":3,
          "SummaryItems":[
             {
                "Count":2,
                "RemainingCount":2,
                "Version":"1.0"
             },
             {
                "Count":1,
                "RemainingCount":1,
                "Version":"2.0"
             }
          ],
          "TotalCount":3
       },
       "TypeName":"Custom:custom_type_name"
    }

    您可以使用以下命令查看已禁用的清单类型。

    aws ssm get-inventory-schema --type-name Custom:custom_type_name
  5. 运行以下命令来删除清单类型。

    aws ssm delete-inventory --type-name "Custom:custom_type_name" --schema-delete-option "DeleteSchema"

    系统将删除指定的自定义类型的架构和所有清单数据。

    系统将返回类似于以下内容的信息。

    {
       "DeletionId":"system_generated_deletion_ID",
       "DeletionSummary":{
          "RemainingCount":3,
          "SummaryItems":[
             {
                "Count":2,
                "RemainingCount":2,
                "Version":"1.0"
             },
             {
                "Count":1,
                "RemainingCount":1,
                "Version":"2.0"
             }
          ],
          "TotalCount":3
       },
       "TypeName":"Custom:custom_type_name"
    }

查看删除状态

您可以使用 describe-inventory-deletions AWS CLI 命令来查看删除操作的状态。您可以指定删除 ID 来查看特定删除操作的状态。或者,您也可以省略删除 ID 来查看最近 30 天运行的所有删除的列表。

  1. 运行以下命令来查看删除操作的状态。系统将返回 delete-inventory 摘要中的删除 ID。

    aws ssm describe-inventory-deletions --deletion-id system_generated_deletion_ID

    系统将返回最新状态。删除操作可能尚未完成。系统将返回类似于以下内容的信息。

    {"InventoryDeletions": 
      [
        {"DeletionId": "system_generated_deletion_ID", 
         "DeletionStartTime": 1521744844, 
         "DeletionSummary": 
          {"RemainingCount": 1, 
           "SummaryItems": 
            [
              {"Count": 1, 
               "RemainingCount": 1, 
               "Version": "1.0"}
            ], 
           "TotalCount": 1}, 
         "LastStatus": "InProgress", 
         "LastStatusMessage": "The Delete is in progress", 
         "LastStatusUpdateTime": 1521744844, 
         "TypeName": "Custom:custom_type_name"}
      ]
    }

    如果删除操作成功,则 LastStatusMessage 指出:Deletion is successful。

    {"InventoryDeletions": 
      [
        {"DeletionId": "system_generated_deletion_ID", 
         "DeletionStartTime": 1521744844, 
         "DeletionSummary": 
          {"RemainingCount": 0, 
           "SummaryItems": 
            [
              {"Count": 1, 
               "RemainingCount": 0, 
               "Version": "1.0"}
            ], 
           "TotalCount": 1}, 
         "LastStatus": "Complete", 
         "LastStatusMessage": "Deletion is successful", 
         "LastStatusUpdateTime": 1521745253, 
         "TypeName": "Custom:custom_type_name"}
      ]
    }
  2. 运行以下命令来查看最近 30 天运行的所有删除的列表。

    aws ssm describe-inventory-deletions --max-results a number
    {"InventoryDeletions": 
      [
        {"DeletionId": "system_generated_deletion_ID", 
         "DeletionStartTime": 1521682552, 
         "DeletionSummary": 
          {"RemainingCount": 0, 
           "SummaryItems": 
            [
              {"Count": 1, 
               "RemainingCount": 0, 
               "Version": "1.0"}
            ], 
           "TotalCount": 1}, 
         "LastStatus": "Complete", 
         "LastStatusMessage": "Deletion is successful", 
         "LastStatusUpdateTime": 1521682852, 
         "TypeName": "Custom:custom_type_name"}, 
        {"DeletionId": "system_generated_deletion_ID", 
         "DeletionStartTime": 1521744844, 
         "DeletionSummary": 
          {"RemainingCount": 0, 
           "SummaryItems": 
            [
              {"Count": 1, 
               "RemainingCount": 0, 
               "Version": "1.0"}
            ], 
           "TotalCount": 1}, 
         "LastStatus": "Complete", 
         "LastStatusMessage": "Deletion is successful", 
         "LastStatusUpdateTime": 1521745253, 
         "TypeName": "Custom:custom_type_name"}, 
        {"DeletionId": "system_generated_deletion_ID", 
         "DeletionStartTime": 1521680145, 
         "DeletionSummary": 
          {"RemainingCount": 0, 
           "SummaryItems": 
            [
              {"Count": 1, 
               "RemainingCount": 0, 
               "Version": "1.0"}
            ], 
           "TotalCount": 1}, 
         "LastStatus": "Complete", 
         "LastStatusMessage": "Deletion is successful", 
         "LastStatusUpdateTime": 1521680471, 
         "TypeName": "Custom:custom_type_name"}
      ], 
     "NextToken": "next-token"

了解删除清单摘要

为帮助您了解删除清单摘要的内容,请考虑以下示例。用户将 Custom:RackSpace 清单分配给了三个实例。清单项目 1 和 2 使用自定义类型版本 1.0 ("SchemaVersion":"1.0")。清单项目 3 使用自定义类型版本 2.0 ("SchemaVersion":"2.0")。

RackSpace 自定义清单 1

{ "CaptureTime":"2018-02-19T10:48:55Z", "TypeName":"CustomType:RackSpace", "InstanceId":"i-1234567890", "SchemaVersion":"1.0" "Content":[ { content of custom type omitted } ] }

RackSpace 自定义清单 2

{ "CaptureTime":"2018-02-19T10:48:55Z", "TypeName":"CustomType:RackSpace", "InstanceId":"i-1234567891", "SchemaVersion":"1.0" "Content":[ { content of custom type omitted } ] }

RackSpace 自定义清单 3

{ "CaptureTime":"2018-02-19T10:48:55Z", "TypeName":"CustomType:RackSpace", "InstanceId":"i-1234567892", "SchemaVersion":"2.0" "Content":[ { content of custom type omitted } ] }

用户运行以下命令来预览将删除哪些数据。

aws ssm delete-inventory --type-name "Custom:RackSpace" --dry-run

系统将返回类似于以下内容的信息。

{
   "DeletionId":"1111-2222-333-444-66666",
   "DeletionSummary":{
      "RemainingCount":3,           
      "TotalCount":3,             
                TotalCount and RemainingCount are the number of items that would be deleted if this was not a dry run. These numbers are the same because the system didn't delete anything.
      "SummaryItems":[
         {
            "Count":2,             The system found two items that use SchemaVersion 1.0. Neither item was deleted.           
            "RemainingCount":2,
            "Version":"1.0"
         },
         {
            "Count":1,             The system found one item that uses SchemaVersion 1.0. This item was not deleted.
            "RemainingCount":1,
            "Version":"2.0"
         }
      ],

   },
   "TypeName":"Custom:RackSpace"
}

用户运行以下命令来删除 Custom:RackSpace 清单。

注意

此命令的输出未显示删除进度。因此,TotalCount 和 Remaining Count 始终相同,因为系统尚未删除任何数据。您可以使用 describe-inventory-deletions 命令来显示删除进度。

aws ssm delete-inventory --type-name "Custom:RackSpace"

系统将返回类似于以下内容的信息。

{
   "DeletionId":"1111-2222-333-444-7777777",
   "DeletionSummary":{
      "RemainingCount":3,           There are three items to delete
      "SummaryItems":[
         {
            "Count":2,              The system found two items that use SchemaVersion 1.0.
            "RemainingCount":2,     
            "Version":"1.0"
         },
         {
            "Count":1,              The system found one item that uses SchemaVersion 2.0.
            "RemainingCount":1,     
            "Version":"2.0"
         }
      ],
      "TotalCount":3                
   },
   "TypeName":"RackSpace"
}

在 CloudWatch Events 中查看清单删除操作

您可以配置 Amazon CloudWatch Events,在用户删除自定义清单时创建事件。CloudWatch Events 为自定义清单删除操作提供三种类型的事件:

  • 实例的删除操作:特定托管实例的自定义清单是否已成功删除。

  • 删除操作摘要:删除操作的摘要。

  • 针对禁用的自定义清单类型的警告:如果用户对之前禁用的自定义清单类型版本调用了 PutInventory API 操作,则会发出警告事件。

下面是每个事件的示例:

实例的删除操作

{
   "version":"0",
   "id":"998c9cde-56c0-b38b-707f-0411b3ff9d11",
   "detail-type":"Inventory Resource State Change",
   "source":"aws.ssm",
   "account":"478678815555",
   "time":"2018-05-24T22:24:34Z",
   "region":"us-east-1",
   "resources":[
      "arn:aws:ssm:us-east-1:478678815555:managed-instance/i-0a5feb270fc3f0b97"
   ],
   "detail":{
      "action-status":"succeeded",
      "action":"delete",
      "resource-type":"managed-instance",
      "resource-id":"i-0a5feb270fc3f0b97",
      "action-reason":"",
      "type-name":"Custom:MyInfo"
   }
}

删除操作摘要

{
   "version":"0",
   "id":"83898300-f576-5181-7a67-fb3e45e4fad4",
   "detail-type":"Inventory Resource State Change",
   "source":"aws.ssm",
   "account":"478678815555",
   "time":"2018-05-24T22:28:25Z",
   "region":"us-east-1",
   "resources":[

   ],
   "detail":{
      "action-status":"succeeded",
      "action":"delete-summary",
      "resource-type":"managed-instance",
      "resource-id":"",
      "action-reason":"The delete for type name Custom:MyInfo was completed. The deletion summary is: {\"totalCount\":2,\"remainingCount\":0,\"summaryItems\":[{\"version\":\"1.0\",\"count\":2,\"remainingCount\":0}]}",
      "type-name":"Custom:MyInfo"
   }
}

针对禁用的自定义清单类型的警告

{
   "version":"0",
   "id":"49c1855c-9c57-b5d7-8518-b64aeeef5e4a",
   "detail-type":"Inventory Resource State Change",
   "source":"aws.ssm",
   "account":"478678815555",
   "time":"2018-05-24T22:46:58Z",
   "region":"us-east-1",
   "resources":[
      "arn:aws:ssm:us-east-1:478678815555:managed-instance/i-0ee2d86a2cfc371f6"
   ],
   "detail":{
      "action-status":"failed",
      "action":"put",
      "resource-type":"managed-instance",
      "resource-id":"i-0ee2d86a2cfc371f6",
      "action-reason":"The inventory item with type name Custom:MyInfo was sent with a disabled schema versison 1.0. You must send a version greater than 1.0",
      "type-name":"Custom:MyInfo"
   }
}

要为自定义清单删除操作创建 CloudWatch Events 规则,请按照以下过程操作。此过程向您介绍如何创建向 Amazon SNS 主题发送自定义清单删除操作通知的规则。开始前,检查您是否拥有 Amazon SNS 主题或者新建一个。有关更多信息,请参阅 Amazon Simple Notification Service Developer Guide 中的入门

为删除清单操作配置 CloudWatch Events

  1. Sign in to the AWS Management Console and open the CloudWatch console at https://console.amazonaws.cn/cloudwatch/.

  2. 在左侧导航窗格中,选择 Events,然后选择 Create rule

  3. Event Source 下,验证已选中 Event Pattern

  4. 服务名称字段中,选择 EC2 Simple Systems Manager (SSM)

  5. Event Type (事件类型) 字段中,选择 Inventory (清单)

  6. 检查是否已选择 Any detail type (任何详细信息类型),然后选择 Add targets (添加目标)

  7. Select target type (选择目标类型) 列表中,选择 SNS topic (SNS 主题),然后从列表中选择您的主题。

  8. Configure input (配置输入) 列表中,检查 Matched event (已匹配事件) 是否处于选中状态。

  9. 选择 Configure details

  10. 指定名称和描述,然后选择 Create rule (创建规则)

本页内容: