Encontre a causa de uma falha na criação de imagem com contexto de falha

Quando a criação de uma imagem falha, o Image Builder relata a falha na imagemstate. O estado carrega uma mensagem que descreve a falha e o contexto estruturado da falha emfailureContext. reason

O contexto de falha é um conjunto de campos que nomeia o fluxo de trabalho, a etapa do fluxo de trabalho, a etapa do componente e as regiões de destino envolvidas na falha. Como os campos são estruturados, sua automação pode se ramificar diretamente neles e você pode passar seus valores para outras operações da API Image Builder para obter mais detalhes.

O Image Builder retorna o contexto de falha das operações de GetImageListImageBuildVersions, e ListImagePipelineImagesda API e o exibe no Image Builder Console de gerenciamento da AWS.

O que o contexto de falha contém

O contexto de falha descreve uma falha em três níveis. Cada membro é opcional, e o Image Builder retorna somente os membros que se aplicam à falha. Para os membros, seus tipos e suas restrições, consulte ImageStatea Referência da API EC2 Image Builder.

A imagem

Em qual estágio a imagem estava quando falhou e em qual fluxo de trabalho e etapa do fluxo de trabalho estavam em execução. Os identificadores do fluxo de trabalho e da execução da etapa têm os mesmos valores que ListWorkflowStepExecutionse GetWorkflowStepExecutionassumem, então você pode passá-los diretamente para essas operações.

A etapa do componente

Para uma falha de compilação ou teste causada por um componente, o componente executado, a fase e a etapa em seu documento, o módulo de AWSTOE ação que a etapa executou e o erro relatado pela etapa. O Image Builder identifica o componente por versão de compilação, então ele nomeia a revisão exata que foi executada mesmo quando sua receita faz referência a uma versão curinga. Para os módulos de ação, consulteMódulos de ação suportados por AWSTOE gerenciador de componentes.

As regiões de destino

Para uma falha de distribuição ou integração, um erro resumido para a distribuição como um todo e uma entrada para cada destino que falhou. Cada entrada contém a forma como a distribuição terminou ali, o erro do serviço que o Image Builder chamou e, para uma distribuição entre contas, o destino para o Conta da AWS qual o Image Builder distribuiu. Quando a cópia da AMI foi bem-sucedida, mas uma etapa posterior não foi bem-sucedida, a entrada também nomeia essa etapa — associar configurações de licença, atualizar modelos de execução, colocar parâmetros de SSM, atualizar as configurações do Amazon EC2 Fast Launch ou exportar a AMI. Os destinos bem-sucedidos são omitidos.

nota

Os membros retornados pelo Image Builder dependem do progresso da construção. Uma falha que ocorre antes do Image Builder iniciar um fluxo de trabalho não tem um fluxo de trabalho para nomear. Por exemplo, se a imagem principal em sua receita não existir mais, o contexto de falha identifica o estágio e nada mais.

Os exemplos Exibir o contexto de falha de uma imagem com falha mostram os membros que o Image Builder retorna em caso de falha de componente e falha de distribuição.

Exibir o contexto de falha de uma imagem com falha

Visualize o contexto da falha no console do Image Builder

O Image Builder exibe os detalhes da falha de uma imagem sempre que exibe o status Failed da imagem.

1. Abra o console https://console.aws.amazon.com/imagebuilder/do EC2 Image Builder em.

2. Escolha Imagens no painel de navegação e, em seguida, escolha a versão de criação da imagem com falha. Você também pode abrir a lista de imagens de saída para um pipeline.

3. Escolha o status Failed da imagem. O Image Builder exibe os detalhes da falha da imagem e vincula a etapa do fluxo de trabalho com falha aos detalhes do tempo de execução.

Obtenha o contexto da falha com o AWS CLI

Execute o get-image comando com o ARN da versão de compilação da imagem com falha.

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"

O exemplo de saída a seguir mostra uma compilação que falhou porque uma etapa do componente executou um script que saiu com um status diferente de 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"
        }
    }
}

O próximo exemplo de saída mostra uma imagem que foi criada e testada com sucesso e, em seguida, falhou enquanto o Image Builder atualizava os modelos de execução em três regiões de destino. A construção foi bem-sucedida em todos os outros destinos, então somente as três regiões que falharam aparecem.

{
    "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'"
                }
            ]
        }
    }
}

Para encontrar as compilações com falha em uma conta sem inspecionar cada uma, liste as versões de compilação da imagem e filtre o status da imagem. O exemplo a seguir retorna as compilações com falha de uma imagem, com o contexto de falha de cada uma.

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]"

Rastreie uma falha até sua causa raiz

O contexto de falha reduz a falha a uma única etapa. Use as etapas a seguir para ir dessa etapa até a evidência que a explica.

1. Leia imageStatus para encontrar o estágio que falhou. Um valor de BUILDING ou TESTING significa que a falha ocorreu na instância do Amazon EC2 que o Image Builder lançou, portanto, os registros do componente são o próximo local a ser examinado. Um valor de DISTRIBUTING ou INTEGRATING significa que a imagem foi criada e a falha está em suas configurações de distribuição ou em uma conta de destino ou.

