Usa il framework AWSTOE dei documenti dei componenti per componenti personalizzati - EC2 Image Builder
Flusso di lavoro relativo ai documentiRegistrazione dei componentiConcatenamento di input e outputSchema e definizioni del documentoEsempi di documenti

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à.

Usa il framework AWSTOE dei documenti dei componenti per componenti personalizzati

Per creare un componente utilizzando il framework di componenti AWS Task Orchestrator and Executor (AWSTOE), devi fornire un documento basato su YAML che rappresenti le fasi e i passaggi applicabili al componente che crei. Servizi AWS usa il tuo componente quando creano una nuova Amazon Machine Image (AMI) o un'immagine del contenitore.

Argomenti

Flusso di lavoro relativo ai documenti

Il documento del AWSTOE componente utilizza fasi e passaggi per raggruppare le attività correlate e organizzarle in un flusso di lavoro logico per il componente.

Suggerimento

Il servizio che utilizza il componente per creare un'immagine potrebbe implementare regole su quali fasi utilizzare per il processo di creazione e quando tali fasi possono essere eseguite. Questo è importante da considerare quando si progetta il componente.

Fasi

Le fasi rappresentano la progressione del flusso di lavoro attraverso il processo di creazione dell'immagine. Ad esempio, il servizio Image Builder utilizza validate le fasi build e le fasi durante la fase di creazione per le immagini che produce. Utilizza container-host-test le fasi test and durante la fase di test per garantire che l'istantanea dell'immagine o l'immagine del contenitore produca i risultati previsti prima di creare l'AMI finale o distribuire l'immagine del contenitore.

Quando il componente viene eseguito, i comandi associati per ogni fase vengono applicati nell'ordine in cui appaiono nel documento del componente.

Regole per le fasi

  • Il nome di ogni fase deve essere univoco all'interno di un documento.

  • È possibile definire molte fasi del documento.

  • È necessario includere almeno una delle seguenti fasi nel documento:

    • build: per Image Builder, questa fase viene generalmente utilizzata durante la fase di creazione.

    • validare: per Image Builder, questa fase viene generalmente utilizzata durante la fase di creazione.

    • test — per Image Builder, questa fase viene generalmente utilizzata durante la fase di test.

  • Le fasi vengono sempre eseguite nell'ordine in cui sono definite nel documento. L'ordine in cui sono specificate per AWSTOE i comandi in non AWS CLI ha effetto.

Fasi

I passaggi sono singole unità di lavoro che definiscono il flusso di lavoro all'interno di ciascuna fase. Le fasi vengono eseguite in ordine sequenziale. Tuttavia, l'input o l'output di una fase possono anche alimentare una fase successiva come input. Questo processo si chiama «concatenamento».

Regole per i passaggi

  • Il nome della fase deve essere univoco per la fase.

  • La fase deve utilizzare un'azione supportata (modulo di azione) che restituisca un codice di uscita.

    Per un elenco completo dei moduli di azione supportati, del loro funzionamento, dei valori di input/output ed esempi, consulta. Moduli di azione supportati dal gestore AWSTOE dei componenti

Registrazione dei componenti

AWSTOE crea una nuova cartella di registro sulle EC2 istanze utilizzate per creare e testare una nuova immagine, ogni volta che viene eseguito il componente. Per le immagini del contenitore, la cartella di registro viene archiviata nel contenitore.

Per facilitare la risoluzione dei problemi in caso di problemi durante il processo di creazione dell'immagine, il documento di input e tutti i file di output AWSTOE creati durante l'esecuzione del componente vengono archiviati nella cartella di registro.

Il nome della cartella di registro è composto dalle seguenti parti:

  1. Directory di log: quando un servizio esegue un AWSTOE componente, questo passa nella directory di log, insieme ad altre impostazioni per il comando. Per gli esempi seguenti, mostriamo il formato di file di registro utilizzato da Image Builder.

    • Linux e macOS: /var/lib/amazon/toe/

    • Windows: $env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\

  2. Prefisso del file: si tratta di un prefisso standard utilizzato per tutti i componenti: "». TOE_

  3. Ora di esecuzione: si tratta di un timestamp in formato _HH-MM-SS_UTC-0. YYYY-MM-DD

  4. ID di esecuzione: è il GUID assegnato quando vengono eseguiti uno o più componenti. AWSTOE

