Trabalhar com inventário personalizado

Você pode atribuir quaisquer metadados desejados aos nós criando um inventário personalizado do AWS Systems Manager Inventory. Por exemplo, digamos que você gerencie um grande número de servidores em racks no seu datacenter e esses servidores tenham sido configurados como nós gerenciados do Systems Manager. Atualmente, você armazena informações sobre a localização de racks de servidor em uma planilha. Com o inventário personalizado, você pode especificar a localização do rack de cada nó como um metadado para o nó. Quando você coleta o inventário usando o Systems Manager, os metadados são coletados com outros metadados do inventário. Você pode então fazer a portabilidade de todos os metadados do inventário para um bucket central do Amazon S3 usando a sincronização de dados de recursos e consultando os dados.

nota

O Systems Manager oferece suporte a no máximo 20 tipos de inventário personalizados por Conta da AWS.

Para atribuir um inventário personalizado a um nó, você pode usar a operação da API PutInventory do Systems Manager, conforme descrito em Demonstração: atribua metadados do inventário personalizado para um nó gerenciado.. Como alternativa, você pode criar um arquivo JSON de inventário personalizado e enviá-lo para o nó. Esta seção descreve como criar o arquivo JSON.

O seguinte arquivo JSON de exemplo com inventário personalizado especifica informações de rack sobre um servidor on-premises. Esse exemplo especifica um tipo de dados de inventário personalizado ("TypeName": "Custom:RackInformation"), com várias entradas em Content que descrevem os dados.


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

Você também pode especificar entradas distintas na seção Content, conforme mostrado no exemplo a seguir.


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

O esquema JSON para inventário personalizado requer as seções SchemaVersion, TypeName e Content, mas você pode definir as informações nessas seções.


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

O valor de TypeName é limitado a 100 caracteres. Além disso, o valor TypeName deve começar com a palavra Custom em maiúsculas. Por exemplo, Custom:PuppetModuleInfo. Portanto, os exemplos a seguir resultariam em uma exceção: CUSTOM:PuppetModuleInfo, custom:PuppetModuleInfo.

A seção Content inclui atributos e dados. Esses itens não diferenciam entre maiúsculas e minúsculas. No entanto, se você definir um atributo (por exemplo: "Vendor": "DELL"), deverá sempre fazer referência a esse atributo em seus arquivos de inventário personalizados. Se você especificar "Vendor": "DELL" (usando um "V" maiúsculo em vendor) em um arquivo e, em seguida, especificar "vendor": "DELL" (usando um "v" minúsculo em vendor) em outro arquivo, o sistema retornará um erro.

nota

Você deve salvar o arquivo com uma extensão .json, e o inventário definido deve consistir somente em valores de string.

Depois de criar o arquivo, salve-o em seu nó. A tabela a seguir mostra o local em que os arquivos JSON do inventário personalizado devem ser armazenados em seu nó:

Sistema operacional	Path
Linux	/var/lib/amazon/ssm/`node-id`/inventory/custom
macOS	`/opt/aws/ssm/data/node-id/inventory/custom`
Windows	%SystemDrive%\ProgramData\Amazon\SSM\InstanceData\`node-id`\inventory\custom

Para obter um exemplo de como usar o inventário personalizado, consulte o tópico sobre Utilização de disco da sua frota usando tipos de inventário personalizados do EC2 Systems Manager.

Excluir inventário personalizado

Você pode usar a operação da API DeleteInventory para excluir um tipo de inventário personalizado e os dados associados a esse tipo. Chame o comando delete-inventory usando a AWS Command Line Interface (AWS CLI) para excluir todos os dados de um tipo de inventário. Você chama o comando delete-inventory com SchemaDeleteOption para excluir um tipo de inventário personalizado.

nota

Um tipo de inventário também é chamado de esquema de inventário.

O parâmetro SchemaDeleteOption inclui as opções a seguir:

