Cloud Run에 Filestore 사용 튜토리얼


이 튜토리얼은 여러 컨테이너와 서비스 간에 데이터를 공유하기 위해 Cloud Run 서비스에 Filestore를 네트워크 파일 시스템으로 마운트하는 방법을 보여줍니다. 이 튜토리얼에서는 Cloud Run 2세대 실행 환경을 사용합니다.

2세대 실행 환경을 통해 네트워크 파일 시스템을 컨테이너의 디렉터리에 마운트할 수 있습니다. 파일 시스템을 마운트하면 호스트 시스템과 인스턴스 간에 리소스를 공유하고 인스턴스가 가비지로 수집된 후에도 리소스를 유지할 수 있습니다.

Cloud Run에서 네트워크 파일 시스템을 사용하려면 컨테이너가 파일 시스템 마운트 및 애플리케이션 프로세스를 비롯한 여러 프로세스를 실행해야 하므로 고급 Docker 지식이 필요합니다. 이 튜토리얼에서는 작업 예시와 함께 필요한 개념을 설명합니다. 하지만 이 튜토리얼을 애플리케이션에 맞게 조정할 때는 변경사항이 미칠 수 있는 영향을 이해해야 합니다.

디자인 개요

Filestore 인스턴스는 Virtual Private Cloud(VPC) 네트워크 내에서 호스팅됩니다. VPC 네트워크 내의 리소스는 비공개 IP 주소 범위를 사용하여 Google API 및 서비스와 통신합니다. 따라서 클라이언트가 Filestore 인스턴스에 저장된 파일에 액세스하려면 해당 인스턴스와 동일한 네트워크에 있어야 합니다. Filestore와 통신하기 위해 Cloud Run 서비스가 VPC 네트워크에 연결하려면 서버리스 VPC 액세스 커넥터가 필요합니다. 서버리스 VPC 액세스에 대해 자세히 알아보기

파일 시스템 아키텍처

이 다이어그램은 서버리스 VPC 액세스 커넥터를 통해 Filestore 인스턴스에 연결하는 Cloud Run 서비스를 보여줍니다. Filestore 인스턴스와 커넥터는 최상의 성능을 위해 동일한 VPC 네트워크 'default' 내에 있으며 Cloud Run 서비스와 같은 리전/영역에 위치합니다.

제한사항

  • 이 튜토리얼에서는 파일 시스템이나 프로덕션에 즉시 사용 가능한 요구사항을 선택하는 방법을 설명하지 않습니다. Filestore 및 사용 가능한 서비스 등급에 대해 자세히 알아보기

  • 이 튜토리얼에서는 파일 시스템으로 작업하거나 파일 액세스 패턴을 논의하는 방법을 보여주지 않습니다.

목표

  • 기본 VPC 네트워크에서 파일 공유 역할을 하는 Filestore 인스턴스를 만듭니다.

  • 동일한 기본 VPC 네트워크에 서버리스 VPC 액세스 커넥터를 만들어 Cloud Run 서비스에 연결합니다.

  • 시스템 패키지 및 init-process를 사용하여 마운트 및 애플리케이션 프로세스를 관리하는 Dockerfile을 빌드합니다.

  • Cloud Run에 배포하고 서비스의 파일 시스템에 대한 액세스 권한을 확인합니다.

비용

이 튜토리얼에서는 다음과 같은 비용이 청구될 수 있는 Google Cloud 구성요소를 사용합니다.

시작하기 전에

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

    프로젝트 선택기로 이동

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

  4. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기로 이동

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

  6. IAM 권한은 Filestore 인스턴스 만들기와 같은 Filestore 작업에 대한 액세스만 제어합니다. 읽기 또는 실행과 같이 파일 공유의 작업에 대한 액세스를 제어하려면 POSIX 파일 권한을 사용하세요. 여기서 액세스 제어에 대해 자세히 알아보세요.
  7. API Cloud Run, Filestore, Serverless VPC Access, Artifact Registry, and Cloud Build 사용 설정

    API 사용 설정

  8. gcloud CLI를 설치하고 초기화합니다.
  9. Google Cloud CLI를 업데이트합니다. gcloud components update

