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. # Benutze die AWSTOE Komponenten-Dokumenten-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-based 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 Komponentendokumente](#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 Komponentendokumente](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 Komponentendokumente 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 im Allgemeinen während der *Buildphase* verwendet. + **validieren** — für Image Builder wird diese Phase im Allgemeinen 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 unterstützt von AWSTOE Komponentenmanager](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 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 UTC-0 Format YYYY-MM-DD \_ HH-MM-SS \_. 1. **Ausführungs-ID** — Dies ist die GUID, die zugewiesen wird, wenn eine oder mehrere Komponenten AWSTOE ausgeführt werden. 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 müssen. 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) und verweist auf das erste Element. **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 | Das `schemaVersion` Feld akzeptiert `"1.0"` oder `"1"` (was normalisiert sich auf`"1.0"`). AWSTOE unterstützt keine anderen Schemaversionen. Sie können das optionale `disableLogging` Feld `true` auf Dokument-, Phasen- oder Schrittebene auf festlegen. Mit dieser Einstellung wird die Protokollausgabe für diesen Bereich unterdrückt. Verwenden Sie diese Einstellung für Schritte, die vertrauliche Daten verarbeiten. Die Schemadefinitionen für eine Phase lauten wie folgt. | Feld | Description | Typ | Erforderlich | | --- | --- | --- | --- | | Name | Name der Phase. Phasennamen müssen den folgenden Regeln entsprechen:+ Phasennamen dürfen nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten.
+ Phasennamen müssen 3 bis 128 Zeichen lang sein.
+ Phasennamen müssen innerhalb eines Dokuments eindeutig sein.
+ Bei Verwendung mit EC2 Image Builder muss mindestens eine Phase benannt werden `build``validate`, oder`test`. | 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 | User-defined Name für den Schritt. Die Namen der Schritte müssen den folgenden Regeln entsprechen:+ Schrittnamen dürfen nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten.
+ Schrittnamen müssen 3 bis 128 Zeichen lang sein.
+ Schrittnamen müssen innerhalb einer Phase eindeutig sein. | 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: + **Abbrechen** — Der Schritt schlägt nach der maximalen Anzahl von Versuchen fehl und beendet die Ausführung. Setzt den Status für Phase und Dokument auf`Failed`.
+ **Fortfahren** — Der Schritt schlägt nach der maximalen Anzahl von Versuchen fehl und setzt die Ausführung der verbleibenden Schritte fort. Setzt den Status für Phase und Dokument auf`Failed`.
+ **Ignorieren** — Legt fest, dass der `IgnoredFailure` Schritt die maximale Anzahl fehlgeschlagener Versuche erreicht hat, und setzt die Ausführung der verbleibenden Schritte fort. Setzt den Status für Phase und Dokument auf`SuccessWithIgnoredFailure`. | 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 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 AWS CLI mit dem MSI-Installer** 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 }}' ``` ------