Referência de ações do Systems Manager Automation

Essa referência descreve as ações do Automation que você pode especificar em um runbook do Automation. O Automation é um recurso do AWS Systems Manager. Essas ações não podem ser usadas em outros tipos de documentos do Systems Manager (SSM). Para obter informações sobre plugins para outros tipos de documento do SSM, consulte Referência de plug-ins de documentos de comando.

O Systems Manager Automation executa as etapas definidas em runbooks de automação. Cada etapa está associada a uma ação específica. A ação determina as entradas, o comportamento e as saídas da etapa. As etapas são definidas na seção mainSteps do seu runbook.

Não é necessário especificar as saídas de uma ação ou etapa. As saídas são predeterminadas pela ação associada à etapa. Quando você especifica entradas de etapa em seus runbooks, você pode fazer referência a um ou mais resultados de uma etapa anterior. Por exemplo, você pode disponibilizar a saída de aws:runInstances para uma ação aws:runCommand subsequente. Você também pode referenciar resultados de etapas anteriores na seção Output do runbook.

Importante

Se você executar um fluxo de trabalho de automação que chama outros serviços usando uma função de serviço do AWS Identity and Access Management (IAM), esteja ciente de que esta função deve ser configurada com permissão para chamar esses serviços. Esse requisito aplica-se a todos os runbooks do Automation da AWS (runbooks da AWS-*), como AWS-ConfigureS3BucketLogging, AWS-CreateDynamoDBBackup e AWS-RestartEC2Instance, entre outros. Esse requisito também se aplica a todos os runbooks personalizados do Automation criados que invoquem outros Serviços da AWS, usando ações que chamam outros serviços. Por exemplo, se você usar as ações aws:executeAwsApi, aws:createStack ou aws:copyImage, configure a função de serviço com permissão para invocar esses serviços. É possível habilitar permissões para outros Serviços da AWS, adicionando uma política em linha do IAM à função. Para obter mais informações, consulte (Opcional) Adicione uma política em linha ou uma política gerenciada pelo cliente para invocar outros Serviços da AWS.

Tópicos

• Propriedades compartilhadas por todas as ações
• aws:approve – Pausa uma automação para aprovação manual
• aws:assertAwsResourceProperty: define um estado do recurso da AWS ou o estado do evento
• aws:branch – Executa etapas de automação condicionais
• aws:changeInstanceState: altera ou declara o estado da instância
• aws:copyImage: copia ou criptografa um Amazon Machine Image
• aws:createImage: cria uma imagem de máquina da Amazon
• aws:createStack: cria uma pilha do AWS CloudFormation
• aws:createTags: cria tags para os recursos da AWS
• aws:deleteImage: exclui uma Imagem de máquina da Amazon
• aws:deleteStack: exclui uma pilha do AWS CloudFormation
• aws:executeAutomation – Executa outra automação
• aws:executeAwsApi— Chame e execute operações de AWS API
• aws:executeScript – Executa um script
• aws:executeStateMachine – Executa uma máquina de estado do AWS Step Functions
• aws:invokeWebhook — Invoque uma integração de webhook do Automation
• aws:invokeLambdaFunction – Invoca uma função do AWS Lambda
• aws:loop: itera nas etapas de uma automação
• aws:pause – Pausa uma automação
• aws:runCommand – Executa um comando em uma instância gerenciada
• aws:runInstances – Executa uma instância do Amazon EC2
• aws:sleep: atrasa uma automação
• aws:updateVariable: atualiza um valor para uma variável do runbook
• aws:waitForAwsResourceProperty: aguarde uma propriedade de recurso da AWS
• Variáveis de sistema de automação

Propriedades compartilhadas por todas as ações

Propriedades comuns são parâmetros ou opções encontradas em todas as ações. Algumas opções definem o comportamento para uma etapa, como o tempo de espera para que uma etapa seja concluída e o que fazer se a etapa falhar. As seguintes propriedades são comuns a todas as ações.

description

Informações que você fornece para descrever a finalidade de um runbook ou de uma etapa.

Tipo: sequência

Obrigatório: não

name

Um identificador que deve ser exclusivo em todos os nomes de etapas do runbook.

Tipo: sequência

Padrão permitido: [a-zA-Z0-9_]+$

Obrigatório: sim

action

