검색을 단순화하고 문서 이용 환경을 개선하기 위해 1세대 및 2세대 문서가 개별 집합으로 분할됩니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Cloud Functions 문제 해결

이 문서에서는 발생 가능한 일반적인 문제와 이를 해결하는 방법을 보여줍니다.

배포

배포 단계에서는 문제가 자주 발생합니다. 배포 중 발생할 수 있는 많은 문제들이 역할 및 권한과 관련됩니다. 그 외에는 잘못된 구성과 관련이 있습니다.

뷰어 역할이 있는 사용자는 함수를 배포할 수 없음

프로젝트 뷰어, Cloud Functions 뷰어 역할이 할당된 사용자는 함수 및 함수 세부정보에 대해 읽기 전용 액세스 권한을 갖습니다. 이러한 역할은 새 함수 배포가 허용되지 않습니다.

오류 메시지

Cloud 콘솔

You need permissions for this action. Required permission(s): cloudfunctions.functions.create

Cloud SDK

ERROR: (gcloud.functions.deploy) PERMISSION_DENIED: Permission
'cloudfunctions.functions.sourceCodeSet' denied on resource
'projects/<PROJECT_ID>/locations/<LOCATION>` (or resource may not exist)

해결 방법

적절한 액세스 권한이 있는 역할을 사용자에게 할당합니다.

프로젝트 뷰어 또는 Cloud 함수 역할이 있는 사용자는 함수를 배포할 수 없음

함수를 배포하려면 프로젝트 뷰어, Cloud 함수 개발자, Cloud 함수 관리자 역할이 할당된 사용자에게 추가 역할을 할당해야 합니다.

오류 메시지

Cloud 콘솔

User does not have the iam.serviceAccounts.actAs permission on
<PROJECT_ID>@appspot.gserviceaccount.com required to create function.
You can fix this by running
'gcloud iam service-accounts add-iam-policy-binding <PROJECT_ID>@appspot.gserviceaccount.com --member=user: --role=roles/iam.serviceAccountUser'

Cloud SDK

ERROR: (gcloud.functions.deploy) ResponseError: status=[403], code=[Forbidden],
message=[Missing necessary permission iam.serviceAccounts.actAs for <USER>
on the service account <PROJECT_ID>@appspot.gserviceaccount.com. Ensure that
service account <PROJECT_ID>@appspot.gserviceaccount.com is a member of the
project <PROJECT_ID>, and then grant <USER> the role 'roles/iam.serviceAccountUser'.
You can do that by running
'gcloud iam service-accounts add-iam-policy-binding <PROJECT_ID>@appspot.gserviceaccount.com --member=<USER> --role=roles/iam.serviceAccountUser'
In case the member is a service account please use the prefix 'serviceAccount:' instead of 'user:'.]

해결 방법

Cloud Functions 런타임 서비스 계정의 범위에서 서비스 계정 사용자 IAM 역할(roles/iam.serviceAccountUser)이라는 추가 역할을 사용자에게 할당합니다.

함수를 배포할 때 배포 서비스 계정에 서비스 에이전트 역할 누락

Cloud Functions 서비스는 프로젝트에서 관리 작업을 수행할 때 Cloud Functions 서비스 에이전트 서비스 계정(service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com)을 사용합니다. 기본적으로 이 계정에는 Cloud Functions cloudfunctions.serviceAgent 역할이 할당됩니다. 이 역할은 Cloud Pub/Sub, IAM, Cloud Storage, Firebase 통합에 필요합니다. 이 서비스 계정의 역할을 변경한 경우, 배포가 실패합니다.

오류 메시지

Cloud 콘솔

Missing necessary permission resourcemanager.projects.getIamPolicy for
serviceAccount:service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com on project <PROJECT_ID>.
Please grant serviceAccount:service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com
the roles/cloudfunctions.serviceAgent role. You can do that by running
'gcloud projects add-iam-policy-binding <PROJECT_ID> --member=serviceAccount:service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com --role=roles/cloudfunctions.serviceAgent'

Cloud SDK

ERROR: (gcloud.functions.deploy) OperationError: code=7,
message=Missing necessary permission resourcemanager.projects.getIamPolicy
for serviceAccount:service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com
on project <PROJECT_ID>. Please grant
serviceAccount:service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com
the roles/cloudfunctions.serviceAgent role. You can do that by running
'gcloud projects add-iam-policy-binding <PROJECT_ID> --member=serviceAccount:service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com --role=roles/cloudfunctions.serviceAgent'

해결 방법

기본 역할로 이 서비스 계정을 재설정합니다.

이벤트 기반 함수를 배포할 때 배포 서비스 계정에 Pub/Sub 권한이 없음

Cloud Functions 서비스는 관리 작업을 수행할 때 Cloud Functions 서비스 에이전트 서비스 계정(service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com)을 사용합니다. 기본적으로 이 계정에는 Cloud Functions cloudfunctions.serviceAgent 역할이 할당됩니다. 이벤트 기반 함수를 배포하려면 Cloud Functions 서비스에서 Cloud Pub/Sub에 액세스하여 주제와 구독을 구성해야 합니다. 서비스 계정에 할당된 역할이 변경되고 적절한 권한이 부여되지 않으면 Cloud Functions 서비스가 Cloud Pub/Sub에 액세스할 수 없고 배포가 실패합니다.

