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

Autopilot 스탠더드

이 문서에서는 Google Kubernetes Engine (GKE)에서 Cloud Storage 버킷에 액세스하도록 Cloud Storage FUSE CSI 드라이버를 설정하는 방법을 보여줍니다.

Cloud Storage FUSE CSI 드라이버를 사용하면 GKE 워크로드가 Cloud Storage 버킷에 로컬 파일 시스템으로 액세스할 수 있습니다. CSI 드라이버는 Cloud Storage를 GKE와 통합하고 컨테이너화된 애플리케이션이 버킷에 저장된 대규모 데이터 세트와 상호작용하는 방식을 간소화합니다. CSI 드라이버는 GKE 스토리지의 표준 인터페이스를 제공합니다. 이 문서에서는 Cloud Storage FUSE CSI 드라이버를 사용하여 환경을 준비하고 GKE 클러스터를 Cloud Storage 버킷에 연결합니다.

이 문서는 GKE 워크로드를 객체 스토리지와 통합하는 개발자, 관리자, 스토리지 전문가를 대상으로 합니다. 콘텐츠 Google Cloud 에서 참조하는 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE 사용자 역할 및 태스크를 참조하세요.

Cloud Storage 버킷 만들기

아직 Cloud Storage 버킷을 만들지 않았으면 지금 만듭니다. 이러한 버킷은 GKE 클러스터에서 볼륨으로 마운트됩니다. 성능을 향상시키려면 위치 유형을 리전으로 설정하고 GKE 클러스터와 일치하는 리전을 선택합니다.

팁: Cloud Storage 버킷 및 GKE 클러스터는 서로 다른 Google Cloud 프로젝트나 동일한 프로젝트에 있을 수 있습니다.

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

GKE Autopilot 클러스터를 사용하는지 아니면 Standard 클러스터를 사용하는지에 따라 다음 단계를 따르세요. 완전 관리형 Kubernetes 환경을 위해서는 Autopilot을 사용하는 것이 좋습니다. 워크로드에 가장 적합한 모드를 선택하려면 GKE 작업 모드 선택을 참조하세요.

Autopilot

기본적으로 Cloud Storage FUSE CSI 드라이버는 Autopilot 클러스터에 사용 설정됩니다. Cloud Storage 버킷에 대한 액세스 구성으로 건너뛸 수 있습니다.

표준

Standard 클러스터에 Cloud Storage FUSE CSI 드라이버가 사용 설정된 경우 Cloud Storage 버킷에 대한 액세스 구성으로 건너뛰세요.

Cloud Storage FUSE CSI 드라이버는 기본적으로 Standard 클러스터에서 사용 설정되지 않습니다. Cloud Storage FUSE CSI 드라이버가 사용 설정된 Standard 클러스터를 만들려면 gcloud container clusters create 명령어를 사용하면 됩니다.

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

클러스터에서 Cloud Storage FUSE CSI 드라이버가 사용 설정되어 있는지 확인하려면 다음 명령어를 실행합니다.

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --format="value(addonsConfig.gcsFuseCsiDriverConfig.enabled)"

Cloud Storage 버킷에 대한 액세스 구성

Cloud Storage FUSE CSI 드라이버는 GKE용 워크로드 아이덴티티 제휴를 사용하므로 GKE 포드가 Cloud Storage에 저장된 데이터에 액세스하는 방법에 대한 세분화된 권한을 설정할 수 있습니다.

GKE 클러스터에서 Cloud Storage 버킷에 액세스할 수 있게 하려면 포드 사양에서 마운트하려는 Cloud Storage 버킷으로 GKE용 워크로드 아이덴티티 제휴를 사용하여 인증합니다.

1. GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있지 않으면 다음 단계에 따라 사용 설정합니다. 기존 노드 풀을 사용하려면 클러스터에서 GKE용 워크로드 아이덴티티 제휴를 사용 설정한 후 노드 풀에서 GKE용 워크로드 아이덴티티 제휴를 수동으로 사용 설정합니다.

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

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

   다음을 바꿉니다.

   • CLUSTER_NAME: GKE용 워크로드 아이덴티티 제휴가 사용 설정된 클러스터의 이름
   • LOCATION: 클러스터의 Compute Engine 리전 또는 영역

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

   kubectl create namespace NAMESPACE
   

   NAMESPACE를 Kubernetes ServiceAccount의 Kubernetes 네임스페이스 이름으로 바꿉니다.

   중요: 워크로드는 반드시 동일한 네임스페이스에서 실행되어야 합니다.

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

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

   KSA_NAME을 Kubernetes ServiceAccount의 이름으로 바꿉니다.

