カスタムインベントリの操作 - AWS Systems Manager

カスタムインベントリの操作

AWS Systems Manager インベントリのカスタムインベントリを作成して、インスタンスに必要なあらゆるメタデータを割り当てることができます。例えば、データセンターのラック内の多数のサーバーを管理しており、それらのサーバーは Systems Manager マネージドインスタンスとして設定されているとします。現在、サーバーラック位置に関する情報はスプレッドシートに保存しています。カスタムインベントリを使うと、各インスタンスのラック位置をインスタンスのメタデータとして指定できます。Systems Manager を使用してインベントリを収集すると、そのメタデータは他のインベントリメタデータとともに収集されます。その後、リソースデータ同期を使用してすべてのインベントリメタデータを中央 Amazon S3 バケットにポートし、データをクエリできます。

注記

Systems Manager では、 あたり最大 20 のカスタムインベントリタイプをサポートしています AWS アカウント

カスタムインベントリをインスタンスに割り当てるには、「チュートリアル: カスタムインベントリメタデータをインスタンスに割り当てる」で説明されているように Systems Manager PutInventory API オペレーションを使用できます。または、カスタムインベントリ JSON ファイルを作成し、インスタンスにアップロードできます。このセクションでは、JSON ファイルを作成する方法について説明します。

カスタムインベントリを含む次の JSON ファイルの例では、オンプレミスサーバーに関するラック情報を指定しています。この例では、1 つのタイプのカスタムインベントリデータ ("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" (ベンダーの「V」が大文字) と指定した場合、別のファイルで "vendor": "DELL" (ベンダーの「v」が小文字) と指定すると、システムはエラーを返します。

注記

.json 拡張子を付けてファイルを保存し、定義するインベントリは文字列値のみで構成する必要があります。

ファイルを作成した後、インスタンスに保存する必要があります。以下の表は、カスタムインベントリの JSON ファイルをインスタンスのどの場所に保存する必要があるかを示します。

オペレーティングシステム パス

Linux

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

macOS

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

Windows

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

カスタムインベントリの使用方法の例については、「EC2 Systems Manager カスタムインベントリ型を使用してインスタンスのディスクの利用状況を取得する」を参照してください。

カスタムインベントリの削除

API オペレーションの DeleteInventory を使用して、カスタムインベントリタイプと当該タイプに関連付けられているデータを削除できます。インベントリタイプのすべてのデータを削除するには、AWS Command Line Interface (AWS CLI) を使用して delete-inventory コマンドを呼び出します。カスタムインベントリタイプを削除するには、SchemaDeleteOption を使用して delete-inventory コマンドを呼び出します。

注記

インベントリタイプは、インベントリスキーマとも呼ばれます。

SchemaDeleteOption パラメータには次のオプションが含まれます。

  • DeleteSchema: このオプションでは、指定したカスタムタイプおよび関連するすべてのデータを削除します。必要に応じて、後でスキーマを再作成できます。

  • DisableSchema: このオプションを選択すると、現在のバージョンが無効になり、すべての関連するデータが削除されます。また、無効化したバージョン以下のバージョンでは、すべての新しいデータが無視されます。このインベントリタイプを再度有効にするには、無効になっているバージョンよりも新しいバージョンの PutInventory アクションを呼び出します。

AWS CLI を使用してカスタムインベントリを削除または無効化するには

  1. まだ AWS Command Line Interface (AWS CLI) をインストールして設定していない場合は、インストールして設定します。

    詳細については、「AWS コマンドラインツールのインストールまたはアップグレード」を参照してください。

  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 は削除が成功したことを示します。

    {"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 インベントリを 3 つのインスタンスに割り当てています。インベントリ項目 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 には、カスタムインベントリの削除オペレーションに対して、次の 3 種類のイベントが用意されています。

  • インスタンスの削除アクション: 特定のマネージドインスタンスのカスタムインベントリが正常に削除されたかどうか。

  • 削除アクションの概要: 削除アクションの概要。

  • 無効にされたカスタムインベントリタイプの警告: 以前に無効にされたカスタムインベントリタイプバージョンの 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. Amazon EventBridge コンソール (https://console.aws.amazon.com/events/) を開きます。

  2. ナビゲーションペインで、[Rules (ルール)] を選択し、[Create rule (ルールの作成)] を選択します。

    -または-

    Amazon EventBridge ホームページが最初に開く場合は、[ルールの作成] を選択します。

  3. ルールの名前と説明を入力します。

    ルールには、同じリージョン内および同じイベントバス上の別のルールと同じ名前を付けることはできません。

  4. [Define pattern (パターンの定義)] で、[Event pattern (イベントパターン)] を選択します。

  5. [Pre-defined pattern by service (サービスによる定義済みパターン)] を選択します。

  6. [Service provider (サービスプロバイダー)] で、[AWS] を選択します。

  7. [Service name (サービス名)] で、[Systems Manager] を選択します。

  8. [イベントタイプ] で [在庫] を選択します。

  9. [任意の詳細タイプ] が選択されていることを確認します。

  10. [Select event bus (イベントバスの選択)] で、このルールに関連付けるイベントバスを選択します。このルールを自分の AWS アカウント から一致するイベントで開始する場合は、[AWS default event bus] を選択します。アカウントの AWS サービスがイベントを発行すると、常にアカウントのデフォルトのイベントバスに移動します。

  11. [ターゲット] で、[SNS トピック] を選択し、[トピック] リストからトピックを選択します。

  12. [入力の設定] を展開し、[一致したイベント] が選択されていることを確認します。

  13. (オプション) ルールに1 つ以上のタグを入力します。詳細については、Amazon EventBridge ユーザーガイドの「Amazon EventBridge リソースのタグ付け」を参照してください 。

  14. [Create] を選択します。