Cloud Run에 Cloud Storage 이벤트 라우팅

Eventarc 트리거는 특정 이벤트 또는 이벤트 집합에 관심이 있음을 선언합니다. 트리거 필터를 지정하여 이벤트 소스와 대상 Cloud Run 서비스를 포함한 이벤트 라우팅을 구성할 수 있습니다.

Eventarc는 HTTP 요청을 통해 CloudEvents 형식으로 이벤트 수신자에 이벤트를 전달합니다.

이 안내에서는 직접 Cloud Storage 이벤트에 의해 트리거되는 Cloud Run 서비스에 대한 이벤트 라우팅을 구성하는 방법을 보여줍니다. 자세한 내용은 지원되는 직접 이벤트 목록을 참조하세요.

참고: Google 제공업체에 직접 및 감사 로그 이벤트가 모두 지원되면 직접 이벤트를 필터링하는 트리거를 만드는 것이 좋습니다. 직접 이벤트는 감사 로그 이벤트에 비해 여러 가지 이점을 제공합니다. 자세한 내용은 이벤트 경로를 참조하세요.

트리거 만들기 준비

트리거를 만들기 전에 다음 기본 요건을 충족하세요.

콘솔

1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 만들거나 선택합니다.

   참고: 이 절차에서 생성한 리소스를 유지하지 않으려면 기존 프로젝트를 선택하지 말고 프로젝트를 새로 만드세요. 작업이 끝나면 프로젝트를 삭제하여 프로젝트와 관련된 모든 리소스를 삭제할 수 있습니다.

   프로젝트 선택자로 이동

2. Cloud Logging, Eventarc, Eventarc Publishing API를 사용 설정합니다.

   API 사용 설정

3. 해당하는 경우 직접 이벤트와 관련된 API를 사용 설정합니다. 예를 들어 Cloud Storage 이벤트의 경우 Cloud Storage API를 사용 설정합니다.

4. 아직 계정이 없는 경우 사용자 관리형 서비스 계정을 만들고 Eventarc에서 대상 서비스의 이벤트를 관리할 수 있도록 필요한 역할과 권한을 계정에 부여합니다.

   1. Google Cloud 콘솔에서 서비스 계정 만들기 페이지로 이동합니다.

      서비스 계정 만들기로 이동

   2. 프로젝트를 선택합니다.

   3. 서비스 계정 이름 필드에 이름을 입력합니다. Google Cloud 콘솔은 이 이름을 기반으로 서비스 계정 ID 필드를 채웁니다.

      서비스 계정 설명 필드에 설명을 입력합니다. 예를 들면 Service account for event trigger입니다.

   4. 만들고 계속하기를 클릭합니다.

   5. 적절한 액세스 권한을 제공하려면 역할 선택 목록에서 인증되었거나 인증되지 않은 호출과 관련해 서비스 계정에 부여할 필수 Identity and Access Management(IAM) 역할을 선택합니다. 자세한 내용은 Cloud Run 대상의 역할 및 권한을 참조하세요.

      역할을 추가하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.

      중요: Cloud Run 서비스에 대한 인증된 호출을 수락하려면 트리거를 roles/run.invoker 역할이 있는 서비스 계정과 연결해야 합니다. 트리거를 만들거나 업데이트할 때 해당 서비스 계정을 선택합니다.

   6. 계속을 클릭합니다.

   7. 계정 만들기를 마치려면 완료를 클릭합니다.

5. Cloud Storage 서비스 에이전트에 Pub/Sub 게시자 역할을 부여합니다. 일반적으로는 [e-mail]입니다. Cloud Storage 서비스 에이전트의 이메일 주소를 가져올 수 있습니다.

   1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

      IAM으로 이동

   2. Cloud Storage 서비스 에이전트 행에서 주 구성원 수정을 클릭합니다. 서비스 에이전트가 나열되지 않는 경우 다음 단계를 진행합니다. 액세스 권한 수정 창이 열립니다.

      1. 다른 역할 추가를 클릭한 다음 Pub/Sub 게시자 역할을 검색합니다.
      2. 역할을 선택합니다.
      3. 저장을 클릭합니다.

   3. 서비스 에이전트가 나열되지 않으면 액세스 권한 부여를 클릭합니다. 액세스 권한 부여 창이 열립니다.

      1. 새 주 구성원 필드에 서비스 에이전트의 이메일 주소를 입력합니다.
      2. 역할 선택 목록에서 Pub/Sub 게시자 역할을 검색합니다.
      3. 역할을 선택합니다.
      4. 저장을 클릭합니다.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Cloud Logging, Eventarc, Eventarc Publishing API를 사용 설정합니다.

   gcloud services enable logging.googleapis.com \
     eventarc.googleapis.com \
     eventarcpublishing.googleapis.com