Esempio: /var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4

AWSTOE memorizza i seguenti file principali nella cartella di registro:

File di input

  • document.yaml — Il documento utilizzato come input per il comando. Dopo l'esecuzione del componente, questo file viene memorizzato come artefatto.

File di output

  • application.log: il registro dell'applicazione contiene informazioni a livello di debug con data e ora AWSTOE relative a ciò che accade durante l'esecuzione del componente.

  • detailedoutput.json: questo file JSON contiene informazioni dettagliate sullo stato di esecuzione, gli input, gli output e gli errori per tutti i documenti, le fasi e i passaggi relativi al componente durante l'esecuzione.

  • console.log — Il registro della console contiene tutte le informazioni sullo standard out (stdout) e sugli errori standard (stderr) che vengono scritte sulla console mentre il componente è in esecuzione. AWSTOE

  • chaining.json: questo file JSON rappresenta le ottimizzazioni applicate per risolvere le espressioni di concatenamento. AWSTOE

Nota

La cartella di registro potrebbe contenere anche altri file temporanei che non sono trattati qui.

Concatenamento di input e output

L'applicazione AWSTOE di gestione della configurazione fornisce una funzionalità per concatenare input e output scrivendo riferimenti nei seguenti formati:

{{ phase_name.step_name.inputs/outputs.variable }}

oppure

{{ phase_name.step_name.inputs/outputs[index].variable }}

La funzione di concatenamento consente di riciclare il codice e migliorare la manutenibilità del documento.

Regole per il concatenamento

  • Le espressioni di concatenamento possono essere utilizzate solo nella sezione degli input di ogni passaggio.

  • Le dichiarazioni con espressioni concatenate devono essere racchiuse tra virgolette. Per esempio:

    • Espressione non valida: echo {{ phase.step.inputs.variable }}

    • Espressione valida: "echo {{ phase.step.inputs.variable }}"

    • Espressione valida: 'echo {{ phase.step.inputs.variable }}'

  • Le espressioni concatenate possono fare riferimento a variabili di altri passaggi e fasi dello stesso documento. Tuttavia, il servizio di chiamata potrebbe avere regole che richiedono che le espressioni concatenate funzionino solo nel contesto di una singola fase. Ad esempio, Image Builder non supporta il concatenamento dalla fase di compilazione alla fase di test, poiché esegue ogni fase in modo indipendente.

  • Gli indici nelle espressioni concatenate seguono l'indicizzazione a base zero. L'indice inizia con zero (0) per fare riferimento al primo elemento.

Examples (Esempi)

Per fare riferimento alla variabile source nella seconda voce del passaggio di esempio seguente, lo schema di concatenamento è{{ build.SampleS3Download.inputs[1].source }}.

phases:
  - name: 'build'
    steps:
      - name: SampleS3Download
        action: S3Download
        timeoutSeconds: 60
        onFailure: Abort
        maxAttempts: 3
        inputs:
          - source: 's3://sample-bucket/sample1.ps1'
            destination: 'C:\sample1.ps1'
          - source: 's3://sample-bucket/sample2.ps1'
            destination: 'C:\sample2.ps1'

Per fare riferimento alla variabile di output (uguale a «Hello») del seguente passaggio di esempio, lo schema di concatenamento è. {{ build.SamplePowerShellStep.outputs.stdout }}

phases:
  - name: 'build'
    steps:
      - name: SamplePowerShellStep
        action: ExecutePowerShell
        timeoutSeconds: 120
        onFailure: Abort
        maxAttempts: 3
        inputs:
          commands:
            - 'Write-Host "Hello"'

Schema e definizioni del documento

Di seguito è riportato lo schema YAML per un documento.

name: (optional)
description: (optional)
schemaVersion: "string"

phases:
  - name: "string"
    steps:
      - name: "string"
        action: "string"
        timeoutSeconds: integer
        onFailure: "Abort|Continue|Ignore"
        maxAttempts: integer
        inputs:

Le definizioni dello schema per un documento sono le seguenti.

