Cloud Storage FUSE 프로필로 성능 조정 자동화

이 문서에서는 Google Kubernetes Engine (GKE)에서 Cloud Storage FUSE 프로필을 사용하여 Cloud Storage FUSE CSI 드라이버의 성능을 자동으로 조정하고 AI/ML 워크로드의 데이터 액세스를 가속화하는 방법을 설명합니다.

Cloud Storage FUSE 프로필은 중요한 성능 조정 프로세스를 자동화합니다. 설정을 수동으로 조정하는 대신 CSI 드라이버를 구성하는 사전 정의된 프로필을 적용할 수 있습니다. AI/ML 애플리케이션의 경우 이러한 프로필을 사용하면 운영 오버헤드가 줄어들어 학습 및 추론 시간이 단축될 수 있습니다.

이 문서는 심층적인 스토리지 조정 전문 지식 없이 애플리케이션의 성능을 개선하려는 애플리케이션 개발자 및 머신러닝 (ML) 엔지니어를 위한 것입니다. 일반적인 역할에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참고하세요.

이 문서를 읽기 전에 Cloud Storage, Kubernetes, Cloud Storage FUSE CSI 드라이버의 기본사항을 숙지해야 합니다. 또한 Cloud Storage FUSE CSI 드라이버 사용 요구사항을 검토하세요.

Cloud Storage FUSE 프로필 사용의 이점

AI/ML 워크로드의 성능 조정을 자동화하기 위해 Cloud Storage FUSE 프로필은 사전 정의된 Cloud Storage FUSE 구성을 사용하고 추가 GKE 관련 설정을 적용합니다. 이러한 설정은 Cloud Storage FUSE 성능 조정 권장사항을 기반으로 합니다. 사전 정의된 프로필을 사용하면 다음과 같은 이점이 있습니다.

  • 간소화된 성능 조정: 사전 정의된 Cloud Storage FUSE 프로필을 사용하여 학습, 서빙, 체크포인팅과 같은 일반적인 AI/ML 워크로드에 최적화된 구성을 적용합니다.
  • 동적 리소스 인식 최적화: Cloud Storage FUSE 프로필을 사용하면 CSI 드라이버가 크기, 객체 수, 위치 유형, 사이드카 제한, 노드의 사용 가능한 리소스와 같은 버킷 또는 하위 디렉터리 특성을 기반으로 캐시 크기를 자동으로 조정하고 RAM 또는 로컬 SSD와 같은 최적의 캐시 매체를 선택할 수 있습니다.
  • 읽기 성능 가속화: gcsfusecsi-serving 프로필을 사용하면 GKE에서 Rapid Cache를 자동으로 사용 설정하여 서빙 워크로드의 읽기 성능을 개선합니다.
  • 성능 조정 통계: 환경의 입력 신호와 드라이버가 적용한 결과 구성을 자세히 설명하는 구조화된 로그를 통해 자동 조정 결정에 관한 통계를 얻을 수 있습니다. 자세한 내용은 추천 통계 보기를 참고하세요.

Cloud Storage FUSE 권장사항이 발전함에 따라 새 GKE 출시를 통해 시간이 지남에 따라 프로필이 업데이트됩니다.

제한사항

요구사항

비용

Cloud Storage FUSE CSI 드라이버와 관련된 표준 GKE 및 Cloud Storage 비용 외에도 Cloud Storage FUSE 프로필을 사용하면 다음 비용이 발생합니다.

버킷 스캔 비용

Cloud Storage FUSE 프로필은 버킷 또는 하위 디렉터리의 백그라운드 스캔을 실행합니다. 기본적으로 이 스캔은 7일마다 실행됩니다. 버킷을 스캔하면 객체 나열에 대해 Cloud Storage 클래스 A 작업 요금이 발생합니다.

Rapid Cache 비용

gcsfusecsi-serving 프로필은 Cloud Storage Rapid Cache 가격 책정에 따라 청구되는 Rapid Cache를 자동으로 사용 설정합니다. 더 이상 필요하지 않은 캐시 인스턴스에 대한 요금이 청구되지 않도록 하려면 비용 관리를 참고하세요.

