Utilizzo di istruzioni condizionali nei runbook - AWS Systems Manager
Utilizzo dell'agente aws:branchEsempi di utilizzo delle opzioni condizionali

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo di istruzioni condizionali nei runbook

Per impostazione predefinita, le fasi definite nella sezione mainSteps di un runbook vengono eseguite in ordine sequenziale. Al completamento di un'operazione viene avviata l'esecuzione dell'operazione successiva specificata nella sezione mainSteps. Inoltre, se l'esecuzione di un'operazione ha esito negativo, l'intera automazione avrà esito negativo (per impostazione predefinita). È possibile utilizzare l'operazione di automazione aws:branch e le opzioni disponibili nel runbook descritte in questa sezione per creare automazioni che eseguono il branching condizionale. Ciò significa che è possibile creare automazioni che passano a una fase diversa dopo aver valutato le diverse scelte disponibili o che rispondono in modo dinamico alle modifiche in seguito al completamento di una fase. Ecco un elenco di opzioni che è possibile utilizzare per creare automazioni dinamiche:

  • aws:branch: questa operazione di automazione consente di creare un'automazione dinamica che valuta le diverse scelte disponibili in una singola fase e quindi passa a una fase diversa nel runbook in base ai risultati di tale valutazione.

  • nextStep: questa opzione specifica la successiva fase in un'automazione da elaborare dopo il completamento di una fase.

  • isEnd: questa opzione arresta l'automazione alla fine di una fase specifica. Il valore predefinito di questa opzione è "false".

  • isCritical: questa opzione designa una fase come fase critica per il corretto completamento dell'automazione. Se una fase con questa definizione ha esito negativo, il servizio di automazione restituisce come stato finale dell'automazione il valore Failed. Il valore predefinito per questa opzione è true.

  • onFailure: questa opzione indica se, in caso di errore, l'automazione deve interrompersi, continuare o passare a un'altra fase. Il valore predefinito di questa opzione è "abort" (interrompi).

Nella sezione seguente viene descritto l'operazione di automazione aws:branch. Per ulteriori informazioni sulle opzioni nextStep, isEnd, isCritical e onFailure, consulta Esempio di runbook aws:branch.

Utilizzo dell'agente aws:branch

L'operazione aws:branch rende disponibile la maggior parte delle opzioni di branching condizionale per le automazioni. Come indicato in precedenza, questa operazione consente all'automazione di valutare più condizioni in un'unica fase e quindi di passare a una nuova fase in base ai risultati di tale valutazione. L'operazione aws:branch è simile a un'istruzione IF-ELIF-ELSE in un ambiente di programmazione.

Di seguito viene riportato un esempio YAML di una fase aws:branch:

- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

Quando per una fase viene specificata l'operazione aws:branch, è necessario specificare l'elemento Choices che l'automazione deve valutare. L'automazione può valutare l'elemento Choices in base al valore di un parametro specificato nella sezione Parameters del runbook. L'automazione può inoltre valutare l'elemento Choices in base all'output di una fase precedente.

L'automazione valuta ogni scelta utilizzando un'espressione booleana. Se la valutazione stabilisce che la prima scelta abbia il valore true, l'automazione passa alla fase definita per tale scelta. Se la valutazione stabilisce che la prima scelta abbia il valore false, l'automazione valuta la scelta successiva. Se la fase include tre o più elementi Choices, l'automazione valuta ogni scelta in ordine sequenziale finché la valutazione di una scelta non restituisce true. L'automazione passa quindi alla fase definita per la scelta di tipo true.

Se nessuna delle Choices restituisce true, l'automazione controlla se la fase contiene un valore Default. Un valore Default definisce una fase a cui l'automazione deve passare se nessuna delle scelte restituisce true. Se non è stato specificato alcun valore di Default per la fase, l'automazione elabora la fase successiva nel runbook.

Ecco un aws:branch passaggio in YAML chiamato ChooSEO. SfromParameter La fase include due elementi Choices: (NextStep: runWindowsCommand) e (NextStep: runLinuxCommand). L'automazione valuta questi elementi Choices per determinare il comando da eseguire per il sistema operativo appropriato. L'elemento Variable per ciascuna scelta usa {{OSName}}, ovvero un parametro che l'autore del runbook ha definito nella sezione Parameters del runbook.

mainSteps:
- name: chooseOSfromParameter
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OSName}}"
      StringEquals: Windows
    - NextStep: runLinuxCommand
      Variable: "{{OSName}}"
      StringEquals: Linux

