Cloud Storage 버킷을 영구 볼륨으로 마운트

이 가이드에서는 Cloud Storage 버킷에서 지원하는 Kubernetes 영구 볼륨을 사용하여 Google Kubernetes Engine(GKE)에서 Kubernetes 포드의 스토리지 리소스를 관리하는 방법을 보여줍니다. 이미 PersistentVolume에 익숙하며 이 리소스 유형을 사용하는 기존 배포와 일관성을 유지하려는 경우에 이 스토리지 옵션을 사용하는 것이 좋습니다.

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

이 페이지를 읽기 전에 Kubernetes 영구 볼륨, Kubernetes 포드, Cloud Storage 버킷을 숙지해야 합니다.

Kubernetes 영구 볼륨에 대한 경험이 필요 없는 간소화된 포드 기반 인터페이스를 사용하려면 Cloud Storage 버킷을 CSI 임시 볼륨으로 마운트를 참조하세요.

시작하기 전에

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

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

Cloud Storage 버킷 영구 볼륨 작동 방식

정적 프로비저닝을 사용하면 기본 스토리지 시스템의 세부정보가 포함된 PersistentVolume 객체를 하나 이상 만듭니다. 그러면 클러스터의 포드가 PersistentVolumeClaims를 통해 스토리지를 사용할 수 있습니다.

Cloud Storage 버킷에서 지원하는 영구 볼륨을 사용하려면 다음 작업을 수행해야 합니다.

1. 스토리지 정의: 사용할 CSI 드라이버와 필요한 모든 파라미터를 포함하여 GKE 클러스터에서 PersistentVolume을 정의합니다. Cloud Storage FUSE CSI 드라이버의 경우 버킷 이름과 기타 관련 세부정보를 지정합니다.

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

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

2. 드라이버 호출: PersistentVolumeClaim에서 PersistentVolume 사양과 일치하는 스토리지를 요청하면 GKE는 Cloud Storage FUSE CSI 드라이버를 호출합니다.

3. 버킷 마운트: CSI 드라이버는 요청 포드가 예약된 노드에 버킷을 마운트합니다. 이렇게 하면 버킷 콘텐츠가 포드 로컬 파일 시스템에 있는 디렉터리로 포드에 액세스할 수 있습니다. 버킷이 파일 시스템에 마운트되는 방식을 미세 조정하려면 마운트 옵션을 사용하면 됩니다. 볼륨 속성을 사용하여 Cloud Storage FUSE CSI 드라이버의 특정 동작을 구성할 수도 있습니다.

4. 재연결: 포드가 다시 시작되거나 다른 노드로 다시 예약되면 CSI 드라이버가 같은 버킷을 새 노드에 다시 마운트하여 데이터 접근성을 보장합니다.

PersistentVolume 만들기

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

   포드

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: gcs-fuse-csi-pv
   spec:
     accessModes:
     - ReadWriteMany
     capacity:
       storage: 5Gi
     storageClassName: example-storage-class  
     mountOptions:
       - implicit-dirs
     csi:
       driver: gcsfuse.csi.storage.gke.io
       volumeHandle: BUCKET_NAME
     claimRef:
       name: gcs-fuse-csi-static-pvc
       namespace: NAMESPACE  
   

   다음 값을 바꿉니다.

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

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

   • spec.csi.driver: gcsfuse.csi.storage.gke.io를 CSI 드라이버 이름으로 사용합니다.

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

   • spec.mountOptions: 마운트 옵션을 Cloud Storage FUSE에 전달합니다. 공백 없이 쉼표로 구분된 하나의 문자열에 플래그를 지정합니다.
   • spec.csi.volumeAttributes: Cloud Storage FUSE에 추가 볼륨 속성을 전달합니다.

   포드(파일 캐싱)

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: gcs-fuse-csi-pv
   spec:
     accessModes:
     - ReadWriteMany
     capacity:
       storage: 5Gi
     storageClassName: example-storage-class 
     mountOptions:
       - implicit-dirs
       - file-cache:max-size-mb:-1
     csi:
       driver: gcsfuse.csi.storage.gke.io
       volumeHandle: BUCKET_NAME
     claimRef:
       name: gcs-fuse-csi-static-pvc
       namespace: NAMESPACE 
   

   다음 값을 바꿉니다.

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

   포드(동시 다운로드)

   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: gcs-fuse-csi-pv
   spec:
     accessModes:
     - ReadWriteMany
     capacity:
       storage: 5Gi
     storageClassName: example-storage-class 
     mountOptions:
       - implicit-dirs
       - file-cache:enable-parallel-downloads:true
       - file-cache:max-size-mb:-1
     csi:
       driver: gcsfuse.csi.storage.gke.io
       volumeHandle: BUCKET_NAME
     claimRef:
       name: gcs-fuse-csi-static-pvc
       namespace: NAMESPACE 
   

   다음 값을 바꿉니다.

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

