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 i 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. **Topics** + [Flusso di lavoro relativo ai documenti](#component-doc-workflow) + [Registrazione dei componenti](#component-logging) + [Concatenamento di input e output](#document-chaining) + [Schema e definizioni del documento](#document-schema) + [Esempi di documenti](#document-example) + [Usa le variabili nel tuo documento componente personalizzato](toe-user-defined-variables.md) + [Usa costrutti condizionali in AWSTOE](toe-conditional-constructs.md) + [Usa gli operatori di confronto nei documenti AWSTOE dei componenti](toe-comparison-operators.md) + [Utilizzo di operatori logici nei documenti AWSTOE dei componenti](toe-logical-operators.md) + [Usa costrutti a ciclo continuo in AWSTOE](toe-looping-constructs.md) ## 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, input/output dei valori e degli esempi, consulta[Moduli di azione supportati dal gestore AWSTOE dei componenti](toe-action-modules.md). ## Registrazione dei componenti AWSTOE crea una nuova cartella di registro sulle istanze EC2 che vengono utilizzate per creare e testare una nuova immagine, ogni volta che il componente viene eseguito. 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\` 1. **Prefisso del file**: si tratta di un prefisso standard utilizzato per tutti i componenti: "». `TOE_` 1. **Ora di esecuzione**: si tratta di un timestamp in formato \_HH-MM-SS\_UTC-0. YYYY-MM-DD 1. **ID di esecuzione: è il GUID** assegnato quando vengono eseguiti uno o più componenti. AWSTOE Ad 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 }}` or `{{ 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. 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. **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 | Description | 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. | List | Sì | Le definizioni dello schema per una fase sono le seguenti. | Campo | Description | Tipo | Richiesto | | --- | --- | --- | --- | | nome | Nome della fase. | Stringa | Sì | | steps | Elenco delle fasi della fase. | List | Sì | Le definizioni dello schema per una fase sono le seguenti. | Campo | Description | Tipo | Richiesto | Valore predefinito | | --- | --- | --- | --- | --- | | nome | Nome definito dall'utente per il passo. | Stringa | | | | operazione | 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: [See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/imagebuilder/latest/userguide/toe-use-documents.html) | 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://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - 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://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - 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 }}' ``` ------