시작하기 전에

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

  • Cloud Storage API 및 Google Kubernetes Engine API를 사용 설정합니다.
    • API 사용 설정
  • 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치했으면 gcloud components update 명령어를 실행하여 최신 버전을 가져옵니다. 이전 gcloud CLI 버전에서는 이 문서의 명령어를 실행하지 못할 수 있습니다.
  • 요구사항에 적합한 Google Cloud 리전을 선택합니다. 성능과 비용을 최적화하려면 GKE 클러스터와 Cloud Storage 버킷을 동일한 리전에 만드는 것이 좋지만, gcsfusecsi-serving 프로필을 사용하거나 Rapid Cache를 사용 설정하려는 경우에는 동일한 리전에 만들어야 합니다.
  • AI/ML 워크로드의 데이터 세트, 모델 또는 체크포인트가 포함된 기존 Cloud Storage 버킷이 있어야 합니다. 버킷을 만들어야 하는 경우 버킷 만들기를 참고하세요.

성능 프로필 선택

워크로드에 가장 적합한 프로필을 선택합니다. 각 프로필은 클러스터에 사전 설치된 StorageClass에 해당합니다. Cloud Storage FUSE 프로필의 자세한 정의는 해당 StorageClass 구성 참조를 참고하세요.

프로필 StorageClass 이름 최적화 목표 주요 특징
학습 gcsfusecsi-training 높은 처리량 읽기 대규모 데이터 세트에서 학습하는 동안 GPU 및 TPU의 데이터 지연 시간을 최적화합니다.
체크포인트 gcsfusecsi-checkpointing 높은 처리량 쓰기 대규모 체크포인트를 저장하는 데 필요한 시간을 최소화하여 학습 일시중지를 줄입니다.
서빙 gcsfusecsi-serving 데이터 액세스 및 캐싱 읽기 작업을 가속화하기 위해 기본적으로 Rapid Cache를 사용 설정합니다.

다음 명령어를 실행하여 클러스터에 설치된 StorageClass를 확인할 수 있습니다.

kubectl get sc -l gke-gcsfuse/profile=true

IAM 권한 구성

GKE 서비스 에이전트에 Cloud Storage 버킷을 분석하고 Rapid Cache를 관리할 수 있는 권한을 부여합니다.

이 섹션의 명령어를 실행할 때 다음 자리표시자를 바꿉니다.

  • GCS_PROJECT: Cloud Storage 버킷이 포함된 프로젝트 ID입니다.
  • PROJECT_NUMBER: GKE 클러스터 프로젝트의 프로젝트 번호입니다.
  • BUCKET_NAME: Cloud Storage 버킷 이름.

프로필 및 사용 요구사항에 맞는 다음 옵션 중 하나를 선택하세요.

옵션 A: 맞춤 역할 (권장)

이 옵션은 Serving 프로필에 필요하거나 Rapid Cache를 사용하는 경우 필요합니다. 게재 프로필을 사용하거나 다른 프로필에 대해 Rapid Cache를 수동으로 사용 설정하려는 경우 해당 캐시를 관리할 권한을 부여해야 합니다.

  1. 객체를 스캔하고 Rapid Cache 캐시를 만들 수 있는 커스텀 IAM 역할을 만듭니다.

    gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

  2. 특정 버킷의 GKE 서비스 에이전트에 맞춤 역할을 바인딩합니다.

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com" \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

옵션 B: 학습 및 체크포인트 프로필의 표준 역할

학습 또는 체크포인트 프로필만 사용하고 Rapid Cache를 사용할 계획이 없는 경우 다음 명령어를 실행합니다.

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com" \
    --role="roles/storage.legacyBucketReader"

Cloud Storage FUSE 프로필로 워크로드 배포

