Cloud Storage 버킷을 CSI 임시 볼륨으로 마운트

Autopilot Standard

---

이 가이드에서는 Cloud Storage 버킷으로 지원되는 CSI 임시 볼륨을 사용하여 Google Kubernetes Engine (GKE)에서 Kubernetes 포드 또는 작업의 스토리지 리소스를 자동으로 관리하는 방법을 보여줍니다. CSI 임시 볼륨은 포드 또는 작업 수명 주기에 연결되며 PersistentVolume 및 PersistentVolumeClaim 객체를 수동으로 처리할 필요가 없습니다.

이 가이드는 GKE 애플리케이션의 스토리지 관리를 간소화하려는 플랫폼 관리자 및 운영자를 대상으로 합니다.

이 페이지를 읽기 전에 CSI 임시 볼륨, Kubernetes 포드 및 작업, Cloud Storage 버킷을 숙지해야 합니다.

PersistentVolume에 이미 익숙하며 이 리소스 유형을 사용하는 기존 배포와 일관성을 유지하려면 Cloud Storage 버킷을 영구 볼륨으로 마운트를 참고하세요.

시작하기 전에

다음 기본 요건을 완료했는지 확인합니다.

• Cloud Storage FUSE CSI 드라이버의 요구사항 및 제한사항을 알아봅니다.
• Cloud Storage 버킷 만들기
• Cloud Storage FUSE CSI 드라이버 사용 설정
• Cloud Storage 버킷에 대한 액세스 구성

Cloud Storage 버킷의 CSI 임시 저장소 작동 방식

CSI 임시 볼륨을 사용하면 GKE에서 애플리케이션의 스토리지 관리가 간소화됩니다. 포드 또는 작업 사양 내에서 직접 CSI 임시 볼륨을 정의합니다. CSI 임시 볼륨을 사용하면 별도의 PersistentVolume 및 PersistentVolumeClaim 객체가 필요하지 않습니다.

CSI 임시 볼륨을 사용하려면 다음 작업이 필요합니다.

1. 스토리지 정의: 사용할 CSI 드라이버 및 필요한 매개변수를 포함하여 포드 또는 작업의 YAML 파일에서 스토리지를 지정합니다. Cloud Storage FUSE CSI 드라이버의 경우 버킷 이름과 기타 관련 세부정보를 지정합니다.

   원하는 경우 파일 캐싱 기능을 사용하여 CSI 드라이버의 성능을 미세 조정할 수 있습니다. 파일 캐싱은 자주 액세스하는 Cloud Storage 파일을 더 빠른 디스크에 캐시하여 GKE 앱 성능을 높일 수 있습니다.

   또한 병렬 다운로드 기능을 사용하여 멀티스레드 다운로드를 위해 Cloud Storage에서 대용량 파일을 더 빠르게 읽을 수 있습니다. 이 기능을 사용하면 특히 크기가 1GB를 초과하는 읽기의 경우 모델 로드 시간을 개선할 수 있습니다.

   도움말: CSI 드라이버의 성능을 미세 조정하는 다른 방법은 Cloud Storage FUSE CSI 드라이버의 성능 최적화를 참고하세요.

2. 드라이버 호출: 포드 또는 작업을 만들면 GKE가 임시 볼륨 요청을 감지하고 Cloud Storage FUSE CSI 드라이버를 호출합니다.

3. 볼륨 마운트 및 연결: CSI 드라이버는 기본 Cloud Storage 버킷을 가리키는 CSI 임시 볼륨을 마운트하고 포드 또는 작업에서 사용할 수 있도록 만들어 애플리케이션에서 액세스할 수 있도록 합니다. 버킷이 파일 시스템에 마운트되는 방식을 미세 조정하려면 마운트 옵션을 사용하면 됩니다. 볼륨 속성을 사용하여 Cloud Storage FUSE CSI 드라이버의 특정 동작을 구성할 수도 있습니다.

4. 수명 주기 관리: 임시 볼륨은 포드 또는 작업의 전체 기간 동안 존재합니다. Pod가 삭제되거나 작업이 완료되면 CSI 드라이버가 자동으로 정리하고 볼륨을 마운트 해제합니다.

참고: CSI 임시 볼륨을 사용하는 경우에도 사용자가 사용 전에 버킷을 만들고 버킷을 삭제해야 합니다.

