Problembehandlung bei Pipeline-Buil Fehlerbehebungsszenarien

Probleme mit Image Builder beheben

EC2Image Builder lässt sich integrieren mit AWS-Services zur Überwachung und Fehlerbehebung, um Ihnen bei der Behebung von Problemen bei der Image-Erstellung zu helfen. Image Builder verfolgt und zeigt den Fortschritt für jeden Schritt im Imageerstellungsprozess an. Darüber hinaus kann Image Builder Protokolle an einen von Ihnen angegebenen Amazon S3 S3-Speicherort exportieren.

Für eine erweiterte Problembehandlung können Sie vordefinierte Befehle und Skripts ausführen mit AWS Systems Manager Befehl ausführen.

Problembehandlung bei Pipeline-Buil

Wenn ein Image Builder-Pipeline-Build fehlschlägt, gibt Image Builder eine Fehlermeldung zurück, die den Fehler beschreibt. Image Builder gibt auch a workflow execution ID in der Fehlermeldung zurück, wie in der folgenden Beispielausgabe:


Workflow Execution ID: wf-12345abc-6789-0123-abc4-567890123abc failed with reason: …

Image Builder organisiert und leitet die Aktionen zur Image-Erstellung über eine Reihe von Schritten, die für die Laufzeitphasen in seinem standardmäßigen Image-Erstellungsprozess definiert sind. Den Erstellungs- und Testphasen des Prozesses ist jeweils ein Workflow zugeordnet. Wenn Image Builder einen Workflow zum Erstellen oder Testen eines neuen Images ausführt, generiert es eine Workflow-Metadatenressource, die die Laufzeitdetails verfolgt.

Container-Images verfügen über einen zusätzlichen Workflow, der während der Verteilung ausgeführt wird.

Recherchieren Sie in Ihrem Workflow nach Einzelheiten zu Ausfällen von Runtime-Instances

Um einen Laufzeitfehler für Ihren Workflow zu beheben, können Sie die GetWorkflowExecutionund ListWorkflowStepExecutionsAPIAktionen mit Ihrem aufrufenworkflow execution ID.

Überprüfen Sie die Workflow-Laufzeitprotokolle

CloudWatch Amazon-Protokolle

Image Builder veröffentlicht detaillierte Workflow-Ausführungsprotokolle in der folgenden Image Builder CloudWatch Builder-Protokollgruppe und dem folgenden Stream:

LogGroup:
```
/aws/imagebuilder/ImageName
```
LogStream (x.x.x/x):
```
ImageVersion/ImageBuildVersion
```
Mit CloudWatch Logs können Sie Protokolldaten mit Filtermustern durchsuchen. Weitere Informationen finden Sie unter Durchsuchen von Protokolldaten mithilfe von Filtermustern im Amazon CloudWatch Logs-Benutzerhandbuch.
AWS CloudTrail

Alle Build-Aktivitäten werden ebenfalls protokolliert CloudTrail , wenn sie in Ihrem Konto aktiviert sind. Sie können CloudTrail Ereignisse nach der Quelle filternimagebuilder.amazonaws.com. Alternativ können Sie nach der EC2 Amazon-Instance-ID suchen, die im Ausführungsprotokoll zurückgegeben wird, um weitere Details zur Pipeline-Ausführung zu erhalten.
Amazon Simple Storage Service (S3)

Wenn Sie in Ihrer Infrastrukturkonfiguration einen S3-Bucket-Namen und ein key prefix angegeben haben, folgt der Laufzeitprotokollpfad des Workflow-Schritts diesem Muster:
```
S3://S3BucketName/KeyPrefix/ImageName/ImageVersion/ImageBuildVersion/WorkflowExecutionId/StepName
```
Die Protokolle, die Sie an Ihren S3-Bucket senden, zeigen die Schritte und Fehlermeldungen für Aktivitäten auf der EC2 Instance während des Image-Build-Prozesses. Die Protokolle enthalten Protokollausgaben des Komponenten-Managers, die Definitionen der Komponenten, die ausgeführt wurden, und die detaillierte Ausgabe (inJSON) aller Schritte, die auf der Instanz ausgeführt wurden. Wenn Sie auf ein Problem stoßen, sollten Sie diese Dateien zunächst überprüfenapplication.log, um die Ursache des Problems auf der Instanz zu diagnostizieren.

Standardmäßig fährt Image Builder die EC2 Amazon-Build- oder Test-Instance herunter, die ausgeführt wird, wenn die Pipeline ausfällt. Sie können die Instance-Einstellungen für die Infrastrukturkonfigurationsressource ändern, die Ihre Pipeline verwendet, um Ihre Build- oder Test-Instance zur Fehlerbehebung beizubehalten.

Um die Instanzeinstellungen in der Konsole zu ändern, müssen Sie das Kontrollkästchen Instanz bei Ausfall beenden deaktivieren, das sich im Bereich Einstellungen zur Fehlerbehebung Ihrer Infrastrukturkonfigurationsressource befindet.