다음 단계에 따라 Cloud Storage FUSE 프로필을 사용하여 워크로드를 배포합니다.

  1. Cloud Storage FUSE 프로필 StorageClass 중 하나를 참조하는 PersistentVolume (PV) 매니페스트를 만듭니다.

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

    다음을 바꿉니다.

    • STORAGECLASS_NAME: 사용할 프로필의 StorageClass 이름입니다. 값은 gcsfusecsi-training, gcsfusecsi-checkpointing 또는 gcsfusecsi-serving이어야 합니다.
    • BUCKET_DIR_PATH: (선택사항) 특정 디렉터리를 마운트하는 경우 Cloud Storage 버킷 내 경로입니다. 지정된 경우 GKE는 이 경로를 검색하여 최적화합니다. 생략하면 GKE가 전체 버킷을 검사합니다.
    • BUCKET_NAME: Cloud Storage 버킷에 대한 액세스를 구성할 때 지정한 Cloud Storage 버킷 이름입니다.

  2. PV와 동일한 StorageClass를 요청하는 PersistentVolumeClaim (PVC)을 만듭니다.

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

    다음을 바꿉니다.

    • NAMESPACE: 포드를 배포할 네임스페이스입니다.
    • STORAGECLASS_NAME: PV에 나열된 StorageClass 이름입니다.

  3. 배포에서 PVC를 사용합니다.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

    다음을 바꿉니다.

배포되면 CSI 드라이버는 GPU 또는 TPU, 메모리, 로컬 SSD, 버킷 또는 하위 디렉터리 크기, 사이드카 리소스 제한과 같은 노드의 리소스를 기반으로 최적의 캐시 크기와 마운트 옵션을 자동으로 계산합니다.

자동 최적화 확인

GKE 백그라운드 프로세스는 버킷을 자동으로 분석하고 Rapid Cache를 동기화합니다 (사용 중인 경우).

버킷 스캔과 캐시의 상태 확인

PV를 만든 후 다음 단계에 따라 버킷 스캔과 캐시의 상태를 확인합니다. 포드가 배포될 때까지 기다릴 필요는 없습니다.

  1. PV 상태를 확인합니다.

    kubectl describe pv my-pv

  2. 출력에 ScanOperationSucceeded 이벤트가 표시되는지 확인합니다. 출력은 다음과 비슷합니다.

    Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

  3. gcsfusecsi-serving 프로필을 사용하는 경우 캐싱 레이어가 준비된 후 AnywhereCacheSyncSucceeded 이벤트가 표시되는지 확인합니다. 출력은 다음과 비슷합니다.

    Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running

  4. PV 주석이 검사 결과로 업데이트되었는지 확인합니다.

    gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

Pod 상태 확인

포드를 배포한 후 다음 명령어를 실행합니다.

kubectl get pods -n NAMESPACE

NAMESPACE를 포드를 배포한 네임스페이스로 바꿉니다.

이제 포드가 RUNNING 상태가 되고 성능 권장사항이 자동으로 적용됩니다. 포드에 SchedulingGated 상태가 표시되면 GKE가 아직 버킷 또는 하위 디렉터리를 스캔하고 있는 것입니다. 포드는 CSI 컨트롤러가 스캔을 완료하고 PV를 업데이트할 때까지 이 상태로 유지됩니다.

포드가 시작된 후 드라이버가 로깅한 특정 조정 결정을 이해하려면 추천 통계 보기를 참고하세요.

오류가 발생하면 문제 해결 섹션을 참고하세요.

StorageClass 구성 참조

이 섹션에서는 사전 설치된 Cloud Storage FUSE 프로필의 StorageClass 매니페스트와 프로필에서 사용되는 마운트 옵션 및 매개변수에 관한 자세한 참조를 제공합니다. 이러한 구성을 통해 gcsfuse.csi.storage.gke.io 드라이버가 AI/ML 워크로드의 성능 조정 및 리소스 관리를 자동화할 수 있습니다.

학습

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

체크포인트

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

서빙

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