3. 해당하는 경우 직접 이벤트와 관련된 API를 사용 설정합니다. 예를 들어 Cloud Storage 이벤트의 경우 storage.googleapis.com를 사용 설정합니다.

4. 아직 계정이 없는 경우 사용자 관리형 서비스 계정을 만들고 Eventarc에서 대상 서비스의 이벤트를 관리할 수 있도록 필요한 역할과 권한을 계정에 부여합니다.

   1. 서비스 계정을 만듭니다.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      SERVICE_ACCOUNT_NAME을 서비스 계정 이름으로 바꿉니다. 6~30자(영문 기준) 사이여야 하며 소문자 영숫자 문자와 대시를 포함할 수 있습니다. 서비스 계정을 만든 후에는 이름을 변경할 수 없습니다.

   2. 인증되었거나 인증되지 않은 호출에 필요한 Identity and Access Management(IAM) 역할 또는 권한을 부여합니다. 자세한 내용은 Cloud Run 대상의 역할 및 권한을 참조하세요.

   중요: Cloud Run 서비스에 대한 인증된 호출을 수락하려면 트리거를 roles/run.invoker 역할이 있는 서비스 계정과 연결해야 합니다. 트리거를 만들거나 수정할 때 --service-account 플래그를 사용하여 해당 서비스 계정을 트리거와 연결합니다.

5. Cloud Storage 서비스 계정에 pubsub.publisher 역할을 부여합니다.

   SERVICE_ACCOUNT="$(gsutil kms serviceaccount -p PROJECT_ID)"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:${SERVICE_ACCOUNT}" \
     --role="roles/pubsub.publisher"
   

트리거 만들기

Google Cloud CLI를 사용하거나 Google Cloud 콘솔을 통해 Eventarc 트리거를 만들 수 있습니다.

참고: 정확히 일치해야 필터링이 이루어지며 필터링에서 와일드 카드 또는 정규 표현식은 지원되지 않습니다.

콘솔

1. Google Cloud 콘솔에서 Eventarc 트리거 페이지로 이동합니다.

   트리거로 이동

2. 트리거 만들기를 클릭합니다.
3. 트리거 이름을 입력합니다.

   트리거의 ID이며 문자로 시작해야 합니다. 최대 63자(영문 기준)의 소문자, 숫자, 하이픈을 포함할 수 있습니다.

4. 트리거 유형으로 Google 소스를 선택합니다.
5. 이벤트 제공자 목록에서 Cloud Storage를 선택합니다.

   연결된 Google Cloud 문서에 사용된 이벤트 제공자 이름에 Cloud 또는 Google Cloud 프리픽스가 없을 수 있습니다. 예를 들어 콘솔에서는 Redis용 Memorystore를 Redis용 Google Cloud Memorystore라고 합니다.

6. 이벤트 유형 목록의 직접 이벤트에서 이벤트 유형을 선택합니다.
   • google.cloud.storage.object.v1.archived: 객체의 라이브 버전이 보관처리되거나 삭제되면 이벤트가 전송됩니다. 이 이벤트는 버전 관리 버킷인 경우에만 전송됩니다.
   • google.cloud.storage.object.v1.delete: 객체가 영구적으로 삭제되면 이벤트가 전송됩니다. 버킷의 객체 버전 관리 설정에 따라 다음과 같은 결과가 발생합니다.
     • 버전 관리 버킷의 경우 버전이 영구적으로 삭제될 때에만 전송됩니다(객체를 보관처리할 때는 전송되지 않음).
     • 버전 관리 버킷이 아닌 경우 객체가 삭제되거나 덮어쓰여질 때 전송됩니다.
   • google.cloud.storage.object.v1.finalized: 버킷에서 새로운 객체를 만들거나 기존 객체를 덮어쓰고 해당 객체의 새로운 세대를 만들면 이벤트가 전송됩니다.
   • google.cloud.storage.object.v1.metadataUpdated: 기존 객체의 [메타데이터](/storage/docs/metadata)가 변경되면 이벤트가 전송됩니다.
7. 이벤트 데이터 콘텐츠 유형 목록에서 이벤트 페이로드의 인코딩을 선택합니다.

   Cloud Storage의 직접 이벤트에서는 application/json이어야 합니다.

