Programação de automações com associações do State Manager - AWS Systems Manager
Criar uma associação que executa uma automação (console)Criar uma associação que executa uma automação (linha de comando)Automações de solução de problemas executadas por associações do State Manager

Programação de automações com associações do State Manager

Você pode iniciar uma automação criando uma associação do State Manager com um runbook. O State Manager é um recurso do AWS Systems Manager. Ao criar uma associação do State Manager com um runbook, você pode direcionar diferentes tipos de recursos da AWS. Por exemplo, é possível criar associações que aplicam um estado desejado a um recurso da AWS, incluindo o seguinte:

  • Anexe uma função do Systems Manager às instâncias do Amazon Elastic Compute Cloud (Amazon EC2) para torná-las instâncias gerenciadas.

  • Aplicar regras de entrada e saída desejadas a um grupo de segurança.

  • Crie ou exclua backups do Amazon DynamoDB.

  • Crie ou exclua snapshots do Amazon Elastic Block Store (Amazon EBS).

  • Desative as permissões de leitura e gravação em buckets do Amazon Simple Storage Service (Amazon S3).

  • Inicie, reinicie ou interrompa instâncias gerenciadas e instâncias do Amazon Relational Database Service (Amazon RDS).

  • Aplique patches às macOS do Linux, AMIs e Windows.

Use os procedimentos a seguir para criar uma associação do State Manager que executa uma automação usando o console do AWS Systems Manager e a AWS Command Line Interface (AWS CLI). Para obter informações gerais sobre associações e informações sobre como criar uma associação que usa um documento SSM Command ou um documento Policy, consulte Criar associações.

Antes de começar

Observe estes detalhes importantes, antes de executar uma automação usando o State Manager.

  • Antes de criar uma associação que executa um runbook, verifique se você configurou permissões para o Automation, um recurso do AWS Systems Manager. Para ter mais informações, consulte Configurar a automação.

  • As associações do State Manager que executam runbooks contribuem para o número máximo de automações em execução simultânea na sua conta da Conta da AWS. É possível ter no máximo 100 automações em execução ao mesmo tempo. Para obter informações, consulte as cotas de serviço do Systems Manager no Referência geral da Amazon Web Services.

  • Ao executar uma automação, o State Manager não registra em log as operações de API iniciadas pela automação em AWS CloudTrail.

  • O Systems Manager cria automaticamente uma função vinculada ao serviço para que o State Manager tenha permissão para chamar operações de API do Systems Manager Automation. Se desejar, você pode criar a função vinculada ao serviço por conta própria executando o seguinte comando na AWS CLI ou no AWS Tools for PowerShell.

    Linux & macOS
    aws iam create-service-linked-role \
--aws-service-name ssm.amazonaws.com
    Windows
    aws iam create-service-linked-role ^