CSI 임시 볼륨 연결

CSI 임시 볼륨을 포드 또는 작업에 연결할지 여부에 따라 다음 안내를 따르세요.

포드

포드에 CSI 임시 볼륨을 연결하려면 다음 단계를 따르세요.

1. 다음 사양으로 포드 YAML 매니페스트를 만듭니다.

   apiVersion: v1
   kind: Pod
   metadata:
     name: gcs-fuse-csi-example-ephemeral 
     namespace: NAMESPACE
     annotations:
       gke-gcsfuse/volumes: "true" 
   spec:
     terminationGracePeriodSeconds: 60
     containers:
     - image: busybox
       name: busybox
       command: ["sleep"]
       args: ["infinity"] 
       volumeMounts:
       - name: gcs-fuse-csi-ephemeral
         mountPath: /data
         readOnly: true
     serviceAccountName: KSA_NAME
     volumes:
     - name: gcs-fuse-csi-ephemeral
       csi:
         driver: gcsfuse.csi.storage.gke.io
         readOnly: true
         volumeAttributes:
           bucketName: BUCKET_NAME
           mountOptions: "implicit-dirs" 
   

   다음 값을 바꿉니다.

   • NAMESPACE: 포드를 배포할 Kubernetes 네임스페이스입니다.
   • KSA_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Kubernetes ServiceAccount의 이름입니다.
   • BUCKET_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Cloud Storage 버킷 이름입니다. Kubernetes ServiceAccount가 액세스할 수 있는 모든 버킷을 마운트하도록 밑줄 (_)을 지정할 수 있습니다. 자세한 내용은 Cloud Storage FUSE 문서의 동적 마운트를 참고하세요.

   다음은 필수 설정을 보여주는 예시 매니페스트입니다.

   • metadata.annotations: 주석 gke-gcsfuse/volumes: "true"는 필수 항목입니다. 선택적 주석은 사이드카 컨테이너 구성을 참고하세요.
   • spec.volumes[n].csi.driver: gcsfuse.csi.storage.gke.io를 CSI 드라이버 이름으로 사용합니다.

   원하는 경우 다음 변수를 조정할 수 있습니다.

   • spec.terminationGracePeriodSeconds: 기본값은 30으로 설정됩니다. Cloud Storage 버킷에 대용량 파일을 써야 하는 경우 애플리케이션이 종료된 후 Cloud Storage FUSE가 데이터를 플러시할 시간이 충분하도록 이 값을 늘립니다. 자세한 내용은 Kubernetes 권장사항: 정상적으로 종료를 참고하세요.
   • spec.volumes[n].csi.volumeAttributes.mountOptions: Cloud Storage FUSE에 마운트 옵션을 전달합니다. 공백 없이 쉼표로 구분된 하나의 문자열에 플래그를 지정합니다.
   • spec.volumes[n].csi.volumeAttributes: Cloud Storage FUSE에 추가 볼륨 속성을 전달합니다.
   • spec.volumes[n].csi.readOnly: 모든 볼륨 마운트가 읽기 전용인 경우 true를 지정합니다.
   • spec.containers[n].volumeMounts[m].readOnly: 특정 볼륨 마운트만 읽기 전용인 경우 true를 지정합니다.

2. 다음 명령어를 실행하여 매니페스트를 클러스터에 적용합니다.

   kubectl apply -f FILE_PATH
   

   FILE_PATH를 YAML 파일의 경로로 바꿉니다.

포드 (파일 캐싱)

포드에서 파일 캐싱이 포함된 CSI 임시 볼륨을 연결하려면 다음 단계를 따르세요.

1. 로컬 SSD 지원 임시 스토리지로 클러스터 또는 노드 풀 만들기의 단계에 따라 로컬 SSD 지원 임시 스토리지가 있는 클러스터 또는 노드 풀을 만듭니다.

   참고: 파일 캐시의 저장소 유형을 미세 조정하려면(예: TPU VM을 사용 중이고 더 빠른 처리를 위해 RAM을 사용하려는 경우) 파일 캐시 백업을 위한 저장소 선택을 참고하세요.

