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

Autopilot Standard

---

이 페이지에서는 GKE용 Cloud Storage FUSE CSI 드라이버를 설정하고 사용할 준비를 하는 방법을 설명합니다.

Cloud Storage FUSE CSI 드라이버를 사용하려면 다음 단계를 따르세요.

• Cloud Storage 버킷 만들기
• 드라이버 사용 설정
• Cloud Storage 버킷에 대한 액세스 구성

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 클러스터의 경우 Cloud Storage FUSE CSI 드라이버는 GKE용 워크로드 아이덴티티 제휴의 제한사항으로 인해 호스트 네트워크 (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에 인증을 참고하세요.

HostNetwork 포드가 Cloud Storage 볼륨에 액세스할 수 있도록 포드 또는 PersistentVolume 정의에서 볼륨 속성 hostNetworkPodKSA: "true"를 지정합니다. 정확한 구성은 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: 표준 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: 표준 GKE 클러스터의 이름입니다.

다음 단계

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