권한 누락, 조직 정책 변경, 앱 구성 문제를 포함한 여러 가지 요인으로 인해 App Engine에서 배포 오류가 발생할 수 있습니다.
이 페이지에서는 다음과 같은 App Engine에서의 일반적인 배포 오류와 이를 해결하는 방법을 설명합니다.
권한 오류
이 섹션에서는 계정 권한 누락 또는 조직 정책 변경으로 인해 앱을 배포할 때 발생할 수 있는 오류를 설명합니다.
Google Cloud 플랫폼에서 Google Cloud CLI 및 기타 도구에 액세스하는 데 사용하는 활성 계정을 식별하려면 다음 중 하나를 수행합니다.
Google Cloud CLI를 사용하여 배포한 경우
gcloud auth list명령어를 실행합니다.IDE에서 배포한 경우 Cloud 도구 플러그인의 설정을 봅니다.
경우에 따라 App Engine 배포자(roles/appengine.deployer) 역할만 할당하는 것이 왜 충분하지 않은지 알아보려면 App Engine 역할을 참조하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
새 프로젝트의 배포 실패
새 프로젝트에서 앱을 처음 배포할 때 다음 오류가 표시될 수 있습니다.
ERROR: (gcloud.app.deploy) Error Response: [13] Failed to create cloud build: com.google.net.rpc3.client.RpcClientException:..........invalid bucket "staging.PROJECT_ID.appspot.com"; service account PROJECT_ID@appspot.gserviceaccount.com does not have access to the bucket
이 문제를 해결하려면 기본 서비스 계정에 스토리지 관리자(roles/storage.admin) 역할을 부여합니다. 자세한 내용은 사용자가 만든 버킷에 빌드 로그 저장을 참조하세요.
배포 중 발생하는 여러 권한 오류에 따라 다른 필수 역할과 함께 스토리지 관리자 역할을 이미 부여했지만 여전히 앱을 배포할 수 없는 경우 이는 다음과 같은 조직 정책 변경사항 때문일 수 있습니다.
2024년 5월부터 Google Cloud 에서 보안 강화를 기본으로 설정한 조직 정책을 모든 조직 리소스에 적용합니다. 이 정책으로 App Engine이 App Engine 기본 서비스 계정에
Editor역할을 부여하지 못합니다.2024년 6월에 Cloud Build가 새 프로젝트에서 서비스 계정을 사용하는 방법에 대한 기본 동작이 변경되었습니다. Cloud Build 서비스 계정 변경에 자세히 설명되어 있습니다. 이러한 변경사항으로 인해 처음으로 버전을 배포하는 새 프로젝트에서 버전을 배포하는 권한이 부족한 기본 App Engine 서비스 계정을 사용할 수 있습니다.
이 문제를 해결하려면 다음 단계를 따르세요.
App Engine 기본 서비스 계정(
PROJECT_ID@appspot.gserviceaccount.com)에Editor역할을 부여합니다.기본 서비스 계정 변경에 대한 Cloud Build의 안내를 검토하고 새 프로젝트의 기본 변경사항을 선택 해제합니다.
호출자에게 프로젝트에 액세스할 수 있는 권한 없음
서비스 계정에 현재 프로젝트에 앱을 배포할 권한이 없으면 다음과 같은 오류가 발생합니다.
User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist).
이 문제를 해결하려면 서비스 계정에 App Engine 배포자(roles/appengine.deployer) 역할을 부여합니다.
레지스트리에서 메타데이터를 가져올 수 없음
스토리지 관리자(roles/storage.admin) 역할이 없는 서비스 계정에서 gcloud app deploy 명령어를 사용하면 다음과 같은 오류가 발생합니다.
Failed to fetch metadata from the registry, with reason: generic::permission_denied
이 문제를 해결하려면 서비스 계정에 스토리지 관리자 역할을 부여합니다.
서비스 계정에는 이미지에 대한 권한이 있어야 함
앱을 배포할 때 다음 오류가 발생합니다.
The App Engine appspot and App Engine flexible environment service accounts must
have permissions on the image IMAGE_NAME
이 오류는 다음 이유 중 하나로 인해 발생합니다.
기본 App Engine 서비스 계정에 스토리지 객체 뷰어(
roles/storage.objectViewer) 역할이 없습니다.이 문제를 해결하려면 서비스 계정에 스토리지 객체 뷰어 역할을 부여합니다.
프로젝트에 액세스 수준을 사용하여 Cloud Storage API에 대한 액세스를 제한하는 VPC 서비스 제어 서비스 경계가 있습니다.
이 문제를 해결하려면 앱을 배포하는 데 사용하는 서비스 계정을 해당 VPC 서비스 제어 서비스 경계 accessPolicies에 추가합니다.
2024년 5월 15일부터 이전에 Container Registry를 사용하지 않은 Google Cloud 프로젝트의
gcr.io도메인 이미지를 Artifact Registry에서 호스팅합니다. 기존 애플리케이션을 이 날짜 이후에 생성된 새 프로젝트에 배포하는 경우 서비스 계정에 앱을 배포하는 데 필요한 권한이 없을 수 있습니다. 필요한 권한을 부여하려면 App Engine에 배포를 참조하세요.
Cloud Build를 만들 수 없음
Cloud Build 편집자(roles/cloudbuild.builds.editor) 역할이 없는 서비스 계정에서 gcloud app deploy 명령어를 사용하면 다음과 같은 오류가 발생합니다.
Failed to create cloud build: Permission denied
이 문제를 해결하려면 서비스 계정에 Cloud Build 편집자 역할을 부여합니다.
애플리케이션 가져오기 오류
앱을 배포하는 데 사용한 서비스 계정에 App Engine 배포자 역할이 없으면 다음과 같은 오류가 발생합니다.
Permissions error fetching application apps/app_name. Please make sure you are using the correct project ID and that you have permission to view applications on the project.
If you are running Google Cloud CLI version 328 or later, the following error occurs
when you deploy your app:
make sure that you have permission to view applications on the project and that
SERVICE_ACCOUNT has the App Engine Deployer (roles/appengine.deployer) role.
이 문제를 해결하려면 앱을 배포하는 데 사용한 서비스 계정에 App Engine 배포자 역할을 부여합니다.
서버리스 VPC 액세스 커넥터로 서비스를 배포할 때 발생하는 오류
서버리스 VPC 액세스 커넥터로 앱을 배포하려는 사용자나 서비스 계정에 필요한 권한이 없으면 다음과 같은 오류가 발생합니다.
Please ensure you have [compute.globalOperations.get] on the service project
이 문제를 해결하려면 배포에 사용된 사용자나 서비스 계정에 서버리스 VPC 액세스 사용자 및 Compute 뷰어 IAM 역할이 있는지 확인합니다.
앱 인프라가 정상이 될 때까지 기다리는 동안 타임아웃됨
앱을 배포할 때 다음 오류가 발생합니다.
Timed out waiting for the app infrastructure to become flex_await_healthy
권한 누락, 코드 오류, CPU 또는 메모리 부족, 상태 확인 실패 등 다양한 요인으로 인해 이 오류가 발생할 수 있습니다.
이 문제를 해결하려면 다음과 같은 가능한 원인을 배제하세요.
프로젝트의 조직 정책이 외부 IP 주소에 대한 액세스를 제한하는지 확인합니다. 자세한 내용은 App Engine 가변형 환경의 알려진 문제를 참조하세요.
애플리케이션을 실행하는 데 사용하는 서비스 계정(일반적으로 기본 서비스 계정,
app-id@appspot.gserviceaccount.com)에 다음 역할을 부여했는지 확인합니다.서비스 계정에 역할이 없는 경우 배포 오류에 따라 나머지 역할을 부여합니다.
공유 VPC 설정에서 배포하고
app.yaml파일에서instance_tag를 구성하는 경우 공유 VPC 설정에서 배포할 때 발생한 잘못된 값 오류를 참조하여 문제를 해결합니다.
실행 중인 버전에서 인스턴스를 다시 시작할 때 발생하는 오류
앱을 배포할 때 다음 오류가 발생합니다.
error when restarting the instance under the running versions
2024년 5월부터 Google Cloud 에서 보안 강화를 기본으로 설정한 조직 정책을 모든 신규 조직에 적용합니다. 이 정책을 적용하려면 새 프로젝트에 만든 모든 VM 인스턴스에서 VM Manager를 사용 설정해야 합니다. 신규 및 기존 프로젝트에서 이 제약조건을 설정하면 프로젝트 또는 인스턴스 수준에서 VM Manager를 사용 중지하는 메타데이터 업데이트가 방지됩니다.
이 문제를 해결하려면 조직 정책 제약조건인 OS 구성 필요(constraints/compute.requireOsConfig)를 사용 중지해야 합니다.
이 문제가 지속되면 프로젝트 또는 조직 수준에서 사용 설정되었을 수 있는 다음 조직 정책도 사용 중지해야 합니다.
VM 인스턴스(
constraints/compute.vmExternalIpAccess)에 허용되는 외부 IP를 정의합니다. 애플리케이션이 비공개 네트워킹만 사용하도록 설정된 경우 이 제약조건을 사용 중지할 필요가 없습니다.Compute Engine 메타데이터의 게스트 속성 사용 중지(
constraints/compute.disableGuestAttributesAccess)
필요한 compute.firewalls.list 권한
공유 VPC 네트워크에 앱을 배포하면 다음과 같은 오류가 발생합니다.
Request to https://compute.googleapis.com/compute/v1/projects/projects/PROJECT_ID/global/firewalls?key failed, details: Required 'compute.firewalls.list' permission for 'projects/PROJECT_ID'
이 오류는 호스트 프로젝트의 다음 서비스 계정에 Compute 네트워크 사용자(roles/compute.networkUser) 역할이 없을 때 발생합니다.
이 문제를 해결하려면 호스트 프로젝트의 Google API 서비스 에이전트 및 App Engine 가변형 환경 서비스 에이전트 서비스 계정에 Compute 네트워크 사용자 역할을 부여합니다.
조직 정책 제약조건으로 인한 배포 실패
앱을 배포할 때 다음 오류가 발생합니다.
ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred while processing task /app-engine-flex/....: Request to https://compute.googleapis.com/compute/VERSION/projects/PROJECT_ID/... failed, details: Constraint constraints/compute.disableGuestAttributesAccess violated for project PROJECT_ID.
앱을 배포할 때 constraints/compute.disableGuestAttributesAccess 제약조건을 적용했기 때문일 수 있습니다. App Engine 가변형 환경의 모든 앱은 기본적으로 이 조직 정책을 적용합니다.
이 문제를 해결하려면 constraints/compute.disableGuestAttributesAccess 제약조건을 사용 중지해야 합니다.
일반적인 배포 오류
이 섹션에서는 앱이나 프로젝트의 구성 오류에 대한 문제 해결 전략을 설명합니다.
공유 VPC 설정에서 배포할 때 발생한 잘못된 값 오류
다음 오류는 앱을 배포할 때 가변형 VM 인스턴스의 Cloud Logging에 표시됩니다.
Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert
이는 app.yaml 파일에서 instance_tag를 설정하면 인스턴스를 만들 때 오류가 발생한다고 알려진 문제입니다.
문제를 해결하려면 app.yaml 파일에서 instance_tag 필드를 삭제하고 다시 배포합니다.
최대 인스턴스가 3개 이하인 앱을 배포할 때 발생하는 오류
max_instances가 3개 이하로 설정된 앱을 배포하면 예상치 못한 오류나 다운타임이 발생할 수 있습니다. 이 문제를 해결하려면 app.yaml 파일에 최대 인스턴스를 최소 4개 이상 지정하여 다시 배포합니다.
최대 인스턴스 한도 초과
앱을 배포할 때 다음 오류가 발생합니다.
You may not have more than 'xx' total max instances in your project.
프로젝트당 만들 수 있는 최대 인스턴스 수에는 한도가 있습니다. 이 제한을 초과하면 추가 인스턴스 만들기 요청이 실패합니다.
이 문제를 해결하려면 app.yaml 파일에서 max_instances 값을 이 한도보다 낮은 값으로 설정하거나 일부 서비스나 버전을 삭제하여 max_instances 합계를 한도 이내로 줄입니다.
로그 오류 없이 배포 중에 빌드 실패
앱을 배포할 때 다음 오류가 발생합니다.
ERROR: (gcloud.app.deploy) Cloud build failed. Check logs at https://console.cloud.google.com/cloud-build/builds/BUILD_ID?project=PROJECT_NUMBER Failure status: UNKNOWN: Error Response: [2] Build failed; check build logs for details
오류 메시지의 링크를 클릭하여 모든 빌드 단계가 성공했음을 확인했지만 여전히 앱에서 빌드할 수 없는 경우 다음 이유 중 한 가지가 원인일 수 있습니다.
- 고객 관리 암호화 키(CMEK)를 사용합니다.
staging.PROJECT_ID.appspot.com버킷에 데이터 보관 정책을 설정합니다.
이 문제를 해결하려면 버킷의 다음 설정을 변경합니다.
- 암호화를 Google-owned and Google-managed encryption keys로 설정합니다.
- 보관 정책을 삭제합니다.
기존 App Engine 버전에 배포할 때 발생하는 오류
App Engine 가변형 환경의 기존 버전에 배포할 때 다음과 같은 오류가 발생할 수 있습니다.
ERROR: (gcloud.app.deploy) Error Response: [9] An internal error occurred while
processing task /app-engine-flex/flex_await_healthy/flex_await_healthy
이 오류는 작동 중인 Docker 이미지로 비정상 배포를 업데이트한다고 해서 항상 정상 배포가 아님을 나타냅니다. 결과는 비정상 배포의 인스턴스 상태에 따라 다릅니다. 오류에도 불구하고 정상 Docker 이미지를 제공하면 배포가 결국 정상 상태가 될 수 있습니다. 허용되지만 기존 버전을 새 Docker 이미지로 업데이트하지 않는 것이 좋습니다. 버전 오류가 발생할 경우 롤백할 수 없습니다.