Execute tarefas do AWS Systems Manager Automation de forma síncrona a partir do AWS Step Functions - Recomendações da AWS
ResumoPré-requisitos e limitaçõesArquiteturaFerramentasÉpicosRecursos relacionadosMais informações

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Execute tarefas do AWS Systems Manager Automation de forma síncrona a partir do AWS Step Functions

Criado por Elie El khoury (AWS)

Repositório de códigos: amazon-stepfunctions-ssm-waitfortasktoken

Ambiente: produção

Tecnologias: sem servidor; computação do DevOps usuário final; operações

Serviços da AWS: AWS Step Functions; AWS Systems Manager

Resumo

Esse padrão explica como se integrar AWS Step Functions com AWS Systems Manager o. Ele usa integrações de serviços do AWS SDK para chamar a startAutomationExecutionAPI Systems Manager com um token de tarefa de um fluxo de trabalho de uma máquina de estado e faz uma pausa até que o token retorne com uma chamada bem-sucedida ou com falha. Para demonstrar a integração, esse padrão implementa um invólucro de documento de automação (runbook) ao redor do AWS-RunPowerShellScript documento AWS-RunShellScript ou e é usado .waitForTaskToken para chamar ou de forma síncrona. AWS-RunShellScript AWS-RunPowerShellScript Para obter mais informações sobre as integrações de serviços do AWS SDK no Step Functions, consulte o AWS Step Functions Developer Guide.

O Step Functions é um serviço de fluxo de trabalho visual de baixo código que você pode usar para criar aplicativos distribuídos, automatizar processos de negócios e de TI e criar pipelines de dados e aprendizado de máquina usando serviços. AWS Os fluxos de trabalho gerenciam falhas, novas tentativas, paralelização, integrações de serviços e observabilidade para que você possa se concentrar em uma lógica de negócios de maior valor.

A automação, uma capacidade do AWS Systems Manager, simplifica tarefas comuns de manutenção, implantação e remediação, Serviços da AWS como Amazon Elastic Compute Cloud (Amazon EC2), Amazon Relational Database Service (Amazon RDS), Amazon Redshift e Amazon Simple Storage Service (Amazon S3). Com o Automation, você tem controle granular sobre a simultaneidade de suas automações. Por exemplo, você pode especificar quantos recursos a destinar simultaneamente e quantos erros podem ocorrer antes que uma automação seja interrompida.

Para obter detalhes da implementação, incluindo etapas, parâmetros e exemplos do runbook, consulte a seção Informações adicionais.

Pré-requisitos e limitações

Pré-requisitos

  • Uma AWS conta ativa

  • AWS Identity and Access Management Permissões (IAM) para acessar Step Functions e Systems Manager

  • Uma instância do EC2 com o Systems Manager Agent (SSM Agent) instalado na instância

  • Um perfil de instância do IAM para Systems Manager anexado à instância em que você planeja executar o runbook

  • Um papel de Step Functions que tem as seguintes permissões do IAM (que seguem o princípio do privilégio mínimo):

{
             "Effect": "Allow",
             "Action": "ssm:StartAutomationExecution",
             "Resource": "*"
 }

Versões do produto

  • Esquema do documento SSM versão 0.3 ou mais recente

  • SSM Agent versão 2.3.672.0 ou mais recente

Arquitetura

Pilha de tecnologias de destino

  • AWS Step Functions

  • AWS Systems Manager Automation

Arquitetura de destino

Arquitetura para executar tarefas de automação do Systems Manager de forma síncrona a partir do Step Functions

Automação e escala

Ferramentas

Serviços da AWS

  • AWS CloudFormationajuda você a configurar AWS recursos, provisioná-los de forma rápida e consistente e gerenciá-los em todo o ciclo de vida em todas Contas da AWS as regiões.

  • AWS Identity and Access Management (IAM) ajuda você a gerenciar com segurança o acesso aos seus AWS recursos controlando quem está autenticado e autorizado a usá-los.

  • AWS Step Functionsé um serviço de orquestração sem servidor que ajuda você a combinar AWS Lambda funções e outras Serviços da AWS para criar aplicativos essenciais para os negócios.

  • O AWS Systems Manager ajuda você a gerenciar suas aplicações e infraestrutura em execução na Nuvem AWS. Ele simplifica o gerenciamento de aplicativos e recursos, reduz o tempo para detectar e resolver problemas operacionais e ajuda você a gerenciar seus AWS recursos com segurança em grande escala.

Código

O código desse padrão está disponível no repositório de implementação do GitHub Step Functions and Systems Manager. 

Épicos