Campo Descrizione Tipo Richiesto
nome Nome del documento. Stringa No
description Descrizione del documento. Stringa

No
schemaVersion Versione dello schema del documento, attualmente 1.0. Stringa

Sì
phases Un elenco di fasi con i relativi passaggi.

Elenco

Sì

Le definizioni dello schema per una fase sono le seguenti.

Campo Descrizione Tipo Richiesto
nome Nome della fase. Stringa Sì
steps Elenco delle fasi della fase. Elenco

Sì

Le definizioni dello schema per una fase sono le seguenti.

Campo Descrizione Tipo Richiesto Valore predefinito
nome Nome definito dall'utente per il passo. Stringa
action Parola chiave relativa al modulo che esegue il passaggio. Stringa
timeoutSeconds

Numero di secondi di esecuzione del passaggio prima di fallire o riprovare.

Inoltre, supporta il valore -1, che indica un timeout infinito. 0 e altri valori negativi non sono consentiti.

 Numero intero

No

 7.200 sec (120 minuti)
onFailure

Specifica cosa deve fare la fase in caso di errore. I valori validi sono:

  • Interrompi: fallisce il passaggio dopo il numero massimo di tentativi e interrompe l'esecuzione. Imposta lo stato della fase e del documento su. Failed

  • Continua: fallisce il passaggio dopo il numero massimo di tentativi e continua a eseguire i passaggi rimanenti. Imposta lo stato della fase e del documento suFailed.

  • Ignora: imposta il passaggio IgnoredFailure successivo al numero massimo di tentativi falliti e continua a eseguire i passaggi rimanenti. Imposta lo stato per la fase e il documento suSuccessWithIgnoredFailure.

Stringa

No

 Interruzione
maxAttempts Numero massimo di tentativi consentiti prima di fallire il passaggio. Numero intero

No

 1
inputs Contiene i parametri richiesti dal modulo di azione per eseguire il passaggio. Dict

Sì

Esempi di documenti

Gli esempi seguenti mostrano i documenti dei AWSTOE componenti che eseguono attività per il sistema operativo di destinazione.

Linux
Esempio 1: eseguire un file binario personalizzato

Di seguito è riportato un documento di esempio che scarica ed esegue un file binario personalizzato su un'istanza Linux.

name: LinuxBin
description: Download and run a custom Linux binary file.
schemaVersion: 1.0
phases:
  - name: build
    steps:
      - name: Download
        action: S3Download
        inputs:
          - source: s3://<replaceable>amzn-s3-demo-source-bucket</replaceable>/<replaceable>myapplication</replaceable>
            destination: /tmp/<replaceable>myapplication</replaceable>
      - name: Enable
        action: ExecuteBash
        onFailure: Continue
        inputs:
          commands:
            - 'chmod u+x {{ build.Download.inputs[0].destination }}'
      - name: Install
        action: ExecuteBinary
        onFailure: Continue
        inputs:
          path: '{{ build.Download.inputs[0].destination }}'
          arguments:
            - '--install'
      - name: Delete
        action: DeleteFile
        inputs:
          - path: '{{ build.Download.inputs[0].destination }}'
Windows
Esempio 1: installare gli aggiornamenti di Windows

Di seguito è riportato un documento di esempio che installa tutti gli aggiornamenti di Windows disponibili, esegue uno script di configurazione, convalida le modifiche prima della creazione dell'AMI e verifica le modifiche dopo la creazione dell'AMI.