2. 클러스터에 매니페스트를 적용합니다.

   kubectl apply -f PV_FILE_PATH
   

   PV_FILE_PATH를 YAML 파일 경로로 바꿉니다.

PersistentVolumeClaim 만들기

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

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: gcs-fuse-csi-static-pvc
     namespace: NAMESPACE
   spec:
     accessModes:
     - ReadWriteMany
     resources:
       requests:
         storage: 5Gi
     storageClassName: example-storage-class
   

   NAMESPACE를 포드를 배포하려는 Kubernetes 네임스페이스로 바꿉니다.

   PersistentVolume을 PersistentVolumeClaim에 바인딩하려면 다음 구성 설정을 확인합니다.

   • PersistentVolume 및 PersistentVolumeClaim 매니페스트의 spec.storageClassName 필드가 일치해야 합니다. storageClassName은 기존 StorageClass 객체를 참조할 필요가 없습니다. 클레임을 볼륨에 바인딩하려면 원하는 이름을 사용하면 되지만 비워 둘 수는 없습니다.
   • PersistentVolume 및 PersistentVolumeClaim 매니페스트의 spec.accessModes 필드가 일치해야 합니다.
   • PersistentVolume 매니페스트의 spec.capacity.storage 필드는 PersistentVolumeClaim 매니페스트의 spec.resources.requests.storage와 일치해야 합니다. Cloud Storage 버킷에는 크기 제한이 없으므로 원하는 용량을 입력할 수 있지만 비워 둘 수는 없습니다.

2. 클러스터에 매니페스트를 적용합니다.

   kubectl apply -f PVC_FILE_PATH
   

   PVC_FILE_PATH를 YAML 파일 경로로 바꿉니다.

포드에서 볼륨 사용

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

   apiVersion: v1
   kind: Pod
   metadata:
     name: gcs-fuse-csi-example-static-pvc  
     namespace: NAMESPACE
     annotations:
       gke-gcsfuse/volumes: "true"
   spec:
     containers:
     - image: busybox
       name: busybox
       command: ["sleep"]
       args: ["infinity"]
       volumeMounts:
       - name: gcs-fuse-csi-static
         mountPath: /data
         readOnly: true
     serviceAccountName: KSA_NAME
     volumes:
     - name: gcs-fuse-csi-static
       persistentVolumeClaim:
         claimName: gcs-fuse-csi-static-pvc
         readOnly: true  
   

   다음 값을 바꿉니다.

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

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

   • metadata.annotations: 주석 gke-gcsfuse/volumes: "true"는 필수 항목입니다. 선택적 주석은 사이드카 컨테이너 구성을 참조하세요.

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

   • spec.containers[n].volumeMonts[n].readOnly: 특정 볼륨 마운트가 읽기 전용인 경우에만 true를 지정합니다.
   • spec.volumes[n].persistentVolumeClaim.readOnly: 모든 볼륨 마운트가 읽기 전용인 경우에 true를 지정합니다.

2. 클러스터에 매니페스트를 적용합니다.

   kubectl apply -f POD_FILE_PATH
   

   POD_FILE_PATH를 YAML 파일 경로로 바꿉니다.

(선택사항) GKE 버전 1.33.0-gke.1932000부터 시작할 수 있는 다른 영구 볼륨 {:#mount-same-bucket-different-pv}로 같은 Cloud Storage 버킷 마운트

서로 다른 영구 볼륨 여러 개를 사용하여 같은 Cloud Storage 버킷을 마운트하려면 각 영구 볼륨에 고유한 volumeHandle를 사용해야 합니다. PersistentVolume 객체에서 volumeHandle 필드에 BUCKET_NAME:UNIQUE_SUFFIX 형식을 사용합니다. BUCKET_NAME을 버킷 이름으로, UNIQUE_SUFFIX를 원하는 고유 식별자로 바꿉니다. 예: myBucket:xyz123

사용 사례 예시는 같은 Cloud Storage 버킷을 같은 노드에 여러 번 마운트하고 각 버킷에 고유한 마운트 옵션 집합을 사용할 수 있습니다.

문제해결

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

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

다음 단계

• Cloud Storage FUSE CSI 드라이버 성능을 최적화하는 방법 알아보기
• GitHub에서 CSI 드라이버를 사용할 수 있도록 추가 샘플 살펴보기
• Cloud Storage Fuse 자세히 알아보기