Mapeamento de destino para uma automação

Use o parâmetro Targets para definir rapidamente quais recursos serão usados como destino por uma automação. Por exemplo, se você quiser executar uma automação que reinicia suas instâncias gerenciadas, em vez de selecionar manualmente dezenas de IDs de instância no console ou digitá-los em um comando, especifique as instâncias de destino especificando as tags do Amazon Elastic Compute Cloud (Amazon EC2) com o parâmetro Targets.

Quando você executa uma automação que usa um destino, o AWS Systems Manager cria uma automação filho para cada destino. Por exemplo, se você definir o destino dos volumes do Amazon Elastic Block Store (Amazon EBS) especificando tags, e essas tags forem resolvidas para 100 volumes do Amazon EBS, o Systems Manager criará 100 automações filho. A automação pai é concluída quando todas as automações filho alcançam um estado final.

nota

Quaisquer input parameters especificados em runtime (na seção Input parameters (parâmetros de entrada) do console ou usando a opção parameters na linha de comando) serão automaticamente processados por todas as automações filho.

Você pode definir recursos como o destino para uma automação usando tags, grupos de recursos e valores de parâmetros. Além disso, você pode usar a opção TargetMaps para definir o destino de vários valores de parâmetro na linha de comando ou em um arquivo. A seção a seguir descreve cada uma dessas opções de destino em mais detalhes.

Definir uma etiqueta como destino

É possível especificar uma única etiqueta como o destino de uma automação. Muitos recursos da AWS oferecem suporte a tags, incluindo instâncias do Amazon Elastic Compute Cloud (Amazon EC2) e Amazon Relational Database Service (Amazon RDS), volumes e snapshots do Amazon Elastic Block Store (Amazon EBS), grupos de recursos e buckets do Amazon Simple Storage Service (Amazon S3), entre outros. É possível executar rapidamente a automação nos recursos da AWS definindo uma etiqueta como destino. Uma etiqueta é um par de chave-valor, como Operating_System:Linux ou Department:Finance. Se você atribuir um nome específico a um recurso, você também pode usar a palavra "Name" como chave, e o nome do recurso como valor.

Quando você especifica uma tag como o destino para uma automação, você também deve especificar um parâmetro de destino. O parâmetro de destino usa a opção TargetParameterName. Ao escolher um parâmetro de destino, você define o tipo de recurso no qual a automação é executada. O parâmetro de destino especificado com a tag deve ser um parâmetro válido definido no runbook. Por exemplo, para ter dezenas de instâncias do EC2 como destino usando tags, escolha o parâmetro de destino InstanceId. Ao escolher este parâmetro, você define as instâncias como o tipo de recurso para a automação. Ao criar um runbook personalizado, é necessário especificar o Tipo de destino como /AWS::EC2::Instance para garantir que somente instâncias sejam usadas. Caso contrário, todos os recursos com a mesma etiqueta serão direcionados. Ao definir instâncias como destino usando uma etiqueta, é possível incluir instâncias encerradas.

A captura de tela a seguir usa o runbook AWS-DetachEBSVolume. O parâmetro de destino lógico é VolumeId.

O runbook AWS-DetachEBSVolume também inclui uma propriedade especial chamada Target type (Tipo de destino), que é definida como /AWS::EC2::Volume. Isso significa que, se o par de tag e chave Finance:TestEnv retornar diferentes tipos de recursos (por exemplo, instâncias do EC2, volumes do Amazon EBS e snapshots do Amazon EBS), apenas os volumes do Amazon EBS serão usados.

Importante

Os nomes dos parâmetros de destino diferenciam maiúsculas de minúsculas. Se você executar automações usando a AWS Command Line Interface (AWS CLI) ou AWS Tools for Windows PowerShell, insira o nome do parâmetro de destino exatamente como ele é definido no runbook. Se não fizer isso, o sistema retornará um erro InvalidAutomationExecutionParametersException. Você pode usar a operação de API DescribeDocument para ver informações sobre os parâmetros de destino disponíveis em um runbook específico. Veja a seguir um exemplo de comando da AWS CLI que fornece informações sobre o documento AWS-DeleteSnapshot.

aws ssm describe-document \
    --name AWS-DeleteSnapshot

Aqui estão alguns exemplos de comandos da AWS CLI que definem recursos como destino usando etiquetas.

Exemplo 1: definir uma etiqueta como destino usando um par de chave-valor para reiniciar instâncias do Amazon EC2

