Cloud Storage FUSE CSI 드라이버로 Cloud Storage 버킷에 액세스

사용자 공간의 파일 시스템(FUSE)은 파일 시스템을 Linux 커널로 내보내는 데 사용되는 인터페이스입니다. Cloud Storage FUSE를 사용하면 Cloud Storage 버킷을 파일 시스템으로 마운트하여 애플리케이션에서 클라우드 관련 API를 사용하지 않고 일반적인 파일 IO 작업(예: 열기, 읽기, 쓰기, 닫기)을 사용하여 버킷의 객체에 액세스할 수 있습니다.

Cloud Storage FUSE CSI 드라이버를 사용하면 Kubernetes API를 사용하여 기존 Cloud Storage 버킷을 볼륨으로 사용할 수 있습니다. 애플리케이션은 Cloud Storage FUSE 파일 시스템 시맨틱스를 사용하여 객체를 업로드 및 다운로드할 수 있습니다. Cloud Storage FUSE CSI 드라이버는 오픈소스 Google Cloud Storage FUSE CSI 드라이버를 기반으로 하는 완전 관리형 환경을 제공합니다.

이 드라이버는 기본적으로 다음과 같은 Cloud Storage 지원 볼륨을 구성하는 방법을 지원합니다.

Cloud Storage FUSE CSI 드라이버를 파일 캐싱과 함께 사용하면 Cloud Storage 버킷에서 작은 파일을 처리하는 애플리케이션의 읽기 성능을 향상시킬 수 있습니다. Cloud Storage FUSE 파일 캐시 기능은 개발자가 선택한 캐시 스토리지에서 더 빠른 파일 반복 읽기를 제공하는 클라이언트 기반 읽기 캐시입니다 가격 대비 성능 니즈에 따라 로컬 SSD 및 영구 디스크 기반 스토리지를 포함하여 읽기 캐시를 위한 다양한 스토리지 옵션 중에서 선택할 수 있습니다. Cloud Storage FUSE CSI 드라이버로 파일 캐싱을 사용 설정하도록 선택해야 합니다. 캐싱 권장사항에 대한 자세한 내용은 Cloud Storage FUSE 성능 및 권장사항을 참조하세요.

혜택

  • 클러스터의 Cloud Storage FUSE CSI 드라이버는 드라이버의 자동 배포 및 관리를 사용 설정합니다. 드라이버는 Standard 및 Autopilot 클러스터 모두에서 작동합니다.
  • Cloud Storage FUSE CSI 드라이버는 일반적으로 FUSE 클라이언트에 필요한 액세스 권한이 필요하지 않습니다. 이를 통해 보안 상황을 개선할 수 있습니다.
  • CSI 임시 볼륨을 지원하면 PersistentVolumeClaim 및 PersistentVolume 객체가 필요하지 않아 볼륨 구성 및 관리가 간소화됩니다.
  • Cloud Storage FUSE CSI 드라이버는 ReadWriteMany, ReadOnlyMany, ReadWriteOnce 액세스 모드를 지원합니다.
  • GKE용 워크로드 아이덴티티 제휴를 사용하여 포드에서 Cloud Storage 객체에 액세스하는 방법을 세밀하게 제어하면서 인증을 관리할 수 있습니다.
  • Ray, PyTorch, Spark, TensorFlow와 같은 프레임워크로 ML 학습 및 서빙 워크로드를 실행하는 경우 Cloud Storage FUSE CSI 드라이버에서 제공하는 이동성과 단순성을 통해 코드를 추가로 변경하지 않고 GKE 클러스터에서 직접 워크로드를 실행할 수 있습니다.
  • 파일 캐싱을 사용 설정하여 Cloud Storage 객체를 읽으면 읽기 성능을 향상시킬 수 있습니다. 파일 캐싱의 이점에 대한 자세한 내용은 Cloud Storage FUSE 문서를 참조하세요.
  • 초기화 컨테이너에서 Cloud Storage FUSE 볼륨을 사용할 수 있습니다.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

  • Google Kubernetes Engine API를 사용 설정합니다.
    • Google Kubernetes Engine API 사용 설정
  • 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.
  • Cloud Storage 버킷 생성. 성능을 향상시키려면 Location type 필드를 Region으로 설정하고 GKE 클러스터가 실행 중인 리전을 선택합니다.

