GKE용 Cloud Storage FUSE CSI 드라이버 사이드카 컨테이너 구성

이 가이드에서는 비공개 이미지, 커스텀 쓰기 버퍼, 커스텀 읽기 캐시 볼륨 설정을 비롯하여 Cloud Storage FUSE CSI 드라이버 사이드카 컨테이너의 리소스를 구성하는 방법을 보여줍니다. 일반적으로 이러한 설정은 변경할 필요가 없습니다.

Cloud Storage FUSE CSI 드라이버는 맞춤설정 가능한 사이드카 컨테이너를 사용하여 Cloud Storage 버킷을 효율적으로 마운트하고 액세스합니다. 사이드카를 구성하면 애플리케이션 성능과 리소스 사용량을 세부적으로 조정할 수 있으므로 데이터 액세스 속도와 처리 시간이 빨라지고 애플리케이션의 전반적인 리소스 소비가 줄어들 수 있습니다.

이 가이드는 GKE와 상호작용하는 애플리케이션의 성능, 보안, 효율성을 최적화하려는 개발자, 관리자, 설계자를 대상으로 합니다.

이 페이지를 읽기 전에 Cloud Storage, Kubernetes, 컨테이너화 개념의 기본사항을 숙지해야 합니다.

사이드카 컨테이너 작동 방식

Cloud Storage FUSE CSI 드라이버는 사이드카 컨테이너를 사용하여 Cloud Storage 버킷을 마운트하여 Kubernetes 애플리케이션에서 이를 로컬 파일 시스템으로 액세스할 수 있도록 합니다. 이름이 gke-gcsfuse-sidecar인 이 사이드카 컨테이너는 동일한 포드 내에서 워크로드 컨테이너와 함께 실행됩니다. 드라이버가 포드 사양에서 gke-gcsfuse/volumes: "true" 주석을 감지하면 사이드카 컨테이너를 자동으로 삽입합니다. 이러한 사이드카 컨테이너 접근 방식은 보안을 강화하고 리소스를 효과적으로 관리하는 데 도움이 됩니다.

사이드카 컨테이너는 Cloud Storage 버킷 마운트의 복잡성을 해결하고 Cloud Storage FUSE 런타임을 직접 관리할 필요 없이 애플리케이션에 파일 시스템 액세스를 제공합니다. gke-gcsfuse/cpu-limit 및 gke-gcsfuse/memory-limit와 같은 주석을 사용하여 사이드카 컨테이너의 리소스 한도를 구성할 수 있습니다. 또한 사이드카 컨테이너 모델은 Cloud Storage FUSE 인스턴스가 워크로드 수명 주기에 연결되도록 하여 불필요하게 리소스를 소비하지 않도록 합니다. 즉, (특히 RestartPolicy가 Never인 작업 워크로드 또는 포드에서) 워크로드 컨테이너가 종료되면 사이드카 컨테이너가 자동으로 종료됩니다.

Istio 호환성

Cloud Storage FUSE CSI 드라이버의 사이드카 컨테이너와 Istio는 포드에서 공존하고 동시에 실행될 수 있습니다. Istio의 사이드카 프록시가 네트워크 트래픽을 관리하고 CSI 사이드카가 스토리지 액세스를 최적화하므로 애플리케이션이 향상된 성능과 모니터링 가능성으로 Google Cloud Storage와 효율적으로 상호작용할 수 있습니다.

커스텀 쓰기 버퍼 구성

Cloud Storage FUSE는 로컬 디렉터리에 쓰기를 스테이징한 후 close 또는 fsync 작업에서 Cloud Storage에 업로드합니다.

이 섹션에서는 Cloud Storage FUSE 쓰기 버퍼링을 위해 커스텀 버퍼 볼륨을 구성하는 방법을 설명합니다. 이 시나리오는 Cloud Storage FUSE가 쓰기 작업에서 파일을 스테이징하기 위해 기본 emptyDir 볼륨을 바꿔야 하는 경우에 적용될 수 있습니다. 이는 Autopilot 클러스터에서 10GiB가 넘는 파일을 기록해야 할 때 유용합니다.

