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

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用自定义清单

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

注意

Systems Manager 最多支持 20 个自定义清单类型的每个Amazon Web Services 账户。

要将自定义清单分配给实例,可以使用 Systems ManagerPutInventoryAPI 操作,如演练:将自定义清单元数据分配给某个实例。或者,您可以创建自定义清单 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 和您指定的数据必须以一个大写字母开头。以下示例会导致异常:“客户定制:机架信息”、“客制:机架信息”。

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

注意

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

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

操作系统 路径

Linux

/var/lib/Amazon /ssm/instance-id/库存/自定义

macOS

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

Windows

%Systems Drive%\ ProgramData\ Amazon\ SSM\ InstanceData\ InstanceData\instance-id\ 清单\ 自定义

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

删除自定义清单

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

注意

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

SchemaDeleteOption 参数包括以下选项:

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

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

使用 删除或禁用自定义清单AmazonCLI

  1. 安装和配置Amazon命令行界面 (AmazonCLI)(如果尚未执行该操作)。

    想要了解有关信息,请参阅安装或升级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"
    }

    系统将从 System Management 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"
    }

查看删除状态

您可以通过使用描述性清单删除操作的状态AmazonCLI 命令。您可以指定删除 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状态:删除成功。

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

在 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 开发人员指南

为删除清单操作配置 EventBridge

  1. 打开位于 https://console.aws.amazon.com/events/ 的 Amazon EventBridge 控制台。

  2. 在导航窗格中,选择Rule,然后选择创建规则

    -或者-

    如果亚马逊 EventBridge 主页首先打开,请选择创建规则

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

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

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

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

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

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

  8. 适用于Event type中,选择清单

  9. 确认 。任意详细信息类型处于选择状态。

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

  11. 适用于目标中,选择SNS 主题,然后从主题列表。

  12. Expand配置输入并确认匹配的事件处于选择状态。

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

  14. 选择创建