서비스의 Cloud Storage 볼륨 마운트 구성

이 페이지에서는 Cloud Run 볼륨 마운트를 사용하여 Cloud Storage 버킷을 스토리지 볼륨으로 마운트하는 방법을 보여줍니다.

Cloud Run에서 버킷을 볼륨으로 마운트하면 버킷 콘텐츠가 컨테이너 파일 시스템에 파일로 제공됩니다. 버킷을 볼륨으로 마운트한 후에는 Google API 클라이언트 라이브러리를 사용하는 대신 프로그래밍 언어의 파일 시스템 작업과 라이브러리를 사용하여 로컬 파일 시스템의 디렉터리처럼 버킷에 액세스합니다.

메모리 요구사항

Cloud Storage 볼륨 마운트는 다음 활동에서 Cloud Run 컨테이너 메모리를 사용합니다.

  • 모든 Cloud Storage FUSE 캐싱에 대해 Cloud Run은 기본적으로 TTL(수명)이 60초인 통계 캐시 설정을 사용합니다. 통계 캐시의 기본 최대 크기는 32MB이며, 유형 캐시의 기본 최대 크기는 4MB입니다.

  • 읽을 때 Cloud Storage FUSE는 통계 및 유형 캐시 이외의 메모리도 사용합니다(예: 읽고 있는 모든 파일과 goroutine에 대한 1MiB 배열).

  • Cloud Storage에 쓰기 작업을 수행하면 파일이 Cloud Storage에 기록되기 전에 전체 파일이 Cloud Run 메모리에 스테이징됩니다.

제한사항

Cloud Run은 이 볼륨 마운트에 Cloud Storage FUSE를 사용합니다. 따라서 Cloud Storage 버킷을 볼륨으로 마운트할 때는 다음 사항에 유의해야 합니다.

  • Cloud Storage FUSE는 동일한 파일에 여러 쓰기(파일 잠금)에 대한 동시 실행 제어를 제공하지 않습니다. 파일 여러 개를 쓰기 위해 파일을 바꾸려고 하면 마지막 쓰기만 성공하고 이전의 모든 쓰기는 손실됩니다.
  • Cloud Storage FUSE는 POSIX와 완전히 호환되는 파일 시스템이 아닙니다. 자세한 내용은 Cloud Storage FUSE 문서를 참조하세요.

시작하기 전에

볼륨으로 마운트할 Cloud Storage 버킷이 필요합니다.

읽기 및 쓰기 성능을 높이려면 직접 VPC를 사용하여 Cloud Run 서비스를 VPC 네트워크에 연결하고 VPC 네트워크를 통해 모든 아웃바운드 트래픽을 라우팅하는 것이 좋습니다. 네트워킹 권장사항 페이지에서 예 2: Google API에 대한 내부 트래픽의 안내를 참조하세요.

필요한 역할

Cloud Storage 볼륨 마운트를 구성하는 데 필요한 권한을 얻으려면 관리자에게 다음의 IAM 역할을 부여해 달라고 요청하세요.

서비스 ID로 파일 및 Cloud Storage 버킷에 액세스하는 데 필요한 권한을 얻으려면 관리자에게 문의하여 서비스 ID에 다음의 IAM 역할을 부여해 달라고 요청하세요.

Cloud Storage 역할 및 권한에 대한 자세한 내용은 Cloud Storage용 IAM을 참조하세요.

Cloud Run과 연결된 IAM 역할 및 권한 목록은 Cloud Run IAM 역할 및 Cloud Run IAM 권한을 참조하세요. Cloud Run 서비스가 Cloud 클라이언트 라이브러리와 같은 Google Cloud API와 상호작용하는 경우에는 서비스 ID 구성 가이드를 참조하세요. 역할 부여에 대한 자세한 내용은 배포 권한 및 액세스 관리를 참조하세요.

허용되지 않는 경로

Cloud Run에서는 볼륨을 /dev, /proc, /sys 또는 해당 하위 디렉터리에 마운트할 수 없습니다.

Cloud Storage 볼륨 마운트

서로 다른 마운트 경로에 여러 버킷을 마운트할 수 있습니다. 또한 컨테이너 간에 동일하거나 서로 다른 마운트 경로를 사용하여 볼륨을 두 개 이상의 컨테이너에 마운트할 수도 있습니다.

여러 컨테이너를 사용하는 경우 먼저 볼륨을 지정한 후 각 컨테이너의 볼륨 마운트를 지정합니다.

볼륨 마운트에는 2세대 실행 환경이 필요합니다. 실행 환경이 명시적으로 구성되지 않은 경우 Cloud Run이 서비스에 대해 2세대 실행 환경을 자동으로 선택합니다.