DeleteSchema: esta opção exclui o tipo personalizado especificado e todos os dados associados a ele. Se desejar, você pode recriar o esquema mais tarde.
DisableSchema: se você escolher essa opção, o sistema desativará a versão atual, excluirá todos os dados dela e ignorará todos os novos dados se a versão for anterior ou igual à versão desativada. Você pode permitir esse tipo de inventário novamente chamando a ação PutInventory para uma versão posterior à versão desativada.

Para excluir ou desativar o inventário personalizado usando a AWS CLI

Instale e configure a AWS Command Line Interface (AWS CLI), caso ainda não o tenha feito.

Para obter informações, consulte Instalar ou atualizar a versão mais recente da AWS CLI.

Execute o seguinte comando para usar a opção dry-run para ver quais dados serão excluídos do sistema. Esse comando não exclui nenhum dado.


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

O sistema retorna informações como estas.

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

Para obter informações sobre como entender o resumo de exclusão do inventário, consulte Noções básicas sobre o resumo de exclusão do inventário.

Execute o seguinte comando para excluir todos os dados de um tipo de inventário personalizado.
```
aws ssm delete-inventory --type-name "Custom:custom_type_name"
```
nota
O resultado desse comando não mostra o andamento da exclusão. Por esse motivo, TotalCount (Total) e Remaining Count (Restante) são sempre os mesmos porque o sistema ainda não excluiu nada. Você pode usar o comando "describe-inventory-deletions" para mostrar o andamento da exclusão, conforme descrito mais adiante neste tópico.

O sistema retorna informações como estas.
```
{
   "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"
}
```
O sistema exclui todos os dados do tipo de inventário personalizado especificado no serviço do Systems Manager Inventory.

Execute o comando a seguir. O comando executa as seguintes ações para a versão atual do tipo de inventário: desativa a versão atual, exclui todos os dados dela e ignora todos os novos dados se a versão for anterior ou igual à versão desativada.


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

O sistema retorna informações como estas.

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

Você pode visualizar um tipo de inventário desativado, usando o comando a seguir.


aws ssm get-inventory-schema --type-name Custom:custom_type_name

Execute o seguinte comando para excluir um tipo de inventário.


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

O sistema exclui o esquema e todos os dados de inventário do tipo personalizado especificado.

O sistema retorna informações como estas.

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

Visualizar o status da exclusão

Você pode verificar o status de uma operação de exclusão usando o comando describe-inventory-deletions da AWS CLI. Você pode especificar um ID de exclusão para visualizar o status de uma determinada operação de exclusão. Ou você pode omitir o ID de exclusão para visualizar uma lista de todas as exclusões executadas nos últimos 30 dias.

Execute o seguinte comando para visualizar o status de uma operação de exclusão. O sistema retornou o ID de exclusão no resumo de exclusão do inventário.


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

O sistema retorna o status mais recente. A operação de exclusão pode não estar concluída. O sistema retorna informações como estas.

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

Se a operação de exclusão for bem-sucedida, a mensagem LastStatusMessage indica: Exclusão bem-sucedida.

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

Execute o seguinte comando para visualizar uma lista de todas as exclusões executadas nos últimos 30 dias.


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"

Noções básicas sobre o resumo de exclusão do inventário

Para ajudar você a compreender o conteúdo do resumo de exclusão do inventário, considere o exemplo a seguir. Um usuário atribuiu o inventário Custom:RackSpace a três nós. Os itens de inventário 1 e 2 usam o tipo personalizado versão 1.0 ("SchemaVersion":"1.0"). O item de inventário 3 usa o tipo personalizado versão 2.0 ("SchemaVersion":"2.0").

Inventário personalizado do RackSpace 1


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

Inventário personalizado do RackSpace 2


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

Inventário personalizado do RackSpace 3


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

O usuário executa o comando a seguir para visualizar quais dados serão excluídos.


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

O sistema retorna informações como estas.

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

