App Engine 오류 문제 해결

배포

App Engine Admin API를 사용하여 앱을 배포할 때 문제가 발생하는 경우 이 페이지에는 표시될 수 있는 오류 메시지가 표시되며, 각 오류를 해결하는 방법을 제공합니다.

호출자에게 프로젝트에 액세스할 수 있는 권한이 없음

앱을 배포할 때 다음 오류가 발생합니다.

User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist): The caller does not have permission

이 오류는 앱을 배포하는 데 사용한 계정에 현재 프로젝트에 앱을 배포할 권한이 없는 경우에 발생합니다.

이 문제를 해결하려면 계정에 App Engine 배포자(roles/appengine.deployer) 역할을 부여합니다. 배포에 사용한 계정을 확인하려면 다음 중 하나를 수행합니다.

  • Google Cloud CLI를 사용하여 배포한 경우 gcloud auth list 명령어를 실행합니다.
  • IDE에서 배포한 경우 Cloud 도구 플러그인의 설정을 봅니다.

레지스트리에서 메타데이터를 가져올 수 없음

앱을 배포할 때 다음 오류가 발생합니다.

Failed to fetch metadata from the registry, with reason: generic::permission_denied

이 오류는 스토리지 관리자(roles/storage.admin) 역할이 없는 서비스 계정으로 gcloud app deploy 명령어를 사용하는 경우에 발생합니다.

이 문제를 해결하려면 서비스 계정에 스토리지 관리자 역할을 부여합니다.

  • 사용한 계정을 확인하려면 gcloud auth list 명령어를 실행합니다.
  • 경우에 따라 App Engine 배포자(roles/appengine.deployer) 역할만 할당하는 것이 왜 충분하지 않은지 알아보려면 App Engine 역할을 참조하세요.

서비스 계정에는 이미지에 대한 권한이 있어야 함

앱을 배포할 때 다음 오류가 발생합니다.

The App Engine appspot and App Engine flexible environment service accounts must have permissions on the image IMAGE_NAME

이 오류는 다음 이유 중 하나로 발생합니다.

Cloud Build를 만들 수 없음

앱을 배포할 때 다음 오류가 발생합니다.

Failed to create cloud build: Permission denied

이 오류는 Cloud Build 편집자(roles/cloudbuild.builds.editor) 역할이 없는 계정으로 gcloud app deploy 명령어를 사용하는 경우에 발생합니다.

이 문제를 해결하려면 앱을 배포하는 데 사용하는 서비스 계정에 Cloud Build 편집자 역할을 부여합니다.

사용한 계정을 확인하려면 gcloud auth list 명령어를 실행합니다.

애플리케이션을 가져오는 중에 발생한 권한 오류

앱을 배포할 때 다음 오류가 발생합니다.

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

Google Cloud CLI 버전 328 이상을 실행하는 경우 앱을 배포할 때 다음 오류가 발생합니다.

Permissions error fetching application apps/app_name. Please
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 배포자(roles/appengine.deployer) 역할이 없는 경우에 발생합니다.

이 문제를 해결하려면 앱을 배포하는 데 사용한 서비스 계정에 App Engine 배포자 역할을 부여했는지 확인합니다. 서비스 계정에 이 역할이 없다면 이 역할을 부여하세요. 배포에 사용한 계정을 확인하려면 다음 중 하나를 수행합니다.

  • Google Cloud CLI를 사용하여 배포한 경우 gcloud auth list 명령어를 실행합니다.
  • IDE에서 배포한 경우 Cloud 도구 플러그인의 설정을 봅니다.

앱 인프라가 정상이 될 때까지 기다리는 동안 타임아웃됨

앱을 배포할 때 다음 오류가 발생합니다.

Timed out waiting for the app infrastructure to become healthy

권한 누락, 코드 오류, CPU 또는 메모리 부족, 상태 확인 실패 등 다양한 요인으로 인해 이 오류가 발생할 수 있습니다. 이 오류는 App Engine 가변형 환경에서만 발생합니다.

이 문제를 해결하려면 다음과 같은 가능한 원인을 배제하세요.

  1. 기본 App Engine 서비스 계정에 편집자(roles/editor) 역할을 부여했는지 확인합니다.
  2. 프로젝트의 조직 정책이 외부 IP 주소에 대한 액세스를 제한하는지 확인합니다. 자세한 내용은 App Engine 가변형 환경의 알려진 문제를 참조하세요.

  3. 애플리케이션을 실행하는 데 사용하는 서비스 계정(일반적으로 기본 서비스 계정, app-id@appspot.gserviceaccount.com)에 다음 역할을 부여했는지 확인합니다.

  4. 서비스 계정에 역할이 없는 경우 역할을 부여합니다.

  5. 공유 VPC 설정에서 배포하고 app.yaml에서 instance_tag을 전달하는 경우 이 섹션을 참조하여 문제를 해결하세요.

서버리스 VPC 액세스 커넥터로 서비스를 배포할 때 발생한 권한 오류

앱을 배포할 때 다음 오류가 발생합니다.

Please ensure you have [compute.globalOperations.get] on the service project

이 오류는 서버리스 VPC 커넥터로 앱을 배포하려는 사용자 또는 서비스 계정에 필요한 권한이 없을 때 발생합니다.

이 문제를 해결하려면 배포를 수행하는 사용자 또는 서비스 계정에 서버리스 VPC 액세스 사용자 및 Compute 뷰어 IAM 역할이 있는지 확인합니다.

공유 VPC 설정에서 배포할 때 발생한 잘못된 값 오류

다음 오류는 앱을 배포할 때 Flex VM 인스턴스의 Cloud Logging에 표시됩니다.

Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert

이 오류는 인스턴스를 생성 시 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 합계를 제한 이내로 줄입니다.

