View a markdown version of this page

실패 컨텍스트를 사용하여 실패한 이미지 빌드의 원인 찾기 - EC2 Image Builder
장애 컨텍스트에 포함된 내용실패한 이미지에 대한 실패 컨텍스트 보기근본 원인에 대한 실패 추적AI 에이전트와 함께 장애 컨텍스트 사용고려 사항

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

실패 컨텍스트를 사용하여 실패한 이미지 빌드의 원인 찾기

이미지 빌드가 실패하면 Image Builder는 이미지에서 실패를 보고합니다state. 상태에는의 실패reason와의 구조화된 실패 컨텍스트를 설명하는 메시지가 들어 있습니다failureContext.

실패 컨텍스트는 워크플로, 워크플로 단계, 구성 요소 단계 및 실패와 관련된 대상 리전의 이름을 지정하는 필드 집합입니다. 필드가 구조화되어 있으므로 자동화가 직접 분기할 수 있으며 해당 값을 다른 Image Builder API 작업에 전달하여 자세한 내용을 확인할 수 있습니다.

Image Builder는 GetImage, ListImageBuildVersions 및 ListImagePipelineImages API 작업에서 실패 컨텍스트를 반환하고 Image Builder에 표시합니다 AWS Management Console.

장애 컨텍스트에 포함된 내용

장애 컨텍스트는 세 가지 수준에서 장애를 설명합니다. 모든 멤버는 선택 사항이며 Image Builder는 실패에 적용되는 멤버만 반환합니다. 멤버, 유형 및 제약 조건은 EC2 Image Builder API 참조의 ImageState를 참조하세요.

이미지

실패한 이미지의 단계와 실행 중인 워크플로 및 워크플로 단계입니다. 워크플로 및 단계 실행 식별자는 ListWorkflowStepExecutions 및 GetWorkflowStepExecution이 취하는 값과 동일하므로 해당 작업에 직접 전달할 수 있습니다.

구성 요소 단계

구성 요소에서 발생한 빌드 또는 테스트 실패의 경우 실행된 구성 요소, 문서 내의 단계 및 단계, 단계가 실행된 AWSTOE 작업 모듈, 단계가 보고한 오류. Image Builder는 빌드 버전별로 구성 요소를 식별하므로 레시피가 와일드카드 버전을 참조하더라도 실행된 정확한 개정의 이름을 지정합니다. 작업 모듈은 단원을 참조하십시오AWSTOE 구성 요소 관리자가 지원하는 작업 모듈.

대상 리전

배포 또는 통합 실패의 경우 배포 전체에 대한 요약 오류와 실패한 각 대상에 대해 하나의 항목입니다. 각 항목에는 , 배포가 종료된 방식, Image Builder가 호출한 서비스의 오류, 교차 계정 배포의 경우 Image Builder AWS 계정 가 배포한 대상이 포함됩니다. AMI 복사가 성공했지만 AMI를 따르는 단계가 성공하지 않은 경우 항목에는 라이선스 구성 연결, 시작 템플릿 업데이트, SSM 파라미터 추가, Amazon EC2 Fast Launch 구성 업데이트 또는 AMI 내보내기와 같은 단계의 이름도 지정됩니다. 성공한 대상은 생략됩니다.

참고

Image Builder가 반환하는 멤버는 빌드가 얼마나 진행되었는지에 따라 달라집니다. Image Builder가 워크플로를 시작하기 전에 발생하는 실패에는 이름을 지정할 워크플로가 없습니다. 예를 들어 레시피의 상위 이미지가 더 이상 존재하지 않는 경우 실패 컨텍스트는 스테이지를 식별하고 더 이상 식별하지 않습니다.

의 예제는 Image Builder가 구성 요소 실패 및 배포 실패에 대해 반환하는 멤버를 실패한 이미지에 대한 실패 컨텍스트 보기 보여줍니다.

실패한 이미지에 대한 실패 컨텍스트 보기

Image Builder 콘솔에서 실패 컨텍스트 보기

