튜토리얼: Google Cloud Run 컴포넌트로 웹 서비스 생성 및 배포

요약

Artifact Registry에 저장된 컨테이너 이미지에서 웹 서비스를 배포하기 위해 Google Cloud Run 컴포넌트를 사용하는 방법을 알아봅니다. Google Cloud 통합 설정의 지침을 따라 다음을 수행합니다:

Artifact Registry에 저장된 컨테이너 이미지에서 웹 서비스를 배포하기 위해 Google Cloud Run 컴포넌트를 사용하는 방법을 알아봅니다.

시작하기 전에#

Google Cloud 통합 설정의 지침을 따라 다음을 수행합니다:
- Google Cloud IAM 설정.
- GitLab을 Google Artifact Registry에 연결.
- Google Cloud에서 CI/CD 작업을 실행하도록 GitLab Runner 설정.
이 페이지의 명령을 실행하려면 다음 개발 환경 중 하나에서 gcloud CLI를 설정합니다:
- Cloud Shell
- 로컬 shell
다음 명령을 실행하여 기본 Google Cloud 프로젝트를 설정합니다:
```
gcloud config set project PROJECT_ID
```
기본 프로젝트를 설정한 후에는 gcloud 명령에 --project 플래그를 전달할 필요가 없습니다.

Compute Engine 및 Cloud Run API를 활성화합니다:

gcloud services enable compute.googleapis.com artifactregistry.googleapis.com run.googleapis.com

워크로드 아이덴티티 풀에 다음 역할을 부여합니다:

Cloud Storage Admin(roles/run.admin) - 서비스를 가져오고, 만들고, 업데이트.
Service Account users(roles/iam.serviceAccountUser) - 서비스 계정으로 작업 실행.

다음 명령을 실행하여 developer_access=true 속성 매핑과 일치하는 워크로드 아이덴티티 풀의 모든 주체에 roles/run.admin 및 roles/iam.serviceAccountUser 역할을 부여합니다:

# Replace ${PROJECT_ID}, ${PROJECT_NUMBER}, ${LOCATION}, ${POOL_ID} with your values below
WORKLOAD_IDENTITY=principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/attribute.developer_access/true
gcloud projects add-iam-policy-binding ${PROJECT_ID} --member="${WORKLOAD_IDENTITY}" --role="roles/run.admin"
gcloud projects add-iam-policy-binding ${PROJECT_ID} --member="${WORKLOAD_IDENTITY}" --role="roles/iam.serviceAccountUser"

새 GitLab 프로젝트에서 IAM 통합 구성#

조직 또는 그룹에 대한 Google IAM 통합을 설정한 후에는 해당 조직 또는 그룹의 새 프로젝트에서 통합을 재사용할 수 있습니다:

조직 또는 그룹에 새 GitLab 프로젝트를 만듭니다.
GitLab 프로젝트에서 Settings > Integrations를 선택합니다.
Google Cloud IAM을 선택합니다.
Google Cloud project 섹션에서 다음을 입력합니다:
- Project ID: 워크로드 아이덴티티 풀의 Google Cloud 프로젝트 ID
- Project number: 동일 프로젝트의 Google Cloud 프로젝트 번호
Google Cloud 프로젝트 ID와 번호를 찾으려면 프로젝트 식별을 참조하세요.
Workload identity federation 섹션에서 다음을 입력합니다:
- Pool ID: 워크로드 아이덴티티 풀에 지정한 이름.
- Provider ID: OIDC 공급자에 지정한 이름.
힌트: 통합을 설정하는 데 원래 사용한 GitLab 프로젝트에서 이 값을 복사할 수 있습니다.
Save changes를 선택합니다. 워크로드 아이덴티티 풀을 이미 가지고 있으므로 제공된 스크립트를 실행하지 마세요.

새 GitLab 프로젝트에서 Google Artifact Registry 통합 구성#

Artifact Registry에 여러 컨테이너 이미지를 저장할 수 있습니다. 새 GitLab 프로젝트에 동일한 저장소를 재사용하려면 프로젝트에서 Google Artifact Management 통합을 구성합니다.

GitLab 프로젝트에서 Settings > Integrations를 선택합니다.
Google Artifact Management를 선택합니다.
Repository 섹션에서 다음을 입력합니다:
- Google Cloud project ID: 사용하려는 Artifact Registry 저장소의 프로젝트 ID
- Repository name: 저장소 이름
- Repository location: 저장소 위치
Save changes를 선택합니다. 워크로드 아이덴티티 풀이 이미 그룹 또는 조직의 GitLab 사용자에게 Artifact Registry Reader 및 Writer 역할을 부여하므로 제공된 스크립트를 실행하지 마세요.