--aws-service-name ssm.amazonaws.com
    PowerShell
    New-IAMServiceLinkedRole `
-AWSServiceName ssm.amazonaws.com

    Para obter mais informações sobre funções vinculadas ao serviço, consulte Usar funções vinculadas ao serviço do Systems Manager.

Criar uma associação que executa uma automação (console)

O procedimento a seguir descreve como usar o console do Systems Manager para criar uma associação do State Manager que executa uma automação.

Como criar uma associação do State Manager que execute uma automação

  1. Abra o console AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha State Manager e selecione Create association.

  3. No campo Name, especifique um nome. Isso é opcional, mas recomendado.

  4. Na lista Document (Documento), escolha um runbook. Use a barra de pesquisa para filtrar os runboks Document type : Equal : Automation. Para visualizar mais runbooks, use os números à direita da barra de pesquisa.

    nota

    Você pode visualizar informações sobre um runbook, selecionando o nome dele.

  5. Escolha Simple execution (Execução simples) para executar a automação em um ou mais destinos, especificando o ID do recurso desses destinos. Escolha Rate control (Controle de taxa) para executar a automação em uma frota de recursos da AWS, especificando uma opção de direcionamento, como tags ou o AWS Resource Groups. Você também pode controlar a operação da automação nos seus recursos, especificando a simultaneidade e limites de erro.

    Se você escolheu Rate control (Controle de taxa), a seção Targets (Destinos) será exibida.

  6. Na seção Targets (Destinos), escolha um método para definir recursos de direcionamento.

    1. (Necessário) Na lista Parameter (Parâmetro), escolha um parâmetro. Os itens na lista Parameter (Parâmetro) são determinados pelos parâmetros no runbook que você selecionou no início deste procedimento. Ao escolher um parâmetro, você define o tipo de recurso no qual a automação é executada.

    2. (Necessário) Na lista Targets (Destinos), escolha um método para definir destinos para os recursos.

      • Resource Group (Grupo de recursos): escolha o nome do grupo na lista Resource Group (Grupo de recursos). Para obter mais informações sobre o direcionamento do AWS Resource Groups em runbooks, consulte AWS Resource Groups como destino.

      • Tags: insira a chave de tag e (opcionalmente) o valor da tag nos campos fornecidos. Escolha Adicionar. Para obter mais informações sobre o direcionamento de tags em runbooks, consulte Definir uma etiqueta como destino.

      • Parameter Values (Valores de parâmetros): insira valores na seção Input parameters (Parâmetros de entrada). 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 a automação, 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. Para obter mais informações sobre direcionar valores de parâmetros em runbooks, consulte Direcionar valores de parâmetro.

  7. Na seção Input parameters (Parâmetros de entrada), especifique os parâmetros de entrada necessários.

    Se você optar por definir o destino dos recursos usando tags ou um grupo de recursos, talvez não precise escolher algumas das opções na seção Input parameters (Parâmetros de entrada). Por exemplo, se você tiver escolhido o runbook AWS-RestartEC2Instance, e definiu o destino das instâncias usando tags, você não precisará especificar ou escolher IDs de instância na seção Input parameters (Parâmetros de entrada). A automação localiza as instâncias para reiniciar usando as tags que você especificou.

    Importante

    Especifique um ARN de função no campo AutomationAssumeRole. O State Manager assume a função para chamar Serviços da AWS especificados no runbook e para executar associações do Automation em seu nome.

  8. Na seção Specify schedule (Especificar programação), escolha On Schedule (Na programação) se quiser executar a associação em intervalos regulares. Se você escolher essa opção, use as opções fornecidas para criar a programação usando expressões Cron ou Rate. Para obter mais informações sobre expressões Cron e Rate para o State Manager, consulte Expressões cron e rate para associações.

    nota

    Expressões de taxa são o mecanismo preferencial de programação para associações do State Manager que usam runbooks. Essas expressões proporcionam mais flexibilidade para a execução de associações, caso você atinja o número máximo de automações executadas ao mesmo tempo. Com uma programação de taxas, o Systems Manager pode tentar a automação novamente logo depois de receber a notificação de que as automações simultâneas atingiram seu limite máximo e foram controladas.

    Escolha No schedule (Sem programação) se quiser executar a associação apenas uma vez.

  9. (Opcional) Na seção Rate Control (Controle de taxa), escolha as opções Concurrency (Simultaneidade) e Error threshold (Limiar de erros) para controlar a implantação da automação nos seus recursos da AWS.

    1. Na seção Concurrency (Simultaneidade), escolha uma opção:

      • Escolha targets (destinos) para inserir um número absoluto de destinos que podem executar a automação simultaneamente.

      • Escolha percentage (porcentagem) para inserir uma porcentagem do conjunto de destino que pode executar a automação simultaneamente.

    2. Na seção Error threshold (Limite de erro), escolha uma opção:

      • Escolha errors (erros) para inserir um número absoluto de erros permitidos antes que o Automation pare de enviar a automação para outros recursos.

      • Escolha percent (por cento) para inserir uma porcentagem de erros permitidos antes que o Automation pare de enviar a automação para outros recursos.

    Para obter mais informações sobre o uso de destinos e controles de taxa com a Automação, consulte Executar operações automatizadas em escala.

  10. Escolha Create Association (Criar associação).

    Importante

    Quando você cria uma associação, ela é executada imediatamente nos destinos especificados. Em seguida, a associação é executada com base na expressão Cron ou Rate que você escolheu. Se você escolheu No schedule (Sem programação), a associação não será executada novamente.

Criar uma associação que executa uma automação (linha de comando)

O procedimento a seguir descreve como usar a AWS CLI (no Linux ou no Windows) ou o AWS Tools for PowerShell para criar uma associação do State Manager que executa uma automação.

Antes de começar

Antes de concluir o procedimento a seguir, certifique-se de ter criado uma função de serviço do IAM com as permissões necessárias para executar o runbook e configurado uma relação de confiança para automação, um recurso do AWS Systems Manager. Para ter mais informações, consulte Tarefa 1: Criar uma função de serviço para a automação.

Para criar uma associação que executa uma automação

  1. Instale e configure a AWS CLI ou o AWS Tools for PowerShell, caso ainda não o tenha feito.

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

  2. Execute o comando a seguir para visualizar uma lista de documentos.

    Linux & macOS
    aws ssm list-documents
    Windows
    aws ssm list-documents
    PowerShell
    Get-SSMDocumentList

    Anote o nome do runbook que você quer usar para a associação.

  3. Execute o comando a seguir para visualizar os detalhes sobre o runbook. No comando a seguir, substitua runbook name por suas próprias informações.

    Linux & macOS
    aws ssm describe-document \
--name runbook name

    Anote o nome de um parâmetro (por exemplo, InstanceId) que você deseja usar para a opção --automation-target-parameter-name. Esse parâmetro determina o tipo de recurso em que a automação é executada.

    Windows
    aws ssm describe-document ^
--name runbook name

    Anote o nome de um parâmetro (por exemplo, InstanceId) que você deseja usar para a opção --automation-target-parameter-name. Esse parâmetro determina o tipo de recurso em que a automação é executada.

    PowerShell
    Get-SSMDocumentDescription `