제한사항

  • Cloud Storage FUSE 파일 시스템은 POSIX 파일 시스템과 비교하여 성능, 가용성, 액세스 승인, 시맨틱스에 차이가 있습니다.
  • GKE Sandbox에서는 Cloud Storage FUSE CSI 드라이버가 지원되지 않습니다.
  • Cloud Storage FUSE CSI 드라이버는 볼륨 스냅샷, 볼륨 클론 또는 볼륨 확장을 지원하지 않습니다.
  • Cloud Storage FUSE CSI 드라이버 GitHub 프로젝트에서 알려진 문제를 참조하세요.
  • Cloud Storage FUSE CSI 드라이버 GitHub 프로젝트에서 미해결 문제를 참조하세요. 문제가 분류되고 있으며 향후 업데이트에서 해결될 예정입니다.

요구사항

Cloud Storage FUSE CSI 드라이버를 사용하려면 클러스터가 다음 요구사항을 충족해야 합니다.

Cloud Storage FUSE CSI 드라이버 사용 설정

Cloud Storage FUSE CSI 드라이버가 사용 설정된 Standard 클러스터를 만들려면 gcloud CLI를 사용하면 됩니다.

gcloud container clusters create CLUSTER_NAME \
    --addons GcsFuseCsiDriver \
    --cluster-version=VERSION \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

다음을 바꿉니다.

  • CLUSTER_NAME: 클러스터 이름
  • VERSION: GKE 버전 번호. 1.24 이상을 선택해야 합니다.
  • LOCATION: 클러스터의 Compute Engine 위치
  • PROJECT_ID: 프로젝트 ID

기존 Standard 클러스터에서 드라이버를 사용 설정하려면 gcloud container clusters update 명령어를 사용합니다.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=ENABLED \
    --location=LOCATION

다음을 바꿉니다.

  • CLUSTER_NAME: 클러스터의 이름입니다.
  • LOCATION: 클러스터의 Compute Engine 위치입니다.

Cloud Storage FUSE CSI 드라이버를 사용 설정한 후에는 드라이버와 프로비저닝 도구 이름(gcsfuse.csi.storage.gke.io)을 지정하여 Kubernetes 볼륨에서 드라이버를 사용할 수 있습니다.

GKE용 GKE 워크로드 아이덴티티 제휴를 사용하여 Cloud Storage 버킷에 대한 액세스 구성

GKE용 워크로드 아이덴티티 제휴를 사용하여 GKE 클러스터에서 Cloud Storage 버킷에 액세스할 수 있게 하려면 다음 단계를 수행합니다. 자세한 내용은 GKE용 워크로드 아이덴티티 제휴를 사용하도록 애플리케이션 구성을 참조하세요.

  1. 클러스터의 사용자 인증 정보를 가져옵니다.

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    다음을 바꿉니다.

    • CLUSTER_NAME: GKE용 워크로드 아이덴티티 제휴가 사용 설정된 클러스터의 이름
    • LOCATION: 클러스터의 Compute Engine 위치

  2. Kubernetes ServiceAccount에 사용할 네임스페이스를 만듭니다. default 네임스페이스 또는 기존 네임스페이스를 사용할 수도 있습니다.

    kubectl create namespace NAMESPACE

    다음을 바꿉니다.

    • NAMESPACE: Kubernetes ServiceAccount의 Kubernetes 네임스페이스 이름

  3. 애플리케이션이 사용할 Kubernetes ServiceAccount를 만듭니다. 또한 default Kubernetes ServiceAccount을 포함하여 모든 네임스페이스에서 기존 Kubernetes ServiceAccount을 사용할 수 있습니다.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    다음을 바꿉니다.

    • KSA_NAME: 새 Kubernetes ServiceAccount의 이름
    • NAMESPACE: Kubernetes ServiceAccount의 Kubernetes 네임스페이스 이름

  4. Cloud Storage에 대한 IAM 역할 중 하나를 Kubernetes ServiceAccount에 부여합니다.

    다음 명령어를 사용하면 특정 Cloud Storage 버킷에만 액세스하도록 Kubernetes ServiceAccount에 역할을 부여할 수 있습니다.

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    다음을 바꿉니다.

    • BUCKET_NAME: Cloud Storage 버킷 이름
    • PROJECT_NUMBER: GKE 클러스터의 숫자 프로젝트 번호. 프로젝트 번호를 찾으려면 프로젝트 식별을 참조하세요.
    • PROJECT_ID: GKE 클러스터의 프로젝트 ID
    • NAMESPACE: Kubernetes ServiceAccount의 Kubernetes 네임스페이스 이름
    • KSA_NAME: 새 Kubernetes ServiceAccount의 이름
    • ROLE_NAME: Kubernetes ServiceAccount에 할당할 IAM 역할
      • 읽기 전용 워크로드의 경우 스토리지 객체 뷰어 역할(roles/storage.objectViewer)을 사용합니다.
      • 읽기-쓰기 워크로드의 경우 스토리지 객체 사용자 역할(roles/storage.objectUser)을 사용합니다.

    원하는 경우 다음 명령어를 사용하여 프로젝트의 모든 Cloud Storage 버킷에 액세스하도록 Kubernetes ServiceAccount에 역할을 부여할 수 있습니다.

    gcloud projects add-iam-policy-binding GCS_PROJECT \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    다음을 바꿉니다.

    • GCS_PROJECT: Cloud Storage 버킷의 프로젝트 ID
    • PROJECT_NUMBER: GKE 클러스터의 숫자 프로젝트 번호. 프로젝트 번호를 찾으려면 프로젝트 식별을 참조하세요.
    • PROJECT_ID: GKE 클러스터의 프로젝트 ID
    • NAMESPACE: Kubernetes ServiceAccount의 Kubernetes 네임스페이스 이름
    • KSA_NAME: 새 Kubernetes ServiceAccount의 이름
    • ROLE_NAME: Kubernetes ServiceAccount에 할당할 IAM 역할
      • 읽기 전용 워크로드의 경우 스토리지 객체 뷰어 역할(roles/storage.objectViewer)을 사용합니다.
      • 읽기-쓰기 워크로드의 경우 스토리지 객체 사용자 역할(roles/storage.objectUser)을 사용합니다.