Sie können die Instanzeinstellungen auch mit dem update-infrastructure-configuration Befehl in der AWS CLI. Stellen Sie false in der JSON Datei, auf die der Befehl mit dem --cli-input-json Parameter verweist, den terminateInstanceOnFailure Wert auf ein. Details hierzu finden Sie unter Aktualisieren Sie eine Infrastrukturkonfiguration.

Fehlerbehebungsszenarien

In diesem Abschnitt werden die folgenden detaillierten Problembehandlungsszenarien aufgeführt:

Zugriff verweigert — Statuscode 403
Timeout beim Erstellen während der Überprüfung der Verfügbarkeit des Systems Manager Agents auf der Build-Instanz
Die sekundäre Windows-Festplatte ist beim Start offline
Der Build schlägt mit dem CIS gehärteten Basis-Image fehl
AssertInventoryCollection schlägt fehl (Systems Manager Automation)

Um die Details eines Szenarios zu sehen, wählen Sie den Titel des Szenarios aus, um es zu erweitern. Sie können mehrere Titel gleichzeitig erweitern lassen.

Beschreibung

Der Pipeline-Build schlägt mit dem Statuscode "AccessDenied: Zugriff verweigert: 403“ fehl.

Ursache

Mögliche Gründe hierfür sind:

Das Instanzprofil verfügt nicht über die erforderlichen Zugriffsberechtigungen für Komponentenressourcen. APIs
In der Instance-Profilrolle fehlen Berechtigungen, die für die Anmeldung bei Amazon S3 erforderlich sind. In den meisten Fällen tritt dies auf, wenn die Instance-Profilrolle keine PutObjectBerechtigungen für Ihre S3-Buckets hat.

Lösung

Je nach Ursache kann dieses Problem wie folgt behoben werden:

Im Instanzprofil fehlen verwaltete Richtlinien — Fügen Sie die fehlenden Richtlinien zu Ihrer Instanzprofilrolle hinzu. Führen Sie dann die Pipeline erneut aus.
Dem Instanzprofil fehlen Schreibberechtigungen für den S3-Bucket — Fügen Sie Ihrer Instanzprofilrolle eine Richtlinie hinzu, die PutObjectSchreibberechtigungen für Ihren S3-Bucket gewährt. Führen Sie dann die Pipeline erneut aus.

Beschreibung

Der Pipeline-Build schlägt mit „Status = 'TimedOut'“ und „Fehlermeldung = 'Timeout für den Schritt bei der Überprüfung der Verfügbarkeit des Systems Manager Manager-Agenten auf den Zielinstanzen“ fehl. '“

Ursache

Mögliche Gründe hierfür sind:

Die Instanz, die gestartet wurde, um die Build-Operationen und Komponenten auszuführen, konnte nicht auf den Systems Manager Manager-Endpunkt zugreifen.
Das Instanzprofil verfügt nicht über die erforderlichen Berechtigungen.

Lösung

Abhängig von der möglichen Ursache kann dieses Problem wie folgt behoben werden:

Zugriffsproblem, privates Subnetz — Wenn Sie ein privates Subnetz einbauen, stellen Sie sicher, dass Sie PrivateLink Endpunkte für Systems Manager, Image Builder und, falls Sie protokollieren möchten, Amazon S3 S3/ eingerichtet haben. CloudWatch Weitere Informationen zum Einrichten von Endpunkten finden Sie unter Access PrivateLink AWS Dienste über AWS PrivateLink.
Fehlende Berechtigungen — Fügen Sie Ihrer IAM serviceverknüpften Rolle für Image Builder die folgenden verwalteten Richtlinien hinzu:
- EC2InstanceProfileForImageBuilder
- EC2InstanceProfileForImageBuilderECRContainerBuilds
- Ein mazonSSMManaged InstanceCore
Weitere Informationen zur dienstverknüpften Image Builder Builder-Rolle finden Sie unterVerwenden Sie IAM serviceverknüpfte Rollen für Image Builder.

Beschreibung

Wenn der Instanztyp, der zum Erstellen eines Image Builder Builder-Windows verwendet wird, AMI nicht mit dem Instanztyp übereinstimmt, der für den Start von verwendet wirdAMI, kann ein Problem auftreten, wenn Nicht-Root-Volumes beim Start offline sind. Dies ist in erster Linie der Fall, wenn die Build-Instance eine neuere Architektur als die Startinstanz verwendet.

Das folgende Beispiel zeigt, was passiert, wenn ein Image Builder auf einem EC2 Nitro-Instanztyp AMI basiert und auf einer EC2 Xen-Instanz gestartet wird:

Build-Instance-Typ: m5.large (Nitro)

Instanztyp starten: t2.medium (Xen)