-Name runbook name

    Anote o nome de um parâmetro (por exemplo, InstanceId) que você deseja usar para a opção AutomationTargetParameterName. Esse parâmetro determina o tipo de recurso em que a automação é executada.

  4. Crie um comando que execute uma automação usando uma associação do State Manager. Substitua cada espaço reservado para recurso de exemplo por suas próprias informações.

    Definir destino usando tags

    Linux & macOS
    aws ssm create-association \
--association-name association name \
--targets Key=tag:key name,Values=value \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression"
    nota

    Se você criar uma associação usando o AWS CLI, use o parâmetro --targets para as instâncias de destino da associação. Não use o parâmetro --instance-id. O parâmetro --instance-id é um parâmetro legado.

    Windows
    aws ssm create-association ^
--association-name association name ^
--targets Key=tag:key name,Values=value ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression"
    nota

    Se você criar uma associação usando o AWS CLI, use o parâmetro --targets para as instâncias de destino da associação. Não use o parâmetro --instance-id. O parâmetro --instance-id é um parâmetro legado.

    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "tag:key name"
$Targets.Values = "value"

New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole" } `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression"
    nota

    Se você criar uma associação usando o AWS Tools for PowerShell, use o parâmetro Target para as instâncias de destino da associação. Não use o parâmetro InstanceId. O parâmetro InstanceId é um parâmetro legado.

    Definir destino usando valores de parâmetro

    Linux & macOS
    aws ssm create-association \
--association-name association name \
--targets Key=ParameterValues,Values=value,value 2,value 3 \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression"
    Windows
    aws ssm create-association ^
--association-name association name ^
--targets Key=ParameterValues,Values=value,value 2,value 3 ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression"
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ParameterValues"
$Targets.Values = "value","value 2","value 3"

New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole"} `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression"

    Definir destino usando AWS Resource Groups

    Linux & macOS
    aws ssm create-association \
--association-name association name \
--targets Key=ResourceGroup,Values=resource group name \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression"
    Windows
    aws ssm create-association ^
--association-name association name ^
--targets Key=ResourceGroup,Values=resource group name ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression"
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "resource group name"

New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole"} `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression"

    Selecionar várias contas e regiões como destino

    Linux & macOS
    aws ssm create-association \
