View a markdown version of this page

Individuate la causa della mancata compilazione di un'immagine con contesto di errore - EC2 Image Builder
Cosa contiene il contesto di erroreVisualizza il contesto di errore per un'immagine fallitaRiconduci un errore alla sua causa principaleUsa il contesto di errore con gli agenti AIConsiderazioni

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à.

Individuate la causa della mancata compilazione di un'immagine con contesto di errore

Quando la creazione di un'immagine non riesce, Image Builder riporta l'errore nell'immagine. state Lo stato contiene un messaggio che descrive l'errore e il contesto di errore strutturato in failureContext esso. reason

Il contesto di errore è un insieme di campi che denominano il flusso di lavoro, la fase del flusso di lavoro, la fase del componente e le regioni di destinazione coinvolte nell'errore. Poiché i campi sono strutturati, l'automazione può diramarsi direttamente su di essi ed è possibile passare i loro valori ad altre operazioni dell'API Image Builder per ottenere maggiori dettagli.

Image Builder restituisce il contesto di errore dalle operazioni GetImageListImageBuildVersions, e ListImagePipelineImagesAPI e lo visualizza in Image Builder. Console di gestione AWS

Cosa contiene il contesto di errore

Il contesto di errore descrive un errore a tre livelli. Ogni membro è facoltativo e Image Builder restituisce solo i membri che si applicano all'errore. Per i membri, i loro tipi e i loro vincoli, consulta la Guida di riferimento ImageStateall'API EC2 Image Builder.

L'immagine

In quale fase si trovava l'immagine al momento dell'errore e in quale fase del flusso di lavoro e in quale fase del flusso di lavoro erano in esecuzione. Gli identificatori del flusso di lavoro e di esecuzione delle fasi hanno gli stessi valori che ListWorkflowStepExecutionsGetWorkflowStepExecutionassumono, quindi è possibile passarli direttamente a tali operazioni.

La fase componente

Per un errore di compilazione o test causato da un componente, il componente che è stato eseguito, la fase e la fase all'interno del relativo documento, il modulo di AWSTOE azione eseguito dalla fase e l'errore segnalato dalla fase. Image Builder identifica il componente in base alla versione di build, quindi assegna un nome alla revisione esatta eseguita anche quando la ricetta fa riferimento a una versione con caratteri jolly. Per i moduli di azione, vedi. Moduli d'azione supportati da AWSTOE gestore dei componenti

Le regioni di destinazione

In caso di errore di distribuzione o integrazione, un errore di riepilogo per l'intera distribuzione e una voce per ogni destinazione non riuscita. Ogni voce riporta la data in cui è terminata la distribuzione, l'errore del servizio chiamato da Image Builder e, per una distribuzione tra account, la destinazione a cui Image Account AWS Builder ha distribuito. Quando la copia dell'AMI ha avuto successo, ma una fase successiva no, la voce indica anche quella fase: associazione delle configurazioni di licenza, aggiornamento dei modelli di avvio, inserimento dei parametri SSM, aggiornamento delle configurazioni Fast Launch di Amazon EC2 o esportazione dell'AMI. Le destinazioni che hanno avuto successo vengono omesse.

Nota

I membri restituiti da Image Builder dipendono dall'avanzamento della build. Un errore che si verifica prima che Image Builder avvii un workflow non ha alcun workflow da nominare. Ad esempio, se l'immagine principale della ricetta non esiste più, il contesto di errore identifica la fase e nient'altro.

Gli esempi illustrati Visualizza il contesto di errore per un'immagine fallita mostrano i membri che Image Builder restituisce in caso di errore di un componente e di distribuzione.

Visualizza il contesto di errore per un'immagine fallita

Visualizza il contesto dell'errore nella console Image Builder

Image Builder visualizza i dettagli dell'errore di un'immagine ovunque mostri lo stato Failed dell'immagine.

  1. Apri la console EC2 Image Builder https://console.aws.amazon.com/imagebuilder/all'indirizzo.

  2. Scegli Immagini dal pannello di navigazione, quindi scegli la versione di creazione dell'immagine non riuscita. Puoi anche aprire l'elenco delle immagini di output per una pipeline.

  3. Scegliete lo stato Failed dell'immagine. Image Builder visualizza i dettagli dell'errore per l'immagine e collega la fase del flusso di lavoro non riuscita ai relativi dettagli di runtime.