2. Leia o membro que descreve a falha específica. Se componentFailure estiver presente, ele identifica a etapa com falha no documento do componente, junto com a ação que a etapa executou e o erro relatado. Se distributionFailure estiver presente, cada entrada regionFailures fornece um destino e seu próprio erro.

3. Inspecione os detalhes do tempo de execução do fluxo de trabalho. Ligue workflowExecutionId para ver cada etapa do fluxo de trabalho e onde a etapa ListWorkflowStepExecutionscom falha se enquadra na sequência. Ligue GetWorkflowStepExecutionstepExecutionIdpara saber as entradas, saídas e o status de reversão da própria etapa com falha.

   O exemplo a seguir lista as etapas de uma falha na execução do fluxo de trabalho.

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

4. Leia os registros da etapa que falhou. Use workflowExecutionId e failedStep para ir diretamente para o caminho de registro dessa etapa. Para obter mais informações, consulte Obtenha a saída completa do componente a partir dos registros.

5. Reproduza a falha, se necessário. Para manter a instância de compilação em execução para que você possa se conectar a ela, limpe a configuração Encerrar instância em caso de falha na configuração de infraestrutura que seu pipeline usa. Para obter mais informações, consulte Solucionar problemas em compilação de pipelines.

Obtenha a saída completa do componente a partir dos registros

O contexto de falha relata o erro que uma etapa do componente gerou, mas não a saída padrão e o erro padrão do script que a etapa executou. O Image Builder mantém essa saída nos registros do componente.

Quando um componente falha, AWSTOE grava os detalhes da primeira etapa com falha no log do console, seguido pela saída de erro padrão completa dessa etapa.

  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é o mesmo valor que componentFailure.componentArn relata, então use-o para combinar o bloco de log com o contexto de falha de uma imagem. Documenté o name que o documento do componente declara, que o autor escolhe independentemente do recurso do componente, para que os dois possam diferir e, por Document si só, não identifique qual componente falhou.

AWSTOE grava ErrorMessage e Stderr somente quando a etapa falhada as produziu.

O Image Builder transmite os registros do componente para o Amazon CloudWatch Logs quando a compilação é concluída. Se você especificou um bucket do Amazon S3 em sua configuração de infraestrutura, o Image Builder também os grava lá. Para os nomes do grupo de registros e do stream, consulteMonitore os registros do Image Builder com o Amazon CloudWatch Logs. Para os arquivos que AWSTOE produz e o que cada um contém, consulteRegistro em log do componente.

Use o contexto de falha com agentes de IA

O contexto de falha foi projetado para ser lido pela automação e também pelas pessoas. Um agente de IA que soluciona problemas de uma compilação com falha lê os campos nomeados e usa seus valores como argumentos para a próxima chamada de API que fizer. Isso torna o diagnóstico repetível e impede o agente de adivinhar qual componente ou investigar.

Você pode usar o contexto de falha de uma das seguintes formas:

• Solução de problemas no Image Builder Console de gerenciamento da AWS — O recurso de solução de problemas, desenvolvido pelo AWS DevOps Agent, usa o contexto de falha para direcionar sua investigação até a etapa e o componente do fluxo de trabalho que falharam antes de examinar os registros e os recursos relacionados. Para obter mais informações, consulte Solucione problemas de compilações com falha com IA - Pré-visualização.

• Seu próprio agente de codificação de IA — Um agente que liga GetImage recebe o contexto de falha na resposta e pode segui-la da mesma maneira. Para dar ao seu agente o conhecimento mais amplo do Image Builder de que ele precisa para agir de acordo com o que encontra, consulteSolucione problemas de compilações com um agente de codificação de IA.

Se você criar sua própria automação no contexto de falha, trate cada membro como opcional e verifique os membros que você usa, e não a presença de failureContext si mesmo. Os membros retornados pelo Image Builder dependem da falha, e o Image Builder pode adicionar membros ao longo do tempo.

Considerações

Observe o seguinte ao usar o contexto de falha:

• O Image Builder retorna o contexto de falha somente para imagens que falharam. Uma imagem bem-sucedida e uma imagem que você cancelou não a têm.

• Uma imagem com falha carrega reason os doisfailureContext. Use reason para obter um resumo legível da falha e failureContext localizá-la.

• Se um componente usa a ExecuteDocument ação para executar um documento aninhado, o contexto de falha identifica o componente que o Image Builder executou a partir da sua receita, não o documento aninhado.

• As mensagens de erro no contexto de falha são limitadas em comprimento e podem ser truncadas. Os registros do componente contêm a saída completa.

• O contexto da falha relata a primeira etapa que falhou. Se mais de uma etapa falhar, revise as execuções das etapas do fluxo de trabalho e os registros dos componentes para o restante.

• As mensagens de erro podem conter texto produzido por um componente ou outro AWS serviço. Trate-os como entrada não confiável se você os renderizar ou passá-los para outro sistema.