Uso do Document Builder para criar runbooks - AWS Systems Manager
Criação de um runbook usando o Document BuilderCrie um runbook que execute scripts

Uso do Document Builder para criar runbooks

Se os runbooks públicos do AWS Systems Manager, não forem compatíveis com todas as ações que você quiser executar em seus recursos da AWS, você poderá criar seus próprios runbooks. Para criar um runbook personalizado, é possível criar manualmente um arquivo local em formato YAML ou JSON com as ações de automação apropriadas. Como alternativa, é possível usar o Document Builder no console do Systems Manager Automation para criar um runbook personalizado.

Usando o Document Builder, é possível adicionar etapas de ação de automação ao runbook personalizado e fornecer os parâmetros necessários sem precisar usar sintaxes JSON ou YAML. Depois de adicionar etapas e criar o runbook, o sistema converterá as ações adicionadas para o formato YAML que o Systems Manager poderá usar para executar a automação.

Runbooks são compatíveis com o uso de Markdown, uma linguagem de marcação que permite adicionar descrições do estilo wiki a runbooks e etapas individuais dentro do runbook. Para obter mais informações sobre como usar Markdown, consulte Usar Markdown na AWS.

Criação de um runbook usando o Document Builder

Antes de começar

Recomendamos que você leia sobre as diferentes ações que podem ser usadas em um runbook. Para ter mais informações, consulte Referência de ações do Systems Manager Automation.

Para criar um runbook usando o Document Builder

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

  2. No painel de navegação, escolha Documents.

  3. Escolha Criar automação.

  4. Em Name (Nome), insira um nome descritivo para o runbook.

  5. Em Document description (Descrição do documento), forneça a descrição de estilo markdown para o runbook. Você pode fornecer instruções para usar o runbook, as etapas numeradas ou qualquer outro tipo de informação para descrever o runbook. Consulte o texto padrão para obter informações sobre como formatar o conteúdo.

    dica

    Alterne entre Hide preview (Ocultar visualização) e Show preview (Exibir visualização) para ver a aparência do conteúdo de descrição à medida que redige.

  6. (Opcional) Em Assume role (Função assumida), insira o nome ou ARN de uma função de serviço para executar ações em seu nome. Se você não especificar uma função, o Automation usará as permissões de acesso do usuário que executar a automação.

    Importante

    Para runbooks não pertencentes à Amazon que usam a ação aws:executeScript, uma função deverá ser especificada. Para ter mais informações, consulte Permissões para usar runbooks.

  7. (Opcional) Em Outputs (Saídas), insira saídas para a automação desse runbook a serem disponibilizadas para outros processos.

    Por exemplo, se o runbook criar uma nova AMI, você poderá especificar ["CreateImage.ImageId"] e usar essa saída para criar novas instâncias em uma automação subsequente.

  8. (Opcional) Expanda a seção Input parameters (Parâmetros de entrada) e faça o seguinte.

    1. Em Parameter name (Nome do parâmetro), insira um nome descritivo para o parâmetro do runbook que estiver criando.

    2. Em Type (Tipo), escolha um tipo para o parâmetro, como String ou MapList.

    3. Em Required (Obrigatório), siga um destes procedimentos:

      • Escolha Yes (Sim) se um valor para esse parâmetro de runbook precisar ser fornecido no runtime.

      • Selecione No (Não) se o parâmetro não for obrigatório e insira um valor de parâmetro padrão (opcional) em Default value (Valor padrão).

    4. Em Description (Descrição), insira uma descrição para o parâmetro do runbook.

    nota

    Para adicionar mais parâmetros do runbook, escolha Add a parameter (Adicionar um parâmetro). Para remover um parâmetro do runbook, escolha o botão X (Remover).

  9. (Opcional) Expanda a seção Target type (Tipo de destino) e escolha um tipo de destino para definir os tipos de recursos nos quais a automação pode ser executada. Por exemplo, para executar um runbook em instâncias do EC2, escolha /AWS::EC2::Instance.

    nota

    Se você especificar um valor de “/”, o runbook poderá ser executado em todos os tipos de recursos. Para obter uma lista dos tipos de recursos válidos, consulte Referência de tipos de recursos da AWS no Manual do usuário do AWS CloudFormation.

  10. (Opcional) Expanda a seção Document tags (Tags de documento) e insira um ou mais pares de chave-valor para aplicar ao runbook. As tags facilitam a identificação, organização e pesquisa de recursos.

  11. Na seção Step 1 (Etapa 1), forneça as seguintes informações.

    • Em Step name (Nome da etapa), insira um nome descritivo para a primeira etapa da automação.

    • Para Action type (Tipo de ação), selecione o tipo de ação a ser usado para esta etapa.

      Para obter uma lista e informações sobre os tipos de ação disponíveis, consulte Referência de ações do Systems Manager Automation.

    • Em Description (Descrição), insira uma descrição para a etapa de automação. Você pode usar Markdown para formatar o texto.

    • Dependendo do Action type (Tipo de ação) selecionado, insira as entradas necessárias para o tipo de ação na seção Step inputs (Entradas da etapa). Por exemplo, se você selecionou a ação aws:approve, deverá especificar um valor para a propriedade Approvers.

      Para obter informações sobre os campos de entrada de etapa, consulte a entrada em Referência de ações do Systems Manager Automation para o tipo de ação selecionado. Por exemplo: aws:executeStateMachine – Executa uma máquina de estado do AWS Step Functions.

    • (Opcional) Em Additional inputs (Entradas adicionais), forneça os valores de entrada adicionais necessários para o runbook. Os tipos de entrada disponíveis dependem do tipo de ação selecionado para a etapa. (Observe que alguns tipos de ação exigem valores de entrada.)

      nota

      Para adicionar mais entradas, escolha Add optional input (Adicionar entrada opcional). Para remover uma entrada, escolha o botão X (Remover).

    • (Opcional) Em Outputs (Saídas), insira saídas para essa etapa a serem disponibilizadas para outros processos.

      nota

      Outputs (Saídas) não está disponível para todos os tipos de ação.

    • (Opcional) Expanda a seção Common properties (Propriedades comuns) e especifique as propriedades para as ações comuns a todas as ações de automação. Por exemplo, em Timeout seconds (Segundos de tempo limite), você pode fornecer um valor em segundos para especificar quanto tempo a etapa pode ser executada antes de ser interrompida.

      Para ter mais informações, consulte Propriedades compartilhadas por todas as ações.

    nota

    Para adicionar mais etapas, selecione Add step (Adicionar etapa) e repita o procedimento de criação de uma etapa. Para remover uma etapa, escolha Remove step (Remover etapa).

  12. Escolha Create automation (Criar automação) para salvar o runbook.