Ecco un aws:branch passaggio di YAML chiamato ChooSEO. SfromOutput La fase include due elementi Choices: (NextStep: runPowerShellCommand) e (NextStep: runShellCommand). L'automazione valuta questi elementi Choices per determinare il comando da eseguire per il sistema operativo appropriato. L'elemento Variable per ciascuna scelta usa {{GetInstance.platform}}, ovvero l'output da una fase precedente nel runbook. Questo esempio include anche un'opzione denominata Default. Se l'automazione valuta entrambi gli elementi Choices e nessuna delle due scelte restituisce true, l'automazione passa alla fase denominata PostProcessing.

mainSteps:
- name: chooseOSfromOutput
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

Creazione di una fase aws:branch in un runbook

Quando in un runbook viene creata una fase aws:branch, viene definito l'elemento Choices che l'automazione deve valutare per determinare a quale fase successiva deve passare. Come specificato precedentemente, gli elementi Choices vengono valutati utilizzando un'espressione booleana. Ogni scelta deve definire le seguenti opzioni:

  • NextStep: Il passaggio successivo del runbook da elaborare se la scelta designata è. true

  • Variabile: specifica il nome di un parametro definito nella Parameters sezione del runbook, una variabile definita nella Variables sezione o specifica un oggetto di output di un passaggio precedente.

    Specificate i valori delle variabili utilizzando il seguente modulo.

    Variable: "{{variable name}}"

    Specificate i valori dei parametri utilizzando il seguente modulo.

    Variable: "{{parameter name}}"

    Specificare le variabili degli oggetti di output utilizzando il formato seguente:

    Variable: "{{previousStepName.outputName}}"

    Nota

    La creazione della variabile di output è descritta in dettaglio nella sezione successiva, Informazioni sulla creazione della variabile di output.

  • Operation: i criteri utilizzati per valutare la scelta, ad esempio StringEquals: Linux. L'operazione aws:branch supporta le operazioni seguenti:

    Operazioni di stringa

    • StringEquals

    • EqualsIgnoreCase

    • StartsWith

    • EndsWith

    • Contiene

    Operazioni numeriche

    • NumericEquals

    • NumericGreater

    • NumericLesser

    • NumericGreaterOrEquals

    • NumericLesser

    • NumericLesserOrEquals

    Operazioni booleane

    • BooleanEquals

    Importante

    Quando si crea un runbook, il sistema convalida ogni operazione nel runbook. Se un'operazione non è supportata, il sistema restituisce un errore quando si tenta di creare il runbook.

  • Default: specificare una fase di fallback (alternativa) a cui l'automazione deve passare se nessuno degli elementi Choices restituisce true.

    Nota

    Se non si desidera specificare un valore Default, è possibile specificare l'opzione isEnd. Se nessuno degli elementi Choices restituisce true e non viene specificato alcun valore Default, l'automazione viene arrestata alla fine della fase.

Utilizza i seguenti modelli per creare la fase aws:branch nei runbook: Sostituisci ciascun segnaposto delle risorse di esempio con le tue informazioni.

YAML
mainSteps:
- name: step name
  action: aws:branch
  inputs:
    Choices:
    - NextStep: step to jump to if evaluation for this choice is true
      Variable: "{{parameter name or output from previous step}}"
      Operation type: Operation value
    - NextStep: step to jump to if evaluation for this choice is true
      Variable: "{{parameter name or output from previous step}}"
      Operation type: Operation value
    Default:
      step to jump to if all choices are false
JSON
{
   "mainSteps":[
      {
         "name":"a name for the step",
         "action":"aws:branch",
         "inputs":{
            "Choices":[
               {
                  "NextStep":"step to jump to if evaluation for this choice is true",
                  "Variable":"{{parameter name or output from previous step}}",
                  "Operation type":"Operation value"
               },
               {
                  "NextStep":"step to jump to if evaluation for this choice is true",
                  "Variable":"{{parameter name or output from previous step}}",
                  "Operation type":"Operation value"
               }
            ],
            "Default":"step to jump to if all choices are false"
         }
      }
   ]
}

Informazioni sulla creazione della variabile di output

Per creare una scelta aws:branch che fa riferimento all'output restituito da una fase precedente, è necessario identificare il nome della fase precedente e il nome del campo di output. È quindi possibile combinare i nomi della fase e del campo utilizzando il formato seguente.

Variable: "{{previousStepName.outputName}}"

Ad esempio, la prima fase dell'esempio riportato di seguito è denominata GetInstance. In outputs è presente un campo denominato platform. Nella seconda fase (ChooseOSforCommands), l'autore vuole fare riferimento all'output del campo "platform" (piattaforma) come variabile. Per creare la variabile, è sufficiente combinare il nome del passaggio (GetInstance) e il nome del campo di output (piattaforma) da creareVariable: "{{GetInstance.platform}}".

mainSteps:
- Name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
    Filters:
    - Key: InstanceIds
      Values: ["{{ InstanceId }}"]
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep

Ecco un esempio che mostra come viene creato "Variable": "{{ describeInstance.Platform }}" dalla fase precedente e il relativo output.

