빌드 오류 문제 해결

이 페이지에서는 빌드 실행 시 발생할 수 있는 몇 가지 일반적인 오류 메시지에 대한 해결 방법과 문제 해결 전략을 제공합니다.

빌드 로그를 살펴보셨나요?

빌드 오류에 대한 자세한 내용은 Logging 또는 Cloud Storage 빌드 로그를 참조하세요. stdout 또는 stderr에 작성된 로그는 Google Cloud 콘솔에 자동으로 표시됩니다.

사용자가 빌드 로그에 액세스할 수 없어 수동 빌드 실패

수동으로 빌드를 실행하려고 하면 다음 오류가 표시됩니다.

AccessDeniedAccess denied. [EMAIL_ADDRESS] does not have storage.objects.get access to the Google Cloud Storage object.

Cloud Build에서는 수동 빌드를 실행하고 기본 Cloud Storage 로그 버킷을 사용하는 사용자에게 Cloud Build 편집자 역할 외에도 프로젝트 뷰어 IAM 역할이 필요하므로 이 오류가 표시됩니다. 이 오류를 해결하려면 다음 중 하나를 수행하세요.

기본 로그 버킷을 사용한 후 빌드를 실행하는 사용자에게 프로젝트 뷰어 역할과 Cloud Build 편집자 역할을 부여합니다. 이 권한을 부여하는 방법은 Cloud Build 리소스에 대한 액세스 구성을 참조하세요.
자체 Cloud Storage 버킷을 만들어 로그를 저장합니다. 자세한 내용은 사용자가 만든 버킷에 빌드 로그 저장을 참조하세요.

서비스 계정 권한이 누락되어 빌드 실패

Cloud Build는 사용자 대신 특별 서비스 계정을 사용하여 빌드를 실행합니다. 작업을 수행하는 데 필요한 권한이 Cloud Build 서비스 계정에 없는 경우 다음 오류가 표시됩니다.

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

이 오류를 해결하려면 서비스 계정에 필수 권한을 부여합니다. 다음 페이지의 정보를 사용하여 Cloud Build 서비스 계정에 부여할 권한을 결정합니다.

서비스 계정 권한 누락으로 인한 빌드 실패는 일반적으로 Cloud Build를 사용하여 배포를 시도할 때 발생합니다.

Cloud Run 함수에 배포할 때 권한 거부 오류 발생

Cloud Run 함수를 사용하려고 시도할 때 다음 오류가 표시됩니다.