GitLab 저장소 복제#

SSH 또는 HTTPS를 사용하여 GitLab 저장소를 작업 환경에 복제하려면 로컬 컴퓨터에 Git 저장소 복제의 지침을 따릅니다.

Dockerfile 만들기#

복제된 저장소에서 Dockerfile이라는 새 파일을 만듭니다.

다음 내용을 Dockerfile에 복사하여 붙여넣습니다:

FROM python:3.12.4

ARG name

RUN mkdir web

RUN cat < web/index.html
<!DOCTYPE html>
<html>
    <head>
        <title>Home</title>
    </head>
    <body>
        <h1 color="green">Welcome to $name</h1>
    </body>
</html>
EOF

CMD ["python3", "-m", "http.server", "8080", "-d", "web"]

Dockerfile을 Git에 추가하고, 커밋한 후 GitLab 저장소에 푸시합니다:
```
git add Dockerfile
git commit -m "add dockerfile"
git push
```
사용자 이름과 개인 액세스 토큰을 입력하라는 메시지가 표시됩니다.

Dockerfile은 HTTP 웹 서비스를 만듭니다.

파이프라인 만들기#

Docker 이미지를 빌드하고, GitLab 컨테이너 레지스트리에 푸시하고, 이미지를 Google Artifact Registry에 복사하고, Cloud Run을 사용하여 Google Cloud 인프라에 배포하는 파이프라인을 만듭니다.

GitLab 프로젝트에서 .gitlab-ci.yml 파일을 만듭니다.

이미지를 빌드하고, GitLab 컨테이너 레지스트리에 푸시하고, Google Artifact Registry에 복사하고, Cloud Run을 사용하여 배포하는 파이프라인을 만들려면 다음과 유사하게 .gitlab-ci.yml 파일의 내용을 수정합니다.

다음 예제에서 다음 항목을 교체합니다:

LOCATION: Google Artifact Registry 저장소를 만든 Google Cloud 지역.
PROJECT: Artifact Registry 저장소의 Google Cloud 프로젝트 ID.
REPOSITORY: Google Artifact Registry 저장소의 저장소 ID.

variables:
  IMAGE_TAG: v$CI_PIPELINE_ID
  AR_IMAGE: LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/python-service

stages:
  - build
  - push
  - deploy

build-job:
  stage: build
  services:
    - docker:24.0.5-dind
  image: docker:git
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$IMAGE_TAG --build-arg="name=Cloud Run" .
    - docker push $CI_REGISTRY_IMAGE:$IMAGE_TAG

include:
  - component: gitlab.com/google-gitlab-components/artifact-registry/upload-artifact-registry@0.1.0
    inputs:
      stage: push
      source: $CI_REGISTRY_IMAGE:$IMAGE_TAG
      target: $AR_IMAGE:$IMAGE_TAG

  - component: gitlab.com/google-gitlab-components/cloud-run/deploy-cloud-run@0.1.0
    inputs:
      stage: deploy
      image: $AR_IMAGE:$IMAGE_TAG
      project_id: PROJECT
      region: LOCATION
      service: python-service

.gitlab-ci.yml 파일을 Git에 추가하고, 커밋한 후 GitLab 저장소에 푸시합니다.

파이프라인은 다음을 완료합니다:

Docker-in-Docker로 이미지 python-service 빌드.
GitLab 컨테이너 레지스트리에 이미지 저장.
Google Artifact Registry GitLab 컴포넌트를 사용하여 Google Artifact Registry에 이미지 푸시.
Google Cloud Run 컴포넌트로 python-service 배포.

Google Cloud Run에서 서비스 보기#

Google Cloud Console에서 Cloud Run 페이지로 이동합니다.
Services 탭에서 만든 서비스를 선택합니다.

서비스 Metrics 탭이 표시되며 서비스 지역, URL 및 기타 세부 정보를 볼 수 있습니다.

서비스를 프록시하여 보기#

서비스는 비공개이므로 인증 없이 Google Cloud Console에 나열된 URL에서 볼 수 없습니다. 서비스를 테스트하려면 gcloud CLI를 사용하여 인증하고 서비스를 http://localhost:8080으로 프록시할 수 있습니다.

다음 명령을 실행하여 서비스를 로컬로 프록시합니다:

gcloud run services proxy SERVICE \
    --project PROJECT_ID \
    --region=LOCATION