필요한 역할

튜토리얼을 완료하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

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

gcloud 기본값 설정

Cloud Run 서비스의 기본값으로 gcloud를 구성하려면 다음 안내를 따르세요.

  1. 기본 프로젝트를 설정합니다.

    gcloud config set project PROJECT_ID

    PROJECT_ID를 이 튜토리얼용으로 만든 프로젝트 이름으로 바꿉니다.

  2. 선택한 리전에 맞게 gcloud를 구성합니다.

    gcloud config set run/region REGION

    REGION을 지원되는 Cloud Run 리전 중 원하는 리전으로 바꿉니다.

  3. Filestore에 대해 gcloud를 구성합니다.

    gcloud config set filestore/zone ZONE
    

    ZONE을 지원되는 Filestore 영역 중 원하는 리전으로 바꿉니다.

코드 샘플 검색

사용할 코드 샘플을 검색하려면 다음 안내를 따르세요.

  1. 샘플 앱 저장소를 로컬 머신에 클론합니다.

    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 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.

    Java

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    또는 zip 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.

  2. Cloud Run 샘플 코드가 포함된 디렉터리로 변경합니다.

    Node.js

    cd nodejs-docs-samples/run/filesystem/

    Python

    cd python-docs-samples/run/filesystem/

    Java

    cd java-docs-samples/run/filesystem/

코드 이해하기

일반적으로 컨테이너 내에서 단일 프로세스 또는 애플리케이션을 실행해야 합니다. 컨테이너당 단일 프로세스를 실행하면 다시 시작 관리, 프로세스가 실패할 경우 컨테이너 종료, 신호 전달 및 좀비 하위 프로세스 제거와 같은 PID 1 책임 관리와 같은 여러 프로세스의 수명 주기 관리에 대한 복잡성이 줄어듭니다. 하지만 Cloud Run에서 네트워크 파일 시스템을 사용하려면 다중 프로세스 컨테이너를 사용하여 파일 시스템 마운트 프로세스와 애플리케이션을 모두 실행해야 합니다. 이 튜토리얼에서는 프로세스 실패 시 컨테이너를 종료하고 PID 1 책임을 관리하는 방법을 보여줍니다. 마운트 명령어에는 재시도를 처리하는 기능이 내장되어 있습니다.

프로세스 관리자를 사용하여 컨테이너의 진입점으로 여러 프로세스를 실행하고 관리할 수 있습니다. 이 튜토리얼은 좀비 프로세스를 정리하고 신호 전달을 수행하는 init 대체인 tini를 사용합니다. 특히 이 init 프로세스는 종료 시 SIGTERM 신호가 애플리케이션에 전파되도록 합니다. SIGTERM 신호는 애플리케이션의 단계적 종료를 위해 포착될 수 있습니다. Cloud Run의 컨테이너 수명 주기에 대해 자세히 알아보세요.

Dockerfile로 환경 구성 정의

이 Cloud Run 서비스를 사용하려면 기본적으로 하나 이상의 추가 시스템 패키지가 필요합니다. RUN 명령어는 tini를 init-process로 설치하며 최소 NFS 클라이언트 기능을 제공하는 nfs-common을 설치합니다. 시스템 패키지 사용 튜토리얼에서 Cloud Run 서비스의 시스템 패키지 작업에 대해 자세히 알아보세요.

다음 안내에서는 작업 디렉터리를 만들고, 소스 코드를 복사하고, 앱 종속 항목을 설치합니다.

ENTRYPOINTCMD 명령어 앞에 추가되는 init-process 바이너리를 지정합니다(이 경우에는 시작 스크립트). 그러면 단일 tini 프로세스가 실행된 다음 수신된 모든 신호를 해당 하위 프로세스의 루트가 되는 세션으로 프록시 처리합니다.