TarefaDescriçãoHabilidades necessárias

Faça o download do CloudFormation modelo.

Baixe o ssm-automation-documents.cfn.json modelo da cloudformation  pasta do GitHub repositório.

AWS DevOps

Crie runbooks.

Faça login no AWS Management Console, abra o AWS CloudFormation console e implante o modelo. Para obter mais informações sobre a implantação CloudFormation de modelos, consulte Criação de uma pilha no AWS CloudFormation console na CloudFormation documentação. 

O CloudFormation modelo implanta três recursos:

  • SfnRunCommandByInstanceIds— Runbook que permite executar AWS-RunShellScript ou usar IDs AWS-RunPowerShellScript de instância.

  • SfnRunCommandByTargets— Runbook que permite correr AWS-RunShellScript ou AWS-RunPowerShellScript usar alvos.

  • SSMSyncRole— A função do IAM assumida pelos runbooks.

AWS DevOps
TarefaDescriçãoHabilidades necessárias

Criar uma máquina de estado de teste.

Siga as instruções no Guia do AWS Step Functions desenvolvedor para criar e executar uma máquina de estado. Para a definição, use o código a seguir. Certifique-se de atualizar o valor InstanceIds com o ID de uma instância válida habilitada para o Systems Manager em sua conta.

{
  "Comment": "A description of my state machine",
  "StartAt": "StartAutomationWaitForCallBack",
  "States": {
    "StartAutomationWaitForCallBack": {
      "Type": "Task",
      "Resource": "arn:aws:states:::aws-sdk:ssm:startAutomationExecution.waitForTaskToken",
      "Parameters": {
        "DocumentName": "SfnRunCommandByInstanceIds",
        "Parameters": {
          "InstanceIds": [
            "i-1234567890abcdef0"
          ],
          "taskToken.$": "States.Array($$.Task.Token)",
          "workingDirectory": [
            "/home/ssm-user/"
          ],
          "Commands": [
            "echo \"This is a test running automation waitForTaskToken\" >> automation.log",
            "sleep 100"
          ],
          "executionTimeout": [
              "10800"
          ],
          "deliveryTimeout": [
              "30"
          ],
          "shell": [
              "Shell"
          ]
            }
      },
      "End": true
    }
  }
}

Esse código chama o runbook para executar dois comandos que demonstram a chamada waitForTaskToken para Systems Manager Automation.

O valor do shell parâmetro (ShellouPowerShell) determina se o documento de automação é executado AWS-RunShellScript ouAWS-RunPowerShellScript.

A tarefa grava “Este é um waitForTask token de automação de execução de teste” no /home/ssm-user/automation.log arquivo e, em seguida, dorme por 100 segundos antes de responder com o token da tarefa e liberar a próxima tarefa no fluxo de trabalho.

Se você quiser chamar o runbook SfnRunCommandByTargets em vez disso, substitua a seção Parameters do código anterior pela seguinte:

