使用自定义清单 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用自定义清单

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

注意

Systems Manager 最多可为每个 Amazon Web Services 账户 支持 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 架构需要 SchemaVersionTypeNameContent 部分,但您可以定义这些部分的信息。

{ "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:PuppetModuleInfoCustom 和您指定的 Data 必须以大写字母开头。以下示例将导致例外:"CUSTOM:RackInformation""custom:rackinformation"

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

注意

您必须使用 .json 扩展名保存文件,并且您定义的清单必须仅包含字符串值。

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

操作系统 路径

Linux

/var/lib/amazon/ssm/node-id/inventory/custom

macOS

/opt/aws/ssm/data/node-id/inventory/custom

Windows

%SystemDrive%\ProgramData\Amazon\SSM\InstanceData\note-id\inventory\custom

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

删除自定义清单

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

注意

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

SchemaDeleteOption 参数包括以下选项:

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

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

使用 Amazon CLI 删除或关闭自定义清单

  1. 安装并配置 Amazon Command Line Interface (Amazon CLI)(如果尚未执行该操作)。

    想要了解有关信息,请参阅安装或升级Amazon命令行工具.

  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 Amazon 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 清单。

注意

此命令的输出未显示删除进度。因此,TotalCountRemainingCount 始终相同,因为系统尚未删除任何数据。您可以使用 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"
}

在 EventBridge 中查看清单删除操作

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

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

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

  • 针对已关闭的自定义清单类型的警告:如果用户对先前关闭的自定义清单类型版本调用了 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 version 1.0. You must send a version greater than 1.0",
      "type-name":"Custom:MyInfo"
   }
}

可以使用以下过程为自定义清单删除操作创建 EventBridge 规则。此过程向您介绍如何创建向 Amazon SNS 主题发送自定义清单删除操作通知的规则。开始前,请验证您是否拥有 Amazon SNS 主题,如果没有请新建一个。有关更多信息,请参阅 Amazon Simple Notification Service Developer Guide 中的入门

为删除清单操作配置 EventBridge

  1. 访问 https://console.aws.amazon.com/events/,打开 Amazon EventBridge 控制台。

  2. 在导航窗格中,选择 Rules (规则),然后选择 Create rule (创建规则)

    -或者-

    如果首先打开 Amazon EventBridge 主页,选择 Create rule (创建规则)

  3. 为规则输入名称和描述。

    规则不能与同一区域中的另一个规则和同一事件总线上的名称相同。

  4. 对于 Define pattern (定义模式),选择 Event pattern (事件模式)

  5. 选择 Pre-defined pattern by service (服务预定义的模式)

  6. 对于 Service provider (服务提供商),选择 AWS

  7. 对于 Service name (服务名称),选择 Systems Manager

  8. 对于 Event type (事件类型),选择 Inventory (清单)

  9. 验证并确保已选择 Any detail type (任意详细信息类型)

  10. 对于 Select event bus(选择事件总线),请选择要与此规则关联的事件总线。如果您希望根据来自您自己的 Amazon Web Services 账户 的匹配事件启动此规则,请选择 Amazon default event bus (默认事件总线)。当您账户中的某个 Amazon 服务发出一个事件时,它始终会发送到您账户的默认事件总线。

  11. 对于 Target (目标),选择 SNS topic (SNS 主题),然后从 Topic (主题) 列表中选择您的主题。

  12. 展开 Configure input (配置输入),验证并确保已选择 Matched event (匹配的事件)

  13. (可选)为规则输入一个或多个标签。有关更多信息,请参阅 Amazon EventBridge 用户指南中的标记 Amazon EventBridge 资源

  14. 选择创建