CMD 명령어는 시작 스크립트인 이미지를 실행할 때 실행할 명령어를 설정합니다. 또한 ENTRYPOINT의 기본 인수도 제공합니다. CMD 및 ENTRYPOINT의 상호작용 방법을 알아보세요.

Node.js


# Use the official Node.js image.
# https://hub.docker.com/_/node
FROM node:20-slim

# Install system dependencies
RUN apt-get update -y && apt-get install -y \
    tini \
    nfs-common \
	libtool \
    && apt-get clean

# Set fallback mount directory
ENV MNT_DIR /mnt/nfs/filestore

# Copy local code to the container image.
ENV APP_HOME /app
WORKDIR $APP_HOME
COPY package*.json ./

# Install production dependencies.
RUN npm install --only=production

# Copy local code to the container image.
COPY . ./

# Ensure the script is executable
RUN chmod +x /app/run.sh

# Use tini to manage zombie processes and signal forwarding
# https://github.com/krallin/tini
ENTRYPOINT ["/usr/bin/tini", "--"]

# Pass the wrapper script as arguments to tini
CMD ["/app/run.sh"]

Python

# Use the official lightweight Python image.
# https://hub.docker.com/_/python
FROM python:3.11-slim

# Install system dependencies
RUN apt-get update -y && apt-get install -y \
    tini \
    nfs-common \
    && apt-get clean

# Set fallback mount directory
ENV MNT_DIR /mnt/nfs/filestore

# Copy local code to the container image.
ENV APP_HOME /app
WORKDIR $APP_HOME
COPY . ./

# Install production dependencies.
RUN pip install -r requirements.txt

# Ensure the script is executable
RUN chmod +x /app/run.sh

# Use tini to manage zombie processes and signal forwarding
# https://github.com/krallin/tini
ENTRYPOINT ["/usr/bin/tini", "--"]

# Pass the startup script as arguments to tini
CMD ["/app/run.sh"]

Java


# Use the official maven image to create a build artifact.
# https://hub.docker.com/_/maven
FROM maven:3-eclipse-temurin-17-alpine as builder

# Copy local code to the container image.
WORKDIR /app
COPY pom.xml .
COPY src ./src

# Build a release artifact.
RUN mvn package -DskipTests

# Use Eclipse Temurin for base image.
# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
FROM eclipse-temurin:18-jdk-focal

# Install filesystem dependencies
RUN apt-get update -y && apt-get install -y \
    tini \
    nfs-kernel-server \
    nfs-common \
    && apt-get clean

# Set fallback mount directory
ENV MNT_DIR /mnt/nfs/filestore

# Copy the jar to the production image from the builder stage.
COPY --from=builder /app/target/filesystem-*.jar /filesystem.jar

# Copy the statup script
COPY run.sh ./run.sh
RUN chmod +x ./run.sh

# Use tini to manage zombie processes and signal forwarding
# https://github.com/krallin/tini
ENTRYPOINT ["/usr/bin/tini", "--"]

# Run the web service on container startup.
CMD ["/run.sh"]

시작 스크립트에서 프로세스 정의

시작 스크립트는 Filestore 인스턴스에 액세스 할 수 있는 마운트 지점 역할을 하는 디렉터리를 만듭니다. 그런 다음 mount 명령어를 사용하여 인스턴스의 IP 주소와 파일 공유 이름을 서비스의 마운트 지점에 지정하여 Filestore 인스턴스를 연결한 다음 애플리케이션 서버를 시작합니다. mount 명령어에는 재시도 기능이 내장되어 있습니다. 따라서 추가 bash 스크립팅은 필요하지 않습니다. 마지막으로 wait 명령어는 모든 백그라운드 프로세스의 종료를 수신 대기하고 스크립트를 종료합니다.

Node.js