5. Cloud Storage에 대한 IAM 역할 중 하나를 Kubernetes ServiceAccount에 부여합니다. Kubernetes ServiceAccount에 특정 Cloud Storage 버킷에만 액세스 권한을 부여하는지 아니면 프로젝트의 모든 버킷에 대한 전역 액세스 권한을 부여하는지에 따라 다음 단계를 따르세요.

   특정 버킷 액세스

   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)을 사용합니다.

   전역 버킷 액세스

   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)을 사용합니다.

호스트 네트워크를 사용하여 포드의 액세스 구성

1.33.3-gke.1226000 이전 버전의 GKE 클러스터에서는 GKE용 워크로드 아이덴티티 제휴의 제한사항으로 인해 Cloud Storage FUSE CSI 드라이버가 호스트 네트워크 (hostNetwork: true)에서 실행되는 포드를 지원하지 않습니다. 하지만 이후 GKE 버전에서는 Cloud Storage FUSE CSI 드라이버를 사용하여 Cloud Storage 버킷을 마운트할 때 hostNetwork 사용 설정 포드의 보안 인증을 구성할 수 있습니다. 호스트 네트워크 지원은 Standard GKE 클러스터에서만 사용할 수 있습니다.

GKE 클러스터가 다음 요구사항을 충족하는지 확인합니다.

• Standard GKE 클러스터의 컨트롤 플레인과 노드 풀 모두 버전 1.33.3-gke.1226000 이상이어야 합니다.
• 클러스터에서 워크로드 아이덴티티를 사용 설정합니다.
• `hostNetwork` 사용 설정 포드가 Cloud Storage 버킷에 액세스하는 데 사용하는 Kubernetes 서비스 계정에 필요한 IAM 권한을 부여합니다. 자세한 내용은 Cloud Storage FUSE에 인증을 참조하세요.

포드 또는 PersistentVolume 정의에서 볼륨 속성 hostNetworkPodKSA: "true"를 지정하여 HostNetwork 포드가 Cloud Storage 볼륨에 액세스할 수 있도록 합니다. 정확한 구성은 Cloud Storage FUSE 사이드카 컨테이너를 관리하는 방법에 따라 다릅니다.

관리형 사이드카

이 섹션은 GKE가 Cloud Storage FUSE 사이드카 컨테이너를 포드에 자동으로 삽입하고 관리하는 경우에 적용됩니다. 이 옵션은 Cloud Storage FUSE CSI 드라이버의 기본 설정이자 권장 설정입니다.

임시 볼륨

다음 포드 매니페스트는 HostNetwork 포드가 Cloud Storage 버킷에 액세스할 수 있도록 임시 볼륨을 구성합니다.

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"

영구 볼륨

다음 PV 매니페스트는 HostNetwork 포드가 Cloud Storage 버킷에 액세스할 수 있도록 PV를 구성합니다.

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"

비공개 사이드카

이 섹션은 포드 내에서 Cloud Storage FUSE 사이드카 컨테이너를 수동으로 관리하거나 커스텀 사이드카 이미지를 사용하는 경우에 적용됩니다.

사이드카 이미지가 Cloud Storage FUSE CSI 드라이버 버전 v1.17.2 이상을 기반으로 하는지 확인합니다.

임시 볼륨

다음 포드 매니페스트는 HostNetwork 포드가 Cloud Storage 버킷에 액세스할 수 있도록 임시 볼륨을 구성합니다.

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"
        identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

identityProvider 필드에서 다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID
• LOCATION: 클러스터의 위치
• CLUSTER_NAME: Standard GKE 클러스터의 이름

영구 볼륨

다음 PV 매니페스트는 HostNetwork 포드가 Cloud Storage 버킷에 액세스할 수 있도록 PV를 구성합니다.

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"
    identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

identityProvider 필드에서 다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID
• LOCATION: 클러스터의 위치
• CLUSTER_NAME: Standard GKE 클러스터의 이름

다음 단계

• Cloud Storage FUSE 문제 해결
• 포드 사양에 따라 버킷을 인라인으로 지정하여 Cloud Storage 버킷을 마운트하는 방법을 알아봅니다.
• PersistentVolume 리소스를 사용하여 Cloud Storage 버킷을 마운트하는 방법을 알아봅니다.
• GKE용 워크로드 아이덴티티 제휴를 사용하도록 애플리케이션을 구성하는 방법을 자세히 알아봅니다.
• Cloud Storage FUSE 프로필로 성능을 자동으로 최적화합니다.
• 성능을 위해 Cloud Storage FUSE를 수동으로 최적화합니다.