http://localhost:8080에서 환영 페이지를 볼 수 있습니다.

정리#

이 페이지에서 사용한 리소스에 대한 Google Cloud 계정 비용이 발생하지 않도록 Google Cloud 리소스 또는 전체 Google Cloud 프로젝트를 삭제할 수 있습니다.

워크로드 아이덴티티 풀이 포함된 프로젝트를 삭제하면 설정 지침을 모두 다시 따르지 않는 한 통합을 사용할 수 없습니다.

GitLab 및 Google 가격 책정과 프로젝트 관리에 대한 자세한 내용은 다음 리소스를 참조하세요:

Google Artifact Registry 저장소 삭제#

Google Artifact Registry 저장소를 삭제하려면 이 섹션의 단계를 따릅니다. 전체 Google Cloud 프로젝트를 삭제하려면 프로젝트 삭제의 단계를 따릅니다.

저장소를 제거하기 전에 보존하려는 이미지가 다른 위치에서 사용 가능한지 확인합니다.

저장소를 삭제하려면 다음 명령을 실행합니다:

gcloud artifacts repositories delete REPOSITORY \
    --location=LOCATION

다음 항목을 교체합니다:

REPOSITORY를 Google Artifact Registry 저장소 ID로
LOCATION을 저장소 위치로

Cloud Run 서비스 삭제#

Google Cloud Console에서 Cloud Run 페이지로 이동합니다.
서비스 옆의 확인란을 선택합니다.
Delete를 선택합니다.

Google Cloud 프로젝트 삭제#

주의: 프로젝트 삭제는 다음과 같은 영향을 미칩니다:

프로젝트의 모든 것이 삭제됩니다. 이 문서의 작업에 기존 프로젝트를 사용한 경우 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
사용자 정의 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 나중에 사용하려는 사용자 정의 프로젝트 ID를 만들었을 수 있습니다. appspot.com URL과 같은 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내의 선택한 리소스를 삭제합니다.

Google Cloud에서 여러 아키텍처, 튜토리얼 또는 빠른 시작 튜토리얼을 탐색할 계획이라면 프로젝트를 재사용하면 프로젝트 할당량 한도를 초과하지 않도록 도움이 됩니다.

Google Cloud 콘솔에서 Manage resources 페이지로 이동합니다.
프로젝트 목록에서 삭제하려는 프로젝트를 선택한 다음 Delete를 선택합니다.
대화 상자에서 프로젝트 ID를 입력한 다음 Shut down을 선택하여 프로젝트를 삭제합니다.

튜토리얼: Google Cloud Run 컴포넌트로 웹 서비스 생성 및 배포

원문 보기

번역일: 2026-05-22

요약

Artifact Registry에 저장된 컨테이너 이미지에서 웹 서비스를 배포하기 위해 Google Cloud Run 컴포넌트를 사용하는 방법을 알아봅니다.

시작하기 전에#

Google Cloud 통합 설정의 지침을 따라 다음을 수행합니다:
- Google Cloud IAM 설정.
- GitLab을 Google Artifact Registry에 연결.
- Google Cloud에서 CI/CD 작업을 실행하도록 GitLab Runner 설정.
이 페이지의 명령을 실행하려면 다음 개발 환경 중 하나에서 gcloud CLI를 설정합니다:
- Cloud Shell
- 로컬 shell
다음 명령을 실행하여 기본 Google Cloud 프로젝트를 설정합니다:
```
gcloud config set project PROJECT_ID
```
기본 프로젝트를 설정한 후에는 gcloud 명령에 --project 플래그를 전달할 필요가 없습니다.

Compute Engine 및 Cloud Run API를 활성화합니다:

gcloud services enable compute.googleapis.com artifactregistry.googleapis.com run.googleapis.com

워크로드 아이덴티티 풀에 다음 역할을 부여합니다:

Cloud Storage Admin(roles/run.admin) - 서비스를 가져오고, 만들고, 업데이트.
Service Account users(roles/iam.serviceAccountUser) - 서비스 계정으로 작업 실행.

# Replace ${PROJECT_ID}, ${PROJECT_NUMBER}, ${LOCATION}, ${POOL_ID} with your values below
WORKLOAD_IDENTITY=principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/attribute.developer_access/true
gcloud projects add-iam-policy-binding ${PROJECT_ID} --member="${WORKLOAD_IDENTITY}" --role="roles/run.admin"
gcloud projects add-iam-policy-binding ${PROJECT_ID} --member="${WORKLOAD_IDENTITY}" --role="roles/iam.serviceAccountUser"