Cloud Storage FUSE 버킷 마운트 준비

이 섹션에서는 클러스터에 Cloud Storage FUSE 버킷을 마운트할 준비를 하는 방법을 설명합니다.

포드 주석 지정

CSI 드라이버는 포드가 Cloud Storage 지원 볼륨을 사용하는지 확인하기 위해 포드 주석을 사용합니다. 드라이버가 필요한 주석을 감지하면 gke-gcsfuse-sidecar라는 사이드카 컨테이너를 워크로드 포드에 삽입합니다. Cloud Storage FUSE 인스턴스는 사이드카 컨테이너 내에서 실행되고 워크로드를 위해 Cloud Storage 버킷을 마운트합니다.

CSI 드라이버가 Cloud Storage 버킷을 마운트할 수 있도록 하려면 포드 사양의 metadata 필드에서 gke-gcsfuse/volumes: "true" 주석을 지정해야 합니다. Cloud Storage 지원 볼륨을 다른 Kubernetes 워크로드 유형(예: 작업, 배포 또는 StatefulSet)에서 사용하려면 spec.template.metadata.annotations 필드에서 주석을 구성해야 합니다.

사이드카 컨테이너의 리소스 구성

기본적으로 사이드카 컨테이너는 다음 리소스 요청에 따라 구성되지만 리소스 한도에 제한이 없습니다.

  • 250m CPU
  • 256MiB 메모리
  • 5GiB 임시 스토리지

이러한 값을 재정의하려면 다음 예시에 표시된 것처럼 gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] 주석을 선택적으로 지정할 수 있습니다.

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

