이 튜토리얼에서는 Cloud Run 서비스를 작성, 배포하고 Pub/Sub 푸시 구독으로부터 호출하는 방법을 보여줍니다.
목표
- Cloud Run에 서비스 작성, 빌드, 배포
- Pub/Sub 주제에 메시지를 게시하여 서비스 호출
비용
이 문서에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.
프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요.
시작하기 전에
- Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Enable the Artifact Registry, Cloud Build, Pub/Sub and Cloud Run APIs.
- gcloud CLI를 설치하고 초기화합니다.
- 구성요소를 업데이트합니다.
gcloud components update
필요한 역할
튜토리얼을 완료하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
Cloud Build 편집자(
roles/cloudbuild.builds.editor
) -
Cloud Run 관리자(
roles/run.admin
) -
서비스 계정 만들기(
roles/iam.serviceAccountCreator
) -
프로젝트 IAM 관리자(
roles/resourcemanager.projectIamAdmin
) -
Pub/Sub 편집자(
roles/pubsub.editor
) -
서비스 계정 사용자(
roles/iam.serviceAccountUser
) -
서비스 사용량 소비자(
roles/serviceusage.serviceUsageConsumer
) -
스토리지 관리자(
roles/storage.admin
)
역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.
gcloud 기본값 설정
Cloud Run 서비스의 기본값으로 gcloud를 구성하려면 다음 안내를 따르세요.
기본 프로젝트를 설정합니다.
gcloud config set project PROJECT_ID
PROJECT_ID를 이 튜토리얼용으로 만든 프로젝트 이름으로 바꿉니다.
선택한 리전에 맞게 gcloud를 구성합니다.
gcloud config set run/region REGION
REGION을 지원되는 Cloud Run 리전 중 원하는 리전으로 바꿉니다.
Cloud Run 위치
Cloud Run은 리전을 기반으로 합니다. 즉, Cloud Run 서비스를 실행하는 인프라가 특정 리전에 위치해 있으며 해당 리전 내의 모든 영역에서 중복으로 사용할 수 있도록 Google이 관리합니다.
Cloud Run 서비스를 실행하는 리전을 선택하는 데 있어 중요한 기준은 지연 시간, 가용성 또는 내구성 요구사항입니다.
일반적으로 사용자와 가장 가까운 리전을 선택할 수 있지만 Cloud Run 서비스에서 사용하는 다른 Google Cloud 제품 위치도 고려해야 합니다.
여러 위치에서 Google Cloud 제품을 함께 사용하면 서비스 지연 시간과 비용에 영향을 미칠 수 있습니다.
Cloud Run은 다음 리전에서 사용할 수 있습니다.
등급 1 가격 적용
asia-east1
(타이완)asia-northeast1
(도쿄)asia-northeast2
(오사카)europe-north1
(핀란드) 낮은 CO2europe-southwest1
(마드리드)europe-west1
(벨기에) 낮은 CO2europe-west4
(네덜란드)europe-west8
(밀라노)europe-west9
(파리) 낮은 CO2me-west1
(텔아비브)us-central1
(아이오와) 낮은 CO2us-east1
(사우스캐롤라이나)us-east4
(북 버지니아)us-east5
(콜럼버스)us-south1
(댈러스)us-west1
(오리건) 낮은 CO2
등급 2 가격 적용
africa-south1
(요하네스버그)asia-east2
(홍콩)asia-northeast3
(대한민국 서울)asia-southeast1
(싱가포르)asia-southeast2
(자카르타)asia-south1
(인도 뭄바이)asia-south2
(인도 델리)australia-southeast1
(시드니)australia-southeast2
(멜버른)europe-central2
(폴란드 바르샤바)europe-west10
(베를린)europe-west12
(토리노)europe-west2
(영국 런던) 낮은 CO2europe-west3
(독일 프랑크푸르트) 낮은 CO2europe-west6
(스위스 취리히) 낮은 CO2me-central1
(도하)me-central2
(담맘)northamerica-northeast1
(몬트리올) 낮은 CO2northamerica-northeast2
(토론토) 낮은 CO2southamerica-east1
(브라질 상파울루) 낮은 CO2southamerica-west1
(칠레 산티아고) 낮은 CO2us-west2
(로스앤젤레스)us-west3
(솔트레이크시티)us-west4
(라스베이거스)
Cloud Run 서비스를 이미 만들었다면 Google Cloud 콘솔의 Cloud Run 대시보드에서 리전을 확인할 수 있습니다.
Artifact Registry 표준 저장소 만들기
컨테이너 이미지를 저장할 Artifact Registry 표준 저장소를 만듭니다.
gcloud artifacts repositories create REPOSITORY \ --repository-format=docker \ --location=REGION
다음과 같이 바꿉니다.
- REPOSITORY를 저장소의 고유한 이름으로 바꿉니다.
- REGION: Artifact Registry 저장소에 사용할 Google Cloud 리전
Pub/Sub 주제 만들기
샘플 서비스가 Pub/Sub 주제에 게시된 메시지로 트리거되므로, Pub/Sub에 주제를 만들어야 합니다.
gcloud
새 Pub/Sub 주제를 만들려면 다음 명령어를 사용합니다.
gcloud pubsub topics create myRunTopic
myRunTopic을 사용하거나 Google Cloud 프로젝트 내에 고유한 주제 이름으로 바꿀 수 있습니다.
Terraform
Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요.
Pub/Sub 주제를 만들려면 기존 main.tf
파일에 다음을 추가합니다.
클라우드 프로젝트 내에서 고유한 주제 이름을 사용할 수 있습니다.
코드 샘플 검색
사용할 코드 샘플을 검색하려면 다음 안내를 따르세요.
샘플 앱 저장소를 로컬 머신에 클론합니다.
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.
자바
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.
C#
git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.
Cloud Run 샘플 코드가 포함된 디렉터리로 변경합니다.
Node.js
cd nodejs-docs-samples/run/pubsub/
Python
cd python-docs-samples/run/pubsub/
Go
cd golang-samples/run/pubsub/
Java
cd java-docs-samples/run/pubsub/
C#
cd dotnet-docs-samples/run/pubsub/
코드 검토
이 튜토리얼의 코드는 다음과 같이 구성됩니다.
새로 추가되는 요청을 처리하는 서버
Node.js
Node.js 서비스를 쉽게 테스트할 수 있도록 서버 구성이 서버 시작과 구분됩니다.
Node.js 웹 서버가
app.js
에 설정됩니다.웹 서버가
index.js
에서 시작됩니다.Python
Go
Java
C#
Pub/Sub 메시지를 처리하고 인사말을 로깅하는 핸들러입니다.
Node.js
Python
Go
Java
C#
정확한 HTTP 응답 코드를 반환하도록 서비스를 코딩해야 합니다. HTTP
200
또는204
와 같은 성공 코드는 Pub/Sub 메시지 처리가 완료되었음을 나타냅니다. HTTP400
또는500
과 같은 오류 코드는 푸시를 사용하여 메시지 수신 가이드에 설명된 것처럼 메시지가 재시도됨을 나타냅니다.서비스의 작동 환경을 정의하는
Dockerfile
입니다.Dockerfile
콘텐츠는 언어별로 다릅니다.Node.js
Python
Go
Java
이 샘플은 Jib를 사용해서 일반적인 Java 도구로 Docker 이미지를 빌드합니다. Jib는 Dockerfile을 사용하거나 Docker를 설치할 필요 없이 컨테이너 빌드를 최적화합니다. Jib로 자바 컨테이너 빌드에 대해 자세히 알아보세요.
C#
Pub/Sub 요청 원본을 인증하는 방법은 Pub/Sub와 통합을 참조하세요.
코드 제공
코드 제공은 Cloud Build로 컨테이너 이미지를 빌드하고, Artifact Registry에 컨테이너 이미지를 업로드하고, 컨테이너 이미지를 Cloud Run에 배포하는 세 단계로 구성됩니다.
코드를 제공하려면 다음 안내를 따르세요.
-
컨테이너를 빌드하고 Artifact Registry에 게시합니다.
Node.js
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub
다음과 같이 바꿉니다.- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
- REPOSITORY를 Artifact Registry 저장소 이름으로 바꿉니다.
- REGION: Artifact Registry 저장소에 사용할 Google Cloud 리전
pubsub
는 이미지 이름입니다.성공하면 ID, 생성 시간, 이미지 이름이 포함된 SUCCESS 메시지가 표시됩니다. 이미지는 Artifact Registry에 저장되며 필요한 경우 다시 사용될 수 있습니다.
Python
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub
다음과 같이 바꿉니다.- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
- REPOSITORY를 Artifact Registry 저장소 이름으로 바꿉니다.
- REGION: Artifact Registry 저장소에 사용할 Google Cloud 리전
pubsub
는 이미지 이름입니다.성공하면 ID, 생성 시간, 이미지 이름이 포함된 SUCCESS 메시지가 표시됩니다. 이미지는 Artifact Registry에 저장되며 필요한 경우 다시 사용될 수 있습니다.
Go
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub
다음과 같이 바꿉니다.- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
- REPOSITORY를 Artifact Registry 저장소 이름으로 바꿉니다.
- REGION: Artifact Registry 저장소에 사용할 Google Cloud 리전
pubsub
는 이미지 이름입니다.성공하면 ID, 생성 시간, 이미지 이름이 포함된 성공 메시지가 표시됩니다. 이미지는 Artifact Registry에 저장되며 필요한 경우 다시 사용될 수 있습니다.
Java
- gcloud CLI 사용자 인증 정보 도우미를 사용하여 Docker가 Artifact Registry로 내보내도록 승인합니다.
gcloud auth configure-docker
-
Jib Maven 플러그인을 사용하여 컨테이너를 빌드하고 Artifact Registry로 내보냅니다.
mvn compile jib:build -D image=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub
다음과 같이 바꿉니다.- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
- REPOSITORY를 Artifact Registry 저장소 이름으로 바꿉니다.
- REGION: Artifact Registry 저장소에 사용할 Google Cloud 리전
pubsub
는 이미지 이름입니다.성공하면 BUILD SUCCESS 메시지가 표시됩니다. 이미지는 Artifact Registry에 저장되며 필요한 경우 다시 사용될 수 있습니다.
C#
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub
다음과 같이 바꿉니다.- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
- REPOSITORY를 Artifact Registry 저장소 이름으로 바꿉니다.
- REGION: Artifact Registry 저장소에 사용할 Google Cloud 리전
pubsub
는 이미지 이름입니다.성공하면 ID, 생성 시간, 이미지 이름이 포함된 성공 메시지가 표시됩니다. 이미지는 Artifact Registry에 저장되며 필요한 경우 다시 사용될 수 있습니다.
-
애플리케이션 배포
명령줄
-
다음 명령어를 실행하여 앱을 배포합니다.
gcloud run deploy pubsub-tutorial --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub --no-allow-unauthenticated
다음과 같이 바꿉니다.- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
- REPOSITORY를 Artifact Registry 저장소 이름으로 바꿉니다.
- REGION: Artifact Registry 저장소에 사용할 Google Cloud 리전
pubsub
는 이미지 이름이고pubsub-tutorial
은 서비스 이름입니다. 컨테이너 이미지는 이전에 gcloud 설정에서 구성한 서비스 및 리전에 배포됩니다.--no-allow-unauthenticated
플래그는 서비스에 대해 인증되지 않은 액세스를 제한합니다. 서비스를 비공개로 유지하면 Cloud Run의 자동 Pub/Sub 통합을 사용해 요청을 인증할 수 있습니다. 구성 방법에 대한 자세한 내용은 Pub/Sub와 통합을 참조하세요. Identity and Access Management(IAM)를 기반으로 한 인증에 대한 자세한 내용은 IAM을 사용하여 액세스 관리를 참조하세요.배포가 완료될 때까지 기다립니다. 이 작업은 30초 정도 걸릴 수 있습니다. 성공하면 명령줄에 서비스 URL이 표시됩니다. 이 URL은 Pub/Sub 구독을 구성하는 데 사용됩니다.
-
서비스에 코드 업데이트를 배포하려면 이전 단계를 반복합니다. 서비스에 배포할 때마다 새 버전이 생성되고 준비가 되면 자동으로 트래픽 제공이 시작됩니다.
Terraform
Cloud Run 서비스를 만들려면 다음을 기존
.tf
파일에 추가합니다.image
값을 이미지 URL(REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub
)로 바꿉니다. -
Pub/Sub와 통합
Pub/Sub와 서비스를 통합하려면 다음 안내를 따르세요.
gcloud
서비스 계정을 만들거나 선택하여 Pub/Sub 구독 ID를 나타냅니다.
gcloud iam service-accounts create cloud-run-pubsub-invoker \ --display-name "Cloud Run Pub/Sub Invoker"
cloud-run-pubsub-invoker
를 사용하거나 Google Cloud 프로젝트 내에서 고유한 이름으로 바꿀 수 있습니다.서비스 계정으로 Pub/Sub 구독을 만듭니다.
호출자 서비스 계정에
pubsub-tutorial
서비스 호출 권한을 부여합니다.gcloud run services add-iam-policy-binding pubsub-tutorial \ --member=serviceAccount:cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/run.invoker
IAM 변경사항을 적용하는 데 몇 분 정도 걸릴 수 있습니다. 그동안 서비스 로그에
HTTP 403
오류가 발생할 수 있습니다.프로젝트에서 인증 토큰을 만들도록 Pub/Sub를 허용합니다.
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator
다음과 같이 바꿉니다.
- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
- PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다.
프로젝트 ID 및 프로젝트 번호는 Google Cloud 콘솔에서 프로젝트의 프로젝트 정보 패널에 나열됩니다.
서비스 계정으로 Pub/Sub 구독을 만듭니다.
gcloud pubsub subscriptions create myRunSubscription --topic myRunTopic \ --ack-deadline=600 \ --push-endpoint=SERVICE-URL/ \ --push-auth-service-account=cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com
다음과 같이 바꿉니다.
- myRunTopic을 이전에 만든 주제로 바꿉니다.
- SERVICE-URL을 서비스 배포 시 제공된 HTTPS URL로 바꿉니다. 이 URL은 도메인 매핑이 추가된 경우에도 작동합니다.
- PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
--push-auth-service-account
플래그는 인증 및 승인을 위한 Pub/Sub 푸시 기능을 활성화합니다.Cloud Run 서비스 도메인은 Pub/Sub 구독에 사용할 수 있도록 자동으로 등록됩니다.
Cloud Run 전용의 경우, 토큰이 유효한지 확인하는 기본 제공되는 인증 검사와 서비스 계정에 Cloud Run 서비스 호출 권한이 있는지 확인하는 승인 검사가 있습니다.
이제 서비스가 Pub/Sub와 완전히 통합되었습니다.
Terraform
서비스 계정을 만들거나 선택하여 Pub/Sub 구독 ID를 나타냅니다.
서비스 계정으로 Pub/Sub 구독을 만듭니다.
호출자 서비스 계정에
pubsub-tutorial
서비스 호출 권한을 부여합니다.프로젝트에서 인증 토큰을 만들도록 Pub/Sub를 허용합니다.
서비스 계정으로 Pub/Sub 구독을 만듭니다.
이제 서비스가 Pub/Sub와 완전히 통합되었습니다.
사용해 보기
엔드 투 엔드 솔루션을 테스트하려면 다음 안내를 따르세요.
주제에 Pub/Sub 메시지를 전송합니다.
gcloud pubsub topics publish myRunTopic --message "Runner"
또한 이 튜토리얼에 표시된 것처럼 명령줄을 사용하는 대신 프로그래매틱 방식으로 메시지를 게시할 수도 있습니다. 자세한 내용은 메시지 게시를 참조하세요.
서비스 로그로 이동합니다.
- Google Cloud 콘솔로 이동합니다.
pubsub-tutorial
서비스를 클릭합니다.로그 탭을 선택합니다.
로그가 나타나려면 시간이 약간 걸릴 수 있습니다. 즉시 표시되지 않으면 잠시 후 다시 확인하세요.
'Hello Runner!' 메시지를 찾습니다.
삭제
Pub/Sub에서 Cloud Run을 사용하는 보다 세부적인 심화 사용 사례를 연습하려면 지금 삭제 단계를 건너뛰고 계속해서 Cloud Run으로 이미지 처리 튜토리얼을 진행하세요.
이 튜토리얼용으로 새 프로젝트를 만든 경우 이 프로젝트를 삭제합니다. 기존 프로젝트를 사용한 경우 이 튜토리얼에 추가된 변경사항은 제외하고 보존하려면 튜토리얼용으로 만든 리소스를 삭제합니다.
프로젝트 삭제
비용이 청구되지 않도록 하는 가장 쉬운 방법은 튜토리얼에서 만든 프로젝트를 삭제하는 것입니다.
프로젝트를 삭제하려면 다음 안내를 따르세요.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
튜토리얼 리소스 삭제
이 튜토리얼에서 배포한 Cloud Run 서비스를 삭제합니다.
gcloud run services delete SERVICE-NAME
여기서 SERVICE-NAME은 선택한 서비스 이름입니다.
Google Cloud 콘솔에서 Cloud Run 서비스를 삭제할 수도 있습니다.
튜토리얼 설정 중에 추가한 gcloud 기본 리전 구성을 삭제합니다.
gcloud config unset run/region
프로젝트 구성을 삭제합니다.
gcloud config unset project
이 튜토리얼에서 만든 다른 Google Cloud 리소스를 삭제합니다.
- Pub/Sub 주제
myRunTopic
을 삭제합니다. - Pub/Sub 구독
myRunSubscription
을 삭제합니다. - Artifact Registry에서 가져온
REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/pubsub
라는 컨테이너 이미지를 삭제합니다. - 호출자 서비스 계정
cloud-run-pubsub-invoker@PROJECT_ID.iam.gserviceaccount.com
삭제
- Pub/Sub 주제
다음 단계
- 내부 인그레스 제어를 사용해 인그레스를 제한하여 프로덕션 보안을 강화하는 방법에 대한 자세한 내용은 인그레스 제한을 참조하세요.
- 이 튜토리얼에서 배포된 샘플 서비스를 확장하여 Cloud Storage에 업로드된 이미지를 수정하는 이미지 처리 기능을 추가하세요.
- Pub/Sub 아키텍처에 주제가 포함되는 방법 및 주제 관리 방법을 자세히 알아보세요.
- 구독 관리에서 Pub/Sub 구독에 대해 자세히 알아보세요.
- Google Cloud에 대한 참조 아키텍처, 다이어그램, 권장사항을 살펴보세요. Cloud 아키텍처 센터를 살펴보세요.