Workflow für Komponentendokumente Protokollierung von Komponenten Verkettung von Eingabe und Ausgabe Schema und Definitionen des Dokuments Beispielschemas für Dokumente

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.

Themen

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 build der Image Builder Builder-Dienst während seiner Erstellungsphase validate Phasen 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, Eingabe-/Ausgabewerte und Beispiele finden Sie unter. Aktionsmodule, die vom AWSTOE Komponentenmanager unterstützt werden

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 folgenden Teilen:

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: /var/lib/amazon/toe/
- Windows: $env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\
Dateipräfix — Dies ist ein Standardpräfix, das für alle Komponenten verwendet wird: "TOE_“.
Laufzeit — Dies ist ein Zeitstempel im Format YYYY-MM-DD_HH-MM-SS_UTC-0.
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 }}

{{ 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. Beispielsweise:
- Ungültiger Ausdruck: echo {{ phase.step.inputs.variable }}
- Gültiger Ausdruck: "echo {{ phase.step.inputs.variable }}"
- Gültiger Ausdruck: 'echo {{ phase.step.inputs.variable }}'
Verkettete Ausdrücke können auf Variablen aus anderen Schritten und Phasen desselben Dokuments verweisen. Der aufrufende Dienst verfügt jedoch möglicherweise über Regeln, nach denen Verkettungsausdrücke nur im Kontext einer einzelnen Phase funktionieren müssen. Image Builder unterstützt beispielsweise keine Verkettung von der Buildphase zur Testphase, da jede Phase unabhängig ausgeführt wird.
Indizes in Verkettungsausdrü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	Beschreibung	Typ	Erforderlich
Name	Name des Dokuments.	String	Nein
description	Beschreibung des Dokuments.	String	Nein
schemaVersion	Schemaversion des Dokuments, derzeit 1.0.	String	Ja
phases	Eine Liste der Phasen mit ihren Schritten.	Auflisten	Ja

Die Schemadefinitionen für eine Phase lauten wie folgt.

Feld	Beschreibung	Typ	Erforderlich
Name	Name der Phase.	String	Ja
steps	Liste der Schritte in der Phase.	Auflisten	Ja

Die Schemadefinitionen für einen Schritt lauten wie folgt.

Feld	Beschreibung	Typ	Erforderlich	Standardwert
Name	Benutzerdefinierter Name für den Schritt.	String
action	Schlüsselwort für das Modul, das den Schritt ausführt.	String
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`.	String	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

Beispielschemas für Dokumente

Im Folgenden finden Sie ein Beispieldokumentschema zum Installieren aller verfügbaren Windows-Updates, zum Ausführen eines Konfigurationsskripts, zum Überprüfen der Änderungen vor der Erstellung des AMI und zum Testen der Änderungen nach der Erstellung des 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}}'

Im Folgenden finden Sie ein Beispieldokumentschema zum Herunterladen und Ausführen einer benutzerdefinierten Linux-Binärdatei.


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>mybucket</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 }}'

Im Folgenden finden Sie ein Beispiel für ein Dokumentschema zur Installation von AWS CLI auf einer Windows-Instanz mithilfe der Setup-Datei.


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 }}'

Im Folgenden finden Sie ein Beispiel für ein Dokumentschema zur Installation AWS CLI mithilfe des MSI-Installationsprogramms.


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 }}'

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Überprüfen Sie die Signatur

Verwenden Sie Variablen