프로필은 gcsfuse.csi.storage.gke.io 드라이버에 다음 마운트 옵션과 매개변수를 사용합니다.

  • mountOptions:
    • profile: AI/ML 워크로드에 맞게 조정된 사전 정의된 Cloud Storage FUSE 최적화 세트를 적용합니다. 미리 설치된 프로필의 유효한 값은 aiml-training, aiml-checkpointing, aiml-serving입니다.
    • read_ahead_kb: 미리 읽기 버퍼의 크기를 킬로바이트 (KB) 단위로 지정합니다. 이 옵션을 사용하면 Cloud Storage FUSE가 Cloud Storage에서 데이터를 미리 가져올 수 있으므로 순차 액세스 패턴의 읽기 성능이 향상될 수 있습니다.
    • file-cache:max-size-mb: 서빙 프로필의 경우 파일 캐시의 최대 크기 (MiB)를 지정합니다. 모델이 일반적으로 GPU 또는 TPU 메모리에 한 번만 로드되는 서빙 워크로드에서 이 매개변수는 0로 설정되어 로컬 Cloud Storage FUSE 파일 캐시를 사용 중지하므로 중복 디스크 I/O를 방지하고 로컬 스토리지를 절약할 수 있습니다.
    • read:enable-buffered-read: 서비스 프로필의 경우 Cloud Storage FUSE가 자체 내부 버퍼를 관리할 수 있도록 지원하여 애플리케이션과 커널 간의 비용이 많이 드는 작은 시스템 호출 수를 줄입니다.
    • read:global-max-blocks: 서비스 프로필의 경우 버퍼링된 읽기에 사용되는 동시 메모리 블록의 총수를 제한합니다. 이 옵션은 여러 요청을 처리할 때 FUSE 프로세스가 사용 가능한 모든 RAM을 소비하지 않도록 방지하는 데 도움이 됩니다.
  • parameters:
    • skipCSIBucketAccessCheck: "true"로 설정되면 CSI 드라이버가 초기 버킷 액세스 확인을 건너뜁니다. 이 매개변수는 잠재적인 할당량 문제를 방지하기 위해 보안 토큰 서비스에 대한 호출을 줄이는 데 도움이 됩니다.
    • gcsfuseMetadataPrefetchOnMount: "true"로 설정되면 볼륨이 마운트되는 즉시 Cloud Storage에서 객체 메타데이터를 로컬 캐시로 prefetching하도록 CSI 드라이버에 지시합니다. 이 매개변수는 파일에 대한 첫 번째 액세스를 가속화할 수 있습니다.
    • fuseFileCacheMediumPriority: Cloud Storage FUSE 파일 캐시에서 사용하는 저장소 미디어의 우선순위 순서를 정의합니다. GPU, TPU 또는 범용 노드가 있는 노드에 대해 서로 다른 환경설정을 지정할 수 있습니다. 미디어 옵션에는 ram 및 lssd (사용 가능하고 사용 설정된 경우 로컬 SSD)이 포함됩니다.
    • fuseMemoryAllocatableFactor: 노드의 할당 가능한 총 메모리 및 사이드카의 메모리 제한과 관련하여 Cloud Storage FUSE 캐시가 사용할 수 있는 최대 메모리를 제한하는 분수를 문자열 형식으로 지정합니다.
    • fuseEphemeralStorageAllocatableFactor: 노드의 할당 가능한 임시 스토리지 또는 캐싱을 위해 제한된 사이드카의 임시 스토리지에 상대적으로 노드에서 Cloud Storage FUSE 캐시의 임시 스토리지 사용을 제한합니다 (예: 파일 캐싱을 위한 로컬 SSD).
    • bucketScanResyncPeriod: Cloud Storage 버킷에 적용된 변경사항을 감지하기 위해 PV를 다시 검색하는 시간 간격을 설정합니다.
    • bucketScanTimeout: 단일 버킷 검색 작업에 허용되는 최대 기간입니다. 스캔이 이 시간을 초과하면 부분 결과가 사용될 수 있습니다.
    • anywhereCacheZones: 빠른 캐시 캐시가 생성되는 지원되는 영역의 쉼표로 구분된 목록을 지정합니다(예: "us-central1-a,us-central1-b"). 클러스터에서 사용할 수 있는 모든 영역을 사용하려면 "*"를 값으로 사용합니다. 이 값을 "none"로 설정하거나 지정하지 않으면 Rapid Cache가 사용 중지됩니다.
    • anywhereCacheTTL: 마지막 액세스부터 측정된 Rapid Cache 캐시에 저장된 데이터의 TTL(수명)입니다. 이 값을 변경하면 기존 Rapid Cache 인스턴스가 새 TTL로 업데이트됩니다.
    • anywhereCacheAdmissionPolicy: 읽기 누락 (요청된 데이터가 캐시에 없음) 후 데이터를 Rapid Cache 캐시에 허용할 시기를 결정합니다. 옵션에는 첫 번째 읽기 부적중 시에 데이터를 허용하는 "admit-on-first-miss" 또는 동일한 객체의 두 번째 읽기 부적중 시에만 데이터를 허용하는 "admit-on-second-miss"이 포함됩니다. 이 값을 변경하면 기존 Rapid Cache 인스턴스가 새 정책으로 업데이트됩니다.

