Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Verwenden Sie das AWSTOE Component Document Framework für benutzerdefinierte Komponenten Um eine Komponente mithilfe des Komponenten-Frameworks AWS Task Orchestrator and Executor (AWSTOE) zu erstellen, müssen Sie ein YAML-basiertes Dokument bereitstellen, das die Phasen und Schritte darstellt, die für die von Ihnen erstellte Komponente gelten. AWS-Services verwenden Sie Ihre Komponente, wenn sie ein neues Amazon Machine Image (AMI) oder Container-Image erstellen. **Topics** + [Workflow für Komponenten-Dokumente](#component-doc-workflow) + [Protokollierung von Komponenten](#component-logging) + [Verkettung von Eingabe und Ausgabe](#document-chaining) + [Schema und Definitionen des Dokuments](#document-schema) + [Beispiele für Dokumente](#document-example) + [Verwenden Sie Variablen in Ihrem Dokument mit benutzerdefinierten Komponenten](toe-user-defined-variables.md) + [Verwenden Sie bedingte Konstrukte in AWSTOE](toe-conditional-constructs.md) + [Verwenden Sie Vergleichsoperatoren in AWSTOE Komponentendokumenten](toe-comparison-operators.md) + [Verwenden Sie logische Operatoren in AWSTOE Komponentendokumenten](toe-logical-operators.md) + [Verwenden Sie Looping-Konstrukte in AWSTOE](toe-looping-constructs.md) ## Workflow für Komponenten-Dokumente Das AWSTOE Komponentendokument verwendet Phasen und Schritte, um verwandte Aufgaben zu gruppieren und diese Aufgaben in einem logischen Workflow für die Komponente zu organisieren. **Tipp** Der Dienst, der Ihre Komponente zum Erstellen eines Images verwendet, implementiert möglicherweise Regeln darüber, welche Phasen für den Build-Prozess verwendet werden sollen und wann diese Phasen ausgeführt werden dürfen. Dies ist wichtig, wenn Sie Ihre Komponente entwerfen. **Phasen** Phasen stellen den Verlauf Ihres Workflows durch den Image-Erstellungsprozess dar. Beispielsweise verwendet der Image Builder Builder-Dienst die `validate` Phasen `build` und Phasen während der *Erstellungsphase* für die von ihm erstellten Images. Es verwendet die `container-host-test` Phasen `test` und während der *Testphase*, um sicherzustellen, dass der Image-Snapshot oder das Container-Image die erwarteten Ergebnisse liefert, bevor das endgültige AMI erstellt oder das Container-Image verteilt wird. Wenn die Komponente ausgeführt wird, werden die zugehörigen Befehle für jede Phase in der Reihenfolge angewendet, in der sie im Komponentendokument erscheinen. **Regeln für Phasen** + Jeder Phasenname muss innerhalb eines Dokuments eindeutig sein. + Sie können viele Phasen in Ihrem Dokument definieren. + Sie müssen mindestens eine der folgenden Phasen in Ihr Dokument aufnehmen: + **build** — für Image Builder wird diese Phase in der Regel während der *Buildphase* verwendet. + **validieren** — für Image Builder wird diese Phase in der Regel während der *Erstellungsphase* verwendet. + **test** — für Image Builder wird diese Phase im Allgemeinen während der *Testphase* verwendet. + Phasen werden immer in der Reihenfolge ausgeführt, in der sie im Dokument definiert sind. Die Reihenfolge, in der sie für AWSTOE Befehle in angegeben sind, AWS CLI hat keine Auswirkung. **Schritte** Schritte sind einzelne Arbeitseinheiten, die den Arbeitsablauf innerhalb jeder Phase definieren. Die Schritte werden nacheinander ausgeführt. Die Eingabe oder Ausgabe für einen Schritt kann jedoch auch als Eingabe in einen nachfolgenden Schritt einfließen. Dies wird als „Verkettung“ bezeichnet. **Regeln für Schritte** + Der Schrittname muss für die Phase eindeutig sein. + Der Schritt muss eine unterstützte Aktion (Aktionsmodul) verwenden, die einen Exit-Code zurückgibt. Eine vollständige Liste der unterstützten Aktionsmodule, deren Funktionsweise, input/output Werte und Beispiele finden Sie unter[Aktionsmodule, die vom AWSTOE Komponentenmanager unterstützt werden](toe-action-modules.md). ## Protokollierung von Komponenten AWSTOE erstellt bei jeder Ausführung Ihrer Komponente einen neuen Protokollordner auf den EC2-Instances, die zum Erstellen und Testen eines neuen Images verwendet werden. Bei Container-Images wird der Protokollordner im Container gespeichert. Zur Unterstützung bei der Problembehandlung, falls bei der Erstellung des Images ein Fehler auftritt, werden das Eingabedokument und alle Ausgabedateien, die bei der Ausführung der Komponente AWSTOE erstellt werden, im Protokollordner gespeichert. Der Name des Protokollordners besteht aus den folgenden Teilen: 1. **Protokollverzeichnis** — Wenn ein Dienst eine AWSTOE Komponente ausführt, übergibt sie das Protokollverzeichnis zusammen mit anderen Einstellungen für den Befehl. In den folgenden Beispielen zeigen wir das Protokolldateiformat, das Image Builder verwendet. + **Linux und macOS**: `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **Dateipräfix** — Dies ist ein Standardpräfix, das für alle Komponenten verwendet wird: "`TOE_`“. 1. **Laufzeit — Dies ist ein Zeitstempel** im Format YYYY-MM-DD \_HH-MM-SS\_UTC-0. 1. **Ausführungs-ID — Dies ist die GUID**, die zugewiesen wird, wenn eine oder mehrere Komponenten ausgeführt werden. AWSTOE Beispiel: `{{/var/lib/amazon/toe/}}TOE_{{2021-07-01_12-34-56_UTC-0}}_{{a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4}}` AWSTOE speichert die folgenden Kerndateien im Protokollordner: **Eingabedateien** + **document.yaml** — Das Dokument, das als Eingabe für den Befehl verwendet wird. Nachdem die Komponente ausgeführt wurde, wird diese Datei als Artefakt gespeichert. **Ausgabedateien** + **application.log** — Das Anwendungsprotokoll enthält Informationen auf Debug-Ebene mit Zeitstempel AWSTOE darüber, was passiert, während die Komponente ausgeführt wird. + **detailedoutput.json** — Diese JSON-Datei enthält detaillierte Informationen zum Ausführungsstatus, zu Eingaben, Ausgaben und Fehlern für alle Dokumente, Phasen und Schritte, die für die Komponente gelten, während sie ausgeführt wird. + **console.log** — Das Konsolenprotokoll enthält alle Standardausgangsinformationen (stdout) und Standardfehlerinformationen (stderr), die in die Konsole AWSTOE geschrieben werden, während die Komponente ausgeführt wird. + **chaining.json** — Diese JSON-Datei stellt Optimierungen dar, die zur Auflösung von Verkettungsausdrücken angewendet wurden. AWSTOE **Anmerkung** Der Protokollordner kann auch andere temporäre Dateien enthalten, die hier nicht behandelt werden. ## Verkettung von Eingabe und Ausgabe Die AWSTOE Konfigurationsverwaltungsanwendung bietet eine Funktion zum Verketten von Eingaben und Ausgaben, indem Verweise in den folgenden Formaten geschrieben werden: `{{ phase_name.step_name.inputs/outputs.variable }}` oder `{{ phase_name.step_name.inputs/outputs[index].variable }}` Mit der Verkettungsfunktion können Sie Code recyceln und die Wartbarkeit des Dokuments verbessern. **Regeln für die Verkettung** + Verkettungsausdrücke können nur im Eingabebereich jedes Schritts verwendet werden. + Anweisungen mit verketteten Ausdrücken müssen in Anführungszeichen gesetzt werden. Beispiel: + **Ungültiger Ausdruck**: `echo {{ phase.step.inputs.variable }}` + **Gültiger Ausdruck**: `"echo {{ phase.step.inputs.variable }}"` + **Gültiger Ausdruck**: `'echo {{ phase.step.inputs.variable }}'` + Durch Verkettung von Ausdrücken können Variablen aus anderen Schritten und Phasen desselben Dokuments referenziert werden. Der aufrufende Dienst verfügt jedoch möglicherweise über Regeln, nach denen Verkettungsausdrücke nur im Kontext einer einzelnen Phase ausgeführt werden dürfen. Image Builder unterstützt beispielsweise keine Verkettung von der *Buildphase* zur *Testphase, da jede Phase* unabhängig ausgeführt wird. + Indizes in der Verkettung von Ausdrücken folgen einer nullbasierten Indizierung. Der Index beginnt mit Null (0), um auf das erste Element zu verweisen. **Beispiele** Um im zweiten Eintrag des folgenden Beispielschritts auf die Quellvariable zu verweisen, lautet `{{ build.{{SampleS3Download}}.inputs[1].source }}` das Verkettungsmuster. ``` 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' ``` Um auf die Ausgangsvariable (entspricht „Hello“) des folgenden Beispielschritts zu verweisen, lautet das Verkettungsmuster. `{{ build.{{SamplePowerShellStep}}.outputs.stdout }}` ``` phases: - name: 'build' steps: - name: {{SamplePowerShellStep}} action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## Schema und Definitionen des Dokuments Das Folgende ist das YAML-Schema für ein Dokument. ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` Die Schemadefinitionen für ein Dokument lauten wie folgt. | Feld | Description | Typ | Erforderlich | | --- | --- | --- | --- | | Name | Name des Dokuments. | Zeichenfolge | Nein | | description | Beschreibung des Dokuments. | Zeichenfolge | Nein | | schemaVersion | Schemaversion des Dokuments, derzeit 1.0. | Zeichenfolge | Ja | | phases | Eine Liste der Phasen mit ihren Schritten. | Auflisten | Ja | Die Schemadefinitionen für eine Phase lauten wie folgt. | Feld | Description | Typ | Erforderlich | | --- | --- | --- | --- | | Name | Name der Phase. | Zeichenfolge | Ja | | steps | Liste der Schritte in der Phase. | Auflisten | Ja | Die Schemadefinitionen für einen Schritt lauten wie folgt. | Feld | Description | Typ | Erforderlich | Standardwert | | --- | --- | --- | --- | --- | | Name | Benutzerdefinierter Name für den Schritt. | Zeichenfolge | | | | action | Schlüsselwort, das sich auf das Modul bezieht, das den Schritt ausführt. | Zeichenfolge | | | | timeoutSeconds | Anzahl der Sekunden, die der Schritt ausgeführt wird, bevor er fehlschlägt oder es erneut versucht.
Unterstützt auch den Wert -1, was auf ein unendliches Timeout hinweist. 0 und andere negative Werte sind nicht zulässig. | Ganzzahl | Nein | 7.200 Sekunden (120 Minuten) | | onFailure | Gibt an, wie der Schritt im Falle eines Fehlers vorgehen soll. Gültige Werte sind: [See the AWS documentation website for more details](http://docs.aws.amazon.com/de_de/imagebuilder/latest/userguide/toe-use-documents.html) | Zeichenfolge | Nein | Abbrechen | | maxAttempts | Höchstzahl zulässiger Versuche, bevor der Schritt fehlschlägt. | Ganzzahl | Nein | 1 | | inputs | Enthält Parameter, die das Aktionsmodul benötigt, um den Schritt auszuführen. | Diktieren | Ja | | ## Beispiele für Dokumente Die folgenden Beispiele zeigen AWSTOE Komponentendokumente, die Aufgaben für das Zielbetriebssystem ausführen. ------ #### [ Linux ] **Beispiel 1: Führen Sie eine benutzerdefinierte Binärdatei aus** Im Folgenden finden Sie ein Beispieldokument, das eine benutzerdefinierte Binärdatei herunterlädt und auf einer Linux-Instanz ausführt. ``` 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 ] **Beispiel 1: Installieren Sie Windows-Updates** Das folgende Beispieldokument installiert alle verfügbaren Windows-Updates, führt ein Konfigurationsskript aus, überprüft die Änderungen, bevor das AMI erstellt wird, und testet die Änderungen, nachdem das AMI erstellt wurde. ``` 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}}' ``` **Beispiel 2: Installieren Sie das AWS CLI auf einer Windows-Instanz** Im Folgenden finden Sie ein Beispieldokument, das mithilfe der Setup-Datei AWS CLI auf einer Windows-Instanz installiert wird. ``` 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 }}' ``` **Beispiel 3: Installieren Sie das AWS CLI mit dem MSI-Installationsprogramm** Im Folgenden finden Sie ein Beispieldokument, das AWS CLI mit dem MSI-Installationsprogramm installiert wird. ``` 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 ] **Beispiel 1: Eine benutzerdefinierte macOS-Binärdatei ausführen** Im Folgenden finden Sie ein Beispieldokument, das eine benutzerdefinierte Binärdatei herunterlädt und auf einer macOS-Instanz ausführt. ``` 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 }}' ``` ------