할당할 리소스 양을 결정할 때 다음 사항을 고려하세요.

  • 리소스 요청 중 하나만 설정하거나 주석을 제한하는 경우 GKE가 리소스 요청 및 리소스 한도에 동일한 값을 적용합니다.
  • 워크로드 포드가 여러 Cloud Storage 볼륨을 사용하는 경우 사이드카 컨테이너 리소스는 여러 Cloud Storage FUSE 인스턴스에서 공유됩니다. 이 경우에 해당하면 여러 Cloud Storage 볼륨을 위해 리소스 할당을 늘리는 것이 좋습니다.
  • 워크로드에 더 높은 처리량이 필요한 경우 사이드카 컨테이너에 더 많은 CPU를 할당합니다. CPU가 부족하면 Cloud Storage FUSE가 제한됩니다.
  • 워크로드가 대량의 파일을 처리해야 하고 Cloud Storage FUSE 메타데이터 캐싱이 사용 설정된 경우 사이드카 컨테이너의 메모리 할당을 늘립니다. 메타데이터 캐싱의 Cloud Storage FUSE 메모리 소비는 파일 수에 비례하지만 파일 크기에 비례하지 않습니다. 메모리가 부족하면 Cloud Storage FUSE 메모리 부족 오류가 발생하고 워크로드 애플리케이션이 비정상 종료됩니다.
  • 파일 캐싱의 경우 Cloud Storage FUSE는 기본적으로 파일을 로컬 임시 디렉터리에 캐시합니다. 파일 캐싱을 위해 워크로드에 필요한 여유 공간을 추정하고 이에 따라 임시 스토리지 한도를 늘립니다. 자세한 내용은 볼륨 속성을 참조하세요.
  • 쓰기 작업의 경우, 기본적으로 파일을 Cloud Storage 버킷에 업로드하기 전에 Cloud Storage FUSE가 로컬 임시 디렉터리의 파일을 스테이징합니다. 대용량 파일을 작성할 때 워크로드를 준비하는 데 필요한 여유 공간을 추정하고 이에 따라 임시 스토리지 한도를 늘립니다. 자세한 내용은 Cloud Storage FUSE GitHub 문서의 읽기/쓰기 시맨틱스를 참조하세요.
  • "0" 값을 사용하여 Standard 클러스터에 대해 리소스 한도 또는 요청 설정을 취소할 수 있습니다. 예를 들어 gke-gcsfuse/memory-limit: "0" 주석은 기본 메모리 요청을 사용해서 사이드카 컨테이너 메모리 한도를 비워 둡니다. 이는 워크로드에 대해 Cloud Storage FUSE에 필요한 리소스 양을 결정할 수 없고 Cloud Storage FUSE가 노드에서 사용 가능한 모든 리소스를 소비하도록 하려는 경우에 유용합니다. 워크로드 측정항목에 따라 Cloud Storage FUSE의 리소스 요구사항을 계산한 후 적절한 한도를 설정할 수 있습니다.

사이드카 컨테이너의 비공개 이미지 구성

이 섹션에서는 비공개 Container Registry에서 호스팅하는 경우 사이드카 컨테이너 이미지를 사용하는 방법을 설명합니다. 이 시나리오는 보안 목적으로 비공개 클러스터를 사용해야 하거나 클러스터가 공개 인터넷에 대한 액세스가 제한된 경우에 적용될 수 있습니다. 비공개 사이드카 컨테이너 이미지를 구성하고 사용하려면 다음 단계를 따르세요.

  1. 호환되는 공개 사이드카 컨테이너 이미지를 찾으려면 이 페이지를 참조하세요.

  2. 로컬 환경으로 가져와서 비공개 Container Registry로 푸시합니다.

  3. 매니페스트에서 image 필드만 포함하는 gke-gcsfuse-sidecar라는 컨테이너를 지정합니다. GKE는 지정된 사이드카 컨테이너 이미지를 사용하여 사이드카 컨테이너 삽입을 준비합니다. 예를 들면 다음과 같습니다.

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

다음을 바꿉니다.

  • PRIVATE_REGISTRY: 비공개 Container Registry입니다.
  • PRIVATE_IMAGE_TAG: 비공개 사이드카 컨테이너 이미지 태그입니다.

사이드카 컨테이너의 커스텀 쓰기 버퍼 볼륨 구성

이 섹션에서는 Cloud Storage FUSE 쓰기 버퍼링을 위해 커스텀 버퍼 볼륨을 구성하는 방법을 설명합니다. 이 시나리오는 Cloud Storage FUSE가 쓰기 작업에서 파일을 스테이징하기 위해 기본 emptyDir 볼륨을 바꿔야 하는 경우에 적용될 수 있습니다. PersistentVolumeClaim과 같이 GKE에서 지원되는 스토리지 유형을 지정할 수 있으며, GKE는 파일 쓰기 버퍼링을 위해 지정된 볼륨을 사용합니다. 이는 Autopilot 클러스터에서 10GiB가 넘는 파일을 기록해야 할 때 유용합니다. 커스텀 버퍼 볼륨을 사용하려면 0이 아닌 fsGroup을 지정해야 합니다. 다음 예시에서는 사전 정의된 PVC를 버퍼 볼륨으로 사용하는 방법을 보여줍니다.

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

다음을 바꿉니다.

  • FS_GROUP: fsGroup ID입니다.
  • BUFFER_VOLUME_PVC: 사전 정의된 PVC 이름입니다.

사이드카 컨테이너의 커스텀 읽기 캐시 볼륨 구성

