Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

파이프라인 실패 문제 해결

Linux

맞춤설정 단계에서 Image Builder 파이프라인이 실패하면 로그 파일을 검토하고, 작업자 VM에서 대화형 디버그 플래그를 구성하거나, 중간 디버그 이미지를 분석하여 컴파일 시간 또는 스크립트 오류를 식별합니다.

시작하기 전에

아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인합니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음 옵션 중 하나를 선택하여 Compute Engine에 인증하면 됩니다.
1. Google Cloud CLI를 설치합니다. 설치 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다.
```
gcloud init
```
  외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
  
  참고: 이전에 gcloud CLI를 설치했으면 gcloud components update를 실행하여 최신 버전이 설치되어 있는지 확인하세요.
2. 기본 리전 및 영역을 설정합니다.

로깅 채널 검토

Image Builder는 스택의 여러 수준에서 오류를 진단할 수 있도록 여러 위치에 로그를 작성합니다.

Cloud Build 오케스트레이터 로그: Cloud Build 콘솔에 대략적인 빌더 단계를 표시합니다. 단계가 실패하면 해당 Cloud Storage workdir 디렉터리 링크가 출력됩니다.
맞춤설정 VM 에이전트 로그: 맞춤설정 에이전트는 맞춤설정 단계의 표준 출력 (stdout)과 표준 오류 (stderr)를 캡처합니다. 오케스트레이터는 이러한 레코드를 폴링하고 Cloud Build 추적 로그로 직접 스트리밍합니다. 로그가 잘리거나 전체를 검사해야 하는 경우 _GCS_WORKDIR 버킷에서 빌드 ID와 일치하는 폴더로 이동합니다.
직렬 콘솔 로그: 게스트 OS가 부팅되지 않으면 맞춤설정 에이전트가 시작될 수 없습니다. 이 경우 직렬 콘솔 로그를 확인하세요. 오케스트레이터는 작업자 VM의 직렬 포트 출력을 Cloud Storage workdir 버킷으로 직접 스트리밍합니다. 실패한 Cloud Build 트레이스 끝에 직렬 로그 파일 링크가 출력됩니다.
게스트 OS 저널 로그: Linux에서 자세한 시스템 수준 문제 해결을 위해 맞춤설정 에이전트는 실행이 끝날 때 전체 시스템 journal 로그 사본을 Cloud Storage workdir 버킷에 업로드합니다.

디버그 플래그를 사용하여 스크립트 실패 해결

기본적으로 맞춤설정 단계가 실패하면 Image Builder는 비용을 관리하기 위해 실행을 종료하고 작업자 VM을 즉시 삭제합니다.

스크립트를 대화형으로 디버그하려면 debug 플래그를 사용 설정하면 됩니다. 이렇게 하면 VM이 활성 상태로 유지되어 SSH를 사용하여 활성 게스트 시스템에 직접 연결할 수 있습니다.

디버그 플래그 사용 설정

imagebuilder.yaml 파일에서 infrastructureConfig 블록 아래에 debug: true를 설정합니다.

infrastructureConfig:
  machineType: e2-standard-4
  zone: us-central1-a
  # Enable interactive debugging
  debug: true
  instanceDurationHours: 1.5

빌드를 트리거하고 실패를 기다립니다.

표준 방법을 사용하여 빌드를 제출합니다. 파이프라인에 스크립트 오류가 발생하면 다음이 발생합니다.

조정자가 빌드 실행을 일시중지합니다.
Image Builder는 작업자 VM을 삭제하지 않습니다. 프로젝트에서 계속 실행됩니다.
VM은 자동 종료되기 전에 instanceDurationHours 속성에 지정된 시간 동안 활성 상태로 유지됩니다.

작업자 VM에 연결하여 디버깅

Cloud Build 콘솔 출력을 확인하여 활성 작업자 VM 인스턴스의 이름을 가져옵니다. 터미널을 열고 gcloud compute ssh를 사용하여 작업자 VM에 연결합니다.

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID

imagebuilder.yaml 파일이 externalIP: none를 구성하여 외부 IP 주소가 없는 경우 Identity-Aware Proxy (IAP) TCP 전달을 사용하여 연결하려면 --tunnel-through-iap 플래그를 포함하세요.

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID \
    --tunnel-through-iap

연결되면 실시간으로 명령어를 실행하고, 타겟 파일을 검사하고, 실행 중인 프로세스를 분석하고, 설치 프로그램 기록 로그를 검토하고, 디스크에서 직접 테스트 스크립트 수정사항을 테스트할 수 있습니다.

중간 디버그 이미지 분석

debug 플래그로 작업자 VM을 활성 상태로 유지하는 대신 자동 생성된 디버그 이미지를 사용하여 디스크 상태를 분석할 수 있습니다.

debug: false (기본값)으로 빌드가 실패할 때마다 오케스트레이터는 부분적으로 맞춤설정된 부팅 디스크를 Compute Engine 이미지로 내보냅니다.
디버그 이미지의 이름은 image-builder-debug-image-BUILD_ID 패턴을 사용하며 image-builder-debug-images 이미지 계열에 할당됩니다.

파일 시스템을 검사하려면 이 디버그 이미지를 부팅 디스크로 사용하여 임시 VM 인스턴스를 만드세요.

gcloud compute instances create temp-debug-vm \
    --image-family=image-builder-debug-images \
    --zone=ZONE \
    --project=PROJECT_ID

temp-debug-vm 인스턴스에 연결하여 디스크를 검사하고 맞춤설정이 실패한 이유를 파악합니다.

Cloud Build 제한 시간 문제 해결

Image Builder 파이프라인 실행이 예상보다 오래 걸리면 Cloud Build 작업이 중지되고 TIMEOUT 상태로 실패합니다.

빌드 시간은 다를 수 있으며 일반적으로 대형 머신 유형의 경우 더 길기 때문에 빌드가 완료되는 데 더 많은 시간이 걸리도록 시간 제한을 설정하세요. 설정하지 않으면 기본 Cloud Build 제한 시간은 1시간 (3600s)입니다.

더 긴 제한 시간을 구성하려면 cloudbuild.yaml 파일의 루트 수준에서 timeout 필드를 설정하세요.

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

# Increase the overall build timeout (for example, 2 hours)
timeout: '7200s'

제한 시간 값을 업데이트한 후 빌드를 다시 실행하고 Image Builder 파이프라인이 완료까지 실행될 수 있는지 확인합니다.

timeout 매개변수에 관한 자세한 내용은 Cloud Build 문서의 timeout를 참고하세요.