Image Builder는 이미지 상태를 표시할 때마다 Failed 이미지에 대한 실패 세부 정보를 표시합니다.

  1. https://console.aws.amazon.com/imagebuilder/에서 EC2 Image Builder 콘솔을 엽니다.

  2. 탐색 창에서 이미지를 선택한 다음 실패한 이미지 빌드 버전을 선택합니다. 파이프라인의 출력 이미지 목록을 열 수도 있습니다.

  3. Failed 이미지 상태를 선택합니다. Image Builder는 이미지에 대한 실패 세부 정보를 표시하고 실패한 워크플로 단계를 런타임 세부 정보에 연결합니다.

를 사용하여 실패 컨텍스트 가져오기 AWS CLI

실패한 이미지의 빌드 버전 ARN으로 get-image 명령을 실행합니다.

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"

다음 예제 출력은 구성 요소 단계가 0이 아닌 상태로 종료된 스크립트를 실행했기 때문에 실패한 빌드를 보여줍니다.

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

다음 예제 출력은 Image Builder가 세 개의 대상 리전에서 시작 템플릿을 업데이트하는 동안 성공적으로 빌드하고 테스트한 다음 실패한 이미지를 보여줍니다. 빌드가 다른 모든 대상에서 성공했으므로 실패한 세 개의 리전만 나타납니다.

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

각 빌드를 검사하지 않고 계정에서 실패한 빌드를 찾으려면 이미지 빌드 버전을 나열하고 이미지 상태를 기준으로 필터링합니다. 다음 예제에서는 이미지에 대해 실패한 빌드를 각각에 대한 실패 컨텍스트와 함께 반환합니다.

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

근본 원인에 대한 실패 추적

장애 컨텍스트는 장애를 단일 단계로 좁힙니다. 다음 단계를 사용하여 해당 단계에서 설명하는 증거로 이동합니다.

  1. imageStatus를 읽고 실패한 스테이지를 찾습니다. BUILDING 또는 값은 Image Builder가 시작한 Amazon EC2 인스턴스에서 장애가 발생했음을 TESTING 의미하므로 구성 요소 로그가 다음 위치가 됩니다. DISTRIBUTING 또는 값은 이미지가 빌드되었고 장애가 배포 설정 또는 대상 계정 또는에 있음을 INTEGRATING 의미합니다.

  2. 특정 실패를 설명하는 멤버를 읽습니다. componentFailure이 있는 경우 구성 요소 문서의 실패 단계와 단계가 실행한 작업 및 보고된 오류를 식별합니다. distributionFailure이 있는 경우의 각 항목은 대상과 자체 오류를 regionFailures 제공합니다.

  3. 워크플로 런타임 세부 정보를 검사합니다. 를 사용하여 ListWorkflowStepExecutions를 호출workflowExecutionId하여 워크플로의 모든 단계와 실패한 단계가 시퀀스에 속하는 위치를 확인합니다. 실패한 단계 자체의 입력, 출력 및 롤백 상태에 stepExecutionId 대해를 사용하여 GetWorkflowStepExecution을 호출합니다.

    다음 예시에서는 실패한 워크플로 실행에 대한 단계를 나열합니다.

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

  4. 실패한 단계의 로그를 읽습니다. workflowExecutionId 및 failedStep를 사용하여 해당 단계의 로그 경로로 바로 이동합니다. 자세한 내용은 로그에서 전체 구성 요소 출력 가져오기 섹션을 참조하세요.

  5. 필요한 경우 실패를 재현합니다. 빌드 인스턴스에 연결할 수 있도록 빌드 인스턴스를 계속 실행하려면 파이프라인에서 사용하는 인프라 구성에서 실패 시 인스턴스 종료 설정을 지웁니다. 자세한 내용은 파이프라인 빌드 문제 해결 섹션을 참조하세요.

로그에서 전체 구성 요소 출력 가져오기

오류 컨텍스트는 구성 요소 단계에서 발생한 오류를 보고하지만 단계가 실행한 스크립트의 표준 출력 및 표준 오류는 보고하지 않습니다. Image Builder는 해당 출력을 구성 요소 로그에 유지합니다.

구성 요소가 실패하면는 첫 번째 실패한 단계의 세부 정보를 콘솔 로그에 AWSTOE 쓴 다음 해당 단계의 전체 표준 오류 출력을 씁니다.

  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는가 componentFailure.componentArn 보고하는 값과 동일하므로 로그 블록을 이미지의 실패 컨텍스트와 일치시키는 데 사용합니다. Document는 구성 요소 문서가 선언name하는 로, 작성자는 구성 요소 리소스와 독립적으로 선택하므로 둘이 다를 수 있고 Document 단독으로는 어떤 구성 요소가 실패했는지 식별하지 못합니다.