#!/usr/bin/env bash
set -eo pipefail

# Create mount directory for service.
mkdir -p $MNT_DIR

echo "Mounting Cloud Filestore."
mount -o nolock $FILESTORE_IP_ADDRESS:/$FILE_SHARE_NAME $MNT_DIR
echo "Mounting completed."

# Start the application
node index.js &

# Exit immediately when one of the background processes terminate.
wait -n

Python

#!/usr/bin/env bash
set -eo pipefail

# Create mount directory for service.
mkdir -p $MNT_DIR

echo "Mounting Cloud Filestore."
mount -o nolock $FILESTORE_IP_ADDRESS:/$FILE_SHARE_NAME $MNT_DIR
echo "Mounting completed."

# Run the web service on container startup. Here we use the gunicorn
# webserver, with one worker process and 8 threads.
# For environments with multiple CPU cores, increase the number of workers
# to be equal to the cores available.
# Timeout is set to 0 to disable the timeouts of the workers to allow Cloud Run to handle instance scaling.
exec gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Java

#!/usr/bin/env bash
set -eo pipefail

# Create mount directory for service
mkdir -p $MNT_DIR

echo "Mounting Cloud Filestore."
mount -o nolock $FILESTORE_IP_ADDRESS:/$FILE_SHARE_NAME $MNT_DIR
echo "Mounting completed."

# Start the application
java -jar filesystem.jar

# Exit immediately when one of the background processes terminate.
wait -n

파일 작업

Node.js

파일 시스템과 상호작용하는 방법은 index.js를 참조하세요.

Python

파일 시스템과 상호작용하는 방법은 main.py를 참조하세요.

Java

파일 시스템과 상호작용하는 방법은 FilesystemApplication.java를 참조하세요.

서비스 제공

  1. Filestore 인스턴스를 만듭니다.

    gcloud filestore instances create INSTANCE_ID \
        --tier=basic-hdd \
        --file-share=name=FILE_SHARE_NAME,capacity=1TiB \
        --network=name="default"
    

    INSTANCE_ID를 Filestore 인스턴스의 이름(my-filestore-instance)으로 바꾸고 FILE_SHARE_NAME을 Filestore 인스턴스에서 제공하는 디렉터리의 이름(vol1)으로 바꿉니다. 인스턴스 이름 지정파일 공유 이름 지정을 참조하세요.

    클라이언트(Cloud Run 서비스)에서 해당 인스턴스에 저장된 파일에 액세스하려면 클라이언트는 Filestore 인스턴스와 동일한 네트워크에 있어야 합니다. 이 명령어는 기본 VPC 네트워크에 인스턴스를 만들고 여유 IP 주소 범위를 할당합니다. 새 프로젝트는 기본 네트워크로 시작하며 대부분 별도의 네트워크를 만들 필요가 없습니다.

    인스턴스 만들기에서 인스턴스 구성에 대해 자세히 알아보세요.

  2. 서버리스 VPC 액세스 커넥터를 설정합니다.

    Filestore 인스턴스에 연결하려면 Cloud Run 서비스에서 Filestore 인스턴스의 승인된 VPC 네트워크에 대한 액세스 권한이 필요합니다.

    모든 VPC 커넥터에는 커넥터 인스턴스를 배치할 자체 /28 서브넷이 필요합니다. 이 IP 범위는 VPC 네트워크에 예약된 기존 IP 주소와 겹치지 않아야 합니다. 예를 들어 10.8.0.0(/28)은 대부분의 새 프로젝트에서 작동하거나 10.9.0.0(/28)과 같이 사용되지 않은 다른 커스텀 IP 범위를 지정할 수 있습니다. Google Cloud 콘솔에서 현재 예약된 IP 범위를 확인할 수 있습니다.

    gcloud compute networks vpc-access connectors create CONNECTOR_NAME \
      --region REGION \
      --range "10.8.0.0/28"
    

    CONNECTOR_NAME을 애플리케이션 이름으로 바꿉니다.

    이 명령어는 e2-micro 머신 크기로 Filestore 인스턴스와 동일하게 기본 VPC 네트워크에 커넥터를 만듭니다. 커넥터의 머신 크기를 늘리면 커넥터의 처리량이 향상되지만 비용도 증가합니다. 또한 커넥터는 Cloud Run 서비스와 동일한 리전에 있어야 합니다. 서버리스 VPC 액세스 구성에 대해 자세히 알아보세요.

  3. Filestore 인스턴스의 IP 주소로 환경 변수를 정의합니다.

    export FILESTORE_IP_ADDRESS=$(gcloud filestore instances describe INSTANCE_ID --format "value(networks.ipAddresses[0])")
    
  4. 서비스 ID로 사용할 서비스 계정을 만듭니다. 기본적으로 여기에는 프로젝트 멤버쉽 이외의 다른 권한이 포함되지 않습니다.

    gcloud iam service-accounts create fs-identity

    이 서비스는 Google Cloud의 다른 항목과 상호작용할 필요가 없습니다. 따라서 이 서비스 계정에 추가 권한을 할당할 필요가 없습니다.

  5. 컨테이너 이미지를 빌드하여 Cloud Run에 배포합니다.

    gcloud run deploy filesystem-app --source . \
        --vpc-connector CONNECTOR_NAME \
        --execution-environment gen2 \
        --allow-unauthenticated \
        --service-account fs-identity \
        --update-env-vars FILESTORE_IP_ADDRESS=$FILESTORE_IP_ADDRESS,FILE_SHARE_NAME=FILE_SHARE_NAME
    

    이 명령어는 Cloud Run 서비스를 빌드 및 배포하고 VPC 커넥터와 2세대 실행 환경을 지정합니다. 소스에서 배포하면 Dockerfile을 기반으로 이미지가 빌드되고 이미지가 Artifact Registry 저장소(cloud-run-source-deploy)에 푸시됩니다.

    소스 코드에서 배포에 대해 자세히 알아보기

