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 *Elie El khoury, Amazon Web Services* ## 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 **startAutomationExecution**API 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](https://docs.aws.amazon.com/step-functions/latest/dg/supported-services-awssdk.html) 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](#run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions-additional). ## 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 EC2 instância com o Systems Manager Agent (SSM Agent) [instalado](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-agent.html) na instância + [Um perfil de instância do IAM para Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html) 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](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/images/pattern-img/47c19e4f-d68d-4f91-bb68-202098757529/images/2d248aae-d858-4565-8af2-593cde0da780.png) **Automação e escala** + Esse padrão fornece um AWS CloudFormation modelo que você pode usar para implantar os runbooks em várias instâncias. (Consulte o repositório de [implementação do GitHub Step Functions e do Systems Manager](https://github.com/aws-samples/amazon-stepfunctions-ssm-waitfortasktoken).) ## Ferramentas **Serviços da AWS** + [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)ajuda 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)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) 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](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)é 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](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html) 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](https://github.com/aws-samples/amazon-stepfunctions-ssm-waitfortasktoken).  ## Épicos ### Crie runbooks | Tarefa | Description | Habilidades 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 Console de gerenciamento da AWS, abra o [CloudFormation console](https://console.aws.amazon.com/cloudformation/) e implante o modelo. Para obter mais informações sobre a implantação CloudFormation de modelos, consulte [Criação de uma pilha no CloudFormation console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html) na CloudFormation documentação. 
O CloudFormation modelo implanta três recursos:[See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/prescriptive-guidance/latest/patterns/run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions.html) | AWS DevOps | ### Criar um exemplo de máquina de estado | Tarefa | Description | Habilidades necessárias | | --- | --- | --- | | Criar uma máquina de estado de teste. | Siga as instruções no [Guia do AWS Step Functions desenvolvedor](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html) 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 (`Shell`ou`PowerShell`) determina se o documento de automação é executado `AWS-RunShellScript` ou`AWS-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](#run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions-additional).  | AWS DevOps | ## Recursos relacionados + [Introdução ao AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html) (*Guia AWS Step Functions do desenvolvedor*) + [Aguarde um retorno de chamada com o token da tarefa](https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token) (*Guia do AWS Step Functions desenvolvedor*, padrões de integração de serviços) + Chamadas de API [send\_task\_success](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_success.html) and [send\_task\_failure](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_failure.html) (documentação do Boto3)  + [AWS Systems Manager Automação](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-automation.html) (*Guia AWS Systems Manager do usuário*) ## Mais informações **Detalhes da implantação** Esse padrão fornece um CloudFormation modelo que implanta dois runbooks do Systems Manager: + `SfnRunCommandByInstanceIds`executa o `AWS-RunPowerShellScript` comando `AWS-RunShellScript` or usando a instância IDs. + `SfnRunCommandByTargets`executa 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 | Description | | --- |--- |--- | | **1** | `Branch` | Verifica o valor do `shell` parâmetro (`Shell`ou`PowerShell`) 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](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_failure.html) 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](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_success.html) do Step Functions, que aceita o token passado pela máquina de estado como entrada. | **Parâmetros do runbook** `SfnRunCommandByInstanceIds`caderno de execução: | | | Nome do parâmetro | Tipo | Opcional ou obrigatório | Description | | --- |--- |--- |--- | | `shell` | String | 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 | A IDs das instâncias em que você deseja executar o comando. | | `taskToken` | String | Obrigatório | O token de tarefa a ser usado para respostas de retorno de chamada. | `SfnRunCommandByTargets`caderno de execução: | | | Nome | Tipo | Opcional ou obrigatório | Description | | --- |--- |--- |--- | | `shell` | String | 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) | Registro de data e hora | | --- |--- |--- |--- |--- |--- | | **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 |