콘솔

  1. Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

    Cloud Run으로 이동

  2. 배포할 새 서비스를 구성하려면 서비스 만들기를 클릭합니다. 기존 서비스를 구성하는 경우 서비스를 클릭한 후 새 버전 수정 및 배포를 클릭합니다.

  3. 새 서비스를 구성하는 경우 원하는 대로 초기 서비스 설정 페이지를 작성한 후 컨테이너, 볼륨, 네트워킹, 보안을 클릭하여 서비스 구성 페이지를 펼칩니다.

  4. 볼륨 탭을 클릭합니다.

    이미지

      • 볼륨 추가를 클릭합니다.
      • 볼륨 유형 드롭다운에서 Cloud Storage 버킷을 볼륨 유형으로 선택합니다.
      • 볼륨 이름 필드에 볼륨에 사용하려는 이름을 입력합니다.
      • 볼륨에 사용할 Cloud Storage 버킷을 찾아서 선택하거나 원하는 경우 새 버킷을 만듭니다.
      • 버킷을 읽기 전용으로 설정하려면 '읽기 전용' 체크박스를 선택합니다.
      • 완료를 클릭합니다.
      컨테이너 탭을 클릭합니다.
      • 볼륨 마운트 탭을 클릭합니다.
      • 볼륨 마운트를 클릭합니다.
      • 메뉴에서 스토리지 볼륨을 선택합니다.
      • 볼륨을 마운트할 경로를 지정합니다.
      • 완료를 클릭합니다.

  5. 만들기 또는 배포를 클릭합니다.

gcloud

참고: 여기서는 gcloud beta run services update 명령어를 보여주지만 다음과 같이 매개변수와 함께 gcloud beta run deploy 명령어를 사용할 수 있습니다.

  • 볼륨을 추가하고 마운트하려면 다음 명령어를 실행합니다.

    gcloud beta run services update SERVICE \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

    다음과 같이 바꿉니다.

    • SERVICE를 서비스 이름으로 바꿉니다.
    • MOUNT_PATH: 볼륨을 마운트할 상대 경로(예: /mnt/my-volume)
    • VOLUME_NAME: 볼륨에 사용할 이름. VOLUME_NAME 값은 볼륨을 볼륨 마운트에 매핑하는 데 사용됩니다.
    • BUCKET_NAME: Cloud Storage 버킷 이름

  • 볼륨을 읽기 전용 볼륨으로 마운트하려면 다음 명령어를 실행합니다.

--add-volume=name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,readonly=true

  • 여러 컨테이너를 사용하는 경우 먼저 볼륨을 지정한 후 각 컨테이너의 볼륨 마운트를 지정합니다.

    gcloud beta run services update SERVICE \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--container CONTAINER_1 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH \
--container CONTAINER_2 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH2

YAML

  1. 새 서비스를 만드는 경우에는 이 단계를 건너뜁니다. 기존 서비스를 업데이트하는 경우 YAML 구성을 다운로드합니다.

    gcloud run services describe SERVICE --format export > service.yaml

  2. 필요에 따라 업데이트합니다. 

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
    spec:
      containers:
      - image: IMAGE_URL
        volumeMounts:
        - name: VOLUME_NAME
          mountPath: MOUNT_PATH
      volumes:
      - name: VOLUME_NAME
        csi:
          driver: gcsfuse.run.googleapis.com
          readOnly: IS_READ_ONLY
          volumeAttributes:
            bucketName: BUCKET_NAME

    바꾸기

    • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
    • MOUNT_PATH: 볼륨을 마운트할 상대 경로(예: /mnt/my-volume)
    • VOLUME_NAME: 볼륨에 사용할 이름. VOLUME_NAME 값은 볼륨을 볼륨 마운트에 매핑하는 데 사용됩니다.
    • IS_READ_ONLY를 True로 지정하여 볼륨을 읽기 전용으로 설정하거나 False로 지정하여 쓰기를 허용합니다.
    • BUCKET_NAME: Cloud Storage 버킷의 이름

  3. 다음 명령어를 사용하여 서비스를 새 구성으로 바꿉니다.

    gcloud run services replace service.yaml

볼륨 읽기 및 쓰기

Cloud Run 볼륨 마운트 기능을 사용하는 경우 로컬 파일 시스템에서 파일을 읽고 쓰는 데 사용하는 것과 동일한 프로그래밍 언어의 라이브러리를 사용하여 마운트된 볼륨에 액세스합니다.

이는 데이터가 로컬 파일 시스템에 저장될 것으로 예상하고 일반 파일 시스템 작업을 사용하여 액세스하는 기존 컨테이너를 사용하는 경우에 특히 유용합니다.

다음 스니펫은 볼륨 마운트의 mountPath가 /mnt/my-volume으로 설정되었다고 가정합니다.

Nodejs

파일 시스템 모듈을 사용하여 새 파일을 만들거나 볼륨 /mnt/my-volume의 기존 항목에 추가: 

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

Python

볼륨 /mnt/my-volume에 보관된 파일에 씁니다. 

f = open("/mnt/my-volume/sample-logfile.txt", "a")

Go

os 패키지를 사용하여 볼륨 /mnt/my-volume에 보관된 새 파일 만들기:

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

Java

Java.io.File 클래스를 사용하여 볼륨 /mnt/my-volume에 로그 파일을 만듭니다. 

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

볼륨 마운트 설정 보기

Cloud Run 서비스의 현재 볼륨 마운트 설정을 보려면 다음과 같이 합니다.

콘솔

  1. Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

    Cloud Run으로 이동

  2. 관심이 있는 서비스를 클릭하여 서비스 세부정보 페이지를 엽니다.

  3. 버전 탭을 클릭합니다.

  4. 볼륨 마운트 설정이 오른쪽 세부정보 패널의 볼륨 탭에 표시됩니다.

gcloud

  1. 다음 명령어를 사용하세요.

    gcloud run services describe SERVICE

  2. 반환된 구성에서 볼륨 마운트 설정을 찾습니다.