name: RunConfig_UpdateWindows
description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.'
schemaVersion: 1.0
phases:
  - name: build
    steps:
      - name: DownloadConfigScript
        action: S3Download
        timeoutSeconds: 60
        onFailure: Abort
        maxAttempts: 3
        inputs:
          - source: 's3://customer-bucket/config.ps1'
            destination: 'C:\config.ps1'

      - name: RunConfigScript
        action: ExecutePowerShell
        timeoutSeconds: 120
        onFailure: Abort
        maxAttempts: 3
        inputs:
          file: '{{build.DownloadConfigScript.inputs[0].destination}}'

      - name: Cleanup
        action: DeleteFile
        onFailure: Abort
        maxAttempts: 3
        inputs:
          - path: '{{build.DownloadConfigScript.inputs[0].destination}}'

      - name: RebootAfterConfigApplied
        action: Reboot
        inputs:
          delaySeconds: 60

      - name: InstallWindowsUpdates
        action: UpdateOS

  - name: validate
    steps:
      - name: DownloadTestConfigScript
        action: S3Download
        timeoutSeconds: 60
        onFailure: Abort
        maxAttempts: 3
        inputs:
          - source: 's3://customer-bucket/testConfig.ps1'
            destination: 'C:\testConfig.ps1'

      - name: ValidateConfigScript
        action: ExecutePowerShell
        timeoutSeconds: 120
        onFailure: Abort
        maxAttempts: 3
        inputs:
          file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}'

      - name: Cleanup
        action: DeleteFile
        onFailure: Abort
        maxAttempts: 3
        inputs:
          - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}'

  - name: test
    steps:
      - name: DownloadTestConfigScript
        action: S3Download
        timeoutSeconds: 60
        onFailure: Abort
        maxAttempts: 3
        inputs:
          - source: 's3://customer-bucket/testConfig.ps1'
            destination: 'C:\testConfig.ps1'

      - name: ValidateConfigScript
        action: ExecutePowerShell
        timeoutSeconds: 120
        onFailure: Abort
        maxAttempts: 3
        inputs:
          file: '{{test.DownloadTestConfigScript.inputs[0].destination}}'
Esempio 2: installalo AWS CLI su un'istanza di Windows

Di seguito è riportato un documento di esempio che installa AWS CLI su un'istanza di Windows, utilizzando il file di installazione.

name: InstallCLISetUp
description: Install &CLI; using the setup file
schemaVersion: 1.0
phases:
  - name: build
    steps:
      - name: Download
        action: S3Download
        inputs:
          - source: s3://aws-cli/AWSCLISetup.exe
            destination: C:\Windows\temp\AWSCLISetup.exe
      - name: Install
        action: ExecuteBinary
        onFailure: Continue
        inputs:
          path: '{{ build.Download.inputs[0].destination }}'
          arguments:
            - '/install'
            - '/quiet'
            - '/norestart'
      - name: Delete
        action: DeleteFile
        inputs:
          - path: '{{ build.Download.inputs[0].destination }}'
Esempio 3: installare il file AWS CLI con il programma di installazione MSI

Di seguito è riportato un documento di esempio che installa il AWS CLI con il programma di installazione MSI.

name: InstallCLIMSI
description: Install &CLI; using the MSI installer
schemaVersion: 1.0
phases:
  - name: build
    steps:
      - name: Download
        action: S3Download
        inputs:
          - source: s3://aws-cli/AWSCLI64PY3.msi
            destination: C:\Windows\temp\AWSCLI64PY3.msi
      - name: Install
        action: ExecuteBinary
        onFailure: Continue
        inputs:
          path: 'C:\Windows\System32\msiexec.exe'
          arguments:
            - '/i'
            - '{{ build.Download.inputs[0].destination }}'
            - '/quiet'
            - '/norestart'
      - name: Delete
        action: DeleteFile
        inputs:
          - path: '{{ build.Download.inputs[0].destination }}'
macOS
Esempio 1: eseguire un file binario macOS personalizzato

Di seguito è riportato un documento di esempio che scarica ed esegue un file binario personalizzato su un'istanza macOS.

name: macOSBin
description: Download and run a binary file on macOS.
schemaVersion: 1.0
phases:
  - name: build
    steps:
      - name: Download
        action: S3Download
        inputs:
          - source: s3://<replaceable>amzn-s3-demo-source-bucket</replaceable>/<replaceable>myapplication</replaceable>
            destination: /tmp/<replaceable>myapplication</replaceable>
      - name: Enable
        action: ExecuteBash
        onFailure: Continue
        inputs:
          commands:
            - 'chmod u+x {{ build.Download.inputs[0].destination }}'
      - name: Install
        action: ExecuteBinary
        onFailure: Continue
        inputs:
          path: '{{ build.Download.inputs[0].destination }}'
          arguments:
            - '--install'
      - name: Delete
        action: DeleteFile
        inputs:
          - path: '{{ build.Download.inputs[0].destination }}'