이 섹션에서는 Cloud Storage FUSE 읽기 캐싱을 위해 커스텀 캐시 볼륨을 구성하는 방법에 대해 설명합니다. 이 시나리오는 Cloud Storage FUSE가 읽기 작업에서 파일을 캐시하기 위해 기본 emptyDir 볼륨을 바꿔야 하는 경우에 적용될 수 있습니다. PersistentVolumeClaim과 같이 GKE에서 지원되는 스토리지 유형을 지정할 수 있으며, GKE는 파일 캐싱을 위해 지정된 볼륨을 사용합니다. 이는 Autopilot 클러스터에서 10GiB가 넘는 파일을 캐시해야 할 때 유용합니다. 커스텀 캐시 볼륨을 사용하려면 0이 아닌 fsGroup을 지정해야 합니다. 다음 예시에서는 사전 정의된 PVC를 캐시 볼륨으로 사용하는 방법을 보여줍니다.

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

다음을 바꿉니다.

  • FS_GROUP: fsGroup ID입니다.
  • CACHE_VOLUME_PVC: 사전 정의된 PVC 이름입니다.

볼륨을 CSI 임시 볼륨으로 프로비저닝

Cloud Storage 버킷에서 지원하는 CSI 임시 볼륨은 포드 수명 주기에 연결됩니다. 이 프로비저닝 방식을 사용하면 포드 종료 후 Cloud Storage 버킷과 연결된 PersistentVolume 및 PersistentVolumeClaim 객체를 유지할 필요가 없습니다.

포드에서 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"
        gcsfuseLoggingSeverity: warning

    이전 예시에서는 포드 매니페스트에서 Cloud Storage 버킷을 인라인으로 지정하는 방법을 보여줍니다. 이 예시에는 다음 필드가 포함되어 있습니다.

    • metadata.annotations: 주석 gke-gcsfuse/volumes: "true"는 필수 항목입니다. 선택적 주석은 사이드카 컨테이너의 리소스 구성을 참조하세요.
    • spec.terminationGracePeriodSeconds: 선택사항입니다. 기본적으로 30으로 설정됩니다. Cloud Storage 버킷에 대용량 파일을 써야 하는 경우 애플리케이션이 종료된 후 Cloud Storage FUSE가 데이터를 플러시할 시간이 충분하도록 이 값을 늘립니다. 자세한 내용은 Kubernetes 권장사항: 정상적으로 종료를 참조하세요.
    • spec.serviceAccountName: GKE용 GKE 워크로드 아이덴티티 제휴를 사용하여 Cloud Storage 버킷에 대한 액세스 구성 단계와 동일한 Kubernetes ServiceAccount를 사용합니다.
    • spec.volumes[n].csi.driver: gcsfuse.csi.storage.gke.io를 CSI 드라이버 이름으로 사용합니다.
    • spec.volumes[n].csi.volumeAttributes.bucketName: Cloud Storage FUSE 버킷 이름을 지정합니다. Kubernetes ServiceAccount가 액세스할 수 있는 모든 버킷을 마운트하도록 밑줄(_)을 지정할 수 있습니다. 자세한 내용은 Cloud Storage FUSE 문서의 동적 마운트를 참조하세요.
    • 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. 다음 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

    다음을 바꿉니다.

    매니페스트는 CSI 임시 볼륨을 통해 Cloud Storage FUSE 버킷을 사용하는 작업을 배포합니다.

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

    kubectl apply -f FILE_PATH

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

Job 워크로드에서 CSI 드라이버를 사용하거나 포드 RestartPolicy가 Never인 경우 사이드카 컨테이너는 다른 모든 워크로드 컨테이너가 종료된 후 자동으로 종료됩니다.

추가 예시는 GitHub 프로젝트 문서의 예시 애플리케이션을 참조하세요.

정적 프로비저닝을 사용하여 볼륨 프로비저닝

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

PersistentVolume 만들기

  1. 다음 YAML 매니페스트를 저장합니다.

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

    예시 매니페스트는 Cloud Storage 버킷에 대해 PersistentVolume을 정의하는 방법을 보여줍니다. 이 예시에는 다음 필드가 포함되어 있습니다.

    • spec.claimRef.namespace: PersistentVolumeClaim 네임스페이스를 지정합니다.
    • spec.claimRef.name: PersistentVolumeClaim 이름을 지정합니다.
    • spec.csi.driver: gcsfuse.csi.storage.gke.io를 CSI 드라이버 이름으로 사용합니다.
    • spec.csi.volumeHandle: Cloud Storage 버킷 이름을 지정합니다. Kubernetes ServiceAccount가 액세스하도록 구성된 모든 버킷을 마운트하기 위해 밑줄(_)을 전달할 수 있습니다. 자세한 내용은 Cloud Storage FUSE 문서의 동적 마운트를 참조하세요.
    • spec.mountOptions: 선택사항. 마운트 옵션을 Cloud Storage FUSE에 전달합니다.
    • spec.csi.volumeAttributes: 선택사항. 볼륨 속성을 Cloud Storage FUSE에 전달합니다.

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

    kubectl apply -f FILE_PATH

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