디버깅

배포에 실패하면 Cloud Logging에서 자세한 내용을 확인합니다.

  • 연결 시간이 초과되면 Filestore 인스턴스의 올바른 IP 주소를 제공하고 있는지 확인합니다.

  • 서버에서 액세스가 거부된 경우 파일 공유 이름이 올바른지 확인하세요.

  • 마운트 프로세스의 모든 로그를 사용하려면 --verbose 플래그를 마운트 명령어(mount --verbose -o nolock $FILESTORE_IP_ADDRESS:/$FILE_SHARE_NAME $MNT_DIR)와 함께 사용합니다.

사용해 보기

전체 서비스를 시도해봅니다.

  1. 브라우저에서 위의 배포 단계로 제공된 URL로 이동합니다.
  2. Filestore 인스턴스에 새로 생성된 파일이 표시됩니다.
  3. 파일을 클릭하여 콘텐츠를 확인합니다.

이러한 서비스를 계속 개발하려면 이들 서비스에 다른 Google Cloud 서비스에 대한 제한적인 Identity and Access Management(IAM) 액세스 권한이 있으며 다른 여러 서비스에 액세스하려면 추가 IAM 역할이 부여되어야 합니다.

비용 토론

아이오와(us-central1)에서 호스팅되고 1TiB Filestore 인스턴스와 서버리스 VPC 액세스 커넥터가 있는 서비스의 비용 분석 예시입니다. 개별 가격 책정 페이지를 방문하여 최신 가격을 확인하세요.

제품 월 비용
Filestore(사용량에 의존하지 않음) 비용 = 프로비저닝 용량(1024GiB 또는 1TiB) * 리전 등급 가격(us-central1)