Este exemplo reinicia todas as instâncias do Amazon EC2 que estiverem marcadas com uma chave Department e um valor HumanResources. O parâmetro de destino usa o parâmetro InstanceId do runbook. O exemplo usa um parâmetro adicional para executar a automação usando uma função de serviço do Automation (também chamado de função assumida).

aws ssm start-automation-execution \
    --document-name AWS-RestartEC2Instance \
    --targets Key=tag:Department,Values=HumanResources \
    --target-parameter-name InstanceId \
    --parameters "AutomationAssumeRole=arn:aws:iam::111122223333:role/AutomationServiceRole"

Exemplo 2: definir uma etiqueta como destino usando um par de chave-valor para excluir snapshots do Amazon EBS

O exemplo a seguir usa o runbook AWS-DeleteSnapshot para excluir todos os snapshots com uma chave de Nome e um valor de January2018Backups. O parâmetro de destino usa o parâmetro VolumeId.

aws ssm start-automation-execution \
    --document-name AWS-DeleteSnapshot \
    --targets Key=tag:Name,Values=January2018Backups \
    --target-parameter-name VolumeId

AWS Resource Groups como destino

É possível especificar um único grupo de recursos da AWS como o destino de uma automação. O Systems Manager cria uma automação filho para cada objeto no grupo de recursos de destino.

Por exemplo, digamos que um de seus grupos de recursos tenha o nome de PatchedAMIs. Esse grupo de recursos inclui uma lista de 25 Amazon Machine Images (AMIs) do Windows que recebem patches rotineiramente. Se você executar uma automação que use o runbook AWS-CreateManagedWindowsInstance e tenha como destino esse grupo de recursos, o Systems Manager criará uma automação filho para cada uma das 25 AMIs. Isso significa que, ao especificar o grupo de recursos PatchedAMIs, a automação cria 25 instâncias em uma lista de AMIs corrigidas pelos patches. A automação pai é concluída quando todas as automações filho finalizam o processamento ou alcançam um estado final.

O comando da AWS CLI a seguir se aplica ao exemplo do grupo de recursos PatchAMIs. O comando usa o parâmetro Amild para a opção --target-parameter-name. O comando não inclui um parâmetro adicional que define qual tipo de instância criar a partir de cada AMI. O runbook AWS-CreateManagedWindowsInstance usa como padrão o tipo de instância t2.medium. Esse comando criaria 25 instâncias t2.medium do Amazon EC2 para o Windows Server.

aws ssm start-automation-execution \
    --document-name AWS-CreateManagedWindowsInstance \
    --targets Key=ResourceGroup,Values=PatchedAMIs  \
    --target-parameter-name AmiId

O exemplo de console a seguir usa um grupo de recursos chamado t2-micro-instances.

Direcionar valores de parâmetro

Você também pode direcionar um valor de parâmetro. Insira ParameterValues como chave e, em seguida, insira o valor do recurso específico em que você deseja que a automação seja executada. Se você especificar vários valores, o Systems Manager executará uma automação secundária em cada valor especificado.

Por exemplo, digamos que o runbook inclui um parâmetro InstanceID. Se você direcionar os valores do parâmetro InstanceID ao executar o Automation, o Systems Manager executará uma automação filho para cada valor especificado para o ID da instância. A automação pai é concluída quando a automação conclui a execução de cada instância especificada, ou se a automação falha. Você pode direcionar um máximo de 50 valores de parâmetro.

O exemplo a seguir usa o runbook AWS-CreateImage. O nome do parâmetro de destino especificado é InstanceId. A chave usa ParameterValues. Os valores são dois IDs de instâncias do Amazon EC2. Esse comando cria uma automação para cada instância, que produz uma AMI em cada instância.

aws ssm start-automation-execution 
    --document-name AWS-CreateImage \
    --target-parameter-name InstanceId \
    --targets Key=ParameterValues,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE

nota

AutomationAssumeRole não é um parâmetro válido. Não escolha esse item ao executar fluxos automações que direcionam um valor de parâmetro.

Direcionar mapas de valores de parâmetros

A opção TargetMaps expande sua capacidade de direcionar ParameterValues. Você pode inserir um conjunto de valores de parâmetro usando TargetMaps na linha de comando. Você pode especificar um máximo de 50 valores de parâmetro na linha de comando. Se quiser executar comandos que especificam mais de 50 valores de parâmetro, você poderá inserir os valores em um arquivo JSON. Você pode, então, chamar o arquivo da linha de comando.

nota

A opção TargetMaps não tem suporte no console.