--association-name association name \
--targets Key=ResourceGroup,Values=resource group name \
--name runbook name \
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole \
--automation-target-parameter-name target parameter \
--schedule "cron or rate expression" \ 
--target-locations Accounts=111122223333,444455556666,444455556666,Regions=region,region
    Windows
    aws ssm create-association ^
--association-name association name ^
--targets Key=ResourceGroup,Values=resource group name ^
--name runbook name ^
--parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/RunbookAssumeRole ^
--automation-target-parameter-name target parameter ^
--schedule "cron or rate expression" ^ 
--target-locations Accounts=111122223333,444455556666,444455556666,Regions=region,region
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "resource group name"

New-SSMAssociation `
-AssociationName "association name" `
-Target $Targets `
-Name "runbook name" `
-Parameters @{
"AutomationAssumeRole"="arn:aws:iam::123456789012:role/RunbookAssumeRole"} `
-AutomationTargetParameterName "target parameter" `
-ScheduleExpression "cron or rate expression" `
-TargetLocations @{
    "Accounts"=["111122223333,444455556666,444455556666"],
    "Regions"=["region,region"]

    O comando retorna detalhes da nova associação semelhantes ao seguinte.

    Linux & macOS
    {
"AssociationDescription": {
    "ScheduleExpression": "cron(0 7 ? * MON *)",
    "Name": "AWS-StartEC2Instance",
    "Parameters": {
        "AutomationAssumeRole": [
            "arn:aws:iam::123456789012:role/RunbookAssumeRole"
        ]
    },
    "Overview": {
        "Status": "Pending",
        "DetailedStatus": "Creating"
    },
    "AssociationId": "1450b4b7-bea2-4e4b-b340-01234EXAMPLE",
    "DocumentVersion": "$DEFAULT",
    "AutomationTargetParameterName": "InstanceId",
    "LastUpdateAssociationDate": 1564686638.498,
    "Date": 1564686638.498,
    "AssociationVersion": "1",
    "AssociationName": "CLI",
    "Targets": [
        {
            "Values": [
                "DEV"
            ],
            "Key": "tag:ENV"
        }
    ]
}
}
    Windows
    {
"AssociationDescription": {
    "ScheduleExpression": "cron(0 7 ? * MON *)",
    "Name": "AWS-StartEC2Instance",
    "Parameters": {
        "AutomationAssumeRole": [
            "arn:aws:iam::123456789012:role/RunbookAssumeRole"
        ]
    },
    "Overview": {
        "Status": "Pending",
        "DetailedStatus": "Creating"
    },
    "AssociationId": "1450b4b7-bea2-4e4b-b340-01234EXAMPLE",
    "DocumentVersion": "$DEFAULT",
    "AutomationTargetParameterName": "InstanceId",
    "LastUpdateAssociationDate": 1564686638.498,
    "Date": 1564686638.498,
    "AssociationVersion": "1",
    "AssociationName": "CLI",
    "Targets": [
        {
            "Values": [
                "DEV"
            ],
            "Key": "tag:ENV"
        }
    ]
}
}
    PowerShell
    Name                  : AWS-StartEC2Instance
InstanceId            : 
Date                  : 8/1/2019 7:31:38 PM
Status.Name           : 
Status.Date           : 
Status.Message        : 
Status.AdditionalInfo :
nota

Se você usar tags para criar uma associação em uma ou mais instâncias de destino e, em seguida, remover as tags de uma instância, essa instância não executará mais a associação. A instância será dissociada do documento do State Manager.

Automações de solução de problemas executadas por associações do State Manager

O Systems Manager Automation impõe um limite de 100 automações simultâneas e 1.000 automações em fila por conta e região. Se uma associação do State Manager que executa um runbook para mostrar um status Failed (Falha) e um status detalhado de AutomationExecutionLimitExceeded, isso significa que a automação pode ter atingido o limite. Como resultado, o Systems Manager controlará as automações. Para resolver esse problema, faça o seguinte:

  • Use uma expressão Cron ou Rate diferente para a sua associação. Por exemplo, se a associação estiver programada para execução a cada 30 minutos, altere-a para que ela seja executada a cada uma ou duas horas.

  • Exclua as automações existentes com um status Pending (Pendente). Ao excluir essas automações, você limpa a fila atual.