PersistentVolumeClaim 만들기

  1. 다음 YAML 매니페스트를 저장합니다.

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

    예시 매니페스트는 PersistentVolumeClaim을 정의하여 PersistentVolume을 바인딩하는 방법을 보여줍니다. 이 예시에는 다음 필드가 포함되어 있습니다.

    • metadata.namespace: 워크로드의 네임스페이스와 일치해야 하는 PersistentVolumeClaim 네임스페이스를 지정합니다.
    • spec.volumeName: PersistentVolume 이름을 지정합니다.

    PersistentVolume을 PersistentVolumeClaim에 바인딩하려면 다음 가이드라인을 따라야 합니다.

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

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

    kubectl apply -f FILE_PATH

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

PersistentVolumeClaim에서 볼륨 사용

  1. 다음 YAML 매니페스트를 저장합니다.

    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

    이 예시에서는 PersistentVolumeClaim을 통해 Cloud Storage FUSE 버킷을 사용하는 포드를 정의하는 방법을 보여줍니다. 이 예시에는 다음 필드가 포함됩니다.

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

    kubectl apply -f FILE_PATH

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

추가 예시는 GitHub 프로젝트 문서의 예시 애플리케이션을 참조하세요.

파일 캐싱이 사용 설정된 볼륨 사용

기본적으로 파일 캐싱 기능은 GKE에서 사용 중지되어 있습니다. 파일 캐싱을 사용 설정하고 제어하려면 볼륨 속성 fileCacheCapacity를 사용합니다.

GKE는 노드 VM 부팅 디스크에서 지원하는 Cloud Storage FUSE 파일 캐싱에 emptyDir 볼륨을 사용합니다. 노드에서 로컬 SSD를 사용 설정하면 GKE는 로컬 SSD를 사용하여 emptyDir 볼륨을 지원합니다.

읽기 작업에서 파일 캐싱의 기본 emptyDir 볼륨을 대체하도록 사이드카 컨테이너의 커스텀 읽기 캐시 볼륨을 구성할 수 있습니다. 로컬 SSD를 지원하는 CPU 및 GPU VM 제품군의 경우 로컬 SSD 스토리지를 사용하는 것이 좋습니다. TPU 계열 또는 Autopilot의 경우 균형 있는 영구 디스크 또는 SSD 영구 디스크를 사용하는 것이 좋습니다.

파일 캐싱이 사용 설정된 CSI 임시 스토리지 볼륨 사용

파일 캐싱이 포함된 CSI 임시 볼륨을 통해 Cloud Storage FUSE 버킷을 사용하는 포드를 배포하려면 다음 단계를 따르세요.

  1. 로컬 SSD 지원 임시 스토리지로 클러스터 또는 노드 풀을 만듭니다.

    GKE 문서에 따라 로컬 SSD 지원 임시 스토리지로 클러스터 또는 노드 풀을 만듭니다.

  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
        gsutil -m cp -r /test_files gs://BUCKET_NAME
  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"
        fileCacheCapacity: "10Gi"

    다음을 바꿉니다.

    초기화 컨테이너 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
...

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

Cloud Storage FUSE 버킷을 마운트하는 방법 구성

이 섹션에서는 Cloud Storage FUSE 볼륨을 구성하는 방법을 설명합니다.

마운트 옵션

Cloud Storage FUSE CSI 드라이버는 로컬 파일 시스템에 Cloud Storage 버킷이 마운트되는 방법을 구성하는 마운트 옵션을 지원합니다. 지원되는 마운트 옵션의 전체 목록은 gcsfuse CLI 문서를 참조하세요.

다음과 같은 방법으로 마운트 플래그를 지정할 수 있습니다.

  • 정적 프로비저닝을 사용하는 경우 PersistentVolume 매니페스트의 spec.mountOptions 필드에서
  • CSI 임시 볼륨을 사용하는 경우 spec.volumes[n].csi.volumeAttributes.mountOptions 필드에서

볼륨 속성