- name: describeInstance
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: DescribeInstances
    InstanceIds:
    - "{{ InstanceId }}"
  outputs:
  - Name: Platform
    Selector: "$.Reservations[0].Instances[0].Platform"
    Type: String
  nextStep: branchOnInstancePlatform
- name: branchOnInstancePlatform
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runEC2RescueForWindows
      Variable: "{{ describeInstance.Platform }}"
      StringEquals: windows
    Default: runEC2RescueForLinux

Esempio di runbook aws:branch

Di seguito sono elencati alcuni runbook di esempio che utilizzano aws:branch.

Esempio 1: utilizzo di aws:branch con una variabile di output per eseguire comandi in base al tipo di sistema operativo

Nella prima fase di questo esempio (GetInstance), l'autore del runbook utilizza l'operazione aws:executeAwsApi per chiamare l'operazione API ssm DescribeInstanceInformation. L'autore usa questa operazione per determinare il tipo di sistema operativo utilizzato da un'istanza. L'operazione aws:executeAwsApi restituisce l'ID dell'istanza e il tipo di piattaforma.

Nella seconda fase (ChooseOSforCommands) l'autore usa l'operazione aws:branch con due elementi Choices (NextStep: runPowerShellCommand) e (NextStep: runShellCommand). L'automazione valuta il sistema operativo dell'istanza utilizzando l'output della fase precedente (Variable: "{{GetInstance.platform}}"). L'automazione passa a una fase relativa al sistema operativo designato.

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
mainSteps:
- name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep
- name: runShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runPowerShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunPowerShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

Esempio 2: utilizzo di aws:branch con una variabile di parametro per eseguire comandi in base al tipo di sistema operativo

L'autore del runbook definisce diverse opzioni di parametro all'inizio del documento nella sezione parameters. Uno dei parametri è denominato OperatingSystemName. Nella prima fase (ChooseOS) l'autore usa l'operazione aws:branch con due Choices (NextStep: runWindowsCommand) e (NextStep: runLinuxCommand). La variabile per questi elementi Choices fa riferimento all'opzione di parametro specificato nella sezione "parameters" (Variable: "{{OperatingSystemName}}"). Quando l'utente esegue questo runbook, deve specificare un valore di tempo di esecuzione per OperatingSystemName. L'automazione utilizza il parametro di tempo di esecuzione durante la valutazione di Choices. L'automazione passa a una fase per il sistema operativo designato in base al parametro di tempo di esecuzione specificato per OperatingSystemName.

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
  OperatingSystemName:
    type: String
  LinuxInstanceId:
    type: String
  WindowsInstanceId:
    type: String
mainSteps:
- name: ChooseOS
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: windows
    - NextStep: runLinuxCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: linux
    Default:
      Sleep
- name: runLinuxCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunShellScript"
    InstanceIds:
    - "{{LinuxInstanceId}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runWindowsCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunPowerShellScript"
    InstanceIds:
    - "{{WindowsInstanceId}}"
    Parameters:
      commands:
      - date
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

Creazione di automazioni con branching complesso con operatori

Puoi creare automazioni con branching complesso utilizzando gli operatori And, Or e Not nelle fasi aws:branch.

Operatore "And"

Utilizza l'operatore And quando vuoi che più variabili restituiscano true per una scelta. Nell'esempio seguente la prima scelta valuta se un'istanza è running e usa il sistema operativo Windows. Se la valutazione di entrambe le variabili restituisce "true", l'automazione passa alla fase runPowerShellCommand. Se una o più variabili restituisce false, l'automazione valuta le variabili della seconda scelta.

mainSteps:
- name: switch2
  action: aws:branch
  inputs:
    Choices:
    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Windows
      NextStep: runPowerShellCommand

    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Linux
      NextStep: runShellCommand
    Default:
      sleep3
Operatore "Or"

Utilizza l'operatore Or quando vuoi che una qualsiasi di più variabili restituisca "true" per una scelta. Nell'esempio seguente la prima scelta valuta se una stringa di parametro è Windows e se l'output da una fase AWS Lambda è "true". Se la valutazione determina che una di queste variabili restituisce "true", l'automazione passa alla fase RunPowerShellCommand. Se entrambe le variabili restituiscono "false", l'automazione valuta le variabili della seconda scelta.

- Or:
  - Variable: "{{parameter1}}"
    StringEquals: Windows
  - Variable: "{{BooleanParam1}}"
    BooleanEquals: true
  NextStep: RunPowershellCommand
- Or:
  - Variable: "{{parameter2}}"
    StringEquals: Linux
  - Variable: "{{BooleanParam2}}"
    BooleanEquals: true
  NextStep: RunShellScript
Operatore "Not"