AWSTOE 는 실패한 단계에서 생성된 Stderr 경우에만 ErrorMessage 및를 작성합니다.

Image Builder는 빌드가 완료되면 구성 요소 로그를 Amazon CloudWatch Logs로 스트리밍합니다. 인프라 구성에서 Amazon S3 버킷을 지정한 경우 Image Builder는 해당 버킷도 여기에 씁니다. 로그 그룹 및 스트림 이름은 섹션을 참조하세요Amazon CloudWatch Logs를 사용하여 Image Builder 로그 모니터링. 가 AWSTOE 생성하는 파일과 각 파일에 포함된 내용은 단원을 참조하십시오구성 요소 로깅.

AI 에이전트와 함께 장애 컨텍스트 사용

장애 컨텍스트는 자동화뿐만 아니라 사람이 읽을 수 있도록 설계되었습니다. 실패한 빌드 문제를 해결하는 AI 에이전트는 명명된 필드를 읽고 해당 값을 다음 API 호출에 대한 인수로 사용합니다. 이렇게 하면 진단을 반복할 수 있으며 에이전트가 어떤 구성 요소를 조사할지 추측하지 못하게 됩니다.

다음 방법 중 하나로 실패 컨텍스트를 사용할 수 있습니다.

  • Image Builder의 문제 해결 AWS Management Console - AWS DevOps Agent에서 제공하는 문제 해결 기능은 실패 컨텍스트를 사용하여 로그 및 관련 리소스를 검사하기 전에 실패한 워크플로 단계 및 구성 요소에 대한 조사 범위를 지정합니다. 자세한 내용은 AI를 사용하여 실패한 빌드 문제 해결 - 미리 보기 섹션을 참조하세요.

  • 자체 AI 코딩 에이전트 -를 호출하는 에이전트는 응답에서 실패 컨텍스트를 GetImage 수신하고 동일한 방식으로 이를 따를 수 있습니다. 에이전트가 찾은 내용에 따라 조치를 취하는 데 필요한 광범위한 Image Builder 지식을 제공하려면 섹션을 참조하세요AI 코딩 에이전트를 사용한 빌드 문제 해결.

실패 컨텍스트에서 자체 자동화를 빌드하는 경우 모든 멤버를 선택 사항으로 취급하고 failureContext 자체 멤버가 있는지 확인하는 대신 사용하는 멤버를 확인합니다. Image Builder가 반환하는 멤버는 실패에 따라 달라지며 Image Builder는 시간이 지남에 따라 멤버를 추가할 수 있습니다.

고려 사항

실패 컨텍스트를 사용할 때 다음 사항에 유의하세요.

  • Image Builder는 실패한 이미지에 대해서만 실패 컨텍스트를 반환합니다. 성공한 이미지와 취소한 이미지에는 해당 이미지가 없습니다.

  • 실패한 이미지에는 reason 및가 모두 포함됩니다failureContext. reason 읽기 가능한 실패 요약과 failureContext를 사용하여 실패를 찾습니다.

  • 구성 요소가 ExecuteDocument 작업을 사용하여 중첩 문서를 실행하는 경우 실패 컨텍스트는 Image Builder가 중첩 문서가 아닌 레시피에서 실행한 구성 요소를 식별합니다.

  • 실패 컨텍스트의 오류 메시지는 길이가 제한되어 있으며 잘릴 수 있습니다. 구성 요소 로그에는 전체 출력이 포함됩니다.

  • 실패 컨텍스트는 실패한 첫 번째 단계를 보고합니다. 둘 이상의 단계가 실패한 경우 워크플로 단계 실행과 나머지 단계에 대한 구성 요소 로그를 검토합니다.

  • 오류 메시지에는 구성 요소 또는 다른 AWS 서비스가 생성한 텍스트가 포함될 수 있습니다. 렌더링하거나 다른 시스템에 전달하는 경우 신뢰할 수 없는 입력으로 취급합니다.