Cloud Functions 문제 해결

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

배포

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

뷰어 또는 브라우저 역할이 있는 사용자는 함수를 배포할 수 없습니다.

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

오류 메시지

Cloud Console

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 Console

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 Console

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 Console

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>

해결 방법

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

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

여러 함수가 여러 리소스에 액세스하는 환경에서는 기본 런타임 서비스 계정(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]

해결 방법

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

함수 배포 중 런타임 서비스 계정에 프로젝트 버킷 권한 누락

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

오류 메시지

Cloud Console

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 권한을 부여합니다.

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

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

오류 메시지

Cloud Console

다음 중 하나입니다.

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 Console

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 Console 또는 Cloud SDK를 통해 배포에 올바르게 지정된 진입점 함수가 포함되어야 합니다.

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

승인되지 않은 개발자가 함수 호출에 대한 인증 설정을 수정할 수 없도록 함수를 배포하는 사용자 또는 서비스에 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를 사용하면 적절한 권한이 있는 최종 사용자 및 서비스 계정으로 함수 액세스 권한을 제한할 수 있습니다. 이 오류 메시지는 호출자에게 함수 호출을 위한 권한이 없음을 나타냅니다.

배포된 함수는 기본적으로 비공개로 설정됩니다.

오류 메시지

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

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

해결 방법

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

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

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

오류 메시지

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

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

해결 방법

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

  • 요청이 Google Cloud 프로젝트 또는 VPC 서비스 제어 서비스 경계로부터 시작되는지 확인합니다.

    또는

  • 함수에 대해 인그레스 설정을 모든 트래픽 허용으로 변경합니다.

로깅

문제 추적을 돕기 위해 로깅을 설정하면 자체적인 문제가 발생할 수 있습니다.

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

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

오류

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

해결 방법

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

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

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

해결 방법

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

예시


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 Functions 로그가 로그 라우터 싱크를 통해 표시되지 않음

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

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

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

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

해결 방법

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