선택사항: 프로필 구성 미세 조정

기본 구성의 이점을 누리면서 프로필의 특정 설정을 맞춤설정할 수 있습니다. 새 StorageClass를 만들지 않고 프로필을 조정하려면 다음 옵션을 사용하세요.

마운트 옵션 및 매개변수 재정의

특정 동작을 수정하려면 PV의 spec.mountOptions 필드에 마운트 옵션을 추가하거나 spec.csi.volumeAttributes 필드에 CSI 매개변수를 추가합니다. GKE는 프로필의 기본값 위에 수동 설정을 적용합니다.

다음 예는 read_ahead_kb 마운트 옵션을 재정의하고 서비스 프로필에서 gcsfuseMetadataPrefetchOnMount 매개변수를 사용 중지하는 방법을 보여줍니다.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

일반적인 사용 사례는 다음과 같습니다.

  • 학습 프로필에 Rapid Cache를 사용 설정하려면 PV 사양에 anywhereCacheZones 매개변수를 직접 추가하세요.
  • 특정 워크로드의 고유한 요구사항을 충족하기 위해 read_ahead_kb 크기를 늘리는 등 특정 Cloud Storage FUSE 동작을 조정합니다.

캐시 크기를 수동으로 구성할 때는 다음 사항을 고려하세요.

  • 수동 캐시 크기를 지정하면 해당 특정 구성요소에 대해서만 자동 동적 크기 조정을 재정의합니다. 동적 크기 조정은 나머지 리소스 예산 내에서 최선을 다해 다른 모든 구성요소에 대해 계속됩니다.
  • metadata-cache:stat-cache-max-size-mb와 같은 metadata-cache 또는 file-cache 옵션을 설정해도 다른 캐시 유형의 자동 계산은 사용 중지되지 않습니다.
  • file-cache:max-size-mb를 수동으로 지정하는 경우 맞춤 읽기 캐시 볼륨도 구성해야 합니다. 이렇게 하면 맞춤 캐시 크기에 충분한 용량의 저장 매체가 명시적으로 정의됩니다.

주석을 사용하여 버킷 검색 우회

주석을 사용하여 자체 객체 수 및 크기 측정항목을 제공하면 자동 버킷 검색 프로세스를 우회할 수 있습니다. CSI 드라이버는 이러한 값을 사용하여 버킷을 스캔하지 않고 최적의 성능 구성을 계산합니다.

다음 예에서는 특정 측정항목 주석과 함께 gke-gcsfuse/bucket-scan-status: "override" 주석을 PV에 추가하는 방법을 보여줍니다.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

일반적인 사용 사례는 다음과 같습니다.

  • 특히 데이터가 거의 변경되지 않는 추론 워크로드의 경우 버킷 크기와 객체 수를 이미 알고 있다면 시작 시 스캔 시간을 우회할 수 있습니다.
  • Cloud Storage API를 일시적으로 사용할 수 없는 경우 이러한 주석을 사용하면 기본 서비스가 수정되는 동안 성능을 유지할 수 있습니다.