ResponseError: status=[403], code=[Ok], message=[Permission 'cloudfunctions.functions.get' denied

이 오류를 해결하려면 Cloud Build 서비스 계정에 Cloud Run 함수 개발자 역할을 부여합니다.

Cloud Run 함수에 배포할 때 권한 누락 오류 발생

Cloud Run 함수에 배포하려고 하면 다음 오류가 표시됩니다.

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

이 오류를 해결하려면 Cloud Build 서비스 계정에 서비스 계정 사용자 역할을 부여합니다.

App Engine에 배포 시 오류 발생

App Engine에 배포하려고 하면 다음 오류가 표시됩니다.

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

이 오류를 해결하려면 Cloud Build 서비스 계정에 App Engine 관리자 역할을 부여합니다.

GKE에 배포 시 오류 발생

GKE에 배포하려고 하면 다음 오류가 표시됩니다.

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

이 오류를 해결하려면 GKE 개발자 역할을 Cloud Build 서비스 계정에 부여합니다.

Cloud Run에 배포 시 오류 발생

Cloud Run에 배포하려고 하면 다음 오류가 표시됩니다.

Missing necessary permission iam.serviceAccounts.actAs for [USER] on the service account [CLOUD_BUILD_SERVICE_ACCOUNT]@PROJECT.iam.gserviceaccount.com

Cloud Build 서비스 계정에 Cloud Run에 배포하는 데 필요한 IAM 권한이 없으므로 이 오류가 표시됩니다. 필요한 권한 부여에 대한 자세한 내용은 Cloud Run에 배포를 참조하세요.

누락된 `cloudbuild.builds.create` 권한으로 인한 빌드 트리거 실패

빌드 트리거를 실행할 때 다음 오류가 표시됩니다.

Failed to trigger build: Permission 'cloudbuild.builds.create' denied on resource 'projects/xxxxxxxx' (or it may not exist)

빌드 트리거는 Cloud Build 서비스 계정을 사용하여 빌드를 만듭니다. 위 오류는 Cloud Build 서비스 계정에 서비스 트리거를 통해 빌드 트리거를 실행하는 데 필요한 cloudbuild.builds.create IAM 권한이 없음을 나타냅니다. 이 오류를 해결하려면 Cloud Build Service Account IAM 역할을 [PROJECT_NUMBER]@cloudbuild.gserviceaccount.com에 부여하면 됩니다. 이 역할을 부여하는 방법은 Cloud Build 서비스 계정에 대한 액세스 구성을 참조하세요.

서비스 에이전트 권한 누락으로 인한 빌드 제출 실패

Cloud Build 서비스 에이전트가 삭제되거나 권한이 없는 경우 빌드를 제출할 때 다음 오류가 발생할 수 있습니다.

Caller does not have required permission to use project $PROJECT_ID. Grant the caller the roles/serviceusage.serviceUsageConsumer role, or a custom role with the serviceusage.services.use permission, by visiting https://console.developers.google.com/iam-admin/iam/project?project=$PROJECT_ID and then retry. Propagation of the new permission may take a few minutes.

이 시나리오에서 호출자는 Cloud Build 서비스 에이전트입니다. 이 권한 문제를 해결하려면 다음 단계를 따르세요.

Cloud Build 서비스 에이전트가 있는지 확인합니다. Google Cloud 콘솔의 IAM 페이지로 이동하여 Google 관리형 서비스 계정 표시 체크박스를 선택하면 프로젝트의 서비스 에이전트를 볼 수 있습니다. 만약 없는 경우 다음 gcloud CLI 명령어를 실행하여 만들 수 있습니다.
```
gcloud beta services identity create --service=cloudbuild.googleapis.com \
    --project=PROJECT_ID
```

그런 다음 Cloud Build 서비스 에이전트에 roles/cloudbuild.serviceAgent IAM 역할을 부여합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com" \
    --role="roles/cloudbuild.serviceAgent"

서비스 에이전트 권한 문제를 일으킨 잠재적 원인이 되는 IAM ID를 확인하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 로그 탐색기를 엽니다.

로그 탐색기로 이동

쿼리 필드에 다음 텍스트를 입력합니다.

resource.type="project"
log_name="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
"service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"

이 쿼리를 사용한 후 로그 항목이 표시되면 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com)에서 권한을 삭제하는지 확인합니다. 그렇다면 해당 로그의 protoPayload.authenticationInfo.principalEmail을 참조하여 오류 메시지에 나열된 해당 권한이 포함된 권한 또는 roles/cloudbuild.serviceAgent 역할을 제거하는 IAM ID를 확인합니다.

`Couldn't read commit` 오류가 표시되면서 트리거 실패

빌드 트리거를 실행할 때 다음 오류가 표시됩니다.

  Failed to trigger build: Couldn't read commit

존재하지 않는 브랜치를 사용하여 빌드를 트리거하려고 하면 Cloud Build가 이 메시지를 반환합니다. 디렉터리 이름의 철자와 일관성을 확인합니다. 트리거 설정에 대한 자세한 내용은 빌드 트리거 만들기 및 관리를 참조하세요.

Pub/Sub 트리거를 만들 수 없음

Pub/Sub 트리거를 만들 때 다음 오류가 표시됩니다.

  Failed to create trigger: Request is prohibited by organization's policy

이 오류는 프로젝트에서 Pub/Sub API가 제한되었음을 나타냅니다. Pub/Sub API를 제한하는 프로젝트는 푸시 구독을 만드는 기능을 제한합니다. 경계의 제한된 서비스에서 Pub/Sub를 일시적으로 삭제하고 트리거를 만들고 Pub/Sub API를 다시 제한하여 오류를 해결할 수 있습니다.

Container Registry에 이미지를 저장하는 중에 오류 발생

빌드에서 빌드된 이미지를 Container Registry에 저장하려고 하면 다음 오류가 표시됩니다.

[EMAIL_ADDRESS] does not have storage.buckets.create access to project [PROJECT_NAME]