Crie um runbook que execute scripts

O procedimento a seguir mostra como usar o Document Builder no console do AWS Systems Manager Automation para criar um runbook personalizado que execute um script.

A primeira etapa do runbook criado executa um script para executar uma instância do Amazon Elastic Compute Cloud (Amazon EC2). A segunda etapa executa outro script para monitorar para que a verificação de status da instância seja alterada ok. Depois, um status geral de Success é relatado para a automação.

Antes de começar

Você deve ter concluído as etapas a seguir:

  • Verifique se você tem privilégios de administrador ou se recebeu as permissões adequadas para acessar o Systems Manager no AWS Identity and Access Management (IAM).

    Para ter mais informações, consulte Verificar o acesso do usuário aos runbooks.

  • Verifique se você tem uma função de serviço do IAM para o Automation (também conhecida como uma função assumida) em sua Conta da AWS. A função é necessária pois essa demonstração usa a ação aws:executeScript.

    Para obter informações sobre como criar essa função, consulte Configurar o acesso a uma função de serviço (função assumida) para automações.

    Para obter informações sobre o requisito de função de serviço do IAM para a execução do aws:executeScript, consulte Permissões para usar runbooks.

  • Verifique se você tem permissão para executar instâncias do EC2.

    Para obter informações, consulte IAM e Amazon EC2 no Guia do usuário do Amazon EC2.