로컬 SSD, Persistent Disk 기반 스토리지, RAM 디스크(메모리)와 같이 Cloud Storage FUSE CSI 드라이버에서 지원하는 모든 유형의 스토리지를 파일 캐싱에 지정할 수 있습니다. GKE는 파일 쓰기 버퍼링을 위해 지정된 볼륨을 사용합니다. 이러한 옵션에 대한 자세한 내용은 파일 캐시를 백업할 스토리지 선택을 참조하세요.

커스텀 버퍼 볼륨을 사용하려면 0이 아닌 fsGroup을 지정해야 합니다.

다음 예시에서는 사전 정의된 PersistentVolumeClaim을 버퍼 볼륨으로 사용하는 방법을 보여줍니다.

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을 지정해야 합니다.

다음 예시에서는 사전 정의된 PersistentVolumeClaim을 캐시 볼륨으로 사용하는 방법을 보여줍니다.

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: 사전 정의된 PersistentVolumeClaim 이름

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

이 섹션에서는 비공개 Container Registry에서 호스팅하는 경우 사이드카 컨테이너 이미지를 사용하는 방법을 설명합니다. 이 시나리오는 보안 목적으로 비공개 노드를 사용해야 하는 경우에 적용될 수 있습니다.

비공개 사이드카 컨테이너 이미지를 구성하고 소비하려면 다음 단계를 따르세요.

1. 이 GKE 호환성 표를 참조하여 호환되는 공개 사이드카 컨테이너 이미지를 찾습니다.
2. 로컬 환경으로 가져와 비공개 컨테이너 레지스트리에 푸시합니다.

3. 매니페스트에서 이미지 필드만 있는 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: 비공개 사이드카 컨테이너 이미지 태그입니다.

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

기본적으로 Standard 및 Autopilot 클러스터에서 gke-gcsfuse-sidecar 컨테이너는 다음과 같은 리소스 요청 및 제한 값으로 구성되어 있습니다.

요청:

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

제한사항(GKE 버전 1.29.1-gke.1670000 이상):

• 무제한 CPU
• 무제한 메모리
• 무제한 임시 스토리지

제한사항(GKE 버전 1.29.1-gke.1670000 이전):

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

기본적으로 Standard 및 Autopilot 클러스터에서 gke-gcsfuse-metadata-prefetch 컨테이너는 다음과 같은 리소스 요청 및 제한 값으로 구성되어 있습니다.

요청:

• 10m CPU
• 10MiB 메모리
• 10MiB 임시 스토리지

제한사항:

• 50m CPU
• 250MiB 메모리
• 무제한 임시 스토리지

Standard 및 Autopilot 클러스터에서는 기본값을 덮어쓸 수 있습니다. GKE가 컨테이너 리소스를 처리하는 방식은 클러스터 작업 모드에 따라 달라집니다.

• Standard 클러스터: 요청 또는 제한 중 하나만 설정하고 다른 하나는 설정하지 않은 경우 포드의 리소스 요청과 제한은 동일한 값으로 설정됩니다. 요청과 제한을 모두 설정한 경우 포드는 사용자가 지정한 정확한 리소스 요청 및 제한 값을 사용합니다. 아무 값도 설정하지 않으면 위에서 설명한 기본 리소스 값이 그대로 적용됩니다.
• Autopilot 클러스터: 요청 또는 제한 중 하나만 설정하고 다른 하나는 설정하지 않은 경우 포드의 리소스 요청과 제한은 동일한 값으로 설정됩니다. Autopilot에서 리소스를 어떻게 재정의하고, 기본 리소스 값이 포드 동작에 어떤 영향을 미치는지에 대한 자세한 내용은 Autopilot에서 리소스 제한 설정을 참조하세요.