Cloud Storage FUSE CSI 드라이버에서는 Cloud Storage FUSE 구성 파일을 직접 지정할 수 없습니다. 다음 볼륨 속성을 사용하여 구성 파일의 일부 필드를 구성할 수 있습니다. 값은 구성 파일 필드로 변환됩니다.

  • gcsfuseLoggingSeverity

    • 설명: Cloud Storage FUSE에서 생성하려는 로그의 심각도이며 enum으로 표시됩니다. 이미 debug_fuse, debug_fs 또는 debug_gcs 마운트 옵션을 사용하고 있는 경우 이 새 구성은 자동으로 trace로 설정됩니다. 이 볼륨 속성은 구성 파일 필드 logging:severity로 변환됩니다.

    • 유효한 값(심각도가 가장 낮은 순에서 높은 순으로 정렬됨):

      • trace
      • debug
      • info
      • warning
      • error

    • 기본값: info

  • fileCacheCapacity

    • 설명: 파일 캐시가 사용할 수 있는 최대 크기입니다. 0이 아닌 값이 있으면 이 볼륨 속성은 Cloud Storage FUSE에서 파일 캐싱을 사용 설정합니다. 이 볼륨 속성은 구성 파일 필드 file-cache:max-size-mb로 변환됩니다.

    • 유효한 값:

      • 수량 값(예: 500Mi, 10Gi)
      • '-1': 캐시 볼륨의 전체 사용 가능 용량을 사용합니다.
      • '0': 파일 캐시가 사용 중지됩니다.

    • 기본값: '0'.

  • fileCacheForRangeRead

    • 설명: 0이 아닌 오프셋에서 첫 번째 읽기를 수행할 때 전체 객체를 비동기식으로 다운로드하여 Cloud Storage FUSE 캐시 디렉터리에 저장해야 하는지 여부입니다. 임의 읽기나 부분 읽기를 여러 번 수행하려면 '참'으로 설정해야 합니다. 이 볼륨 속성은 구성 파일 필드 file-cache:cache-file-for-range-read로 변환됩니다.

    • 유효한 값:

      • 문자열 형식의 불리언 값: 'true', 'false'.

    • 기본값: 'false'.

  • metadataStatCacheCapacity

    • 설명: 통계 캐시가 사용할 수 있는 최대 크기입니다. 통계 캐시는 항상 메모리에 온전히 보관됩니다. stat-cache-capacity 마운트 옵션을 이미 사용 중인 경우 해당 값이 그대로 유지되며 이 새로운 구성으로 적절하게 변환됩니다. 이 볼륨 속성은 구성 파일 필드 metadata-cache:stat-cache-max-size-mb로 변환됩니다.

    • 유효한 값:

      • 수량 값(예: 500Mi, 1Gi)
      • '-1': 통계 캐시에서 필요한 만큼 메모리를 사용하도록 합니다.
      • '0': 통계 캐시가 사용 중지됩니다.
      • 워크로드에 파일이 최대 20,000개까지 포함된 경우 기본값 32Mi를 사용하세요. 워크로드가 파일 20,000개를 초과하면 파일 6,000개가 추가될 때마다 크기가 10MiB씩 증가합니다(파일당 평균은 약 1,500바이트).

    • 기본값: 32Mi

  • metadataTypeCacheCapacity

    • 설명: 유형 캐시가 사용할 수 있는 디렉터리당 최대 크기입니다. 유형 캐시는 항상 메모리에 온전히 보관됩니다. 이 볼륨 속성은 구성 파일 필드 metadata-cache:type-cache-max-size-mb로 변환됩니다.

    • 유효한 값:

      • 수량 값(예: 500Mi, 1Gi)
      • '-1': 유형 캐시에서 필요한 만큼 메모리를 사용하도록 합니다.
      • '0': 유형 캐시가 사용 중지됩니다.
      • 마운트하는 버킷의 단일 디렉터리 내에 있는 최대 파일 수에 파일이 20,000개 이하로 포함된 경우 기본값 4Mi를 사용합니다. 마운트하는 단일 디렉터리 내의 최대 파일 수에 파일이 20,000개 넘게 있으면 파일 5,000개마다 1MiB씩 늘립니다(파일당 평균 약 200 바이트).

    • 기본값: 4Mi

  • metadataCacheTtlSeconds

    • 설명: 캐시된 메타데이터 항목의 초 단위 TTL(수명)입니다. stat-cache-ttl 또는 type-cache-ttl 마운트 옵션을 이미 사용 중인 경우 해당 값이 그대로 유지되며 이 새로운 구성으로 적절하게 변환됩니다. 이 볼륨 속성은 구성 파일 필드 metadata-cache:ttl-secs로 변환됩니다.

    • 유효한 값:

      • 문자열 형식의 정수 값(예: '600')
      • '-1': TTL 만료를 우회하고 사용 가능할 때마다 캐시에서 파일을 제공합니다.
      • '0': 최신 파일을 읽도록 합니다. 0 값을 사용하면 Get 메타데이터 호출을 실행하여 캐시에 있는 파일의 객체 생성이 Cloud Storage에 저장된 객체 생성과 일치하는지 확인합니다.

    • 기본값: '60'.