O nome da ação que a etapa deve executar. aws:runCommand – Executa um comando em uma instância gerenciada é um exemplo de uma ação que você pode especificar aqui. Esse documento fornece informações detalhadas sobre todas as ações disponíveis.

Tipo: string

Obrigatório: sim

maxAttempts

Quantas vezes a etapa deve ser repetida em caso de falha. Se o valor for maior que 1, a etapa não será considerada falha até que todas as novas tentativas tenham falhado. O valor padrão é 1.

Tipo: inteiro

Obrigatório: não

timeoutSeconds

O valor de tempo limite para a etapa. Se o tempo limite for atingido, e o valor de maxAttempts for maior que 1, a etapa não será considerada expirada até que todas as novas tentativas tenham sido feitas.

Tipo: inteiro

Obrigatório: não

onFailure

Indica se a automação deve ser interrompida, se deve continuar ou seguir para outra etapa, no caso de falha. O valor padrão desta opção é anular.

Tipo: sequência

Valores válidos: Anular | Continuar | etapa:step_name

Obrigatório: não

onCancel

Indica para qual etapa a automação deve passar no caso de um usuário cancelar a automação. A automação executa o fluxo de trabalho de cancelamento por um máximo de dois minutos.

Tipo: sequência

Valores válidos: Abort | step:step_name

Obrigatório: não

A propriedade onCancel não oferece suporte para mover para as seguintes ações:

• aws:approve

• aws:copyImage

• aws:createImage

• aws:createStack

• aws:createTags

• aws:loop

• aws:pause

• aws:runInstances

• aws:sleep

isEnd

Essa opção interrompe automação no final de determinada etapa. A automação é interrompida se a execução da etapa falhar ou for bem-sucedida. O valor padrão é falso.

Tipo: booliano

Valores válidos: verdadeiro | falso

Obrigatório: não

nextStep

Especifica qual etapa de uma automação deve ser processada imediatamente após a conclusão bem-sucedida de uma etapa.

Tipo: sequência

Obrigatório: não

isCritical

Designa uma etapa como essencial para a conclusão bem sucedida da automação. Se uma etapa com essa designação falhar, a automação relatará o status final do Automation como Failed (com falha). Essa propriedade só será avaliada se você a definir explicitamente em sua etapa. Se o a propriedade onFailure for definida como Continue em uma etapa, o valor padrão será falso. Caso contrário, valor padrão desta opção é verdadeiro.

Tipo: booliano

Valores válidos: verdadeiro | falso

Obrigatório: não

inputs

As propriedades específicas da ação.

Tipo: mapa

Obrigatório: sim

Exemplo

---
description: "Custom Automation Example"
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
  AutomationAssumeRole:
    type: String
    description: "(Required) The ARN of the role that allows Automation to perform
      the actions on your behalf. If no role is specified, Systems Manager Automation
      uses your IAM permissions to run this runbook."
    default: ''
  InstanceId:
      type: String
      description: "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot."
      default: ''
mainSteps:
- name: getInstanceDetails
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: DescribeInstances
    InstanceIds:
    - "{{ InstanceId }}"
  outputs:
    - Name: availabilityZone
      Selector: "$.Reservations[0].Instances[0].Placement.AvailabilityZone"
      Type: String
    - Name: rootDeviceName
      Selector: "$.Reservations[0].Instances[0].RootDeviceName"
      Type: String
  nextStep: getRootVolumeId
- name: getRootVolumeId
  action: aws:executeAwsApi
  maxAttempts: 3
  onFailure: Abort
  inputs:
    Service: ec2
    Api: DescribeVolumes
    Filters:
    -  Name: attachment.device
       Values: ["{{ getInstanceDetails.rootDeviceName }}"]
    -  Name: attachment.instance-id
       Values: ["{{ InstanceId }}"]
  outputs:
    - Name: rootVolumeId
      Selector: "$.Volumes[0].VolumeId"
      Type: String
  nextStep: getSnapshotsByStartTime
