Pub/Sub 메시지를 사용하여 이벤트 수신(Terraform)

표준

이 빠른 시작에서는 Terraform을 사용하여 Pub/Sub에서 직접 이벤트를 수신하고 이벤트를 Cloud Run 서비스로 라우팅하는 Eventarc 트리거를 만드는 방법을 보여줍니다. Terraform을 사용하여 Eventarc 트리거를 만드는 방법에 관한 자세한 내용은 Terraform을 사용하여 트리거 만들기를 참고하세요.

이 빠른 시작에서 학습할 내용은 다음과 같습니다.

Terraform 배포를 준비합니다.
다음을 수행하는 Terraform 구성을 정의합니다.
1. API 사용 설정
2. 서비스 계정을 만듭니다.
3. Pub/Sub 주제를 이벤트 제공업체로 만듭니다.
4. Cloud Run에 서비스를 이벤트 대상으로 배포합니다.
5. Eventarc 트리거를 만듭니다.
Terraform 구성을 적용합니다.

이렇게 하면 메시지를 Pub/Sub 주제에 게시하여 이벤트를 생성할 수 있습니다. Eventarc 트리거는 메시지를 Cloud Run에 배포된 이벤트 수신자 서비스로 라우팅하고 서비스는 이벤트 메시지를 로깅하여 이벤트 기반 아키텍처의 간단한 예를 제공합니다.

시작하기 전에

조직에서 정의한 보안 제약조건으로 인해 다음 단계를 완료하지 못할 수 있습니다. 문제 해결 정보는 제한된 Google Cloud 환경에서 애플리케이션 개발을 참조하세요.

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Cloud Resource Manager 및 Identity and Access Management (IAM) API를 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할 (roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

로컬 셸을 사용하는 경우 사용자 계정에 대한 로컬 인증 사용자 인증 정보를 만듭니다.

gcloud auth application-default login

Cloud Shell을 사용하는 경우 이 작업을 수행할 필요는 없습니다.

인증 오류가 반환되고 외부 ID 공급업체(IdP)를 사용하는 경우 제휴 ID로 gcloud CLI에 로그인했는지 확인합니다.

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

Google Cloud 프로젝트를 만듭니다.
```
gcloud projects create PROJECT_ID
```
PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.
생성한 Google Cloud 프로젝트를 선택합니다.
```
gcloud config set project PROJECT_ID
```
PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Cloud Resource Manager 및 Identity and Access Management (IAM) API를 사용 설정합니다.

API 사용 설정에 필요한 역할

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

로컬 셸을 사용하는 경우 사용자 계정에 대한 로컬 인증 사용자 인증 정보를 만듭니다.

gcloud auth application-default login

Cloud Shell을 사용하는 경우 이 작업을 수행할 필요는 없습니다.

인증 오류가 반환되고 외부 ID 공급업체(IdP)를 사용하는 경우 제휴 ID로 gcloud CLI에 로그인했는지 확인합니다.

이 가이드에 기존 프로젝트를 사용하는 경우 이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다. 새 프로젝트를 만든 경우에는 이미 필요한 권한이 있습니다.
필수 권한

빠른 시작을 완료하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
- Cloud Run 관리자(roles/run.admin)
- Eventarc 관리자(roles/eventarc.admin)
- 로그 뷰 접근자 (roles/logging.viewAccessor)
- 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin)
- Pub/Sub 게시자 (roles/pubsub.publisher)
- 서비스 계정 관리자(roles/iam.serviceAccountAdmin)
- 서비스 계정 사용자(roles/iam.serviceAccountUser)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

Terraform 배포 준비

Terraform 리소스를 배포하기 전에 Terraform 구성 파일을 만들어야 합니다. Terraform 구성 파일을 사용하면 Terraform 구문을 사용하여 인프라에 대해 원하는 최종 상태를 정의할 수 있습니다.

로컬 셸을 사용하는 경우 Terraform을 설치합니다.

Terraform은 이미 Cloud Shell 환경에 통합되어 있으며 Terraform을 설치하지 않고도 Cloud Shell을 사용하여 Terraform 리소스를 배포할 수 있습니다.
Cloud Shell 또는 로컬 셸에서 Terraform 구성을 적용할 기본 Google Cloud 프로젝트를 설정합니다. 이 명령어는 프로젝트당 한 번만 실행하면 되며 어떤 디렉터리에서도 실행할 수 있습니다.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
PROJECT_ID를 Google Cloud 프로젝트의 ID로 바꿉니다.

Terraform 구성 파일에서 명시적 값을 설정하면 환경 변수가 재정의됩니다.
각 Terraform 구성 파일에는 자체 디렉터리(루트 모듈이라고도 함)가 있어야 합니다. 디렉터리를 만들고 해당 디렉터리 내에 새 파일을 만듭니다.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
DIRECTORY을 Terraform 디렉터리의 이름으로 바꿉니다.