Utilizza l'operatore Not quando vuoi passare a una fase definita quando una variabile non restituisce "true". Nell'esempio seguente la prima scelta valuta se una stringa di parametro è Not Linux. Se la valutazione determina che la variabile non è Linux, l'automazione passa alla fase sleep2. Se la valutazione della prima scelta determina che è Linux, l'automazione valuta la scelta successiva.

mainSteps:
- name: switch
  action: aws:branch
  inputs:
    Choices:
    - NextStep: sleep2
      Not:
        Variable: "{{testParam}}"
        StringEquals: Linux
    - NextStep: sleep1
      Variable: "{{testParam}}"
      StringEquals: Windows
    Default:
      sleep3

Esempi di utilizzo delle opzioni condizionali

In questa sezione sono riportati diversi esempi di come utilizzare le opzioni dinamiche in un runbook. Ogni esempio in questa sezione estende le funzionalità del runbook seguente. Il runbook include due operazioni. La prima operazione è denominata InstallMsiPackage. Utilizza l'operazione aws:runCommand per installare un'applicazione su un'istanza di Windows Server. La seconda operazione è denominata TestInstall. Utilizza l'operazione aws:invokeLambdaFunction per eseguire un test dell'applicazione installata se l'applicazione è stata installata correttamente. La fase una specifica onFailure: Abort. Ciò significa che se l'applicazione non è stata installata correttamente, l'automazione viene interrotta prima della fase due.

Esempio 1: runbook con due operazioni lineari

---
schemaVersion: '0.3'
description: Install MSI package and run validation.
assumeRole: "{{automationAssumeRole}}"
parameters:
  automationAssumeRole:
    type: String
    description: "(Required) Assume role."
  packageName:
    type: String
    description: "(Required) MSI package to be installed."
  instanceIds:
    type: String
    description: "(Required) Comma separated list of instances."
mainSteps:
- name: InstallMsiPackage
  action: aws:runCommand
  maxAttempts: 2
  onFailure: Abort
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
...

Creazione di un'automazione dinamica che passa a fasi diverse mediante l'opzione onFailure

L'esempio seguente utilizza le opzioni onFailure: step:step name, nextStep e isEnd per creare un'automazione dinamica. In questo esempio, se l'InstallMsiPackageazione fallisce, l'automazione passa a un'azione chiamata PostFailure(onFailure: step:PostFailure) per eseguire una AWS Lambda funzione per eseguire un'azione nel caso in cui l'installazione non riesca. Se l'installazione ha esito positivo, l'automazione passa all' TestInstall azione (). nextStep: TestInstall Le fasi TestInstall e PostFailure usano entrambe l'opzione isEnd (isEnd: true) in modo tale che l'automazione termini al completamento di una di queste due fasi.

Nota

L'uso dell'opzione isEnd nell'ultima fase della sezione mainSteps è facoltativo. Se l'ultima fase non passa ad altre fasi, l'automazione viene interrotta dopo l'esecuzione dell'operazione nell'ultima fase.

Esempio 2: un'automazione dinamica che passa a diverse fasi

mainSteps
- name: InstallMsiPackage
  action: aws:runCommand
  onFailure: step:PostFailure
  maxAttempts: 2
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
  nextStep: TestInstall
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
  isEnd: true
- name: PostFailure
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: PostFailureRecoveryLambdaFunction
  isEnd: true
...
Nota

Prima di elaborare un runbook, il sistema verifica che il runbook non crei un loop infinito. Se viene rilevato un loop infinito, il servizio di automazione restituisce un errore e una traccia a forma di cerchio che evidenzia le fasi che causano il loop.

Creazione di un'automazione dinamica che definisce le fasi critiche

È possibile specificare una fase come fase critica per il successo complessivo dell'automazione. Se una fase critica ha esito negativo, il servizio di automazione indica lo stato dell'automazione come Failed, anche se una o più fasi sono state eseguite correttamente. Nell'esempio seguente, l'utente identifica il VerifyDependenciespassaggio se il InstallMsiPackagepassaggio fallisce (). onFailure: step:VerifyDependencies L'utente specifica che la fase InstallMsiPackage non è una fase critica (isCritical: false). In questo esempio, se l'applicazione non viene installata, il servizio di automazione elabora la fase VerifyDependencies per determinare se mancano una o più dipendenze; è proprio la mancanza di una dipendenza il motivo che ha causato la mancata installazione dell'applicazione.

Esempio 3: definizione delle fasi critiche per l'automazione 

---
name: InstallMsiPackage
action: aws:runCommand
onFailure: step:VerifyDependencies
isCritical: false
maxAttempts: 2
inputs:
  InstanceIds:
  - "{{instanceIds}}"
  DocumentName: AWS-RunPowerShellScript
  Parameters:
    commands:
    - msiexec /i {{packageName}}
nextStep: TestPackage
...