'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) 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 버킷에 데이터 보존 정책을 설정한 경우 발생합니다.

이 문제를 해결하려면 staging.PROJECT_ID.appspot.com 버킷의 다음 설정을 변경하세요.

조직 정책 제약조건으로 인해 배포 실패

앱을 배포할 때 다음 오류가 발생합니다.

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred while processing task /app-engine-flex/....: Request to https://compute.googleapis.com/compute/[VERSSION]/[PROJECT_ID]/... failed, details: Constraint constraints/compute.disableGuestAttributesAccess violated for project [PROJECT_ID].

이 오류는 앱을 배포할 때 조직 정책 제약조건 constraints/compute.disableGuestAttributesAccess를 적용으로 인해 발생할 수 있습니다. 이 정책은 App Engine 가변형 환경의 모든 앱에 기본적으로 적용됩니다.

이 문제를 해결하려면 조직 정책 제약조건 constraints/compute.disableGuestAttributesAccess를 사용 중지해야 합니다.

기존 가변형 환경 버전에 배포할 때 발생하는 오류

기존 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 이미지로 업데이트하지 않는 것이 좋습니다.

현재 버전 오류가 발생할 경우 롤백할 수 없습니다.

서빙

다음 섹션에서는 앱 초기화와 서빙 오류를 설명합니다.

기본 서비스 계정으로 앱을 만들 때의 권한 오류

App Engine API를 처음 사용 설정한 후 앱을 만들면 다음 오류가 표시되면서 실패합니다.

  • gcloud CLI:

    An internal error occurred while calling service consumer manager for service account.
Creating  App Engine application in project [PROJECT__ID] and [REGION]....failed. DEBUG: (gcloud.app.create) Error Response: [13] an internal error has occurred

  • 요청 로그:

    Service account creation is not allowed on this project.

  • Console:

    Error while initialising App Engine.

이 오류는 앱을 만들 때 조직 정책 제약조건 constraints/iam.disableServiceAccountCreation 적용으로 인해 발생할 수 있습니다. 이 정책은 App Engine 기본 서비스 계정 PROJECT_ID@appspot.gserviceaccount.com의 프로비저닝을 방지합니다. 기본 서비스 계정은 앱을 만들 때 필요하며 건너뛸 수 없습니다. 버전별 서비스 계정을 사용할 때도 마찬가지입니다.

이 문제를 해결하려면 App Engine 기본 서비스 계정을 만들고 배포할 수 있도록 조직 정책 제약조건 constraints/iam.disableServiceAccountCreation을 일시적으로 삭제해야 합니다. 그런 다음 App Engine 기본 서비스 계정을 삭제하거나 배포가 성공한 후에 만드는 서비스 계정으로 바꿀 수 있습니다.

만든 서비스 계정을 사용하는 경우 역할 권장사항 개요를 검토하여 서비스 에이전트에 만드는 서비스 계정에 대한 토큰 생성자 역할 제공과 같이 권한을 제한하는 방법을 알아봅니다.

Nginx가 앱 컨테이너에 연결하지 못함

다음 오류는 App Engine 가변형 환경에서만 발생하며 일반적으로 오류 발생 직후 502 오류와 함께 반환됩니다.

recv() failed (104: Connection reset by peer) while reading response header from upstream

이 오류는 nginx 역방향 프록시(nginx 사이드카)가 앱 컨테이너에 연결할 수 없음을 나타냅니다. 로그에서 nginx 로그에 있는 502 오류의 종료 시간을 nginx.error 로그의 시간과 비교할 수 있습니다. nginx.error 다음에 즉시 502 nginx 오류가 발생한 경우 nginx 502 오류의 원인일 수 있습니다.

이 오류는 애플리케이션의 연결 유지 제한 시간이 nginx의 연결 유지 제한 시간보다 작을 때 자주 발생합니다. App Engine 가변형 환경의 nginx는 keepalive_timeout이 650초이므로 애플리케이션이 최소한 이 시간 동안 연결을 유지해야 합니다. 기본적으로 Node.js 애플리케이션의 keepAliveTimeout은 5,000밀리초입니다. 이 경우 server.keepAliveTimeout을 700,000밀리초로 설정할 수 있습니다.

문제 해결을 위해서는 VM 인스턴스에 연결하여 앱 컨테이너에서 실행되는 코드에 기록된 로그를 확인하고 필요한 경우 로깅을 추가하여 근본 원인을 찾습니다.

메모리 부족

다음 오류는 App Engine 가변형 환경에서 발생하며 일반적으로 502 오류와 함께 반환됩니다.

kernel: [  133.706951] Out of memory: Kill process 4490 (java) score 878 or sacrifice child
kernel: [  133.714468] Killed process 4306 (java) total-vm:5332376kB, anon-rss:2712108kB, file-rss:0kB

이 오류는 App Engine이 애플리케이션을 종료했음을 나타냅니다.

이 오류는 인스턴스의 메모리가 부족할 때 발생합니다. 기본적으로 App Engine 가변형 환경의 메모리는 1GB이며 애플리케이션 컨테이너에 600MB만 사용할 수 있습니다.

문제를 해결하려면 로그를 확인하고 메모리 부족 항목이 있는지 확인합니다. memory_gb 구성을 업데이트하고 다시 배포합니다.

수신 요청을 처리할 수 있는 개방형 연결 부족

최대 대기 연결 수가 활성 연결 수의 75% 이상이면 앱에 502 오류가 발생할 수 있습니다.

문제를 해결하려면 Cloud Monitoring 측정항목에서 최대 활성 연결 수와 대기 연결 수를 확인하여 최대 대기 연결 수가 활성 연결 수의 75% 이하가 되도록 대기 연결 수를 줄입니다.