오류 메시지

Cloud 콘솔

Failed to configure trigger PubSub projects/<PROJECT_ID>/topics/<FUNCTION_NAME>

Cloud SDK

ERROR: (gcloud.functions.deploy) OperationError: code=13,
message=Failed to configure trigger PubSub projects/<PROJECT_ID>/topics/<FUNCTION_NAME>

해결 방법

다음 작업을 수행할 수 있습니다.

기본 역할로 이 서비스 계정을 재설정합니다.

또는
서비스 계정에 pubsub.subscriptions.* 및 pubsub.topics.* 권한을 부여합니다.

기본 런타임 서비스 계정이 존재하지 않음

사용자 관리 런타임 서비스 계정을 지정하지 않으면 1세대 함수는 기본적으로 런타임 서비스 계정으로 App Engine 서비스 계정을 사용합니다. 이 기본 계정이 삭제되었고 사용자 관리 계정이 지정되지 않았으면 배포가 실패합니다.

오류 메시지

Cloud 콘솔

Default service account '<PROJECT_ID>@appspot.gserviceaccount.com' doesn't exist. Please recreate this account or specify a different account. Please visit https://cloud.google.com/functions/docs/troubleshooting for in-depth troubleshooting documentation.

Cloud SDK

ERROR: (gcloud.functions.deploy) ResponseError: status=[400], code=[Ok], message=[Default service account '<PROJECT_ID>@appspot.gserviceaccount.com' doesn't exist. Please recreate this account or specify a different account. Please visit https://cloud.google.com/functions/docs/troubleshooting for in-depth troubleshooting documentation.]

해결 방법

1세대 함수를 배포할 때 사용자 관리 런타임 서비스 계정을 지정합니다.

또는
프로젝트에 대해 @appspot.gserviceaccount.com 기본 서비스 계정을 다시 만듭니다.

함수를 배포할 때 사용자에게 런타임 서비스 계정 권한 누락

여러 함수가 여러 리소스에 액세스하는 환경에서는 일반적으로 기본 런타임 서비스 계정(PROJECT_ID@appspot.gserviceaccount.com) 대신 이름이 지정된 런타임 서비스 계정에 함수별 ID를 사용합니다.

하지만 기본값이 아닌 런타임 서비스 계정을 사용하려면 배포자에게 해당 기본값이 아닌 계정에 대한 iam.serviceAccounts.actAs 권한이 있어야 합니다. 기본값이 아닌 런타임 서비스 계정을 만드는 사용자에게는 이 권한이 자동으로 부여되지만 올바른 권한이 있는 사용자가 다른 배포자에게 이 권한을 부여해야 합니다.

오류 메시지

Cloud SDK

ERROR: (gcloud.functions.deploy) ResponseError: status=[400], code=[Bad Request],
message=[Invalid function service account requested: <SERVICE_ACCOUNT_NAME@<PROJECT_ID>.iam.gserviceaccount.com]

해결 방법

기본값이 아닌 <SERVICE_ACCOUNT_NAME> 런타임 서비스 계정에 대한 roles/iam.serviceAccountUser 역할을 사용자에게 할당합니다. 이 역할에는 iam.serviceAccounts.actAs 권한이 포함됩니다.

함수를 배포하는 동안 Cloud Functions 서비스 에이전트 서비스 계정에 프로젝트 버킷 권한 누락

Cloud Functions는 동일한 Google Cloud Platform 프로젝트에 있는 Cloud Storage 버킷의 이벤트에 의해서만 트리거될 수 있습니다. 또한 Cloud Functions 서비스 에이전트 서비스 계정(service-<PROJECT_NUMBER>@gcf-admin-robot.iam.gserviceaccount.com)에는 프로젝트에 대한 cloudfunctions.serviceAgent 역할이 필요합니다.

오류 메시지

Cloud 콘솔

Deployment failure: Insufficient permissions to (re)configure a trigger
(permission denied for bucket <BUCKET_ID>). Please, give owner permissions
to the editor role of the bucket and try again.

Cloud SDK

ERROR: (gcloud.functions.deploy) OperationError: code=7, message=Insufficient
permissions to (re)configure a trigger (permission denied for bucket <BUCKET_ID>).
Please, give owner permissions to the editor role of the bucket and try again.

해결 방법

다음 작업을 수행할 수 있습니다.

기본 역할로 이 서비스 계정을 재설정합니다.

또는
런타임 서비스 계정에 cloudfunctions.serviceAgent 역할을 부여합니다.

또는
런타임 서비스 계정에 storage.buckets.{get, update} 및 resourcemanager.projects.get 권한을 부여합니다.

프로젝트 편집자 역할이 있는 사용자는 함수를 공개로 만들 수 없음

승인되지 않은 개발자가 함수 호출에 대한 인증 설정을 수정할 수 없도록 함수를 배포하는 사용자 또는 서비스에 cloudfunctions.functions.setIamPolicy 권한이 있어야 합니다.

오류 메시지

Cloud SDK

ERROR: (gcloud.functions.add-iam-policy-binding) ResponseError: status=[403], code=[Forbidden], message=[Permission 'cloudfunctions.functions.setIamPolicy' denied on resource 'projects/<PROJECT_ID>/locations/<LOCATION>/functions/<FUNCTION_NAME> (or resource may not exist).]

해결 방법

다음 작업을 수행할 수 있습니다.

배포자에게 프로젝트 소유자 또는 Cloud Functions 관리자 역할을 할당합니다. 두 역할 모두 cloudfunctions.functions.setIamPolicy 권한을 포함합니다.

또는
커스텀 역할을 만들어 권한을 수동으로 부여합니다.

VPC-SC를 지원하지 않는 Cloud Build로 인해 함수 배포 실패

Cloud Functions는 Cloud Build를 사용하여 소스 코드를 실행 가능한 컨테이너에 빌드합니다. VPC 서비스 제어와 함께 Cloud Functions를 사용하려면 서비스 경계에서 Cloud Build 서비스 계정에 대한 액세스 수준을 구성해야 합니다.

오류 메시지

Cloud 콘솔

다음 중 하나입니다.

Error in the build environment

OR

Unable to build your function due to VPC Service Controls. The Cloud Build
service account associated with this function needs an appropriate access
level on the service perimeter. Please grant access to the Cloud Build
service account: '{PROJECT_NUMBER}@cloudbuild.gserviceaccount.com' by
following the instructions at
https://cloud.google.com/functions/docs/securing/using-vpc-service-controls#grant-build-access"

Cloud SDK

다음 중 하나입니다.

ERROR: (gcloud.functions.deploy) OperationError: code=13, message=Error in
the build environment

OR

Unable to build your function due to VPC Service Controls. The Cloud Build
service account associated with this function needs an appropriate access
level on the service perimeter. Please grant access to the Cloud Build
service account: '{PROJECT_NUMBER}@cloudbuild.gserviceaccount.com' by
following the instructions at
https://cloud.google.com/functions/docs/securing/using-vpc-service-controls#grant-build-access"

해결 방법

프로젝트의 감사 대상 리소스 로그가 VPC 서비스 제어 섹션에 '조직 정책에 따라 요청이 금지됨'을 멘션하고 Cloud Storage 라벨이 있으면 Cloud Build 서비스 계정에 VPC 서비스 제어 경계에 대한 액세스 권한을 부여해야 합니다.

잘못 지정된 진입점으로 인해 함수 배포 실패

코드 진입점 즉, 내보낸 함수 이름이 잘못 지정된 경우 Cloud Functions 배포가 실패할 수 있습니다.

오류 메시지

Cloud 콘솔

Deployment failure: Function failed on loading user code. Error message:
Error: please examine your function logs to see the error cause:
https://cloud.google.com/functions/docs/monitoring/logging#viewing_logs

Cloud SDK

ERROR: (gcloud.functions.deploy) OperationError: code=3, message=Function
failed on loading user code. Error message: Please examine your function
logs to see the error cause:
https://cloud.google.com/functions/docs/monitoring/logging#viewing_logs

해결 방법

Cloud 콘솔 또는 Cloud SDK를 통해 소스 코드에 배포에서 올바르게 지정된 진입점 함수가 포함되어야 합니다.

리소스 위치 제약조건 조직 정책을 사용할 때 함수 배포 실패

조직에서 리소스 위치 제약조건 정책을 사용하면 로그에 이 오류가 표시될 수 있습니다. 이는 배포 파이프라인에서 멀티 리전 스토리지 버킷을 만들 수 없음을 나타냅니다.

오류 메시지

Cloud Build 로그에서 다음이 표시됩니다.

Token exchange failed for project '<PROJECT_ID>'.
Org Policy Violated: '<REGION>' violates constraint 'constraints/gcp.resourceLocations'

Cloud Storage 로그에서 다음이 표시됩니다.

<REGION>.artifacts.<PROJECT_ID>.appspot.com` storage bucket could not be created.

해결 방법

조직 정책 제약조건에서 constraints/gcp.resourceLocations를 사용하는 경우 적절한 멀티 리전 위치를 지정해야 합니다. 예를 들어 us 리전에 배포하는 경우 us-locations를 사용해야 합니다.

하지만 더 세밀하게 제어해야 하고 함수 배포를 여러 리전이 아닌 단일 리전으로 제한하려면 먼저 멀티 리전 버킷을 만듭니다.

전체 멀티 리전 허용
테스트 함수 배포
배포가 성공한 후 조직 정책을 다시 변경하여 특정 리전만 허용합니다.

Multi-Regional Storage 버킷은 해당 리전에서 계속 사용 가능하므로 후속 배포가 성공할 수 있습니다. 나중에 Multi-Regional Storage 버킷이 생성된 리전 외부의 리전을 allowlist하려면 이 프로세스를 반복해야 합니다.

함수의 전역 범위를 실행하는 동안 함수 배포 실패

이 오류는 코드에 문제가 있음을 나타냅니다. 배포 파이프라인에서 함수 배포가 완료되었지만 마지막 단계인 함수에 상태 확인 보내기 단계에서 실패했습니다. 이 상태 확인은 예외, 비정상 종료 또는 제한 시간이 발생할 수 있는 함수의 전역 범위를 실행하려고 합니다. 전역 범위는 일반적으로 라이브러리에 로드하고 클라이언트를 초기화하는 위치입니다.

오류 메시지

Cloud Logging 로그에서 다음이 표시됩니다.

"Function failed on loading user code. This is likely
due to a bug in the user code."

해결 방법

자세한 오류 메시지는 함수의 빌드 로그와 함수의 런타임 로그를 확인하세요. 함수가 전역 범위를 실행할 수 없는 이유가 명확하지 않으면 전역 변수의 지연 초기화를 사용하여 코드를 일시적으로 요청 호출로 이동하는 것이 좋습니다. 이를 통해 클라이언트 라이브러리 전반에 추가 로그 구문을 추가할 수 있습니다. 이로 인해 특히 다른 서비스를 호출하는 경우 인스턴스화 시간이 초과되거나 비정상 종료되고 예외가 실행될 수 있습니다. 또한 함수 제한 시간을 늘려 볼 수 있습니다.

빌드

함수 소스 코드를 Cloud Functions에 배포하면 소스가 Cloud Storage 버킷에 저장됩니다. 그러면 Cloud Build가 코드를 자동으로 컨테이너 이미지로 빌드하고 이미지를 Container Registry에 푸시합니다. Cloud Functions는 함수를 실행하려면 컨테이너를 실행해야 하는 경우에 이 이미지에 액세스합니다.

Container Registry 이미지 누락으로 인해 빌드 실패

Cloud Functions(1세대)는 Container Registry를 사용하여 함수의 이미지를 관리합니다. Container Registry는 Cloud Storage를 사용하여 STORAGE-REGION.artifacts.PROJECT-ID.appspot.com이라는 버킷에 이미지 레이어를 저장합니다. 이러한 버킷에 객체 수명 주기 관리를 사용하면 배포에서 존재하는 이러한 이미지를 사용하므로 함수 배포가 중단됩니다.

오류 메시지

Cloud 콘솔

Build failed: Build error details not available. Please check the logs at
<CLOUD_CONSOLE_LINK>

CLOUD_CONSOLE_LINK contains an error like below :
failed to get OS from config file for image 'us.gcr.io/<PROJECT_ID>/gcf/us-central1/<UUID>/worker:latest'"

Cloud SDK

ERROR: (gcloud.functions.deploy) OperationError: code=13, message=Build
failed: Build error details not available. Please check the logs at
<CLOUD_CONSOLE_LINK>

CLOUD_CONSOLE_LINK contains an error like below :
failed to get OS from config file for image 'us.gcr.io/<PROJECT_ID>/gcf/us-central1/<UUID>/worker:latest'"

해결 방법

Container Registry에 필요한 버킷에서 수명 주기 관리를 중지합니다.
영향을 받는 함수의 모든 이미지를 삭제합니다. 빌드 로그에 액세스하여 이미지 경로를 찾을 수 있습니다. 스크립트를 참조하여 이미지를 일괄 삭제합니다. 현재 배포된 함수에는 영향을 미치지 않습니다.
함수를 다시 배포합니다.

제공

제공 단계에서도 오류가 발생할 수 있습니다.

인증이 필요한 함수로 인한 제공 권한 오류

인증되지 않은 호출 허용이 사용 설정되지 않은 HTTP 함수는 적절한 권한이 없는 최종 사용자 및 서비스 계정에 대한 액세스 권한을 제한합니다. 이 오류 메시지는 호출자에게 함수를 호출할 수 있는 권한이 없음을 나타냅니다.

오류 메시지

HTTP 오류 응답 코드: 403 금지됨

HTTP 오류 응답 본문: 오류: 금지됨. 클라이언트에 이 서버에서 URL /<FUNCTION_NAME>을 가져올 수 있는 권한이 없습니다.

해결 방법

다음 작업을 수행할 수 있습니다.

조직에서 지원하는 경우 함수를 다시 배포하여 인증되지 않은 호출을 허용합니다. 이는 테스트 목적으로 유용할 수 있습니다.
요청 헤더에서 사용자 인증 정보를 사용하여 HTTP 함수를 호출합니다. 예를 들어 다음과 같이 gcloud를 통해 ID 토큰을 가져올 수 있습니다.
```
curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://REGION-PROJECT_ID.cloudfunctions.net/FUNCTION_NAME
```
호출 인증을 참조하세요.
Cloud Functions(1세대)의 경우 특정 함수에 대해 모든 사용자에게 공개(인증되지 않음) 액세스를 허용합니다.
Cloud Functions(2세대)의 경우 다음 중 하나를 수행할 수 있습니다.
- 사용자에게 특정 함수에 대한 Cloud Run 호출자 Cloud IAM 역할을 할당합니다.
- Google Cloud 콘솔에서 다음을 수행합니다.
  Google Cloud 콘솔로 이동
  1. 액세스 권한을 부여할 함수의 연결된 이름을 클릭합니다.
  2. 함수 세부정보 개요 페이지의 오른쪽 상단에 있는 링크에서 Cloud Run 제공 링크를 클릭합니다.
  3. 트리거를 클릭하고 인증되지 않은 호출 허용을 선택합니다.
  4. 저장을 클릭합니다.

'내부 트래픽만 허용' 구성으로 인해 제공 권한 오류

인그레스 설정은 Google Cloud 프로젝트 또는 VPC 서비스 제어 서비스 경계 외부의 리소스에서 HTTP 함수를 호출할 수 있는지 여부를 제한합니다. 인그레스 네트워킹에 '내부 트래픽만 허용' 설정이 구성된 경우 이 오류 메시지는 동일 프로젝트나 VPC 서비스 제어 경계에서 VPC 네트워크의 요청만 허용됨을 나타냅니다.

오류 메시지

HTTP 오류 응답 코드: 403 금지됨

HTTP 오류 응답 본문: 오류 403(금지됨) 403. 오류가 발생했습니다. 액세스가 금지되었습니다. 이외에 더 확인된 사항은 없습니다.

해결 방법

다음 작업을 수행할 수 있습니다.

Google Cloud 프로젝트나 VPC 서비스 제어 서비스 경계에서 요청을 보내는지 확인합니다.

또는
인그레스 설정을 함수의 모든 트래픽 허용으로 변경합니다.

함수 호출에 유효한 사용자 인증 정보가 없음

제한된 액세스로 설정된 Cloud Functions 함수를 호출하려면 ID 토큰이 필요합니다. 액세스 토큰 또는 갱신 토큰은 작동하지 않습니다.

오류 메시지

HTTP 오류 응답 코드: 401 Unauthorized

HTTP 오류 응답 본문: 클라이언트가 요청된 URL에 대한 권한이 없습니다.

해결 방법

요청에 Authorization: Bearer ID_TOKEN 헤더가 포함되어 있고 토큰이 액세스 또는 갱신 토큰이 아닌 ID 토큰인지 확인합니다. 서비스 계정의 비공개 키를 사용하여 수동으로 이 토큰을 생성하는 경우 이 가이드를 따라 자체 서명된 JWT 토큰을 Google에서 서명한 ID 토큰으로 교환해야 합니다.

`curl` 리디렉션을 사용해 Google 로그인 페이지로 함수를 호출하려고 시도합니다.

존재하지 않는 함수를 호출하려고 하면 Cloud Functions가 Google 계정 로그인 페이지로 이동하는 HTTP/2 302 리디렉션으로 응답합니다. 잘못되었습니다. HTTP/2 404 오류 응답 코드로 응답해야 합니다. 문제를 해결하는 중입니다.

해결 방법

함수 이름을 올바르게 지정해야 합니다. 누락된 함수에 올바른 404 오류를 반환하는 gcloud functions call을 사용하여 언제든지 확인할 수 있습니다.

애플리케이션 비정상 종료 및 함수 실행 실패

이 오류는 함수를 실행하는 프로세스가 중단되었음을 나타냅니다. 이는 일반적으로 함수 코드의 문제로 인한 런타임 비정상 종료로 인해 발생합니다. 함수 코드의 교착 상태 또는 기타 조건으로 인해 런타임이 수신 요청에 응답하지 않는 경우에도 발생할 수 있습니다.

오류 메시지

Cloud Logging 로그: "인프라가 함수와 통신할 수 없습니다. 사용자가 제공한 코드에 비정상 종료나 교착 상태가 있을 수 있습니다."

해결 방법

여러 가지 시나리오에서 다른 런타임이 비정상 종료될 수 있습니다. 근본 원인을 찾으려면 자세한 디버그 수준 로그를 출력하고 애플리케이션 로직을 확인한 후 특이한 사례를 테스트합니다.

Cloud Functions Python37 런타임에는 현재 로깅을 처리할 수 있는 속도에 대한 알려진 제한 사항이 있습니다. Python37 런타임 인스턴스의 로그 구문 작성 속도가 충분히 빠르면 이 오류가 발생할 수 있습니다. Python 런타임 버전 3.8 이상에서는 이 제한사항이 없습니다. 이 문제가 방지되도록 사용자는 더 높은 버전의 Python 런타임으로 마이그레이션하는 것이 좋습니다.

여전히 오류 원인이 확실하지 않으면 Google 지원 페이지를 참조하세요.

함수가 실행 중간에 중지되거나 코드가 완료된 후에도 계속 실행됨

일부 Cloud Functions 런타임에서는 사용자가 비동기 작업을 실행할 수 있습니다. 함수가 이러한 작업을 생성하는 경우 작업이 완료될 때까지 명시적으로 대기해야 합니다. 그렇지 않으면 잘못된 시간에 함수 실행이 중지될 수 있습니다.

오류 동작

함수는 다음 동작 중 하나를 나타냅니다.

지정된 제한 시간 기간이 경과하기 전에 비동기 작업이 실행되는 동안 함수가 종료됩니다.
이러한 작업이 완료될 때 함수의 실행은 중지되지 않으며 제한 시간 기간이 경과할 때까지 계속 실행됩니다.

해결 방법

함수가 조기 종료되는 경우 다음 작업을 수행하기 전에 함수의 비동기 작업이 모두 완료되었는지 확인해야 합니다.

값 반환
반환된 Promise 객체 확인 또는 거부(Node.js 함수만 해당)
포착되지 않은 예외 또는 오류 발생
HTTP 응답 보내기
콜백 함수 호출

모든 비동기 작업이 완료된 후 함수가 종료되지 않으면 함수가 완료되었을 때 함수가 Cloud Functions에 올바르게 신호를 보내는지 확인해야 합니다. 특히 함수가 비동기 작업을 완료하는 즉시 위에 나열된 작업 중 하나를 수행해야 합니다.

자바스크립트 힙 메모리 부족

메모리 한도가 2GiB를 초과하는 Node.js 12+ 함수의 경우 사용자가 NODE_OPTIONS를 max_old_space_size로 구성하여 자바스크립트 힙 한도가 함수의 메모리 한도와 같도록 해야 합니다.

오류 메시지

Cloud 콘솔

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

해결 방법

NODE_OPTIONS가 max_old_space_size를 함수의 메모리 제한으로 설정하도록 구성된 Node.js 12+ 함수를 배포합니다. 예를 들면 다음과 같습니다.

gcloud functions deploy envVarMemory \
--runtime nodejs20 \
--set-env-vars NODE_OPTIONS="--max_old_space_size=8192" \
--memory 8Gi \
--trigger-http

함수 종료됨

런타임 오류 또는 의도적인 종료로 인해 해당 코드를 실행하는 프로세스가 종료되었을 때 다음 오류 메시지 중 하나가 표시될 수 있습니다. 드물지만 일부 경우에 인프라 오류가 발생할 수 있습니다.

오류 메시지

함수 호출이 중단되었습니다. 오류: 함수가 종료되었습니다. 권장 조치: 로그에서 종료 이유를 조사합니다. 추가 문제 해결 정보는 Logging에서 찾을 수 있습니다.

요청이 거부됨 오류: 함수가 종료되었습니다. 권장 조치: 로그에서 종료 이유를 조사합니다. 추가 문제 해결 정보는 Logging에서 찾을 수 있습니다.

함수를 초기화할 수 없습니다. 오류: 함수가 종료되었습니다. 권장 조치: 로그에서 종료 이유를 조사합니다. 추가 문제 해결 정보는 Logging에서 찾을 수 있습니다.

해결 방법

executionID가 오류로 종료된 요청과 연관되었을 때 백그라운드(Pub/Sub 트리거됨) 함수에 대해 오류 시 재시도를 사용 설정합니다. 이렇게 하면 재시도 가능한 예외가 발생할 때 함수 실행 재시도를 허용합니다. 무한 재시도 루프 방지 및 재시도 가능한/치명적인 오류를 서로 다르게 관리하기 위한 방법을 포함하여 이 옵션을 안전하게 사용하는 방법에 대한 자세한 내용은 권장사항을 참조하세요.
함수 종료 후 발생하는 모든 백그라운드 작업은 문제를 일으키므로, 코드를 확인하세요. Cloud Functions는 함수의 실행 기간 중 실행되는 작업을 제외하고 다른 어떤 작업도 보장하지 않습니다. 따라서 작업이 백그라운드에서 실행되는 경우 삭제 프로세스로 종료될 수 있습니다.
갑작스러운 트래픽 증가가 있으면 약간 더 워크로드를 분산해보세요. 또한 누락되었거나 충돌된 종속 항목으로 인해 오류가 발생하지 않도록 Cloud Functions를 배포하기 전에 함수 프레임워크를 사용하여 로컬로 함수를 테스트합니다.

VPC-SC로 보호되는 리소스에 액세스할 때 런타임 오류

기본적으로 Cloud Functions는 공개 IP 주소를 사용하여 다른 서비스에 대해 아웃바운드 요청을 수행합니다. 함수가 VPC 서비스 제어 경계 내부에 없으면 서비스 경계 거부로 인해 VPC-SC로 보호되는 Google Cloud 서비스에 액세스하려고 시도할 때 HTTP 403 응답이 수신될 수 있습니다.

오류 메시지

감사된 리소스 로그에서 다음과 같은 항목:

"protoPayload": {
  "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
  "status": {
    "code": 7,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.PreconditionFailure",
        "violations": [
          {
            "type": "VPC_SERVICE_CONTROLS",
  ...
  "authenticationInfo": {
    "principalEmail": "CLOUD_FUNCTION_RUNTIME_SERVICE_ACCOUNT",
  ...
  "metadata": {
    "violationReason": "NO_MATCHING_ACCESS_LEVEL",
    "securityPolicyInfo": {
      "organizationId": "ORGANIZATION_ID",
      "servicePerimeterName": "accessPolicies/NUMBER/servicePerimeters/SERVICE_PERIMETER_NAME"
  ...

해결 방법

Google Cloud 프로젝트에서 Cloud Functions를 서비스 경계의 보호 리소스로 추가하고 VPC-SC 호환 기능을 배포합니다. 자세한 내용은 VPC 서비스 제어 사용을 참조하세요.

또는 Cloud Functions 프로젝트를 서비스 경계에 추가할 수 없으면 경계 외부 기능에 VPC 서비스 제어 사용을 참조하세요.

확장성

Cloud Functions 인프라와 관련된 확장 문제는 여러 상황에서 발생할 수 있습니다.

대기 중인 큐 요청 취소와 관련된 Cloud Logging 오류

다음 조건은 확장 실패와 관련이 있을 수 있습니다.

트래픽 급증
긴 콜드 스타트 시간
긴 요청 처리 시간
높은 함수 오류율
최대 인스턴스 한도에 도달하여 시스템이 더 이상 확장할 수 없음
Cloud Functions 서비스로 인한 일시적 요소

위의 경우 모두 Cloud Functions가 트래픽을 관리할 만큼 충분히 확장되지 않을 수 있습니다.

오류 메시지

The request was aborted because there was no available instance
- severity=WARNING( 응답 코드: 429) 구성 중에 설정한 max-instances 한도로 인해 Cloud Functions가 확장될 수 없습니다.
- severity=ERROR( 응답 코드: 500) Cloud Functions는 기본적으로 트래픽 속도를 관리할 수 없습니다.

해결 방법

HTTP 트리거 기반 함수의 경우 클라이언트가 삭제해서는 안 되는 요청에 대해 지수 백오프 및 재시도를 구현하도록 합니다. Workflows에서 Cloud Functions를 트리거하는 경우 try/retry 문법을 사용하여 이를 수행할 수 있습니다.
백그라운드/이벤트 기반 함수의 경우 Cloud Functions는 최소 1회 전송을 지원합니다. 재시도를 명시적으로 사용 설정하지 않아도 이벤트가 자동으로 다시 전송되고 함수 실행이 재시도됩니다. 자세한 내용은 이벤트 기반 함수 재시도를 참조하세요.
문제의 근본 원인이 Cloud Functions만으로 인해 증가된 일시적인 오류 기간이거나 해당 문제에 대한 도움이 필요한 경우 지원팀에 문의하세요.

로깅

문제를 추적하는 데 도움이 되도록 로깅을 설정하면 자체적인 문제가 발생할 수 있습니다.

로그 항목에 로그 심각도 수준이 없거나 잘못된 경우

Cloud Functions에는 기본적으로 간단한 런타임 로깅이 포함되어 있습니다. stdout 또는 stderr에 작성된 로그는 Google Cloud 콘솔에 자동으로 표시됩니다. 그러나 이러한 로그 항목에는 기본적으로 간단한 문자열 메시지만 포함됩니다.

오류 메시지

로그에 로그 심각도 수준이 없거나 잘못된 경우

해결 방법

로그 심각도를 포함하려면 구조화된 로그 항목을 전송해야 합니다.

장애 발생 시 예외를 다르게 처리 또는 로깅

장애 정보를 관리하고 로깅하는 방법을 맞춤설정할 수 있습니다.

해결 방법

함수를 try 블록에 래핑하여 예외 및 로깅 스택 트레이스 처리를 맞춤설정합니다.

예시


import logging
import traceback
def try_catch_log(wrapped_func):
  def wrapper(*args, **kwargs):
    try:
      response = wrapped_func(*args, **kwargs)
    except Exception:
      # Replace new lines with spaces so as to prevent several entries which
      # would trigger several errors.
      error_message = traceback.format_exc().replace('\n', '  ')
      logging.error(error_message)
      return 'Error';
    return response;
  return wrapper;


#Example hello world function
@try_catch_log
def python_hello_world(request):
  request_args = request.args

  if request_args and 'name' in request_args:
    1 + 's'
  return 'Hello World!'

Node.js 10 이상, Python 3.8, Go 1.13, 자바 11에서 로그가 너무 큼

이러한 런타임에서 일반 로그 항목의 최대 크기는 105KiB입니다.

해결 방법

이 제한보다 작은 로그 항목을 보내야 합니다.

Cloud 함수가 오류를 반환하지만 로그가 누락됨

Cloud 함수 로그는 프로젝트가 생성될 때 생성 및 사용 설정된 기본 버킷으로 스트리밍됩니다. 기본 버킷이 중지되었거나 Cloud 함수 로그가 제외 필터에 있으면 로그 탐색기에 로그가 표시되지 않습니다.

해결 방법

기본 로그가 사용 설정되어 있는지 확인합니다.

Cloud Functions 로그가 로그 탐색기에 표시되지 않음

일부 Cloud Logging 클라이언트 라이브러리는 비동기 프로세스를 사용하여 로그 항목을 작성합니다. 함수에 오류가 발생하거나 종료되는 경우 일부 로그 항목이 아직 기록되지 않았을 수 있으며 나중에 표시될 수 있습니다. 일부 로그가 손실되어 로그 탐색기에 표시되지 않을 수도 있습니다.

해결 방법

클라이언트 라이브러리 인터페이스를 사용하여 함수를 종료하기 전에 버퍼링된 로그 항목을 삭제하거나, 라이브러리를 사용하여 로그 항목을 동기식으로 작성합니다. stdout 또는 stderr에 로그를 직접 동기식으로 작성할 수도 있습니다.

Cloud Functions 로그가 로그 라우터 싱크를 통해 표시되지 않음

로그 항목은 로그 라우터 싱크를 사용하여 다양한 대상으로 라우팅됩니다.

싱크 세부정보 보기가 강조표시된 Console 로그 라우터 스크린샷

설정에는 단순히 삭제 가능한 항목을 정의하는 제외 필터가 있습니다.

제외 필터를 보여주는 Console 로그 라우터 싱크 세부정보 팝업 스크린샷

해결 방법

resource.type="cloud_functions"에 제외 필터가 설정되어 있지 않은지 확인합니다.

데이터베이스 연결

데이터베이스에 연결할 때 여러 문제가 발생할 수 있으며 연결 제한 초과 또는 시간 초과와 관련된 경우가 많습니다. 로그에 Cloud SQL 경고(예: '컨텍스트 기한 초과')가 표시되면 연결 구성을 조정해야 할 수 있습니다. 자세한 내용은 Cloud SQL 문서를 참조하세요.

네트워킹

네트워크 연결

이그레스 설정을 구성한 후에도 Cloud 함수의 모든 아웃바운드 요청이 실패하는 경우에는 연결 테스트를 실행하여 기본 네트워크 연결 문제를 식별하면 됩니다. 자세한 내용은 연결 테스트 만들기 및 실행을 참조하세요.

서버리스 VPC 액세스 커넥터가 준비되지 않았거나 존재하지 않음

서버리스 VPC 액세스 커넥터가 실패하면 커넥터 전용의 필수 /28 서브넷 마스크가 사용 중이 아니기 때문일 수 있습니다.

오류 메시지

VPC connector projects/xxxxx/locations/REGION/connectors/xxxx
is not ready yet or does not exist.

해결 방법

서브넷을 나열하여 커넥터가 /28 서브넷 마스크를 사용하는지 확인하세요.

사용하지 않으면 /28 서브넷을 사용하도록 새 커넥터를 다시 만들거나 만드세요. 다음 사항을 참고하세요.

커넥터를 다시 만들 때 다른 함수를 다시 배포할 필요가 없습니다. 커넥터를 다시 만들 때 네트워크 중단이 발생할 수 있습니다.
새로운 대체 커넥터를 만들 때는 새 커넥터를 사용하도록 함수를 다시 배포한 후 원래 커넥터를 삭제합니다. 이 방법은 네트워크 중단을 방지합니다.

TCP 포트 25를 사용하는 외부 대상 IP 주소에 대한 SMTP 트래픽이 차단됨

Google Cloud는 보안 강화를 위해 함수에서 이메일을 보낼 때 TCP 목적지 포트 25로의 연결을 차단합니다.

해결 방법

이러한 연결을 차단 해제하려면 다음 옵션 중 하나를 선택합니다.

TCP 포트 587 또는 465와 같은 다른 포트에서 SMTP 서버에 연결합니다.
사용할 서드 파티 이메일 서비스를 선택합니다.

Cloud Functions 문제 해결

배포

뷰어 역할이 있는 사용자는 함수를 배포할 수 없음

Cloud 콘솔

Cloud SDK

프로젝트 뷰어 또는 Cloud 함수 역할이 있는 사용자는 함수를 배포할 수 없음

Cloud 콘솔

Cloud SDK

함수를 배포할 때 배포 서비스 계정에 서비스 에이전트 역할 누락

Cloud 콘솔

Cloud SDK

이벤트 기반 함수를 배포할 때 배포 서비스 계정에 Pub/Sub 권한이 없음

Cloud 콘솔

Cloud SDK

기본 런타임 서비스 계정이 존재하지 않음

Cloud 콘솔

Cloud SDK

함수를 배포할 때 사용자에게 런타임 서비스 계정 권한 누락

함수를 배포하는 동안 Cloud Functions 서비스 에이전트 서비스 계정에 프로젝트 버킷 권한 누락

Cloud 콘솔

Cloud SDK

프로젝트 편집자 역할이 있는 사용자는 함수를 공개로 만들 수 없음

VPC-SC를 지원하지 않는 Cloud Build로 인해 함수 배포 실패

Cloud 콘솔

Cloud SDK

잘못 지정된 진입점으로 인해 함수 배포 실패

Cloud 콘솔

Cloud SDK

리소스 위치 제약조건 조직 정책을 사용할 때 함수 배포 실패

함수의 전역 범위를 실행하는 동안 함수 배포 실패

빌드

Container Registry 이미지 누락으로 인해 빌드 실패

Cloud 콘솔

Cloud SDK

제공

인증이 필요한 함수로 인한 제공 권한 오류

'내부 트래픽만 허용' 구성으로 인해 제공 권한 오류

함수 호출에 유효한 사용자 인증 정보가 없음

curl 리디렉션을 사용해 Google 로그인 페이지로 함수를 호출하려고 시도합니다.

애플리케이션 비정상 종료 및 함수 실행 실패

함수가 실행 중간에 중지되거나 코드가 완료된 후에도 계속 실행됨

자바스크립트 힙 메모리 부족

Cloud 콘솔

함수 종료됨

VPC-SC로 보호되는 리소스에 액세스할 때 런타임 오류

확장성

대기 중인 큐 요청 취소와 관련된 Cloud Logging 오류

로깅

로그 항목에 로그 심각도 수준이 없거나 잘못된 경우

장애 발생 시 예외를 다르게 처리 또는 로깅

Node.js 10 이상, Python 3.8, Go 1.13, 자바 11에서 로그가 너무 큼

Cloud 함수가 오류를 반환하지만 로그가 누락됨

Cloud Functions 로그가 로그 탐색기에 표시되지 않음

Cloud Functions 로그가 로그 라우터 싱크를 통해 표시되지 않음

데이터베이스 연결

네트워킹

네트워크 연결

서버리스 VPC 액세스 커넥터가 준비되지 않았거나 존재하지 않음

TCP 포트 25를 사용하는 외부 대상 IP 주소에 대한 SMTP 트래픽이 차단됨

`curl` 리디렉션을 사용해 Google 로그인 페이지로 함수를 호출하려고 시도합니다.