문제 해결

다음 정보를 사용하여 Cloud Storage FUSE 프로필의 상태를 모니터링하고 버킷 스캔 및 캐시 동기화 중에 발생하는 일반적인 문제를 해결하세요.

잘못된 구성 매개변수 (InvalidArgument)

매니페스트에 제공된 하나 이상의 매개변수가 잘못되어 백그라운드 최적화 작업을 시작하지 못했습니다.

증상

PV에 rpc error: code = InvalidArgument이 포함된 메시지가 있는 ScanOperationStartError 또는 AnywhereCacheSyncError 이벤트가 표시됩니다. 예를 들면 다음과 같습니다.

  • Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
  • Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

원인

PV의 spec.csi.volumeAttributes 필드에 있는 하나 이상의 매개변수의 형식이 잘못되었거나 시스템에서 파싱할 수 없는 값이 포함되어 있습니다.

해결 방법

PV 매니페스트에서 잘못된 매개변수 값을 수정하고 PV를 다시 배포합니다. 모든 기간 값 (예: bucketScanTimeout)이 올바른 형식 (예: 2m 또는 10m)을 사용하고 모든 프로필별 설정이 지원되는 유효한 값과 일치하는지 확인합니다.

Cloud Storage 버킷을 스캔할 때 권한이 거부됨

GKE가 필요한 성능 분석을 실행하기 위해 지정된 Cloud Storage 버킷에 액세스할 수 없습니다.

증상

PV에는 호출자에게 storage.buckets.get 액세스 권한이 없음을 나타내는 Error 403: Forbidden 메시지와 함께 ScanOperationStartError 이벤트가 표시됩니다.

원인

GKE 서비스 에이전트에 필요한 IAM 권한이 없거나 버킷 이름이 잘못되었습니다.

해결 방법

  • PV의 volumeHandle 필드에 있는 버킷 이름이 올바르고 버킷이 존재하는지 확인합니다.
  • 특정 버킷의 service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com ID에 GKE 서비스 에이전트 권한이 부여되었는지 확인합니다. 자세한 내용은 IAM 권한 구성을 참고하세요.

Rapid Cache 위치 불일치

요청된 영역이 버킷의 위치와 호환되지 않으므로 Rapid Cache 캐시를 만들 수 없습니다.

증상

PV에 Invalid zone. Rapid Cache isn't available in the requested zone. 메시지가 포함된 AnywhereCacheSyncWarning 이벤트가 표시됩니다.

원인

Rapid Cache 캐시는 버킷의 리전 위치 내에 있는 영역에 만들어야 합니다. 이 오류는 일반적으로 GKE 클러스터와 Cloud Storage 버킷이 서로 다른 리전에 있는 경우 발생합니다.

해결 방법

Cloud Storage 버킷을 GKE 클러스터 위치와 일치하는 리전으로 이동하고 PV를 다시 배포합니다.

버킷 검사 타임아웃

Cloud Storage 버킷 분석이 구성된 제한 시간보다 오래 걸려 최적화 결과가 부분적으로만 표시됩니다.

증상

PV에는 ScanOperationTimedOut 이벤트가 표시됩니다. PV에는 객체 수와 총 크기에 대한 부분 결과가 주석으로 표시됩니다.

원인

버킷에 객체가 매우 많이 포함되어 있습니다 (일반적으로 수백만 개). 기본 2분 제한 시간 내에 모두 나열할 수 없습니다.

해결 방법

  • PV의 spec.csi.volumeAttributes 섹션에서 bucketScanTimeout 필드의 값을 더 큰 값(예: 10m)으로 설정합니다.
  • 버킷 크기가 정적인 경우 객체 수와 크기를 수동으로 제공하여 스캔을 우회합니다.

메모리 예산에 의해 제한되는 메타데이터 캐시

드라이버가 노드의 사용 가능한 리소스에 맞게 메타데이터 캐시 크기를 제한하여 성능이 저하될 수 있습니다.

증상