gke-gcsfuse-sidecar 컨테이너의 기본값을 덮어쓰려면 다음 예시와 같이 선택적으로 gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] 주석을 지정할 수 있습니다.

GKE 버전 1.32.3-gke.1717000 이상부터 gke-gcsfuse-metadata-prefetch 컨테이너의 기본값을 덮어쓰려면 다음 예시와 같이 gke-gcsfuse/[metadata-prefetch-cpu-limit|metadata-prefetch-memory-limit|metadata-prefetch-ephemeral-storage-limit|metadata-prefetch-cpu-request|metadata-prefetch-memory-request|metadata-prefetch-ephemeral-storage-request] 주석을 선택적으로 지정할 수 있습니다.

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"

    # gke-gcsfuse-sidecar overrides
    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-gcsfuse-metadata-prefetch overrides
    gke-gcsfuse/metadata-prefetch-cpu-limit: "10"
    gke-gcsfuse/metadata-prefetch-memory-limit: 10Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-limit: 1Ti
    gke-gcsfuse/metadata-prefetch-cpu-request: 500m
    gke-gcsfuse/metadata-prefetch-memory-request: 1Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-request: 50Gi

"0" 값을 사용하여 리소스 제한이나 요청을 해제할 수 있습니다. 다만, gke-gcsfuse-sidecar 컨테이너는 이미 모든 제한 값(cpu-limit, memory-limit, ephemeral-storage-limit)이 해제되어 있으며, gke-gcsfuse-metadata-prefetch 컨테이너도 이미 ephemeral-storage-limit이 해제되어 있기 때문에, GKE 버전 1.32.3-gke.1717000 이상이 적용된 클러스터에서 이들 항목에 "0"을 설정해도 아무런 동작도 발생하지 않습니다.

예를 들어 gke-gcsfuse/metadata-prefetch-memory-limit: "0"으로 설정하면 gke-gcsfuse-metadata-prefetch 컨테이너의 메모리 제한을 해제하겠다는 의도를 나타냅니다. 이는 메타데이터 미리 가져오기 기능이 워크로드에 필요한 리소스 양을 예측하기 어렵고, 노드의 사용 가능한 모든 리소스를 소비하도록 허용하고자 할 때 유용하게 사용됩니다.

로깅 세부정보 수준 구성

기본적으로 gke-gcsfuse-sidecar 컨테이너는 info 및 error 수준에서 로그를 생성합니다. 그러나 디버깅이나 더 자세한 분석을 위해서는 로깅 세부정보 수준을 조정해야 할 수 있습니다. 이 섹션에서는 로깅 수준을 높이거나 낮추는 방법을 간략히 설명합니다.

마운트 옵션을 사용하여 로깅 세부정보 수준을 구성하거나 CSI 드라이버의 기능을 사용하여 볼륨 속성 값을 필요한 gcsfuse 구성 설정으로 변환할 수 있습니다.

대상 포드 매니페스트에 다음 구성을 포함합니다.

      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity:  LOGGING_SEVERITY

마운트 옵션을 사용하려면 대상 포드 매니페스트에 다음 구성을 포함합니다.

  mountOptions: "logging:severity:LOGGING_SEVERITY"

다음을 바꿉니다.

• BUCKET_NAME: Cloud Storage 버킷 이름
• LOGGING_SEVERITY: 요구사항에 따라 다음 값 중 하나
  • trace
  • debug
  • info
  • warning
  • error

포드가 배포된 후, CSI 드라이버는 새로 설정한 로깅 수준으로 gcsfuse를 실행합니다.

다음 필터를 사용하여 로깅 심각도가 올바르게 적용되었는지 확인할 수 있습니다.

resource.labels.container_name="gke-gcsfuse-sidecar"
resource.type="k8s_container"
resource.labels.pod_name="POD_NAME"
"severity:"

문제 해결

Cloud Storage FUSE CSI 드라이버 문제를 해결하는 방법에 대한 자세한 내용은 GitHub 프로젝트 문서의 문제 해결 가이드를 참조하세요.

다음 단계

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