Para criar um runbook personalizado usando o Document Builder

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

  2. No painel de navegação, escolha Documents.

  3. Escolha Criar automação.

  4. Em Name (Nome), digite este nome descritivo para o runbook: LaunchInstanceAndCheckStatus.

  5. (Opcional) Em Document description (Descrição do documento), substitua o texto padrão por uma descrição desse runbook, usando Markdown (Marcação). Veja um exemplo a seguir.

    ##Title: LaunchInstanceAndCheckState
    -----
    **Purpose**: This runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this runbook continuously checks the instance status check value for the launched instance until the status ```ok``` is returned.
    
    ##Parameters:
    -----
    Name | Type | Description | Default Value
    ------------- | ------------- | ------------- | -------------
    assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | -
    imageId  | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}

  6. Em Assume role (Função assumida) insira o ARN da função de serviço do IAM para o Automation (função assumida) para a execução de automação, no formato arn:aws:iam::111122223333:role/AutomationServiceRole. Substitua o ID da Conta da AWS por 111122223333.

    A função especificada é usada para fornecer as permissões necessárias para iniciar a automação.

    Importante

    Para runbooks não pertencentes à Amazon que usam a ação aws:executeScript, uma função deverá ser especificada. Para ter mais informações, consulte Permissões para usar runbooks.

  7. Expanda Input parameters (Parâmetros de entrada) e faça o seguinte.

    1. Em Parameter name (Nome do parâmetro), insira imageId.

    2. Em Type (Tipo), escolha String.

    3. Em Required (Obrigatório), escolha No.

    4. Em Default value (Valor padrão), insira o seguinte.

      {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}
      nota

      Esse valor executa uma instância do Amazon EC2 usando o ID da Amazon Machine Image (AMI) do Amazon Linux 1 mais recente. Se você quiser usar uma AMI diferente, substitua o valor pelo ID da sua AMI.

    5. Em Description (Descrição), insira o seguinte.

      (Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux AMI ID.

  8. Escolha Add a parameter (Adicionar um parâmetro) para criar o segundo parâmetro, tagValue, e insira o seguinte.

    1. Em Parameter name (Nome do parâmetro), insira tagValue.

    2. Em Type (Tipo), escolha String.

    3. Em Required (Obrigatório), escolha No.

    4. Em Default value (Valor padrão), insira LaunchedBySsmAutomation. Isso adiciona o valor Name:LaunchedBySsmAutomation do par de chaves da tag à instância.

    5. Em Description (Descrição), insira o seguinte.

      (Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.

  9. Escolha Add a parameter (Adicionar um parâmetro) para criar o terceiro parâmetro, instanceType, e insira as informações a seguir.

    1. Em Parameter name (Nome do parâmetro), insira instanceType.

    2. Em Type (Tipo), escolha String.

    3. Em Required (Obrigatório), escolha No.

    4. Em Default value (Valor padrão), insira t2.micro.

    5. Em Parameter description (Descrição do parâmetro), insira o seguinte.

      (Optional) The instance type to use for the instance. The default value is t2.micro.

  10. Expanda Target type (Tipo de destino) e escolha "/".

  11. (Opcional) Expanda Document tags (Tags do documento) para aplicar tags de recurso ao runbook. Em Tag key (Chave de tag), insira Purpose e, em Tag value (Valor da tag), insira LaunchInstanceAndCheckState.

  12. Na seção Step 1 (Etapa 1), conclua as etapas a seguir.

    1. Em Step name (Nome da etapa), insira este nome descritivo para a primeira etapa da automação: LaunchEc2Instance.

    2. Em Action type (Tipo de ação), escolha Run a script (Executar um script) (aws:executeScript).

    3. Em Description (Descrição), insira uma descrição para a etapa de automação, como a seguinte.

      **About This Step**
    
    This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.

    4. Expanda Inputs (Entradas).

    5. Em Runtime, escolha a linguagem do runtime a ser usada para executar o script fornecido.

    6. Em Handler (Manipulador), insira launch_instance. Esse é o nome da função declarado no script a seguir.

      nota

      Isso não é necessário para o PowerShell.

    7. Em Script, substitua o conteúdo padrão pelo seguinte. Certifique-se de corresponder o script com o valor de runtime correspondente.

      Python
      def launch_instance(events, context):
      import boto3
      ec2 = boto3.client('ec2')
    
      image_id = events['image_id']
      tag_value = events['tag_value']
      instance_type = events['instance_type']
    
      tag_config = {'ResourceType': 'instance', 'Tags': [{'Key':'Name', 'Value':tag_value}]}
    
      res = ec2.run_instances(ImageId=image_id, InstanceType=instance_type, MaxCount=1, MinCount=1, TagSpecifications=[tag_config])
    
      instance_id = res['Instances'][0]['InstanceId']
    
      print('[INFO] 1 EC2 instance is successfully launched', instance_id)
    
      return { 'InstanceId' : instance_id }
      PowerShell
      Install-Module AWS.Tools.EC2 -Force
    Import-Module AWS.Tools.EC2
    
    $payload = $env:InputPayload | ConvertFrom-Json
    
    $imageid = $payload.image_id
    
    $tagvalue = $payload.tag_value
    
    $instanceType = $payload.instance_type
    
    $type = New-Object Amazon.EC2.InstanceType -ArgumentList $instanceType
    
    $resource = New-Object Amazon.EC2.ResourceType -ArgumentList 'instance'
    
    $tag = @{Key='Name';Value=$tagValue}
    
    $tagSpecs = New-Object Amazon.EC2.Model.TagSpecification
    
    $tagSpecs.ResourceType = $resource
    
    $tagSpecs.Tags.Add($tag)
    
    $res = New-EC2Instance -ImageId $imageId -MinCount 1 -MaxCount 1 -InstanceType $type -TagSpecification $tagSpecs
    
    return @{'InstanceId'=$res.Instances.InstanceId}

    8. Expanda Additional inputs (Entradas adicionais).

    9. Em Input name (Nome da entrada), escolha InputPayload. Em Input value (Valor de entrada), insira os dados YAML a seguir. 

      image_id: "{{ imageId }}"
    tag_value: "{{ tagValue }}"
    instance_type: "{{ instanceType }}"

  13. Expanda Outputs (Saídas) e faça o seguinte:

    • Em Nome, digite payload.

    • Em Selector (Seletor), insira $.Payload.

    • Em Type (Tipo), escolha StringMap.

  14. Selecione Add step (Adicionar etapa) para adicionar uma segunda etapa ao runbook. A segunda etapa consulta o status da instância executada na Etapa 1 e aguarda até que o status retornado seja ok.

  15. Na seção Step 2 (Etapa 2), faça o seguinte.

    1. Em Step name (Nome da etapa), insira este nome descritivo para a segunda etapa da automação: WaitForInstanceStatusOk.

    2. Em Action type (Tipo de ação), escolha Run a script (Executar um script) (aws:executeScript).

    3. Em Description (Descrição), insira uma descrição para a etapa de automação, como a seguinte.

      **About This Step**
    
    The script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned.

    4. Em Runtime, escolha a linguagem do runtime a ser usada para executar o script fornecido.

    5. Em Handler (Manipulador), insira poll_instance. Esse é o nome da função declarado no script a seguir.

      nota

      Isso não é necessário para o PowerShell.

    6. Em Script, substitua o conteúdo padrão pelo seguinte. Certifique-se de corresponder o script com o valor de runtime correspondente.

      Python
      def poll_instance(events, context):
      import boto3
      import time
    
      ec2 = boto3.client('ec2')
    
      instance_id = events['InstanceId']
    
      print('[INFO] Waiting for instance status check to report ok', instance_id)
    
      instance_status = "null"
    
      while True:
        res = ec2.describe_instance_status(InstanceIds=[instance_id])
    
        if len(res['InstanceStatuses']) == 0:
          print("Instance status information is not available yet")
          time.sleep(5)
          continue
    
        instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
    
        print('[INFO] Polling to get status of the instance', instance_status)
    
        if instance_status == 'ok':
          break
    
        time.sleep(10)
    
      return {'Status': instance_status, 'InstanceId': instance_id}
      PowerShell
      
    Install-Module AWS.Tools.EC2 -Force
    
    $inputPayload = $env:InputPayload | ConvertFrom-Json
    
    $instanceId = $inputPayload.payload.InstanceId
    
    $status = Get-EC2InstanceStatus -InstanceId $instanceId
    
    while ($status.Status.Status -ne 'ok'){
       Write-Host 'Polling get status of the instance', $instanceId
    
       Start-Sleep -Seconds 5
    
       $status = Get-EC2InstanceStatus -InstanceId $instanceId
    }
    
    return @{Status = $status.Status.Status; InstanceId = $instanceId}

    7. Expanda Additional inputs (Entradas adicionais).

    8. Em Input name (Nome da entrada), escolha InputPayload. Em Input value (Valor de entrada), insira o seguinte:

      {{ LaunchEc2Instance.payload }}

  16. Escolha Create automation (Criar automação) para salvar o runbook.