새 GitLab 프로젝트에서 IAM 통합 구성#

조직 또는 그룹에 대한 Google IAM 통합을 설정한 후에는 해당 조직 또는 그룹의 새 프로젝트에서 통합을 재사용할 수 있습니다:

조직 또는 그룹에 새 GitLab 프로젝트를 만듭니다.
GitLab 프로젝트에서 Settings > Integrations를 선택합니다.
Google Cloud IAM을 선택합니다.
Google Cloud project 섹션에서 다음을 입력합니다:
- Project ID: 워크로드 아이덴티티 풀의 Google Cloud 프로젝트 ID
- Project number: 동일 프로젝트의 Google Cloud 프로젝트 번호
Google Cloud 프로젝트 ID와 번호를 찾으려면 프로젝트 식별을 참조하세요.
Workload identity federation 섹션에서 다음을 입력합니다:
- Pool ID: 워크로드 아이덴티티 풀에 지정한 이름.
- Provider ID: OIDC 공급자에 지정한 이름.
힌트: 통합을 설정하는 데 원래 사용한 GitLab 프로젝트에서 이 값을 복사할 수 있습니다.
Save changes를 선택합니다. 워크로드 아이덴티티 풀을 이미 가지고 있으므로 제공된 스크립트를 실행하지 마세요.

새 GitLab 프로젝트에서 Google Artifact Registry 통합 구성#

GitLab 프로젝트에서 Settings > Integrations를 선택합니다.
Google Artifact Management를 선택합니다.
Repository 섹션에서 다음을 입력합니다:
- Google Cloud project ID: 사용하려는 Artifact Registry 저장소의 프로젝트 ID
- Repository name: 저장소 이름
- Repository location: 저장소 위치
Save changes를 선택합니다. 워크로드 아이덴티티 풀이 이미 그룹 또는 조직의 GitLab 사용자에게 Artifact Registry Reader 및 Writer 역할을 부여하므로 제공된 스크립트를 실행하지 마세요.

GitLab 저장소 복제#

SSH 또는 HTTPS를 사용하여 GitLab 저장소를 작업 환경에 복제하려면 로컬 컴퓨터에 Git 저장소 복제의 지침을 따릅니다.

Dockerfile 만들기#

복제된 저장소에서 Dockerfile이라는 새 파일을 만듭니다.

다음 내용을 Dockerfile에 복사하여 붙여넣습니다:

FROM python:3.12.4

ARG name

RUN mkdir web

RUN cat < web/index.html
<!DOCTYPE html>
<html>
    <head>
        <title>Home</title>
    </head>
    <body>
        <h1 color="green">Welcome to $name</h1>
    </body>
</html>
EOF

CMD ["python3", "-m", "http.server", "8080", "-d", "web"]

Dockerfile을 Git에 추가하고, 커밋한 후 GitLab 저장소에 푸시합니다:
```
git add Dockerfile
git commit -m "add dockerfile"
git push
```
사용자 이름과 개인 액세스 토큰을 입력하라는 메시지가 표시됩니다.

Dockerfile은 HTTP 웹 서비스를 만듭니다.

파이프라인 만들기#

GitLab 프로젝트에서 .gitlab-ci.yml 파일을 만듭니다.

다음 예제에서 다음 항목을 교체합니다:

LOCATION: Google Artifact Registry 저장소를 만든 Google Cloud 지역.
PROJECT: Artifact Registry 저장소의 Google Cloud 프로젝트 ID.
REPOSITORY: Google Artifact Registry 저장소의 저장소 ID.

variables:
  IMAGE_TAG: v$CI_PIPELINE_ID
  AR_IMAGE: LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/python-service

stages:
  - build
  - push
  - deploy

build-job:
  stage: build
  services:
    - docker:24.0.5-dind
  image: docker:git
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$IMAGE_TAG --build-arg="name=Cloud Run" .
    - docker push $CI_REGISTRY_IMAGE:$IMAGE_TAG

include:
  - component: gitlab.com/google-gitlab-components/artifact-registry/upload-artifact-registry@0.1.0
    inputs:
      stage: push
      source: $CI_REGISTRY_IMAGE:$IMAGE_TAG
      target: $AR_IMAGE:$IMAGE_TAG

  - component: gitlab.com/google-gitlab-components/cloud-run/deploy-cloud-run@0.1.0
    inputs:
      stage: deploy
      image: $AR_IMAGE:$IMAGE_TAG
      project_id: PROJECT
      region: LOCATION
      service: python-service