Use o formato a seguir para especificar vários valores de parâmetro usando a opção TargetMaps em um comando. Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

aws ssm start-automation-execution \
    --document-name runbook name \
    --target-maps “parameter=value, parameter 2=value, parameter 3=value”  “parameter 4=value, parameter 5=value, parameter 6=value”
                        

Se você deseja inserir mais de 50 valores de parâmetro para a opção TargetMaps, especifique os valores em um arquivo usando o seguinte formato JSON. Usar um arquivo JSON também melhora a legibilidade ao fornecer vários valores de parâmetro.

[

    {“parameter”: "value", “parameter 2”: "value", “parameter 3”: "value"},

    {“parameter 4”: "value", “parameter 5”: "value", "parameter 6": "value"}

]

Salve o arquivo com a extensão .json. Você pode chamar o arquivo usando o seguinte comando: Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

aws ssm start-automation-execution \
    --document-name runbook name \
    –-parameters input parameters \
    --target-maps path to file/file name.json

Você também pode baixar o arquivo de um bucket do Amazon Simple Storage Service (Amazon S3), desde que tenha permissão para ler dados do bucket. Use o seguinte formato de comando: Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

aws ssm start-automation-execution \
    --document-name runbook name \
    --target-maps http://DOC-EXAMPLE-BUCKET.s3.amazonaws.com/file_name.json

Este é um cenário de exemplo para ajudar você a compreender a opção TargetMaps. Nesse cenário, um usuário deseja criar instâncias do Amazon EC2 de diferentes tipos em diferentes AMIs. Para executar essa tarefa, o usuário cria um runbook chamado AMI_Testing. Este runbook define dois parâmetros de entrada: instanceType e imageId.

{
  "description": "AMI Testing",
  "schemaVersion": "0.3",
  "assumeRole": "{{assumeRole}}",
  "parameters": {
    "assumeRole": {
      "type": "String",
      "description": "Role under which to run the automation",
      "default": ""
    },
    "instanceType": {
      "type": "String",
      "description": "Type of EC2 Instance to launch for this test"
    },
    "imageId": {
      "type": "String",
      "description": "Source AMI id from which to run instance"
    }
  },
  "mainSteps": [
    {
      "name": "runInstances",
      "action": "aws:runInstances",
      "maxAttempts": 1,
      "onFailure": "Abort",
      "inputs": {
        "ImageId": "{{imageId}}",
        "InstanceType": "{{instanceType}}",
        "MinInstanceCount": 1,
        "MaxInstanceCount": 1
      }
    }
  ],
  "outputs": [
    "runInstances.InstanceIds"
  ]
}

O usuário especifica os seguintes valores de parâmetro de destino em um arquivo chamado AMI_instance_types.json.

[
  {
    "instanceType" : ["t2.micro"],     
    "imageId" : ["ami-b70554c8"]     
  },
  {
    "instanceType" : ["t2.small"],     
    "imageId" : ["ami-b70554c8"]     
  },
  {
    "instanceType" : ["t2.medium"],     
    "imageId" : ["ami-cfe4b2b0"]     
  },
  {
    "instanceType" : ["t2.medium"],     
    "imageId" : ["ami-cfe4b2b0"]     
  },
  {
    "instanceType" : ["t2.medium"],     
    "imageId" : ["ami-cfe4b2b0"]     
  }
]

O usuário pode executar a automação e criar as cinco instâncias do EC2 definidas em AMI_instance_types.json, executando o seguinte comando:

aws ssm start-automation-execution \
    --document-name AMI_Testing \
    --target-parameter-name imageId \
    --target-maps file:///home/TestUser/workspace/runinstances/AMI_instance_types.json

Direcionar todas as instâncias do Amazon EC2

É possível executar uma automação em todas as instâncias do Amazon EC2 na Conta da AWS e na Região da AWS atuais ao escolher Todas as instâncias na lista Destinos. Por exemplo, se você quiser reiniciar todas as instâncias do Amazon EC2 em sua Conta da AWS e nas Região da AWS atuais, escolha o runbook AWS-RestartEC2Instance e selecione Todas as instâncias na lista Destinos.

Depois de escolher All instances (Todas as instâncias), o Systems Manager preenche o campo Instância com um asterisco (*) e torna o campo indisponível para alterações (o campo ficará esmaecido). O Systems Manager também torna o campo InstanceId em Input parameters (Parâmetros de entrada) indisponível para alterações. Tornar esses campos indisponíveis para alterações será o comportamento esperado se você optar por direcionar todas as instâncias.