"Parameters": {
          "Targets": [
            {
              "Key": "InstanceIds",
              "Values": [
                "i-02573cafcfEXAMPLE",
                "i-0471e04240EXAMPLE"
              ]
            }
          ],
AWS DevOps

Atualize o perfil do IAM para a máquina de estado.

A etapa anterior cria automaticamente um perfil do IAM dedicado para a máquina de estado. No entanto, ele não concede permissões para chamar o runbook. Atualize o perfil adicionando as seguintes permissões:

{
      "Effect": "Allow",
      "Action": "ssm:StartAutomationExecution",
      "Resource": "*"
 }
AWS DevOps

Valide as chamadas síncronas.

Execute a máquina de estado para validar a chamada síncrona entre Step Functions e Systems Manager Automation. 

Para obter um exemplo de resultado, consulte a seção Informações adicionais. 

AWS DevOps

Recursos relacionados

Mais informações

Detalhes da implantação

Esse padrão fornece um CloudFormation modelo que implanta dois runbooks do Systems Manager:

  • SfnRunCommandByInstanceIdsexecuta o AWS-RunPowerShellScript comando AWS-RunShellScript or usando IDs de instância.

  • SfnRunCommandByTargetsexecuta o AWS-RunPowerShellScript comando AWS-RunShellScript or usando alvos.

Cada runbook implementa quatro etapas para obter uma chamada síncrona ao usar a .waitForTaskToken opção em Step Functions.

Etapa

Ação

Descrição

1

Branch

Verifica o valor do shell parâmetro (ShellouPowerShell) para decidir se deve ser executado AWS-RunShellScript no Linux ou AWS-RunPowerShellScript no Windows.

2

RunCommand_Shell ou RunCommand_PowerShell

Recebe várias entradas e executa o RunPowerShellScript comando RunShellScript or. Para obter mais informações, verifique a guia Detalhes do documento RunCommand_Shell ou RunCommand_PowerShell Automação no console do Systems Manager.

3

SendTaskFailure

É executado quando a etapa 2 é abortada ou cancelada. Ele chama a API send_task_failure do Step Functions, que aceita três parâmetros como entrada: o token aprovado pela máquina de estado, o erro de falha e uma descrição da causa da falha.

4

SendTaskSuccess

É executado quando a etapa 2 é bem-sucedida. Ele chama a API send_task_success do Step Functions, que aceita o token passado pela máquina de estado como entrada.

Parâmetros do runbook

SfnRunCommandByInstanceIdscaderno de execução:

Nome do parâmetro

Tipo

Opcional ou obrigatório

Descrição

shell

Cadeia de caracteres

Obrigatório

O shell de instâncias para decidir se deve ser executado AWS-RunShellScript no Linux ou AWS-RunPowerShellScript no Windows.

deliveryTimeout

Inteiro

Opcional

O tempo, em segundos, de espera pela entrega de um comando ao agente SSM em uma instância. Esse parâmetro tem um valor mínimo de 30 (0,5 minuto) e um valor máximo de 2592000 (720 horas).

executionTimeout

String

Opcional

O tempo em segundos para um comando ser concluído antes de ser considerado como tendo falhado. O valor padrão é 3600 (1 hora). O valor máximo é 172800 (48 horas).

workingDirectory

String

Opcional

O caminho para o diretório de trabalho em sua instância.

Commands

StringList

Obrigatório

O script ou comando do shell a ser executado.

InstanceIds

StringList

Obrigatório

Os IDs das instâncias onde você deseja executar o comando.

taskToken

String

Obrigatório

O token de tarefa a ser usado para respostas de retorno de chamada.

SfnRunCommandByTargetscaderno de execução:

Nome

Tipo

Opcional ou obrigatório

Descrição

shell

Cadeia de caracteres

Obrigatório

O shell de instâncias para decidir se deve ser executado AWS-RunShellScript no Linux ou AWS-RunPowerShellScript no Windows.

deliveryTimeout

Inteiro

Opcional

O tempo, em segundos, de espera pela entrega de um comando ao agente SSM em uma instância. Esse parâmetro tem um valor mínimo de 30 (0,5 minuto) e um valor máximo de 2592000 (720 horas).

executionTimeout

Inteiro

Opcional

O tempo em segundos para um comando ser concluído antes de ser considerado como tendo falhado. O valor padrão é 3600 (1 hora). O valor máximo é 172800 (48 horas).

workingDirectory

String

Opcional

O caminho para o diretório de trabalho em sua instância.

Commands

StringList

Obrigatório

O script ou comando do shell a ser executado.

Targets

MapList

Obrigatório

Uma matriz de critérios de pesquisa que identifica instâncias usando os pares de chave-valor que você especificar. Por exemplo: [{"Key":"InstanceIds","Values":["i-02573cafcfEXAMPLE","i-0471e04240EXAMPLE"]}]

taskToken

String

Obrigatório

O token de tarefa a ser usado para respostas de retorno de chamada.

Exemplo de saída

A tabela a seguir fornece um exemplo de saída da Step Function. Ele mostra que o tempo total de execução é superior a 100 segundos entre a etapa 5 (TaskSubmitted) e a etapa 6 (TaskSucceeded). Isso demonstra que a função step aguardou a conclusão do sleep 100 comando antes de passar para a próxima tarefa no fluxo de trabalho.

ID

Tipo

Etapa

Recurso

Tempo decorrido (ms)

Timestamp

1

ExecutionStarted

-

0

11 de março de 2022 14:50:34.303

2

TaskStateEntered

StartAutomationWaitForCallBack

-

40

11 de março de 2022 14:50:34.343

3

TaskScheduled

StartAutomationWaitForCallBack

-

40

11 de março de 2022 14:50:34.343

4

TaskStarted

StartAutomationWaitForCallBack

-

154

11 de março de 2022 14:50:34.457

5

TaskSubmitted

StartAutomationWaitForCallBack

-

657

11 de março de 2022 14:50:34.960

6

TaskSucceeded

StartAutomationWaitForCallBack

-

103835

11 de março de 2022 14:52:18.138

7

TaskStateExited

StartAutomationWaitForCallBack

-

103860

11 de março de 2022 14:52:18.163

8

ExecutionSucceeded

-

103897

11 de março de 2022 14:52:18.200