기본 HDD 등급: 1024GiB * $0.16/월 = $163.84
영역(SSD): 1024GiB * $0.25/월 = $256.00
엔터프라이즈(SSD, 리전 가용성): 1024GiB * $0.45/월 = $460.80
서버리스 VPC 액세스 비용 = 머신 크기 가격 * 인스턴스 수(최소 인스턴스 기본값은 2)

f1-micro: $3.88 * 2개 인스턴스 = $7.76
e2- 마이크로: $6.11 * 인스턴스 2개 = $12.22
e2-standard-4: $97.83 * 인스턴스 2개 = $195.66
Cloud Run 비용 = CPU + 메모리 + 요청 + 네트워킹
합계 $163.84 + $12.22 = $176.06/월 + Cloud Run 비용

이 튜토리얼에서는 기본 HDD 등급 Filestore 인스턴스를 사용합니다. Filestore 인스턴스의 서비스 등급은 인스턴스 유형 및 스토리지 유형의 조합입니다. 용량 및 확장성을 높이기 위해 인스턴스 유형을 업그레이드할 수 있습니다. 성능 향상을 위해 스토리지 유형을 업그레이드할 수 있습니다. 스토리지 유형 권장사항 자세히 알아보기 리전 및 용량도 Filestore 가격 책정에 영향을 미칩니다. 예를 들어 아이오와(us-central1)의 기본 HDD 등급 1TiB 인스턴스 비용은 매월 1GiB당 $0.16, 즉 매월 약 $163.84입니다.

서버리스 VPC 액세스 커넥터는 네트워크 이그레스뿐만 아니라 인스턴스 크기 및 개수에 따라 가격 책정됩니다. 크기와 개수를 늘리면 처리량이 늘어나거나 메시지 지연 시간이 줄어듭니다. 머신에는 f1-micro, e2-micro, e2-standard-4의 3가지 크기가 있습니다. 인스턴스의 최소 개수는 2개이므로, 최소 비용은 해당 머신 크기의 두 배입니다.

Cloud Run은 메모리, CPU, 요청 수, 네트워킹에 대해 가장 가까운 100ms로 반올림된 리소스 사용량에 따라 가격 책정됩니다. 따라서 비용은 서비스 설정, 요청 수, 실행 시간에 따라 달라집니다. 이 서비스의 최소 요금은 월별 $176.06입니다. Google Cloud 가격 계산기에서 예상 비용을 확인하고 검색해 보세요.

삭제

이 튜토리얼용으로 새 프로젝트를 만든 경우 이 프로젝트를 삭제합니다. 기존 프로젝트를 사용한 경우 이 튜토리얼에 추가된 변경사항은 제외하고 보존하려면 튜토리얼용으로 만든 리소스를 삭제합니다.

프로젝트 삭제

비용이 청구되지 않도록 하는 가장 쉬운 방법은 튜토리얼에서 만든 프로젝트를 삭제하는 것입니다.

프로젝트를 삭제하려면 다음 안내를 따르세요.

  1. Google Cloud 콘솔에서 리소스 관리 페이지로 이동합니다.

    리소스 관리로 이동

  2. 프로젝트 목록에서 삭제할 프로젝트를 선택하고 삭제를 클릭합니다.
  3. 대화상자에서 프로젝트 ID를 입력한 후 종료를 클릭하여 프로젝트를 삭제합니다.

튜토리얼 리소스 삭제

  1. 이 튜토리얼에서 배포한 Cloud Run 서비스를 삭제합니다.

    gcloud run services delete SERVICE-NAME

    여기서 SERVICE-NAME은 선택한 서비스 이름입니다.

    Google Cloud 콘솔에서 Cloud Run 서비스를 삭제할 수도 있습니다.

  2. 튜토리얼 설정 중에 추가한 gcloud 기본 리전 구성을 삭제합니다.

     gcloud config unset run/region
    
  3. 프로젝트 구성을 삭제합니다.

     gcloud config unset project
    
  4. 이 튜토리얼에서 만든 다른 Google Cloud 리소스를 삭제합니다.

다음 단계