.gitlab-ci.yml 파일을 Git에 추가하고, 커밋한 후 GitLab 저장소에 푸시합니다.

파이프라인은 다음을 완료합니다:

Docker-in-Docker로 이미지 python-service 빌드.
GitLab 컨테이너 레지스트리에 이미지 저장.
Google Artifact Registry GitLab 컴포넌트를 사용하여 Google Artifact Registry에 이미지 푸시.
Google Cloud Run 컴포넌트로 python-service 배포.

Google Cloud Run에서 서비스 보기#

Google Cloud Console에서 Cloud Run 페이지로 이동합니다.
Services 탭에서 만든 서비스를 선택합니다.

서비스 Metrics 탭이 표시되며 서비스 지역, URL 및 기타 세부 정보를 볼 수 있습니다.

서비스를 프록시하여 보기#

다음 명령을 실행하여 서비스를 로컬로 프록시합니다:

gcloud run services proxy SERVICE \
    --project PROJECT_ID \
    --region=LOCATION

http://localhost:8080에서 환영 페이지를 볼 수 있습니다.

정리#

이 페이지에서 사용한 리소스에 대한 Google Cloud 계정 비용이 발생하지 않도록 Google Cloud 리소스 또는 전체 Google Cloud 프로젝트를 삭제할 수 있습니다.

워크로드 아이덴티티 풀이 포함된 프로젝트를 삭제하면 설정 지침을 모두 다시 따르지 않는 한 통합을 사용할 수 없습니다.

GitLab 및 Google 가격 책정과 프로젝트 관리에 대한 자세한 내용은 다음 리소스를 참조하세요:

Google Artifact Registry 저장소 삭제#

Google Artifact Registry 저장소를 삭제하려면 이 섹션의 단계를 따릅니다. 전체 Google Cloud 프로젝트를 삭제하려면 프로젝트 삭제의 단계를 따릅니다.

저장소를 제거하기 전에 보존하려는 이미지가 다른 위치에서 사용 가능한지 확인합니다.

저장소를 삭제하려면 다음 명령을 실행합니다:

gcloud artifacts repositories delete REPOSITORY \
    --location=LOCATION

다음 항목을 교체합니다:

REPOSITORY를 Google Artifact Registry 저장소 ID로
LOCATION을 저장소 위치로

Cloud Run 서비스 삭제#

Google Cloud Console에서 Cloud Run 페이지로 이동합니다.
서비스 옆의 확인란을 선택합니다.
Delete를 선택합니다.

Google Cloud 프로젝트 삭제#

주의: 프로젝트 삭제는 다음과 같은 영향을 미칩니다:

프로젝트의 모든 것이 삭제됩니다. 이 문서의 작업에 기존 프로젝트를 사용한 경우 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
사용자 정의 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 나중에 사용하려는 사용자 정의 프로젝트 ID를 만들었을 수 있습니다. appspot.com URL과 같은 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내의 선택한 리소스를 삭제합니다.

Google Cloud 콘솔에서 Manage resources 페이지로 이동합니다.
프로젝트 목록에서 삭제하려는 프로젝트를 선택한 다음 Delete를 선택합니다.
대화 상자에서 프로젝트 ID를 입력한 다음 Shut down을 선택하여 프로젝트를 삭제합니다.

튜토리얼: Google Cloud Run 컴포넌트로 웹 서비스 생성 및 배포

시작하기 전에#

새 GitLab 프로젝트에서 IAM 통합 구성#

새 GitLab 프로젝트에서 Google Artifact Registry 통합 구성#

GitLab 저장소 복제#

Dockerfile 만들기#

파이프라인 만들기#

Google Cloud Run에서 서비스 보기#

서비스를 프록시하여 보기#

정리#

Google Artifact Registry 저장소 삭제#

Cloud Run 서비스 삭제#

Google Cloud 프로젝트 삭제#

관련 주제#

튜토리얼: Google Cloud Run 컴포넌트로 웹 서비스 생성 및 배포

시작하기 전에#

새 GitLab 프로젝트에서 IAM 통합 구성#

새 GitLab 프로젝트에서 Google Artifact Registry 통합 구성#

GitLab 저장소 복제#

Dockerfile 만들기#

파이프라인 만들기#

Google Cloud Run에서 서비스 보기#

서비스를 프록시하여 보기#

정리#

Google Artifact Registry 저장소 삭제#

Cloud Run 서비스 삭제#

Google Cloud 프로젝트 삭제#

관련 주제#