Ottieni il contesto dell'errore con AWS CLI

Esegui il get-image comando con la versione di build ARN dell'immagine fallita.

aws imagebuilder get-image \
    --image-build-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1 \
    --query "image.state"

L'output di esempio seguente mostra una compilazione non riuscita perché una fase del componente ha eseguito uno script che è uscito con uno stato diverso da zero.

{
    "status": "FAILED",
    "reason": "Workflow Execution ID: 'wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' failed with reason: Document arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1 failed!",
    "failureContext": {
        "imageStatus": "BUILDING",
        "workflowExecutionId": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "workflowArn": "arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/x.x.x/x",
        "stepExecutionId": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
        "failedStep": "ApplyBuildComponents",
        "componentFailure": {
            "componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1",
            "phaseName": "build",
            "stepName": "InstallPackages",
            "action": "ExecuteBash",
            "errorMessage": "exit status 1"
        }
    }
}

L'output di esempio successivo mostra un'immagine creata e testata con successo, poi fallita mentre Image Builder aggiornava i modelli di avvio in tre regioni di destinazione. La compilazione è riuscita in tutte le altre destinazioni, quindi vengono visualizzate solo le tre regioni non riuscite.

{
    "status": "FAILED",
    "reason": "Integration failed with JobId 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1'. …",
    "failureContext": {
        "imageStatus": "INTEGRATING",
        "distributionFailure": {
            "errorMessage": "In region 'eu-west-1' - 'EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'' …",
            "regionFailures": [
                {
                    "region": "eu-west-1",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'"
                },
                {
                    "region": "us-east-1",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-1a2b3c4d5EXAMPLE' does not exist'"
                },
                {
                    "region": "us-east-2",
                    "status": "FAILED",
                    "imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
                    "errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-2a3b4c5d6EXAMPLE' does not exist'"
                }
            ]
        }
    }
}

Per trovare le build fallite in un account senza controllarle ognuna, elenca le versioni di build dell'immagine e filtra in base allo stato dell'immagine. L'esempio seguente restituisce le build fallite di un'immagine, con il contesto di errore per ciascuna di esse.

aws imagebuilder list-image-build-versions \
    --image-version-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0 \
    --query "imageSummaryList[?state.status=='FAILED'].[arn, state.failureContext]"

Riconduci un errore alla sua causa principale

Il contesto di errore limita un errore a un singolo passaggio. Utilizza i seguenti passaggi per passare da quel passaggio alle prove che lo spiegano.

  1. Leggi imageStatus per scoprire la fase che è fallita. Un valore di BUILDING o TESTING indica che l'errore si è verificato sull'istanza Amazon EC2 lanciata da Image Builder, quindi i log dei componenti sono la prossima cosa da consultare. Un valore di DISTRIBUTING o INTEGRATING indica che l'immagine è stata creata e l'errore è nelle impostazioni di distribuzione o in un account di destinazione o.

  2. Leggi il membro che descrive l'errore specifico. Se componentFailure presente, identifica la fase non riuscita nel documento del componente, insieme all'azione eseguita e all'errore segnalato. Se distributionFailure è presente, ogni voce regionFailures fornisce una destinazione e il relativo errore.

  3. Esamina i dettagli del runtime del flusso di lavoro. Chiama ListWorkflowStepExecutionscon workflowExecutionId per vedere ogni passaggio del flusso di lavoro e dove rientra il passaggio non riuscito nella sequenza. Chiama GetWorkflowStepExecutionwith stepExecutionId per conoscere gli input, gli output e lo stato di rollback del passaggio fallito stesso.

    L'esempio seguente elenca i passaggi per un'esecuzione non riuscita del flusso di lavoro.

    aws imagebuilder list-workflow-step-executions \
    --workflow-execution-id wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

  4. Leggete i registri relativi al passaggio non riuscito. Usa workflowExecutionId e failedStep vai direttamente al percorso di registro relativo a quel passaggio. Per ulteriori informazioni, consulta Ottieni l'output completo dei componenti dai log.

  5. Se necessario, riproduci l'errore. Per mantenere l'istanza di build in esecuzione in modo da potervi connettere, deselezionate l'impostazione Terminate instance on failure nella configurazione dell'infrastruttura utilizzata dalla pipeline. Per ulteriori informazioni, consulta Risolvi i problemi relativi alle build della pipeline.