Cloud Build 서비스 계정에 Container Registry에 컨테이너 이미지를 저장하는 데 필요한 스토리지 관리자 역할이 없으므로 이 오류가 표시됩니다.

잘못된 SSH 승인으로 인한 빌드 실패

빌드를 실행할 때 다음 오류가 표시됩니다.

Could not parse ssh: [default]: invalid empty ssh-agent socket, make sure SSH_AUTH_SOCK is set

이 오류는 SSH 승인과 관련된 문제를 나타냅니다. 일반적인 예시로는 Cloud Build로 비공개 GitHub 저장소에 액세스할 때 발생하는 SSH 승인 오류입니다. GitHub용 SSH를 설정하는 방법은 비공개 GitHub 저장소 액세스를 참조하세요.

`No route to host` 오류로 인한 빌드 실패

비공개 풀에서 빌드를 실행할 때 다음과 비슷한 오류가 표시됩니다.

Unable to connect to the server: dial tcp 192.168.10.XX:<port>: connect: no route to host

Cloud Build는 Docker 컨테이너를 사용하여 Google 관리 프로젝트의 가상 머신에서 Cloud 빌더를 실행합니다. Docker 브리지 인터페이스 (및 이 인터페이스에 연결된 컨테이너)에 192.168.10.0/24의 IP 범위가 할당되면 동일한 서브넷의 외부 호스트와 통신할 수 없습니다. 비공개 풀 구성 중에 프로젝트의 리소스에 IP 범위를 할당할 때는 192.168.10.0/24 외부의 범위를 선택하는 것이 좋습니다. 자세한 내용은 비공개 풀 환경 설정을 참조하세요.

사용 설정된 외부 IP가 없어 외부 리소스에 연결 실패

비공개 풀에서 외부 리소스에 연결할 때 다음 오류가 표시됩니다.

 Failed to connect to <external_domain>: Connection timed out

비공개 풀은 외부 IP를 사용하여 외부 저장소와 같은 공개 인터넷의 리소스에 액세스합니다. 비공개 풀을 만들거나 업데이트할 때 비공개 풀에 외부 IP를 할당할 상자를 선택합니다. 비공개 풀 내에서 필드를 만들거나 업데이트하는 방법은 비공개 풀 만들기 및 관리를 참조하세요.

I/O 제한 시간 오류

빌드를 실행할 때 다음 오류가 표시됩니다.

Timeout - last error: dial tcp IP_ADDRESS: i/o timeout

이 오류는 빌드가 비공개 네트워크의 리소스에 액세스하려고 시도하지만 실패하면 발생할 수 있습니다. 기본적으로 Cloud Build를 통해 실행되는 빌드는 저장소 또는 레지스트리의 리소스와 같은 공개 인터넷의 비공개 리소스에 액세스할 수 있습니다. 그러나 비공개 풀을 사용하고 비공개 네트워크에 액세스하도록 빌드를 구성하는 경우에만 빌드가 비공개 네트워크의 리소스에 액세스할 수 있습니다. 비공개 네트워크에서 Cloud Build 사용을 참조하세요.

4xx 클라이언트 오류

이 오류 그룹은 요청을 보낸 사용자의 오류로 인해 빌드 요청이 성공하지 않은 것으로 보임을 나타냅니다. 4xx 클라이언트 오류의 예시는 다음과 같습니다.

**Error**: 404 : Requested entity was not found
**Error**: 404 : Trigger not found
**Error**: 400 : Failed Precondition
**Error**: 403 : Permission denied

4xx 클라이언트 오류가 표시되면 빌드 로그에 오류의 원인에 대한 자세한 정보가 포함되어 있는지 확인합니다. 클라이언트 오류의 일반적인 원인은 다음과 같습니다.

지정한 소스 위치에 커밋할 새 항목이 없고 작업 트리가 깨끗합니다. 이 경우 소스 코드 위치를 확인하고 다시 빌드합니다.
저장소에 빌드 구성 파일이 없습니다. 이 경우 저장소에 빌드 구성 파일을 업로드하고 빌드를 다시 실행합니다.
잘못된 트리거 ID를 지정했습니다.
최근 GitHub 앱을 설치한 후 새 저장소를 추가했으며 Cloud Build에 새 저장소에 액세스할 권한이 없습니다. 이 경우 새 저장소를 Cloud Build에 연결합니다.
서비스 계정에 다른 권한을 부여해야 합니다.