2. 다음 사양으로 포드 YAML 매니페스트를 만듭니다.

   apiVersion: v1
   kind: Pod
   metadata:
     name: gcs-fuse-csi-file-cache-example 
     namespace: NAMESPACE
     annotations:
       gke-gcsfuse/volumes: "true"
       gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
   spec:
     nodeSelector:
       cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
     restartPolicy: Never
     initContainers:
     - name: data-loader
       image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
       resources:
         limits:
           cpu: 500m
           memory: 1Gi
         requests:
           cpu: 500m
           memory: 1Gi
       command:
         - "/bin/sh"
         - "-c"
         - |
           mkdir -p /test_files
           for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
           gcloud storage cp /test_files gs://BUCKET_NAME --recursive
     containers:
     - name: data-validator
       image: busybox
       resources:
         limits:
           cpu: 500m
           memory: 512Mi
         requests:
           cpu: 500m
           memory: 512Mi
       command:
         - "/bin/sh"
         - "-c"
         - |
           echo "first read with cache miss"
           time cat /data/test_files/file_* > /dev/null
   
           echo "second read from local cache"
           time cat /data/test_files/file_* > /dev/null 
       volumeMounts:
       - name: gcs-fuse-csi-ephemeral
         mountPath: /data
     serviceAccountName: KSA_NAME
     volumes:
     - name: gcs-fuse-csi-ephemeral
       csi:
         driver: gcsfuse.csi.storage.gke.io
         volumeAttributes:
           bucketName: BUCKET_NAME
           mountOptions: "implicit-dirs,file-cache:max-size-mb:-1"
   

   다음 값을 바꿉니다.

   • NAMESPACE: 포드를 배포할 Kubernetes 네임스페이스입니다.
   • KSA_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Kubernetes ServiceAccount의 이름입니다.

   • BUCKET_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Cloud Storage 버킷 이름입니다. Kubernetes ServiceAccount가 액세스할 수 있는 모든 버킷을 마운트하도록 밑줄 (_)을 지정할 수 있습니다. 자세한 내용은 Cloud Storage FUSE 문서의 동적 마운트를 참고하세요.

     이 매니페스트 예시에서 초기화 컨테이너 data-loader는 크기가 64KiB인 파일 1,000개를 생성하고 파일을 Cloud Storage 버킷에 업로드합니다. 기본 컨테이너 data-validator는 버킷의 모든 파일을 두 번 읽고 시간을 기록합니다.

3. 다음 명령어를 실행하여 매니페스트를 클러스터에 적용합니다.

   kubectl apply -f FILE_PATH
   

   FILE_PATH를 YAML 파일의 경로로 바꿉니다.

4. 로그 출력을 보려면 다음 명령어를 실행합니다.

   kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator
   

   NAMESPACE를 워크로드의 네임스페이스로 바꿉니다.

   출력은 다음과 비슷하게 표시됩니다.

   first read with cache miss
   real    0m 54.68s
   ...
   second read from local cache
   real    0m 0.38s
   ...
   

   출력에는 로컬 캐시를 사용하는 두 번째 읽기가 캐시 부적중이 있는 첫 번째 읽기보다 훨씬 빠른 것으로 나타납니다.

포드 (동시 다운로드)

포드에서 병렬 다운로드와 함께 CSI 임시 볼륨을 연결하려면 다음 단계를 따르세요.

1. 다음 사양으로 포드 YAML 매니페스트를 만듭니다.

   apiVersion: v1
   kind: Pod
   metadata:
     name: gcs-fuse-csi-example-ephemeral 
     namespace: NAMESPACE
     annotations:
       gke-gcsfuse/volumes: "true"
       gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
   spec:
     containers:
     ...
     volumes:
     - name: gcs-fuse-csi-ephemeral 
       csi:
         driver: gcsfuse.csi.storage.gke.io
         volumeAttributes:
           bucketName: BUCKET_NAME
           mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:max-size-mb:-1"
           fileCacheCapacity: "-1"
   

   다음 값을 바꿉니다.

   • NAMESPACE: 포드를 배포할 Kubernetes 네임스페이스입니다.
   • BUCKET_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Cloud Storage 버킷 이름입니다. Kubernetes ServiceAccount가 액세스할 수 있는 모든 버킷을 마운트하도록 밑줄 (_)을 지정할 수 있습니다. 자세한 내용은 Cloud Storage FUSE 문서의 동적 마운트를 참고하세요.