Ottieni l'output completo dei componenti dai log

Il contesto di errore riporta l'errore generato da una fase del componente, ma non lo standard output e l'errore standard dello script eseguito dal passaggio. Image Builder mantiene l'output nei log dei componenti.

Quando un componente si guasta, AWSTOE scrive i dettagli del primo passaggio non riuscito nel registro della console, seguiti dall'output di errore standard completo relativo a quel passaggio.

  Document: MyExampleDocument
  ComponentArn: arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1
  Phase: build
  Step: InstallPackages
  Action: ExecuteBash
  ErrorMessage: exit status 1
  Stderr: the full standard error output of the step

ComponentArnè lo stesso valore componentFailure.componentArn riportato, quindi usalo per abbinare il blocco di registro al contesto di errore di un'immagine. Documentè quello dichiarato dal documento componente, name che l'autore sceglie indipendentemente dalla risorsa del componente, quindi i due possono differire e Document da soli non identificano quale componente ha avuto esito negativo.

AWSTOE scrive ErrorMessage e Stderr solo quando il passaggio fallito li ha prodotti.

Image Builder trasmette i log dei componenti ad CloudWatch Amazon Logs al termine della build. Se hai specificato un bucket Amazon S3 nella configurazione dell'infrastruttura, Image Builder li scrive anche lì. Per i nomi dei gruppi di log e degli stream, consulta. Monitora i log di Image Builder con Amazon Logs CloudWatch Per i file che AWSTOE produce e il contenuto di ognuno di essi, vediRegistrazione dei componenti.

Usa il contesto di errore con gli agenti AI

Il contesto di errore è progettato per essere letto dall'automazione così come dalle persone. Un agente AI che risolve i problemi di una build fallita legge i campi denominati e ne usa i valori come argomenti per la successiva chiamata API che effettua. Ciò rende una diagnosi ripetibile e impedisce all'agente di indovinare su quale componente indagare.

È possibile utilizzare il contesto di errore in uno dei seguenti modi:

  • Risoluzione dei problemi in Image Console di gestione AWS Builder: la funzionalità di risoluzione dei problemi, fornita AWS DevOps da Agent, utilizza il contesto degli errori per analizzare la fase del flusso di lavoro e il componente che ha avuto esito negativo prima di esaminare i log e le risorse correlate. Per ulteriori informazioni, consulta Risolvi i problemi relativi alle build fallite con AI - Preview.

  • Il tuo agente di codifica AI: un agente che chiama GetImage riceve il contesto di errore nella risposta e può seguirlo allo stesso modo. Per fornire al tuo agente la conoscenza più ampia di Image Builder di cui ha bisogno per agire su ciò che trova, vedi. Risolvi i problemi relativi alle build con un agente di codifica AI

Se costruisci la tua automazione sul contesto di errore, considera ogni membro come facoltativo e controlla i membri che utilizzi anziché la presenza dei failureContext membri stessi. I membri restituiti da Image Builder dipendono dall'errore e Image Builder può aggiungere membri nel tempo.

Considerazioni

Quando si utilizza il contesto di errore, tenere presente quanto segue:

  • Image Builder restituisce il contesto di errore solo per le immagini che hanno avuto esito negativo. Un'immagine riuscita e un'immagine che hai cancellato non ce l'hanno.

  • Un'immagine fallita contiene entrambi reason efailureContext. Utilizzatelo reason per un riepilogo leggibile dell'errore e failureContext per localizzarlo.

  • Se un componente utilizza l'ExecuteDocumentazione per eseguire un documento nidificato, il contesto di errore identifica il componente che Image Builder ha eseguito dalla ricetta, non il documento nidificato.

  • I messaggi di errore nel contesto di errore hanno una lunghezza limitata e possono essere troncati. I log dei componenti contengono l'output completo.

  • Il contesto di errore riporta il primo passaggio non riuscito. Se più di un passaggio non è riuscito, esamina le esecuzioni delle fasi del flusso di lavoro e i registri dei componenti per il resto.

  • I messaggi di errore possono contenere testo prodotto da un componente o da un altro AWS servizio. Trattali come input non attendibili se li renderizzi o li passi a un altro sistema.