할당량 제한으로 인한 빌드 실패

특정 리전의 할당량 제한으로 인해 빌드가 실패하고 있음을 나타내는 다음 오류가 표시됩니다.

Failed to trigger build: generic::failed_precondition: due to quota restrictions, cannot run builds in this region. Please contact support.

특정 리전의 할당량을 늘리려면 Cloud Customer Care에 문의하세요. 할당량 및 한도에 대한 자세한 내용은 할당량 및 한도를 참고하세요.

Docker 레지스트리에서 이미지를 가져올 때 제한 시간 문제

실행 후 Cloud Build 로그에 다음과 같은 제한 시간 오류가 표시됩니다.

Step #0: Pulling image: python:3.8.16-alpine3.17
Step #0: Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

Step 1/7 : FROM python:3.8.16-alpine3.17
Get "https://registry-1.docker.io/v2/": dial tcp 34.205.13.154:443: i/o timeout

오류를 해결하려면 crane을 사용하여 Docker 이미지를 다운로드하고 계속해서 이미지를 Cloud Build Docker 이미지에 로드합니다.

cloudbuild.yaml 파일에 다음 스니펫을 추가합니다.

...
  # Crane runs as a regular user so we need to allow it to access the directory where it saves the image.
  - name: gcr.io/cloud-builders/docker
    args:
    - a+w
    - /workspace
    entrypoint: chmod
  # Use crane to download the image through the proxy
  - name: gcr.io/go-containerregistry/crane
    env: - 'HTTPS_PROXY=HTTPS_PROXY'
    args:
    - pull
    - 'python:3.8.16-alpine3.17'
    - /workspace/image.tar
  # Use docker load to add the image into the local Cloud Build registry
  - name: gcr.io/cloud-builders/docker
    args: [load, --input, "/workspace/image.tar"]
      - .

HTTPS_PROXY: HTTP 프록시의 주소(예: https://proxy.example.com:8888/).

이미지가 로드되면 기존 cloudbuid.yaml 단계가 정상적으로 작동합니다. 예:

...
  - name: python:3.8.16-alpine3.17
    args:
    - echo
    - hello
    entrypoint: bash
  # Or use it internally on a Dockerfile
  - name: gcr.io/cloud-builders/docker
    args:
    - build

장기 실행 Docker 단계의 `Unauthenticated` 오류

한 시간 이상 실행되는 Docker 명령어가 포함된 빌드 단계(예: 큰 이미지를 Artifact Registry로 푸시)는 인증 오류와 함께 실패할 수 있습니다. Cloud Build는 매시간 인증 토큰을 새로고침하지만 Docker는 이러한 새 토큰을 가져오지 못하여 인증 문제가 발생할 수 있습니다. 커스텀 수명을 사용하여 자체 토큰을 작성하고 Docker 명령어에 대해 파일을 작성하고 참조할 수 있습니다.

VPC 네트워크와 피어링된 비공개 풀의 큐에 추가된 빌드

서비스 프로듀서 네트워크가 사용자의 VPC 네트워크에 피어링된 비공개 풀에서 빌드를 실행할 때는 이러한 두 네트워크 간의 비공개 연결이 그대로 유지되어야 합니다. 비공개 풀이 사용하는 비공개 연결을 삭제하면 비공개 풀을 손상시킬 수 있습니다. 결국 시간 초과될 때까지 큐에 남아 있는 빌드로 표시될 수 있습니다. 따라서 비공개 연결을 삭제하려면 이 비공개 연결을 사용하여 서비스 프로듀서 네트워크를 자체 VPC 네트워크에 연결한 비공개 풀도 삭제해야 합니다.

2개월 이상 대기 중인 빌드를 승인하거나 거부하려고 시도함

대기 중인 빌드가 2개월이 지난 경우 승인하거나 거부할 수 없습니다. 이렇게 하면 다음과 같은 오류 메시지가 표시될 수 있습니다.

 404, "message": "Requested entity was not
found.", "status": "NOT_FOUND" } }

이 경우 새 빌드를 제출해 보세요.

다음 단계

빌드 로그를 관리하는 방법 알아보기