파일 이름에는 .tf 확장자가 있어야 합니다. 예를 들어 이 빠른 시작에서는 구성 파일이 main.tf입니다.

Terraform 구성 정의

다음 Terraform 코드 스니펫을 main.tf 파일에 복사합니다. 또는 GitHub에서 전체 코드 샘플을 복사하려면 코드 스니펫의 오른쪽 상단에서 > GitHub에서 보기를 클릭합니다.

API 사용 설정

Terraform 구성을 적용하는 데 필요한 API를 사용 설정하려면 google_project_service Terraform 리소스를 사용하세요.

# Enable Cloud Run API
resource "google_project_service" "run" {
  service            = "run.googleapis.com"
  disable_on_destroy = false
}

# Enable Eventarc API
resource "google_project_service" "eventarc" {
  service            = "eventarc.googleapis.com"
  disable_on_destroy = false
}

# Enable Pub/Sub API
resource "google_project_service" "pubsub" {
  service            = "pubsub.googleapis.com"
  disable_on_destroy = false
}

서비스 계정 만들기

모든 Eventarc 트리거는 IAM 서비스 계정과 연결됩니다. 테스트 목적으로 전용 서비스 계정을 만들려면 google_service_account Terraform 리소스를 사용하세요.

# Create a dedicated service account
resource "google_service_account" "eventarc" {
  account_id   = "eventarc-trigger-sa"
  display_name = "Eventarc trigger service account"
}

2021년 4월 8일 이전에 Pub/Sub 서비스 에이전트를 사용 설정한 경우 서비스 에이전트에 서비스 계정 토큰 생성자 역할 (roles/iam.serviceAccountTokenCreator)을 부여합니다.

resource "google_project_iam_member" "tokencreator" {
  project  = data.google_project.project.id
  role     = "roles/iam.serviceAccountTokenCreator"
  member   = "serviceAccount:service-${data.google_project.project.number}@gcp-sa-pubsub.iam.gserviceaccount.com"
}

Pub/Sub 주제를 이벤트 제공자로 만들기

Pub/Sub 주제를 만들려면 google_pubsub_topic Terraform 리소스를 사용합니다. 주제 수준에서 서비스 계정에 Pub/Sub 게시자 역할 (roles/pubsub.publisher)을 부여하려면 google_pubsub_topic_iam_member Terraform 리소스를 사용합니다.

# Create a Pub/Sub topic
resource "google_pubsub_topic" "default" {
  name = "pubsub_topic"
}

# Grant permission to publish messages to a Pub/Sub topic
resource "google_pubsub_topic_iam_member" "pubsubpublisher" {
  project    = google_pubsub_topic.default.project
  topic      = google_pubsub_topic.default.name
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  role       = "roles/pubsub.publisher"
  depends_on = [google_pubsub_topic.default]
}

Cloud Run에 이벤트 수신자 배포

Cloud Run 서비스를 이벤트 대상으로 만들려면 google_cloud_run_v2_service Terraform 리소스를 사용합니다. 서비스 수준에서 서비스 계정에 Cloud Run 호출자 역할 (roles/run.invoker)을 부여하려면 google_cloud_run_v2_service_iam_member Terraform 리소스를 사용하세요.

# Deploy a Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "hello-events"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # This sample container listens to HTTP requests and logs received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

# Grant permission to invoke Cloud Run services
resource "google_cloud_run_v2_service_iam_member" "runinvoker" {
  project    = google_cloud_run_v2_service.default.project
  location   = google_cloud_run_v2_service.default.location
  name       = google_cloud_run_v2_service.default.name
  role       = "roles/run.invoker"
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  depends_on = [google_cloud_run_v2_service.default]
}

Eventarc 트리거 만들기

Pub/Sub 메시지를 리슨하는 Eventarc 트리거를 만들려면 google_eventarc_trigger Terraform 리소스를 사용하세요.

# Create an Eventarc trigger, routing Pub/Sub events to Cloud Run
resource "google_eventarc_trigger" "default" {
  name     = "trigger-pubsub-cloudrun-tf"
  location = google_cloud_run_v2_service.default.location

  # Capture messages published to a Pub/Sub topic
  matching_criteria {
    attribute = "type"
    value     = "google.cloud.pubsub.topic.v1.messagePublished"
  }

  # Send events to Cloud Run
  destination {
    cloud_run_service {
      service = google_cloud_run_v2_service.default.name
      region  = google_cloud_run_v2_service.default.location
    }
  }

  transport {
    pubsub {
      topic = google_pubsub_topic.default.id
    }
  }

  service_account = google_service_account.eventarc.email
  depends_on = [
    google_project_service.eventarc,
    google_pubsub_topic_iam_member.pubsubpublisher
  ]
}

Terraform 구성 적용

Terraform CLI를 사용하여 구성 파일을 기반으로 인프라를 프로비저닝합니다. 자세한 내용은 기본 Terraform 명령어를 참고하세요.