PS C:\Users\Administrator> get-disk
Number  Friendly Name  Serial Number         Health Status  Operational Status  Total Size  Partition Style
------  -------------  -------------         -------------  ------------------  ----------  ---------------
0       AWS PVDISK     vol0abc12d34e567f8a9  Healthy        Online                   30 GB  MBR
1       AWS PVDISK     vol1bcd23e45f678a9b0  Healthy        Offline                   8 GB  MBR

Ursache

Aufgrund der Windows-Standardeinstellungen werden neu entdeckte Festplatten nicht automatisch online geschaltet und formatiert. Wenn der Instanztyp aktiviert wirdEC2, behandelt Windows dies so, als würden neue Festplatten erkannt. Das liegt an der zugrunde liegenden Treiberänderung.

Lösung

Wir empfehlen, dass Sie beim Erstellen Ihres Windows dasselbe System von Instance-Typen verwendenAMI, von dem aus Sie starten möchten. Nehmen Sie in Ihrer Infrastrukturkonfiguration keine Instance-Typen auf, die auf unterschiedlichen Systemen basieren. Wenn einer der von Ihnen angegebenen Instance-Typen das Nitro-System verwendet, sollten alle das Nitro-System verwenden.

Weitere Informationen zu Instances, die auf dem Nitro-System basieren, finden Sie im EC2Amazon-Benutzerhandbuch unter Instances, die auf dem Nitro-System basieren.

Beschreibung

Sie verwenden ein CIS gehärtetes Basis-Image und der Build schlägt fehl.

Ursache

Wenn das /tmp Verzeichnis als klassifiziert istnoexec, kann dies dazu führen, dass Image Builder fehlschlägt.

Lösung

Wählen Sie im workingDirectory Feld des Image-Rezepts einen anderen Speicherort für Ihr Arbeitsverzeichnis. Weitere Informationen finden Sie in der Beschreibung des ImageRecipeDatentyps.

Beschreibung

Systems Manager Automation zeigt einen Fehler im AssertInventoryCollection Automatisierungsschritt an.

Ursache

Möglicherweise haben Sie oder Ihre Organisation eine Systems Manager State Manager-Zuordnung erstellt, die Inventarinformationen für EC2 Instances sammelt. Wenn die erweiterte Erfassung von Bildmetadaten für Ihre Image Builder-Pipeline aktiviert ist (dies ist die Standardeinstellung), versucht Image Builder, eine neue Inventarzuordnung für die Build-Instanz zu erstellen. Systems Manager lässt jedoch nicht mehrere Inventarzuordnungen für verwaltete Instanzen zu und verhindert eine neue Zuordnung, falls bereits eine vorhanden ist. Dadurch schlägt der Vorgang fehl und der Pipeline-Build schlägt fehl.

Lösung

Um dieses Problem zu beheben, deaktivieren Sie die erweiterte Erfassung von Bildmetadaten mit einer der folgenden Methoden:

Aktualisieren Sie Ihre Image-Pipeline in der Konsole, um das Kontrollkästchen Erweiterte Metadatensammlung aktivieren zu deaktivieren. Speichern Sie Ihre Änderungen und führen Sie einen Pipeline-Build aus.

Weitere Informationen zum Aktualisieren Ihrer AMI Image-Pipeline mithilfe der EC2 Image Builder Builder-Konsole finden Sie unterAktualisieren Sie AMI Image-Pipelines von der Konsole aus. Weitere Informationen zur Aktualisierung Ihrer Container-Image-Pipeline mithilfe der EC2 Image Builder Builder-Konsole finden Sie unterAktualisieren Sie eine Container-Image-Pipeline von der Konsole aus.

Sie können Ihre Image-Pipeline auch mit dem update-image-pipeline Befehl im AWS CLI. Fügen Sie dazu die EnhancedImageMetadataEnabled Eigenschaft in Ihre JSON Datei ein und setzen Sie sie auffalse. Das folgende Beispiel zeigt die Eigenschaft, die auf gesetzt istfalse.


{
    "name": "MyWindows2019Pipeline",
    "description": "Builds Windows 2019 Images",
    "enhancedImageMetadataEnabled": false,
    "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03",
    "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration",
    "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration",
    "imageTestsConfiguration": {
        "imageTestsEnabled": true,
        "timeoutMinutes": 60
    },
    "schedule": {
        "scheduleExpression": "cron(0 0 * * SUN *)",
        "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE"
    },
    "status": "ENABLED"
}

Um zu verhindern, dass dies bei neuen Pipelines passiert, deaktivieren Sie das Kontrollkästchen Erweiterte Metadatensammlung aktivieren, wenn Sie mit der EC2 Image Builder Builder-Konsole eine neue Pipeline erstellen, oder legen Sie den Wert der EnhancedImageMetadataEnabled Eigenschaft in Ihrer JSON Datei auf fest, false wenn Sie Ihre Pipeline mit dem AWS CLI.

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

Bewährte Methoden

Dokumentverlauf