다음 방법으로 볼륨 속성을 지정할 수 있습니다.

  • 정적 프로비저닝을 사용하는 경우 PersistentVolume 매니페스트의 spec.csi.volumeAttributes 필드에서
  • CSI 임시 볼륨을 사용하는 경우 spec.volumes[n].csi.volumeAttributes 필드에서

고려사항

마운트 구성 시 다음 사항을 고려하세요.

  • app-name, temp-dir, foreground, log-file, log-format, key-file, token-url, reuse-token-from-url 플래그는 허용되지 않습니다.
  • Cloud Storage FUSE는 기본적으로 암시적 디렉터리를 표시하지 않습니다. 이러한 디렉터리를 표시하려면 implicit-dirs 마운트 플래그를 사용 설정하면 됩니다. 자세한 내용은 Cloud Storage FUSE GitHub 문서의 파일 및 디렉터리를 참조하세요.
  • 포드 또는 컨테이너에 대한 보안 컨텍스트를 사용하거나 컨테이너 이미지에서 루트가 아닌 사용자 또는 그룹을 사용하는 경우 uid 및 gid 마운트 플래그를 설정해야 합니다. 또한 file-mode 및 dir-mode 마운트 플래그를 사용하여 파일 시스템 권한을 설정해야 합니다. Cloud Storage FUSE 파일 시스템에 대해 chmod, chown 또는 chgrp 명령어를 실행할 수 없으므로 루트가 아닌 사용자 또는 그룹에 액세스를 제공하려면 uid, gid, file-mode, dir-mode 마운트 플래그가 필요합니다.
  • 전체 버킷 대신 버킷의 디렉터리를 마운트하려면 only-dir=relative/path/to/the/bucket/root 플래그를 사용하여 디렉터리 상대 경로를 전달합니다.
  • Cloud Storage FUSE 캐싱 동작을 미세 조정하려면 볼륨 속성을 구성합니다. 자세한 내용은 Cloud Storage FUSE 캐싱 문서를 참조하세요.
  • 코어 또는 스레드 수가 100보다 높으면 max-conns-per-host를 이 값으로 변경합니다.
  • Linux 커널 마운트 옵션을 구성해야 하는 경우 o 플래그를 사용하여 옵션을 전달할 수 있습니다. 예를 들어 마운트된 파일 시스템에서 바이너리 직접 실행을 허용하지 않으려면 o=noexec 플래그를 설정합니다. 각 옵션에는 개별 플래그가 필요합니다(예: o=noexec,o=noatime). exec, noexec, atime, noatime, sync, async, dirsync 옵션만 허용됩니다.
  • Cloud Storage FUSE 문제를 해결해야 하는 경우 debug_fuse, debug_fs, debug_gcs 플래그를 설정합니다. 세 가지 옵션 중 하나가 지정되면 gcsfuseLoggingSeverity 볼륨 속성이 자동으로 trace로 설정됩니다.
  • Cloud Storage FUSE CSI 드라이버에서는 Cloud Storage FUSE 구성 파일의 cache-dir 필드를 수정할 수 없습니다. fileCacheCapacity 볼륨 속성을 사용하여 파일 캐싱을 사용 설정 또는 중지할 수 있습니다. 파일 캐싱에 대한 기본 emptyDir 볼륨을 대체하려면 사이드카 컨테이너에 대한 커스텀 캐시 볼륨을 구성하면 됩니다.

Cloud Storage FUSE CSI 드라이버 사용 중지

Autopilot 클러스터에서는 Cloud Storage FUSE CSI 드라이버를 사용 중지할 수 없습니다.

Google Cloud CLI를 사용하여 기존 Standard 클러스터에서 Cloud Storage FUSE CSI 드라이버를 사용 중지할 수 있습니다.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

CLUSTER_NAME을 클러스터 이름으로 바꿉니다.

문제 해결

Cloud Storage FUSE CSI 드라이버 사용 시 문제를 해결하려면 GitHub 프로젝트 문서의 문제 해결 가이드를 참조하세요.

다음 단계