8. Cloud Storage 버킷의 전역적으로 고유한 식별자를 지정하거나 찾습니다.

   Cloud Storage 버킷은 Eventarc 트리거와 동일한 Google Cloud 프로젝트 및 리전 또는 멀티 리전에 있어야 합니다.

9. 리전을 선택합니다.

   Eventarc용 Cloud Storage 트리거는 단일 리전, 이중 리전, 멀티 리전 위치에서 사용할 수 있습니다. Cloud Storage 버킷은 Eventarc 트리거와 동일한 Google Cloud 프로젝트 및 리전 또는 멀티 리전에 있어야 합니다.

   이벤트는 Cloud Storage의 Pub/Sub 알림을 사용하여 전송됩니다. 같은 버킷에 등록된 알림을 너무 많이 설정하면 Cloud Storage bucket ...: Pub/Sub notification limit reached 오류로 표시된 버킷의 알림 한도가 소진될 수 있습니다. 특정 이벤트에 트리거되는 알림 구성은 10개까지 사용할 수 있습니다. Cloud Storage 할당량 및 한도 페이지에서 추가 할당량 및 제한사항을 참조하세요.

10. 서비스 또는 워크플로를 호출할 서비스 계정을 선택합니다.

    또는 새 서비스 계정을 만들 수 있습니다.

    이는 트리거와 연결되어 있고 이전에 Eventarc에 필요한 특정 역할을 부여한 Identity and Access Management(IAM) 서비스 계정 이메일을 지정합니다.

11. 이벤트 대상 목록에서 Cloud Run을 선택합니다.
12. 서비스를 선택합니다.
    

    트리거의 이벤트를 수신하는 서비스의 이름입니다. 서비스는 트리거와 동일한 프로젝트에 있어야 하며 이벤트가 생성될 때마다 해당 이벤트를 기준 URL 경로(/)로 전송되는 HTTP POST 요청으로 수신합니다.

13. 필요한 경우, 들어오는 요청을 보낼 서비스 URL 경로를 지정할 수 있습니다.

    이는 트리거의 이벤트가 전송되어야 하는 대상 서비스의 상대 경로입니다. 예를 들면 /, /route, route, route/subroute입니다.

14. 만들기를 클릭합니다.

트리거가 생성된 후에는 이벤트 소스 필터를 수정할 수 없습니다. 대신 새 트리거를 만들고 이전 트리거를 삭제합니다. 자세한 내용은 트리거 관리를 참조하세요.

gcloud

필수 및 선택적 플래그와 함께 gcloud eventarc triggers create 명령어를 실행하여 트리거를 만들 수 있습니다.

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

다음을 바꿉니다.

• TRIGGER: 트리거의 ID 또는 정규화된 식별자입니다.
• LOCATION: Eventarc 트리거 위치입니다. 또는 eventarc/location 속성을 설정할 수 있습니다(예: gcloud config set eventarc/location us-central1).

  Cloud Storage 버킷은 Eventarc 트리거와 동일한 Google Cloud 프로젝트 및 리전 또는 멀티 리전에 있어야 합니다. 자세한 내용은 Eventarc 위치를 참조하세요.

• DESTINATION_RUN_SERVICE: 트리거의 이벤트를 수신하는 Cloud Run 서비스의 이름입니다. 서비스는 Cloud Run에서 지원하는 모든 위치에 있을 수 있으며 트리거와 동일한 위치에 있지 않아도 됩니다. 그러나 서비스는 트리거와 동일한 프로젝트에 있어야 하며 이벤트가 생성될 때마다 해당 이벤트를 기준 URL 경로(/)로 전송되는 HTTP POST 요청으로 수신합니다.
• DESTINATION_RUN_REGION: (선택사항) 대상 Cloud Run 서비스를 찾을 수 있는 리전입니다. 이 리전이 지정되지 않으면 서비스가 트리거와 동일한 리전에 있다고 가정합니다.
• EVENT_FILTER_TYPE: Cloud Storage 이벤트의 식별자이며 다음 중 하나일 수 있습니다.
  • google.cloud.storage.object.v1.finalized: 버킷에서 새로운 객체를 만들거나 기존 객체를 덮어쓰고 해당 객체의 새로운 세대를 만들면 이벤트가 전송됩니다.
  • google.cloud.storage.object.v1.archived: 객체의 서비스 중인 버전이 보관처리되거나 삭제될 때 이벤트가 전송됩니다. 이 이벤트는 버전 관리 버킷인 경우에만 전송됩니다.
  • google.cloud.storage.object.v1.deleted: 객체가 영구적으로 삭제될 때 이벤트가 전송됩니다. 버킷의 객체 버전 관리 설정에 따라 다음과 같은 결과가 발생합니다.
    • 버전 관리 버킷의 경우 버전이 영구적으로 삭제될 때에만 전송됩니다(객체를 보관처리할 때는 전송되지 않음).
    • 버전 관리 버킷이 아닌 경우 객체가 삭제되거나 덮어쓰여질 때 전송됩니다.
  • google.cloud.storage.object.v1.metadataUpdated: 기존 객체의 메타데이터가 변경될 때 이벤트가 전송됩니다.