Terraform을 초기화합니다. 이 작업은 디렉터리당 한 번만 수행하면 됩니다.
```
terraform init
```
원하는 경우 최신 Google 공급업체 버전을 사용하려면 -upgrade 옵션을 포함합니다.
```
terraform init -upgrade
```
구성을 검토하고 Terraform에서 만들거나 업데이트할 리소스가 예상과 일치하는지 확인합니다.
```
terraform plan
```
필요에 따라 구성을 수정합니다.
다음 명령어를 실행하고 프롬프트에 yes를 입력하여 Terraform 구성을 적용합니다.
```
terraform apply
```
일반적으로 전체 구성을 한 번에 적용합니다. 하지만 특정 리소스를 타겟팅할 수도 있습니다. 예를 들면 다음과 같습니다.
```
terraform apply -target="google_eventarc_trigger.default"
```
API를 사용 설정한 후 작업이 전파되고 추가 리소스를 배포할 수 있기까지 몇 분 정도 걸릴 수 있습니다. 문제가 발생하면 Terraform 구성을 다시 적용해 보세요.

Terraform에 '적용 완료' 메시지가 표시될 때까지 기다립니다.

리소스 생성 확인

Cloud Run 서비스가 생성되었는지 확인합니다.

gcloud run services list --region us-central1

출력은 다음과 비슷하게 표시됩니다.

SERVICE: hello-events
REGION: us-central1
URL: https://hello-events-13335919645.us-central1.run.app
LAST DEPLOYED BY: ...
LAST DEPLOYED AT: 2024-12-16T15:00:52.606160Z

Eventarc 트리거가 생성되었는지 확인합니다.

gcloud eventarc triggers list --location us-central1

출력은 다음과 비슷하게 표시됩니다.

NAME: trigger-pubsub-cloudrun-tf
TYPE: google.cloud.pubsub.topic.v1.messagePublished
DESTINATION: Cloud Run service: hello-events
ACTIVE: Yes
LOCATION: us-central1

Pub/Sub 주제 이벤트 생성 및 확인

메시지를 Pub/Sub 주제에 게시하면 이벤트를 생성할 수 있습니다. Eventarc 트리거는 메시지를 Cloud Run에 배포된 이벤트 수신자 서비스로 라우팅하고 서비스는 이벤트 메시지를 로깅합니다.

Pub/Sub 주제를 환경 변수로 찾아서 설정합니다.

gcloud config set eventarc/location us-central1
export RUN_TOPIC=$(gcloud eventarc triggers describe trigger-pubsub-cloudrun-tf \
    --format='value(transport.pubsub.topic)')

이벤트를 생성하려면 Pub/Sub 주제에 메시지를 게시하세요.
```
gcloud pubsub topics publish $RUN_TOPIC --message "Hello World!"
```
이벤트는 Cloud Run 서비스로 라우팅되어 이벤트 메시지를 로깅합니다.

서비스에서 만든 로그 항목을 필터링합니다.

gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.pubsub.topic.v1.messagePublished"'

다음과 같은 로그 항목을 찾습니다.
```
jsonPayload:
...
message: 'Received event of type google.cloud.pubsub.topic.v1.messagePublished.
    Event data: Hello World!'
```
참고: 로그 항목이 표시되지 않으면 몇 분 정도 기다린 후 gcloud logging read 명령어를 다시 시도합니다.

Terraform을 사용하여 Cloud Run에 이벤트 수신자 서비스를 배포하고 Eventarc 트리거를 만들었습니다. Pub/Sub에서 이벤트를 생성하면 Cloud Run 로그에서 이벤트를 볼 수 있습니다.

삭제

이 빠른 시작에 설명된 태스크를 완료했으면 만든 리소스를 삭제하여 청구가 계속되는 것을 방지할 수 있습니다.

다음 명령어를 실행하고 프롬프트에 yes를 입력하여 이전에 Terraform 구성에 적용된 리소스를 삭제합니다.

terraform destroy

또는 Google Cloud 프로젝트를 삭제하여 비용 청구를 방지할 수 있습니다. Google Cloud 프로젝트를 삭제하면 해당 프로젝트 내에서 사용되는 모든 리소스에 대한 청구가 중단됩니다.

Google Cloud 프로젝트를 삭제합니다.

gcloud projects delete PROJECT_ID

여러 튜토리얼과 빠른 시작을 살펴보려는 경우 프로젝트를 재사용하면 프로젝트 할당량 한도 초과를 방지할 수 있습니다.

Pub/Sub 메시지를 사용하여 이벤트 수신(Terraform)

시작하기 전에

필수 권한

Terraform 배포 준비

Terraform 구성 정의

API 사용 설정

서비스 계정 만들기

Pub/Sub 주제를 이벤트 제공자로 만들기

Cloud Run에 이벤트 수신자 배포

Eventarc 트리거 만들기

Terraform 구성 적용

리소스 생성 확인

Pub/Sub 주제 이벤트 생성 및 확인

삭제

다음 단계