작업에 대한 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 Run에서는 볼륨을 /dev, /proc, /sys 또는 해당 하위 디렉터리에 마운트할 수 없습니다.

시작하기 전에

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

Cloud Storage에 대한 읽기/쓰기 성능을 최적화하려면 Cloud Storage FUSE 네트워크 대역폭 성능 최적화를 참조하세요.

필요한 역할

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

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

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

콘솔

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

Cloud Run으로 이동
컨테이너 배포를 클릭하고 작업을 선택하여 초기 작업 설정 페이지를 작성합니다. 기존 작업을 구성하는 경우 작업을 선택한 후 수정을 클릭합니다.
컨테이너, 변수 및 보안 비밀, 연결, 보안을 클릭하여 작업 속성 페이지를 펼칩니다.
볼륨 탭을 클릭합니다.
- 볼륨에서 다음과 같이 합니다.
  - 볼륨 추가를 클릭합니다.
  - 볼륨 유형 드롭다운에서 Cloud Storage 버킷을 볼륨 유형으로 선택합니다.
  - 볼륨 이름 필드에 볼륨에 사용하려는 이름을 입력합니다.
  - 볼륨에 사용할 버킷을 찾아 선택합니다.
  - 원하는 경우 읽기 전용 체크박스를 선택하여 버킷을 읽기 전용으로 설정할 수 있습니다.
  - 완료를 클릭합니다.
- 컨테이너 탭을 클릭한 다음 볼륨을 마운트할 컨테이너를 펼쳐 컨테이너를 수정합니다.
- 볼륨 마운트 탭을 클릭합니다.
- 볼륨 마운트를 클릭합니다.
만들기 또는 업데이트를 클릭합니다.

gcloud

볼륨을 추가하고 마운트하려면 다음 명령어를 실행합니다.
```
gcloud 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 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:
  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 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.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
```
반환된 구성에서 볼륨 마운트 설정을 찾습니다.

Cloud Storage FUSE 네트워크 대역폭 성능 최적화

읽기 및 쓰기 성능을 향상시키기 위해서는 직접 VPC를 사용하고 VPC 네트워크에서 모든 아웃바운드 트래픽을 라우팅하여 Cloud Run 작업을 VPC 네트워크에 연결합니다. 이렇게 하려면 다음 옵션 중 하나를 사용하면 됩니다.

비공개 Google 액세스를 사용 설정하고 vpc-egress 매개변수를 all-traffic으로 설정합니다.
예시 2 Google API의 내부 트래픽의 네트워킹 권장사항 페이지에 설명된 옵션 중 하나를 사용합니다.

컨테이너 시작 시간 및 Cloud Storage FUSE 마운트

Cloud Storage FUSE를 사용하면 컨테이너를 시작하기 전에 볼륨 마운트가 시작되므로 Cloud Run 컨테이너 콜드 스타트 시간이 약간 늘어날 수 있습니다. Cloud Storage FUSE가 성공적으로 마운트된 경우에만 컨테이너가 시작됩니다.

Cloud Storage FUSE는 Cloud Storage에 대한 연결을 설정한 후에만 볼륨을 성공적으로 마운트합니다. 네트워킹 지연은 컨테이너 시작 시간에 영향을 미칠 수 있습니다. 따라서 연결 시도가 실패하면 Cloud Storage FUSE가 마운트되지 않고 Cloud Run 작업이 시작하지 않습니다. 또한 Cloud Storage FUSE에서 마운트하는 데 30초 넘게 걸리면 Cloud Run에서 모든 마운트를 수행하는 제한 시간이 총 30초이므로 Cloud Run 작업을 시작할 수 없습니다.

Cloud Storage FUSE 성능 특성

각각 다른 버킷을 가리키는 두 개의 볼륨을 정의하면 두 개의 Cloud Storage FUSE 프로세스가 시작됩니다. 마운트와 프로세스는 동시에 실행됩니다.

Cloud Storage FUSE를 사용하는 작업은 Cloud Storage FUSE가 Cloud Storage API를 사용해서 Cloud Storage와 통신하기 때문에 네트워크 대역폭의 영향을 받습니다. 네트워크 대역폭이 낮으면 버킷 콘텐츠 나열과 같은 일부 작업이 느려질 수 있습니다. 마찬가지로 큰 파일 읽기도 네트워크 대역폭의 제한을 받기 때문에 시간이 걸릴 수 있습니다.

버킷에 쓰기를 수행할 때 Cloud Storage FUSE는 객체를 메모리에 완전히 스테이징합니다. 즉, 큰 파일 쓰기는 컨테이너 인스턴스에 사용 가능한 메모리 양의 제한을 받습니다(최대 컨테이너 메모리 한도는 32GiB).

close 또는 fsync를 수행할 때만 버킷에 쓰기가 플러시되고, 그런 후 전체 객체가 버킷에 업로드/재업로드됩니다. 객체가 버킷에 완전히 재업로드되지 않는 유일한 예외는 2MiB 이상인 파일에 콘텐츠를 추가할 때입니다.

자세한 내용은 다음 리소스를 참조하세요.