로그에는 필요한 메타데이터 통계 캐시 크기가 사용 가능한 Cloud Storage FUSE 메모리 예산으로 제한되었다는 메시지가 포함되어 있습니다.

원인

버킷에 있는 객체 수의 메타데이터 캐시가 Cloud Storage FUSE 사이드카에 할당된 메모리 또는 노드의 사용 가능한 메모리를 초과합니다.

해결 방법

  • only-dir 마운트 옵션을 사용하여 객체가 적은 더 작은 하위 디렉터리로 볼륨의 범위를 지정합니다.
  • Cloud Storage FUSE 사이드카 컨테이너의 메모리 한도를 늘립니다.
    • 사이드카 제한이 이미 충분한 경우 할당 가능한 메모리가 더 많은 노드 유형을 사용하세요.

리소스 한도로 인해 파일 캐시가 사용 중지됨

GKE에서 공간이 충분한 적합한 저장 매체를 찾을 수 없어 로컬 파일 캐시를 사용 중지했습니다.

증상

로그에 No suitable file cache medium found or requirement exceeded limits for all options라는 경고가 표시됩니다.

원인

계산된 파일 캐시 크기가 사용 가능한 노드의 RAM과 사용 가능한 로컬 SSD 스토리지를 모두 초과합니다.

해결 방법

  • only-dir 마운트 옵션을 사용하여 객체가 적은 더 작은 하위 디렉터리로 볼륨의 범위를 지정합니다.
  • Cloud Storage FUSE 사이드카의 리소스 한도를 늘립니다.
  • 메모리가 더 많은 노드 유형을 사용하거나 노드 풀에서 로컬 SSD를 사용 설정하세요.

PersistentVolume 이벤트를 사용하여 상태 모니터링

GKE는 주요 구성 이벤트와 오류를 PV에 로깅합니다. 이러한 이벤트를 확인하려면 다음 명령어를 실행하세요.

kubectl describe pv PV_NAME

버킷 검사가 성공하면 ScanOperationSucceeded 이벤트가 표시됩니다. gcsfusecsi-serving 프로필을 사용하는 경우 캐싱 레이어가 작동한 후 AnywhereCacheSyncSucceeded 이벤트가 표시됩니다.

CSI 드라이버 로그를 사용하여 상태 모니터링

Cloud Storage FUSE CSI 드라이버는 상세한 구성 결정과 성능 통계를 로깅합니다. Cloud Logging에서 이러한 로그를 보려면 다음 쿼리를 사용하세요.

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

추천 통계 보기

자동 조정 로직에서 이루어진 특정 입력 신호와 결정을 이해하려면 CSI 드라이버 로그에서 GCSFuseCSIRecommendation 문자열을 검색하세요. 결과 JSON 페이로드는 다음을 포함한 세부 측정항목을 제공합니다.

  • inputSignals: 버킷 객체 수, 총 데이터 크기, 사용 가능한 노드 리소스 (RAM 및 임시 스토리지)입니다.
  • decision: 최종 계산된 캐시 크기 및 선택된 스토리지 매체(ram 또는 lssd)
{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

삭제

이 가이드에서 만든 리소스에 대해 Google Cloud 계정에 비용이 청구되지 않도록 하려면 다음 단계를 수행합니다.

  1. 배포를 삭제합니다.

    kubectl delete deployment my-deployment -n NAMESPACE

    NAMESPACE을 배포를 만든 Kubernetes 네임스페이스로 바꿉니다.

  2. PersistentVolumeClaim을 삭제합니다.

    kubectl delete pvc my-pvc -n NAMESPACE

    NAMESPACE를 PVC를 만든 Kubernetes 네임스페이스로 바꿉니다.

  3. PersistentVolume을 삭제합니다.

    kubectl delete pv my-pv

  4. gcsfusecsi-serving 프로필을 사용했거나 Rapid Cache를 수동으로 사용 설정한 경우 캐시 사용 중지 안내에 따라 캐시 인스턴스에 대한 요금이 청구되지 않도록 하세요.

다음 단계