• BUCKET: Cloud Storage 버킷의 전역 고유 식별자입니다.
• SERVICE_ACCOUNT_NAME: 사용자 관리형 서비스 계정의 이름입니다.
• PROJECT_ID: Google Cloud 프로젝트 ID입니다.

참고:

• Cloud Storage의 직접 이벤트에서는 이벤트 페이로드 인코딩이 application/json입니다.
• 이 플래그들은 필수사항입니다.
  • --event-filters="type=EVENT_FILTER_TYPE"
  • --event-filters="bucket=BUCKET"
• 각 트리거에 여러 이벤트 필터를 넣거나(한 개의 --event-filters=[ATTRIBUTE=VALUE,...] 플래그에 쉼표로 구분하여 입력) 플래그를 반복하여 필터를 추가할 수 있습니다. 모든 필터와 일치하는 이벤트만 대상으로 전송됩니다. 와일드 카드와 정규 표현식은 지원되지 않습니다.
• 트리거가 생성된 후에는 이벤트 필터 유형을 변경할 수 없습니다. 다른 이벤트 유형의 경우 새 트리거를 만들어야 합니다.
• 이벤트는 Cloud Storage의 Pub/Sub 알림을 사용하여 전송됩니다. 같은 버킷에 등록된 알림을 너무 많이 설정하면 Cloud Storage bucket ...: Pub/Sub notification limit reached 오류로 표시된 버킷의 알림 한도가 소진될 수 있습니다. 특정 이벤트에 트리거되는 알림 구성은 10개까지 사용할 수 있습니다. Cloud Storage 할당량 및 한도 페이지에서 추가 할당량 및 제한사항을 참조하세요.
• --service-account 플래그는 트리거와 연결된 Identity and Access Management(IAM) 서비스 계정 이메일을 지정하는 데 사용됩니다.
• 필요한 경우 --destination-run-path 플래그를 사용하여 트리거 이벤트가 전송되어야 하는 대상 Cloud Run 서비스의 상대 경로를 지정합니다.

예를 들면 다음과 같습니다.

gcloud eventarc triggers create helloworld-trigger \
    --location=us-central1 \
    --destination-run-service=helloworld-events \
    --destination-run-region=us-central1 \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=my-bucket" \
    --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

이 명령어는 Cloud Storage 버킷 my-bucket 및 google.cloud.storage.object.v1.finalized로 식별된 이벤트에 대해 helloworld-trigger라는 트리거를 만듭니다.

Terraform

Terraform을 사용하여 Cloud Run 대상에 대한 트리거를 만들 수 있습니다. 자세한 내용은 Terraform을 사용하여 트리거 만들기를 참조하세요.

참고: 트리거는 즉시 생성되지만 트리거에서 이벤트를 전파하고 필터링하는 데 최대 2분이 걸릴 수 있습니다.

트리거 나열

Google Cloud CLI를 사용하거나 Google Cloud 콘솔을 통해 Eventarc 트리거를 나열하여 트리거 생성을 확인할 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 Eventarc 트리거 페이지로 이동합니다.

   트리거로 이동

   이 페이지에서는 모든 위치의 트리거를 나열하고 이름, 리전, 이벤트 제공자, 대상 등과 같은 세부정보를 포함합니다.

2. 트리거를 필터링하려면 다음 안내를 따르세요.

   1. 필터 또는 트리거 필터링 필드를 클릭합니다.
   2. 속성 목록에서 트리거를 필터링하는 옵션을 선택합니다.

   단일 속성을 선택하거나 OR 논리 연산자를 사용하여 속성을 추가할 수 있습니다.

3. 트리거를 정렬하려면 지원되는 열 제목 옆에 있는 정렬을 클릭합니다.

gcloud

다음 명령어를 실행하여 트리거를 나열합니다.

gcloud eventarc triggers list --location=-

이 명령어는 모든 위치의 트리거를 나열하고 이름, 유형, 대상, 상태와 같은 세부정보를 포함합니다.

다음 단계

• Eventarc 자세히 알아보기
• 트리거 관리 방법 알아보기