작업에 대한 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 버킷이 필요합니다.

필요한 역할

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

Cloud Run 작업에 대한 Cloud Run 개발자(roles/run.developer) 역할
서비스 ID에 대한 서비스 계정 사용자(roles/iam.serviceAccountUser) 역할

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

스토리지 관리자(roles/storage.admin)

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 볼륨 마운트

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

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

gcloud

볼륨을 추가하고 마운트하려면 다음 명령어를 실행합니다.
```
gcloud beta run jobs update JOB \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH
```
다음과 같이 바꿉니다.
- JOB을 작업 이름으로 바꿉니다.
- 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 jobs update JOB \
--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

새 작업을 만드는 경우에는 이 단계를 건너뜁니다. 기존 작업을 업데이트하는 경우 YAML 구성을 다운로드합니다.
```
gcloud run jobs describe JOB_NAME --format export > job.yaml
```
필요에 따라 MOUNT_PATH, VOLUME_NAME, BUCKET_NAME, IS_READ_ONLY를 업데이트합니다.
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB_NAME
spec:
  metadata:
    annotations:
      run.googleapis.com/launch-stage: BETA
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
    spec:
      template:
        spec:
          containers:
          - image: IMAGE_URL
            volumeMounts:
            - mountPath: MOUNT_PATH
              name: VOLUME_NAME
          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 버킷의 이름
다음 명령어를 사용하여 서비스를 새 구성으로 바꿉니다.
```
gcloud beta run jobs replace job.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");

볼륨 마운트 설정 보기

콘솔

Google Cloud 콘솔에서 Cloud Run 작업 페이지로 이동합니다.

Cloud Run 작업으로 이동
관심 있는 작업을 클릭하여 작업 세부정보 페이지를 엽니다.
볼륨 탭을 클릭합니다.
볼륨 세부정보 페이지에서 볼륨 마운트 설정을 찾습니다.

gcloud

다음 명령어를 사용하세요.
```
gcloud run jobs describe JOB_NAME
```
반환된 구성에서 볼륨 마운트 설정을 찾습니다.