2. 다음 명령어를 실행하여 매니페스트를 클러스터에 적용합니다.

   kubectl apply -f FILE_PATH
   

   FILE_PATH를 YAML 파일의 경로로 바꿉니다.

작업

작업에서 CSI 임시 볼륨을 연결하려면 다음 단계를 따르세요.

1. 다음 사양으로 작업 YAML 매니페스트를 만듭니다.

   apiVersion: batch/v1
   kind: Job
   metadata:
     name: gcs-fuse-csi-job-example 
     namespace: NAMESPACE 
   spec:
     template:
       metadata: 
         annotations:
           gke-gcsfuse/volumes: "true"
       spec:
         serviceAccountName: KSA_NAME 
         containers:
         - name: writer
           image: busybox
           command:
             - "/bin/sh"
             - "-c"
             - touch /data/test && echo $(date) >> /data/test && sleep 10
           volumeMounts:
           - name: gcs-fuse-csi-ephemeral
             mountPath: /data
         - name: reader
           image: busybox
           command:
             - "/bin/sh"
             - "-c"
             - sleep 10 && cat /data/test 
           volumeMounts:
           - name: gcs-fuse-csi-ephemeral
             mountPath: /data
             readOnly: true
         volumes:
         - name: gcs-fuse-csi-ephemeral
           csi:
             driver: gcsfuse.csi.storage.gke.io
             volumeAttributes:
               bucketName: BUCKET_NAME
         restartPolicy: Never 
     backoffLimit: 1
   

   다음 값을 바꿉니다.

   • NAMESPACE: 포드를 배포하는 Kubernetes 네임스페이스입니다.
   • KSA_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Kubernetes ServiceAccount의 이름입니다.
   • BUCKET_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Cloud Storage 버킷 이름입니다. Kubernetes ServiceAccount가 액세스할 수 있는 모든 버킷을 마운트하도록 밑줄 (_)을 지정할 수 있습니다. 자세한 내용은 Cloud Storage FUSE 문서의 동적 마운트를 참고하세요.

   다음은 필수 설정을 보여주는 예시 매니페스트입니다.

   • metadata.annotations: 주석 gke-gcsfuse/volumes: "true"는 필수 항목입니다. 선택적 주석은 사이드카 컨테이너 구성을 참고하세요.
   • spec.volumes[n].csi.driver: gcsfuse.csi.storage.gke.io를 CSI 드라이버 이름으로 사용합니다.

   원하는 경우 다음 변수를 조정할 수 있습니다.

   • spec.volumes[n].csi.volumeAttributes.mountOptions: Cloud Storage FUSE에 마운트 옵션을 전달합니다. 공백 없이 쉼표로 구분된 하나의 문자열에 플래그를 지정합니다.
   • spec.volumes[n].csi.volumeAttributes: Cloud Storage FUSE에 추가 볼륨 속성을 전달합니다.
   • spec.volumes[n].csi.readOnly: 모든 볼륨 마운트가 읽기 전용인 경우 true를 지정합니다.
   • spec.containers[n].volumeMounts[m].readOnly: 특정 볼륨 마운트만 읽기 전용인 경우 true를 지정합니다.

2. 다음 명령어를 실행하여 매니페스트를 클러스터에 적용합니다.

   kubectl apply -f FILE_PATH
   

   FILE_PATH를 YAML 파일의 경로로 바꿉니다.

문제 해결하기

Cloud Storage FUSE 문제를 해결해야 하는 경우 log-severity 플래그를 TRACE로 설정할 수 있습니다. 배포 YAML 내에서 드라이버의 컨테이너 사양 args 섹션에 플래그를 설정합니다. 그러면 gcsfuseLoggingSeverity 볼륨 속성이 자동으로 trace로 설정됩니다.

추가 문제 해결 도움말은 GitHub 프로젝트 문서의 문제 해결 가이드를 참고하세요.

다음 단계

• Cloud Storage FUSE CSI 드라이버의 성능을 최적화하는 방법을 알아봅니다.
• GitHub에서 CSI 드라이버 사용을 위한 추가 샘플 살펴보기
• Cloud Storage Fuse 자세히 알아보기