O usuário executa o comando a seguir para excluir o inventário Custom:RackSpace.

nota

O resultado desse comando não mostra o andamento da exclusão. Por esse motivo, TotalCount e RemainingCount são sempre os mesmos porque o sistema ainda não excluiu nada. Você pode usar o comando describe-inventory-deletions para mostrar o andamento da exclusão.


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

O sistema retorna informações como estas.

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

Visualizar ações de exclusão de inventário no EventBridge

Você pode configurar o Amazon EventBridge para criar um evento sempre que um usuário excluir o inventário personalizado. O EventBridge oferece três tipos de eventos para operações de exclusão do inventário personalizado:

Excluir ação de uma instância: se o inventário personalizado de um nó gerenciado específico foi excluído com êxito ou não.
Excluir resumo da ação: Um resumo da ação de exclusão.
Aviso para tipo de inventário personalizado desativado: um evento de aviso se um usuário chamou a operação de API PutInventory para uma versão do tipo de inventário personalizado que foi desativada anteriormente.

Veja exemplos de cada evento:

Delete action for an instance (Excluir ação de uma instância)

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

Delete action summary (Excluir resumo da ação)

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

Aviso para tipo de inventário personalizado desativado

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

Use o procedimento a seguir para criar uma regra do EventBridge para operações de exclusão de inventário personalizadas. Este procedimento mostra como criar uma regra que envia notificações para excluir operações de inventário personalizadas em um tópico do Amazon SNS. Antes de começar, verifique se você tem um tópico do Amazon SNS ou crie um novo. Para obter mais informações, consulte Conceitos básicos no Guia do desenvolvedor do Amazon Simple Notification Service.

Para configurar o EventBridge para excluir operações de inventário

Abra o console do Amazon EventBridge em https://console.aws.amazon.com/events/.
No painel de navegação, escolha Rules (Regras).
Escolha Create rule (Criar regra).
Insira um nome e uma descrição para a regra.

Uma regra não pode ter o mesmo nome que outra regra na mesma região e no mesmo barramento de eventos.
Em Event bus (Barramento de eventos), escolha o barramento de eventos que você deseja associar a essa regra. Se você quiser que essa regra responda a eventos correspondentes provenientes da sua Conta da AWS, selecione default (padrão). Quando um AWS service (Serviço da AWS) na sua conta emite um evento, ele sempre vai para o barramento de eventos padrão da sua conta.
Em Rule type (Tipo de regra), escolha Rule with an event pattern (Regra com um padrão de evento).
Escolha Next (Próximo).
Em Event source (Origem do evento), escolha Eventos da AWS ou eventos de parceiro do EventBridge.
Na seção Event patter (Padrão de evento), selecione Event pattern form (Formulário de padrão de evento).
Em Event source (Origem do evento), escolha AWS services (Serviços da ).
Em Serviço da AWS, escolha Systems Manager.
Para Event type (Tipo de evento), escolha Inventory (Inventário).
Em Specific detail type(s) (Tipos de detalhes específicos), escolha Inventory Resource State Change (Alteração de estado de recursos de inventário).
Escolha Next (Próximo).
Em Target types (Tipos de destinos), escolha AWS service (Serviço da ).
Em Select a target (Selecionar um destino), escolha SNS topic (Tópico do SNS) e depois escolha seu tópico em Topic.
Na seção Additional settings (Configurações adicionais), para Configure target input (Configurar entrada do destino), verifique se a opção Matched event (Evento correspondido) está selecionada.
Escolha Next (Próximo).
(Opcional) Insira uma ou mais tags para a regra. Para obter mais informações, consulte Marcar recursos do Amazon EventBridge no Guia do usuário do Amazon EventBridge.
Escolha Next (Próximo).
Analise os detalhes da regra e escolha Create rule (Criar regra).

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Agregar dados do inventário

Visualizar o histórico do inventário e o controle de alterações