- name: getSnapshotsByStartTime
  action: aws:executeScript
  timeoutSeconds: 45
  onFailure: Abort
  inputs:
    Runtime: python3.8
    Handler: getSnapshotsByStartTime
    InputPayload:
      rootVolumeId : "{{ getRootVolumeId.rootVolumeId }}"
    Script: |-
      def getSnapshotsByStartTime(events,context):
        import boto3

        #Initialize client
        ec2 = boto3.client('ec2')
        rootVolumeId = events['rootVolumeId']
        snapshotsQuery = ec2.describe_snapshots(
          Filters=[
            {
              "Name": "volume-id",
              "Values": [rootVolumeId]
            }
          ]
        )
        if not snapshotsQuery['Snapshots']:
          noSnapshotFoundString = "NoSnapshotFound"
          return { 'noSnapshotFound' : noSnapshotFoundString }
        else:
          jsonSnapshots = snapshotsQuery['Snapshots']
          sortedSnapshots = sorted(jsonSnapshots, key=lambda k: k['StartTime'], reverse=True)
          latestSortedSnapshotId = sortedSnapshots[0]['SnapshotId']
          return { 'latestSnapshotId' : latestSortedSnapshotId }
  outputs:
  - Name: Payload
    Selector: $.Payload
    Type: StringMap
  - Name: latestSnapshotId
    Selector: $.Payload.latestSnapshotId
    Type: String
  - Name: noSnapshotFound
    Selector: $.Payload.noSnapshotFound
    Type: String 
  nextStep: branchFromResults
- name: branchFromResults
  action: aws:branch
  onFailure: Abort
  onCancel: step:startInstance
  inputs:
    Choices:
    - NextStep: createNewRootVolumeFromSnapshot
      Not:
        Variable: "{{ getSnapshotsByStartTime.noSnapshotFound }}"
        StringEquals: "NoSnapshotFound"
  isEnd: true
- name: createNewRootVolumeFromSnapshot
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: CreateVolume
    AvailabilityZone: "{{ getInstanceDetails.availabilityZone }}"
    SnapshotId: "{{ getSnapshotsByStartTime.latestSnapshotId }}"
  outputs:
    - Name: newRootVolumeId
      Selector: "$.VolumeId"
      Type: String
  nextStep: stopInstance
- name: stopInstance
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: StopInstances
    InstanceIds:
    - "{{ InstanceId }}"
  nextStep: verifyVolumeAvailability
- name: verifyVolumeAvailability
  action: aws:waitForAwsResourceProperty
  timeoutSeconds: 120
  inputs:
    Service: ec2
    Api: DescribeVolumes
    VolumeIds:
    - "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
    PropertySelector: "$.Volumes[0].State"
    DesiredValues:
    - "available"
  nextStep: verifyInstanceStopped
- name: verifyInstanceStopped
  action: aws:waitForAwsResourceProperty
  timeoutSeconds: 120
  inputs:
    Service: ec2
    Api: DescribeInstances
    InstanceIds:
    - "{{ InstanceId }}"
    PropertySelector: "$.Reservations[0].Instances[0].State.Name"
    DesiredValues:
    - "stopped"
  nextStep: detachRootVolume
- name: detachRootVolume
  action: aws:executeAwsApi
  onFailure: Abort
  isCritical: true
  inputs:
    Service: ec2
    Api: DetachVolume
    VolumeId: "{{ getRootVolumeId.rootVolumeId }}"
  nextStep: verifyRootVolumeDetached
- name: verifyRootVolumeDetached
  action: aws:waitForAwsResourceProperty
  timeoutSeconds: 30
  inputs:
    Service: ec2
    Api: DescribeVolumes
    VolumeIds:
    - "{{ getRootVolumeId.rootVolumeId }}"
    PropertySelector: "$.Volumes[0].State"
    DesiredValues:
    - "available"
  nextStep: attachNewRootVolume
- name: attachNewRootVolume
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: AttachVolume
    Device: "{{ getInstanceDetails.rootDeviceName }}"
    InstanceId: "{{ InstanceId }}"
    VolumeId: "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
  nextStep: verifyNewRootVolumeAttached
- name: verifyNewRootVolumeAttached
  action: aws:waitForAwsResourceProperty
  timeoutSeconds: 30
  inputs:
    Service: ec2
    Api: DescribeVolumes
    VolumeIds:
    - "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
    PropertySelector: "$.Volumes[0].Attachments[0].State"
    DesiredValues:
    - "attached"
  nextStep: startInstance
- name: startInstance
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: StartInstances
    InstanceIds:
    - "{{ InstanceId }}"