GKE 볼륨 채우기를 사용하여 동적 프로비저닝 중에 Cloud Storage에서 데이터 전송

Autopilot Standard

---

GKE 볼륨 채우기는 초대를 받아야만 사용할 수 있습니다. Google Cloud 프로젝트에서 GKE 볼륨 채우기 도구에 대한 액세스 권한을 요청하려면 영업 담당자에게 문의하세요.

GKE 볼륨 채우기를 사용하면 수동 데이터 전송을 위해 추가 스크립트나 CLI 명령어를 실행하지 않고도 동적 프로비저닝 중에 소스 저장소의 데이터를 대상 PersistentVolumeClaim에 미리 로드할 수 있습니다. 이 기능은 Kubernetes 볼륨 채우기 도구 기능을 활용하여 데이터 전송 프로세스를 자동화하고 간소화합니다. 원활한 데이터 이동성을 제공하므로 스토리지 유형을 전환하여 가격 또는 성능 최적화의 이점을 누릴 수 있습니다.

Cloud Storage 버킷에서 다른Google Cloud 스토리지 유형 (예: Parallelstore)으로 지원되는 PersistentVolumeClaim으로 대용량 데이터를 전송해야 하는 경우 이 기능을 사용하세요.

주로 gcloud CLI 및 kubectl CLI를 통해 GKE 볼륨 채우기 도구와 상호작용합니다. GKE 볼륨 채우기는 Autopilot 및 Standard 클러스터 모두에서 지원됩니다. GKE 볼륨 채우기를 사용 설정할 필요는 없습니다. 기본적으로 사용 설정되는 GKE 관리 구성요소입니다.

이점

• 관리형 병렬 파일 시스템의 성능을 활용하고 싶지만 데이터가 Cloud Storage에 저장되어 있다면 GKE 볼륨 채우기를 사용하여 데이터 전송을 간소화할 수 있습니다.
• GKE 볼륨 채우기를 사용하면 데이터를 이동할 수 있으므로 필요에 따라 데이터를 이동할 수 있습니다.
• GKE 볼륨 채우기는 IAM 기반 인증을 지원하므로 세분화된 액세스 제어를 유지하면서 데이터를 전송할 수 있습니다.

이 다이어그램은 데이터가 소스 스토리지에서 대상 스토리지로 이동하는 방식과 GKE 볼륨 채우기를 사용하여 대상 스토리지의 PersistentVolume을 만드는 방법을 보여줍니다.

제한사항

• GKE 볼륨 채우기는 소스 스토리지로 Cloud Storage 버킷만, 대상 스토리지 유형으로 Parallelstore 인스턴스만 지원합니다.
• GKE 볼륨 채우기는 volumeBindingMode가 Immediate로 설정된 StorageClass 리소스만 지원합니다.
• GCPDataSource 맞춤 리소스는 Kubernetes 워크로드와 동일한 네임스페이스에 있어야 합니다. 교차 네임스페이스 데이터 소스가 있는 볼륨은 지원되지 않습니다.
• GKE 볼륨 채우기는 IAM 서비스 계정을 Kubernetes 서비스 계정에 바인딩하는 GKE용 워크로드 아이덴티티 제휴만 지원합니다. Kubernetes 서비스 계정에 IAM 권한을 직접 부여하는 것은 지원되지 않습니다.

시작하기 전에

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

• Parallelstore API 및 Google Kubernetes Engine API를 사용 설정합니다.
API 사용 설정
• 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.
  참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.

• 제한사항 및 요구사항은 Parallelstore CSI 드라이버 개요를 참고하세요.
• 전송할 데이터가 채워진 Cloud Storage 버킷을 만듭니다.

요구사항

GKE 볼륨 채우기를 사용하려면 클러스터가 다음 요구사항을 충족해야 합니다.

• GKE 클러스터 버전 1.31.1-gke.1729000 이상을 사용합니다.
• Parallelstore CSI 드라이버가 사용 설정되어 있어야 합니다. GKE는 신규 및 기존 GKE Autopilot 클러스터에서 기본적으로 CSI 드라이버를 사용 설정합니다. 신규 및 기존 Standard 클러스터에서 CSI 드라이버를 사용 설정해야 합니다.

개발 환경 준비

이 섹션에서는 GKE 클러스터를 만들고 GKE 볼륨 채우기를 사용하는 데 필요한 권한을 설정하는 단계를 설명합니다.

VPC 네트워크 설정

참고: Parallelstore CSI 드라이버 설정의 일환으로 이미 VPC 네트워크를 구성한 경우 이 섹션을 건너뛸 수 있습니다.

Parallelstore 인스턴스와 클라이언트 Compute Engine VM 또는 GKE 클러스터를 만들 때 동일한 Virtual Private Cloud (VPC) 네트워크를 지정해야 합니다. VPC가 트래픽을 퍼블릭 인터넷에 노출하지 않고도 Google Cloud서비스에 비공개로 연결할 수 있도록 하려면 아직 구성하지 않은 경우 비공개 서비스 액세스(PSA)를 일회성으로 구성해야 합니다.

PSA를 구성하려면 다음 단계를 따르세요.

1. 프로젝트의 네트워크 피어링을 설정하려면 Compute 네트워크 관리자 (roles/compute.networkAdmin) IAM 권한을 구성합니다.

   역할을 부여하려면 다음 명령어를 실행하세요.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="user:EMAIL_ADDRESS" \
       --role=roles/compute.networkAdmin
   

   EMAIL_ADDRESS를 이메일 주소로 바꿉니다.

2. 서비스 네트워킹을 사용 설정합니다.

   gcloud services enable servicenetworking.googleapis.com
   

3. VPC 네트워크를 만듭니다.

   gcloud compute networks create NETWORK_NAME \
     --subnet-mode=auto \
     --mtu=8896 \
     --project=PROJECT_ID
   

   다음을 바꿉니다.

   • NETWORK_NAME: Parallelstore 인스턴스를 만들 VPC 네트워크의 이름입니다.
   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
   참고: mtu 값 (최대 전송 단위 또는 이 네트워크에서 전송할 수 있는 최대 IP 패킷 크기)을 허용되는 최대 값인 8, 896으로 설정하면 기본값인 1,460바이트에 비해 성능이 최대 10% 향상됩니다.

4. IP 범위를 만듭니다.

   비공개 서비스 액세스를 사용하려면 접두사 길이가 /24 이상 (256개 주소)인 IP 주소 범위 (CIDR 블록)가 필요합니다. Parallelstore는 인스턴스당 64개의 주소를 예약합니다. 즉, 필요한 경우 이 IP 범위를 다른 서비스 또는 다른 Parallelstore 인스턴스에서 재사용할 수 있습니다.

   gcloud compute addresses create IP_RANGE_NAME \
     --global \
     --purpose=VPC_PEERING \
     --prefix-length=24 \
     --description="Parallelstore VPC Peering" \
     --network=NETWORK_NAME \
     --project=PROJECT_ID
   

   IP_RANGE_NAME을 VPC 네트워크 IP 범위 이름으로 바꿉니다.

5. 이전 단계에서 만든 범위와 연결된 CIDR 범위로 환경 변수를 설정합니다.

   CIDR_RANGE=$(
     gcloud compute addresses describe IP_RANGE_NAME \
       --global  \
       --format="value[separator=/](address, prefixLength)" \
       --project=PROJECT_ID \
   )
   

6. 만든 IP 범위의 TCP 트래픽을 허용하는 방화벽 규칙을 만듭니다.

   gcloud compute firewall-rules create FIREWALL_NAME \
     --allow=tcp \
     --network=NETWORK_NAME \
     --source-ranges=$CIDR_RANGE \
     --project=PROJECT_ID
   

   만들려는 IP 범위의 TCP 트래픽을 허용하도록 FIREWALL_NAME을 방화벽 규칙의 이름으로 바꿉니다.

7. 피어링을 연결합니다.

   gcloud services vpc-peerings connect \
     --network=NETWORK_NAME \
     --ranges=IP_RANGE_NAME \
     --project=PROJECT_ID \
     --service=servicenetworking.googleapis.com
   

VPC 네트워크를 설정하는 중에 문제가 발생하면 Parallelstore 문제 해결 가이드를 확인하세요.

GKE 클러스터 만들기

완전 관리형 Kubernetes 환경을 위해서는 Autopilot 클러스터를 사용하는 것이 좋습니다. 워크로드 요구사항에 가장 적합한 GKE 작업 모드를 선택하려면 GKE 작업 모드 선택을 참고하세요.

Autopilot

Autopilot을 사용하여 GKE 클러스터를 만들려면 다음 명령어를 실행합니다.

gcloud container clusters create-auto CLUSTER_NAME  \
    --network=NETWORK_NAME  \
    --cluster-version=CLUSTER_VERSION \
    --location=CLUSTER_LOCATION

GKE는 Autopilot 클러스터에서 기본적으로 GKE용 워크로드 아이덴티티 제휴 및 Parallelstore CSI 드라이버를 사용 설정합니다.

다음 값을 바꿉니다.

• CLUSTER_NAME: 클러스터 이름입니다.
• CLUSTER_VERSION : GKE 버전 번호입니다. 1.31.1-gke.1729000 이상을 지정해야 합니다.
• NETWORK_NAME: Parallelstore 인스턴스를 위해 만든 VPC 네트워크의 이름입니다. 자세한 내용은 VPC 네트워크 구성을 참고하세요.
• CLUSTER_LOCATION: 클러스터를 만들 리전입니다. 최적의 성능을 위해 지원되는 Parallelstore 위치에 클러스터를 만드는 것이 좋습니다. 지원되지 않는 Parallelstore 위치에 클러스터를 만들려면 Parallelstore StorageClass를 만들 때 지원되는 Parallelstore 위치를 사용하는 커스텀 토폴로지를 지정해야 합니다. 그러지 않으면 프로비저닝이 실패합니다.

스탠더드

다음 명령어를 사용하여 Parallelstore CSI 드라이버와 GKE용 워크로드 아이덴티티 제휴가 사용 설정된 Standard 클러스터를 만듭니다.

gcloud container clusters create CLUSTER_NAME \
    --addons=ParallelstoreCsiDriver \
    --cluster-version=CLUSTER_VERSION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --network=NETWORK_NAME \
    --location=CLUSTER_LOCATION

다음 값을 바꿉니다.

• CLUSTER_NAME: 클러스터 이름입니다.
• CLUSTER_VERSION: GKE 버전 번호입니다. 1.31.1-gke.1729000 이상을 지정해야 합니다.
• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• NETWORK_NAME: Parallelstore 인스턴스를 위해 만든 VPC 네트워크의 이름입니다. 자세한 내용은 VPC 네트워크 구성을 참고하세요.
• CLUSTER_LOCATION: 클러스터를 만들 리전 또는 영역입니다. 최적의 성능을 위해 지원되는 Parallelstore 위치에 클러스터를 만드는 것이 좋습니다. 지원되지 않는 Parallelstore 위치에 클러스터를 만들려면 Parallelstore StorageClass를 만들 때 지원되는 Parallelstore 위치를 사용하는 커스텀 토폴로지를 지정해야 합니다. 그러지 않으면 프로비저닝이 실패합니다.

필요한 권한 설정

Cloud Storage 버킷에서 데이터를 전송하려면 GKE용 워크로드 아이덴티티 제휴의 권한을 설정해야 합니다.

1. Kubernetes 네임스페이스를 만듭니다.

   kubectl create namespace NAMESPACE
   

   NAMESPACE를 워크로드가 실행될 네임스페이스로 바꿉니다.

2. Kubernetes 서비스 계정을 만듭니다.

   kubectl create serviceaccount KSA_NAME \
       --namespace=NAMESPACE
   

   KSA_NAME를 포드가 Google Cloud API에 인증하는 데 사용하는 Kubernetes 서비스 계정의 이름으로 바꿉니다.

   주의: 동일한 네임스페이스 내 워크로드에서 이 Kubernetes 서비스 계정을 재사용하면 해당 포드가 Cloud Storage 버킷에 액세스할 수 있습니다. 네임스페이스의 워크로드에 이 서비스 계정을 재사용하지 않는 것이 좋습니다.

3. IAM 서비스 계정을 만듭니다. 조직의 프로젝트에 있는 기존 IAM 서비스 계정을 사용할 수도 있습니다.

   gcloud iam service-accounts create IAM_SA_NAME \
       --project=PROJECT_ID
   

   다음을 바꿉니다.

   • IAM_SA_NAME: IAM 서비스 계정의 이름입니다.
   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

4. IAM 서비스 계정이 Cloud Storage 버킷에 액세스할 수 있도록 roles/storage.objectViewer 역할을 부여합니다.

   gcloud storage buckets \
       add-iam-policy-binding gs://GCS_BUCKET \
       --member "serviceAccount:IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --role "roles/storage.objectViewer"
   

   GCS_BUCKET을 Cloud Storage 버킷 이름으로 바꿉니다.

5. Kubernetes 서비스 계정에 IAM 서비스 계정을 가장할 수 있는 액세스 권한을 부여하는 IAM 허용 정책을 만듭니다.

   gcloud iam service-accounts \
       add-iam-policy-binding IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --role roles/iam.workloadIdentityUser \
       --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
   

6. GKE에 서비스 계정 간의 링크가 표시되도록 Kubernetes 서비스 계정에 주석을 추가합니다.

   kubectl annotate serviceaccount KSA_NAME \
       --namespace NAMESPACE \
       iam.gke.io/gcp-service-account=IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   

7. Parallelstore 서비스 ID를 만듭니다.

   gcloud beta services identity create \
       --service=parallelstore.googleapis.com \
       --project=PROJECT_ID
   

8. Parallelstore 서비스 ID에 roles/iam.serviceAccountTokenCreator 역할을 부여하여 IAM 서비스 계정을 가장하도록 허용합니다. 이후 단계에서 사용할 수 있도록 PROJECT_NUMBER 환경 변수를 설정합니다.

   export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   gcloud iam service-accounts \
       add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --member=serviceAccount:"service-${PROJECT_NUMBER?}@gcp-sa-parallelstore.iam.gserviceaccount.com" \
       --role=roles/iam.serviceAccountTokenCreator
   

   PROJECT_NUMBER 값은 프로젝트의 자동으로 생성된 고유 식별자입니다. 이 값을 찾으려면 프로젝트 만들기 및 관리를 참고하세요.

9. Parallelstore 서비스 ID에 roles/iam.serviceAccountUser 역할을 부여하여 IAM 서비스 계정에서 액세스할 수 있는 모든 리소스에 액세스할 수 있도록 합니다.

   gcloud iam service-accounts \
       add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --member=serviceAccount:"service-${PROJECT_NUMBER?}@gcp-sa-parallelstore.iam.gserviceaccount.com" \
       --role=roles/iam.serviceAccountUser
   

10. GKE 서비스 ID에 roles/iam.serviceAccountUser 역할을 부여하여 IAM 서비스 계정이 액세스할 수 있는 모든 리소스에 액세스할 수 있도록 합니다. GKE 클러스터와 IAM 서비스 계정이 동일한 프로젝트에 있는 경우에는 이 단계가 필요하지 않습니다.

    gcloud iam service-accounts \
        add-iam-policy-binding "IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --member=serviceAccount:"service-${PROJECT_NUMBER?}@container-engine-robot.iam.gserviceaccount.com" \
        --role=roles/iam.serviceAccountUser
    

미리 로드된 데이터가 포함된 Parallelstore 볼륨 만들기

다음 섹션에서는 GKE 볼륨 채우기를 사용하여 Cloud Storage 버킷에서 미리 로드된 데이터가 포함된 Parallelstore 볼륨을 만드는 일반적인 프로세스를 설명합니다.

1. GCPDataSource 리소스를 만듭니다.
2. Parallelstore StorageClass를 만듭니다.
3. 볼륨에 액세스할 PersistentVolumeClaim을 만듭니다.
4. PersistentVolumeClaim 프로비저닝이 완료되었는지 확인합니다.
5. (선택사항) 데이터 전송 진행률 보기
6. 볼륨을 사용하는 워크로드를 만듭니다.

GCPDataSource 리소스 만들기

GKE 볼륨 채우기를 사용하려면 GCPDataSource 커스텀 리소스를 만듭니다. 이 리소스는 볼륨 채우기에 사용할 소스 저장소 속성을 정의합니다.

1. gcpdatasource.yaml 파일에 다음 매니페스트를 저장합니다.

   apiVersion: datalayer.gke.io/v1
   kind: GCPDataSource
   metadata:
     name: GCP_DATA_SOURCE
     namespace: NAMESPACE
   spec:
     cloudStorage:
       serviceAccountName: KSA_NAME
       uri: gs://GCS_BUCKET/
   

   다음 값을 바꿉니다.

   • GCP_DATA_SOURCE: Cloud Storage 버킷 참조를 보유한 GCPDataSource CRD의 이름입니다. 자세한 내용은 GCPDataSource CRD 참조를 참고하세요.
   • NAMESPACE: 워크로드가 실행되는 네임스페이스입니다. 네임스페이스 값은 워크로드 네임스페이스와 동일해야 합니다.
   • KSA_NAME: 포드가 Google Cloud API에 인증하는 데 사용하는 Kubernetes 서비스 계정의 이름입니다. cloudStorage.serviceAccountName 값은 필요한 권한 설정 단계에서 GKE용 워크로드 아이덴티티 제휴에 설정한 Kubernetes 서비스 계정입니다.
   • GCS_BUCKET: Cloud Storage 버킷 이름 또는 uri 필드에 gs://GCS_BUCKET/PATH_INSIDE_BUCKET/를 지정할 수도 있습니다.

2. 다음 명령어를 실행하여 GCPDataSource 리소스를 만듭니다.

   kubectl apply -f gcpdatasource.yaml
   

Parallelstore StorageClass 만들기

StorageClass를 만들어 Parallelstore CSI 드라이버가 GKE 클러스터와 동일한 리전에 Parallelstore 인스턴스를 프로비저닝하도록 지시합니다. 이렇게 하면 최적의 I/O 성능을 보장할 수 있습니다.

1. 다음 매니페스트를 parallelstore-class.yaml로 저장합니다. StorageClass 정의의 volumeBindingMode 필드가 Immediate로 설정되어 있는지 확인합니다.

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: parallelstore-class
   provisioner: parallelstore.csi.storage.gke.io
   volumeBindingMode: Immediate
   reclaimPolicy: Delete
   

2. 다음 명령어를 실행하여 StorageClass를 만듭니다.

   kubectl apply -f parallelstore-class.yaml
   

특정 토폴로지로 커스텀 StorageClass를 만들려면 Parallelstore CSI 가이드를 참고하세요.

PersistentVolumeClaim을 만들어 볼륨에 액세스

다음 매니페스트 파일에서는 앞에서 만든 StorageClass를 참조하는 ReadWriteMany 액세스 모드에서 PersistentVolumeClaim을 만드는 방법에 대한 예시를 보여줍니다.

1. volume-populator-pvc.yaml이라는 파일에 매니페스트를 저장합니다.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: PVC_NAME
     namespace: NAMESPACE
   spec:
     accessModes:
     - ReadWriteMany
     storageClassName: parallelstore-class
     resources:
       requests:
         storage: 12Gi
     dataSourceRef:
       apiGroup: datalayer.gke.io
       kind: GCPDataSource
       name: GCP_DATA_SOURCE
   

   다음 값을 바꿉니다.

   • PVC_NAME: 데이터를 전송할 PersistentVolumeClaim의 이름입니다. PersistentVolumeClaim은 Parallelstore 인스턴스에 의해 지원되어야 합니다.
   • NAMESPACE: 워크로드가 실행되는 네임스페이스입니다. 네임스페이스 값은 워크로드 네임스페이스와 동일해야 합니다.
   • GCP_DATA_SOURCE: Cloud Storage 버킷 참조를 보유한 GCPDataSource CRD의 이름입니다. 자세한 내용은 GCPDataSource CRD 참조를 참고하세요.

2. 다음 명령어를 실행하여 PersistentVolumeClaim을 만듭니다.

   kubectl apply -f volume-populator-pvc.yaml
   

PersistentVolumeClaim 프로비저닝이 완료될 때까지 GKE는 워크로드 포드를 예약하지 않습니다. 데이터 전송 진행률을 확인하려면 데이터 전송 진행률 보기를 참고하세요. 프로비저닝 중에 오류가 발생하면 문제 해결을 참고하세요.

PersistentVolumeClaim 프로비저닝이 완료되었는지 확인

주의: Autopilot을 사용하는 경우 이 확인을 수행하기 전에 먼저 볼륨을 사용하는 워크로드를 만드세요. 이 단계는 GKE에서 노드를 만들도록 트리거하는 데 필요합니다. 그러지 않으면 "error generating accessibility requirements: no available topology found"와 같은 오류가 발생하여 몇 분 동안 지속될 수 있습니다.

GKE 볼륨 채우기는 볼륨 프로비저닝을 위해 gke-managed-volumepopulator 네임스페이스의 임시 PersistentVolumeClaim을 사용합니다.

임시 PersistentVolumeClaim은 본질적으로 아직 전송 중인 (데이터가 완전히 로드될 때까지 대기 중인) PersistentVolumeClaim의 스냅샷입니다. 이름은 prime-YOUR_PVC_UID 형식입니다.

상태를 확인하려면 다음 단계를 따르세요.

1. 다음 명령어를 실행합니다.

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   
   TEMP_PVC=prime-$PVC_UID
   
   echo $TEMP_PVC
   
   kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator
   

   출력이 비어 있으면 임시 PersistentVolumeClaim이 생성되지 않은 것입니다. 이 경우 문제 해결 섹션을 참고하세요.

   프로비저닝에 성공하면 출력은 다음과 비슷합니다. ProvisioningSucceeded 로그를 찾습니다.

   Warning  ProvisioningFailed     9m12s                   parallelstore.csi.storage.gke.io_gke-10fedd76bae2494db688-2237-793f-vm_5f284e53-b25c-46bb-b231-49e894cbba6c  failed to provision volume with StorageClass "parallelstore-class": rpc error: code = DeadlineExceeded desc = context deadline exceeded
   Warning  ProvisioningFailed     3m41s (x11 over 9m11s)  parallelstore.csi.storage.gke.io_gke-10fedd76bae2494db688-2237-793f-vm_5f284e53-b25c-46bb-b231-49e894cbba6c  failed to provision volume with StorageClass "parallelstore-class": rpc error: code = DeadlineExceeded desc = Volume pvc-808e41a4-b688-4afe-9131-162fe5d672ec not ready, current state: CREATING
   Normal   ExternalProvisioning   3m10s (x43 over 13m)    persistentvolume-controller                                                                                  Waiting for a volume to be created either by the external provisioner 'parallelstore.csi.storage.gke.io' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
   Normal  Provisioning  8s (x13 over 10m)  "xxx"  External provisioner is provisioning volume for claim "xxx"
   Normal  ProvisioningSucceeded  7s  "xxx"  Successfully provisioned volume "xxx"
   

   참고: CSI 프로비저닝이 볼륨 프로비저닝 상태를 조정하려고 하므로 출력에 경고가 표시될 수 있습니다. Parallelstore 볼륨 프로비저닝에는 일반적으로 10분 정도 걸립니다.

2. Parallelstore 인스턴스 생성이 시작되었는지 확인합니다.

   gcloud beta parallelstore instances list \
       --project=PROJECT_ID \
       --location=-
   

   출력은 다음과 비슷합니다. 볼륨이 CREATING 상태인지 확인합니다. Parallelstore 인스턴스 생성이 완료되면 상태가 ACTIVE로 변경됩니다.

   "projects/PROJECT_ID/locations/<my-location>/<my-volume>"  12000  2024-10-09T17:59:42.582857261Z  2024-10-09T17:59:42.582857261Z  CREATING  projects/PROJECT_ID/global/NETWORK_NAME
   

프로비저닝에 실패한 경우 Parallelstore 문제 해결 가이드에서 추가 안내를 참고하세요.

(선택사항) 데이터 전송 진행률 보기

이 섹션에서는 Cloud Storage 버킷에서 Parallelstore 볼륨으로의 데이터 전송 진행 상황을 추적하는 방법을 보여줍니다. 이렇게 하면 전송 상태를 모니터링하고 데이터가 성공적으로 복사되었는지 확인할 수 있습니다. PersistentVolumeClaim 바인딩 작업이 너무 오래 걸리는 경우에도 이 명령어를 실행해야 합니다.

1. 다음 명령어를 실행하여 PersistentVolumeClaim의 상태를 확인합니다.

   kubectl describe pvc PVC_NAME -n NAMESPACE
   

2. PersistentVolumeClaim 이벤트 메시지를 확인하여 데이터 전송 진행률을 확인합니다. GKE는 메시지를 1분에 한 번 정도 로깅합니다. 출력은 다음과 비슷합니다.

   Reason                          Message
   ------                          -------
   PopulateOperationStartSuccess   Populate operation started
   PopulateOperationStartSuccess   Populate operation started
   Provisioning                    External provisioner is provisioning volume for claim "my-namespace/my-pvc"
   Provisioning                    Assuming an external populator will provision the volume
   ExternalProvisioning            Waiting for a volume to be created either by the external provisioner 'parallelstore.csi.storage.gke.io' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
   PopulateOperationStartSuccess   Populate operation started
   PopulatorPVCCreationProgress    objects found 7, objects copied 7, objects skipped 0. bytes found 1000020010, bytes copied 1000020010, bytes skipped 0
   PopulateOperationFinished       Populate operation finished
   PopulatorFinished               Populator finished
   

채우기 작업이 시작되기까지 다소 시간이 걸릴 수 있습니다. 이 작업은 파일 크기에 따라 다릅니다. 몇 분 후에도 데이터 전송 진행률이 표시되지 않으면 문제 해결 섹션을 참고하세요.

볼륨을 사용하는 워크로드 만들기

이 섹션에서는 앞에서 만든 PersistentVolumeClaim 리소스를 사용하는 포드를 만드는 방법에 대한 예시를 보여줍니다.

1. 포드의 다음 YAML 매니페스트를 pod.yaml로 저장합니다.

   apiVersion: v1
   kind: Pod
   metadata:
     name: POD_NAME
     namespace: NAMESPACE
   spec:
     volumes:
     - name: parallelstore-volume
       persistentVolumeClaim:
         claimName: PVC_NAME
     containers:
     - image: nginx
       name: nginx
       volumeMounts:
       - name: parallelstore-volume
         mountPath: /mnt/data
   

   다음 값을 바꿉니다.

   • POD_NAME: 워크로드를 실행하는 포드의 이름입니다.
   • NAMESPACE: 워크로드가 실행될 네임스페이스입니다. 네임스페이스 값은 워크로드 네임스페이스와 동일해야 합니다.
   • PVC_NAME: 데이터를 전송할 PersistentVolumeClaim의 이름입니다. PersistentVolumeClaim은 Parallelstore 인스턴스에 의해 지원되어야 합니다.

2. 다음 명령어를 실행하여 매니페스트를 클러스터에 적용합니다.

   kubectl apply -f pod.yaml
   

3. 포드 상태를 확인하고 상태가 RUNNING가 될 때까지 기다립니다. 워크로드를 실행하려면 PersistentVolumeClaim을 바인딩해야 합니다.

   kubectl describe pod POD_NAME -n NAMESPACE
   

4. 파일이 전송되었는지, 워크로드에서 액세스할 수 있는지 확인합니다.

   kubectl exec -it POD_NAME -n NAMESPACE -c nginx -- /bin/sh
   

   /mnt/data 디렉터리로 변경하고 ls를 실행합니다.

   cd /mnt/data
   ls
   

   출력에는 Cloud Storage 버킷 URI에 있는 모든 파일이 나열됩니다.

동적 프로비저닝 중에 PersistentVolumeClaim 삭제

동적 프로비저닝 중에 데이터가 전송되는 동안 PersistentVolumeClaim을 삭제해야 하는 경우 조용히 삭제와 강제 삭제라는 두 가지 옵션이 있습니다.

조용히 삭제하는 방법은 더 적은 노력이 들지만 시간이 더 오래 걸릴 수 있으며 데이터 전송을 완료하지 못하게 하는 사용자 구성 오류를 고려하지 않습니다. 강제 삭제는 더 빠르고 유연하며 제어 가능한 대안을 제공합니다. 이 옵션은 구성 오류를 빠르게 다시 시작하거나 수정해야 할 때 적합합니다.

단계적 삭제

이 삭제 옵션을 사용하면 GKE에서 연결된 리소스를 삭제하기 전에 데이터 전송 프로세스가 완료되도록 할 수 있습니다.

1. 다음 명령어를 실행하여 워크로드 포드(있는 경우)를 삭제합니다.

   kubectl delete pod POD_NAME -n NAMESPACE
   

2. 임시 PersistentVolumeClaim의 이름을 찾습니다.

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   TEMP_PVC=prime-$PVC_UID
   
   echo $TEMP_PVC
   

3. PersistentVolume의 이름을 찾습니다.

   PV_NAME=$(kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')
   
   echo ${PV_NAME?}
   

   출력이 비어 있으면 PersistentVolume이 아직 생성되지 않았음을 의미합니다.

4. 다음 명령어를 실행하여 PersistentVolumeClaim을 삭제합니다. finalizer가 삭제 작업을 차단합니다. Ctrl+C 키를 누른 다음 다음 단계로 이동합니다.

   kubectl delete pvc PVC_NAME -n NAMESPACE
   

   데이터 전송이 완료될 때까지 기다립니다. GKE는 결국 PersistentVolumeClaim, PersistentVolume, Parallelstore 인스턴스를 삭제합니다.

5. 임시 PersistentVolumeClaim, PersistentVolumeClaim, PersistentVolume 리소스가 삭제되었는지 확인합니다.

   kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
   

6. Parallelstore 인스턴스가 삭제되었는지 확인합니다. Parallelstore 인스턴스는 PersistentVolume과 동일한 이름을 공유합니다. 3단계에서 PersistentVolume이 생성되지 않았음을 확인한 경우에는 이 명령어를 실행할 필요가 없습니다.

   gcloud beta parallelstore instances list \
       --project=PROJECT_ID \
       --location=- | grep ${PV_NAME?}
   

강제 삭제

데이터 전송 프로세스가 완료되기 전에 PersistentVolumeClaim 및 연결된 리소스를 삭제해야 하는 경우 이 삭제 옵션을 사용하세요. 데이터 전송이 너무 오래 걸리거나 오류가 발생했거나 리소스를 빠르게 재사용해야 하는 경우에 이 작업이 필요할 수 있습니다.

1. 워크로드 포드가 있는 경우 삭제합니다.

   kubectl delete pod POD_NAME -n NAMESPACE
   

2. PersistentVolume 재확보 정책을 Delete로 업데이트합니다. 이렇게 하면 연결된 PersistentVolumeClaim이 삭제될 때 기본 스토리지와 함께 PersistentVolume이 자동으로 삭제됩니다.

   다음 중 하나라도 해당하는 경우 다음 명령어를 건너뜁니다.

   • PersistentVolume 또는 기본 스토리지를 삭제하고 싶지 않습니다.
   • 현재 재사용 정책이 Retain이고 기본 스토리지를 유지하려고 합니다. 필요에 따라 PersistentVolume 및 스토리지 인스턴스를 수동으로 정리합니다.
   • 다음 echo $PV_NAME 명령어는 빈 문자열을 출력합니다. 즉, PersistentVolume이 아직 생성되지 않았음을 의미합니다.

   PV_NAME=$(kubectl describe pvc $TEMP_PVC -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')
   
   echo $PV_NAME
   
   kubectl patch pv $PV_NAME -p '{"spec":{"persistentVolumeReclaimPolicy":"Delete"}}'
   

3. 임시 PersistentVolumeClaim의 이름을 찾고 나중에 사용할 환경 변수를 설정합니다.

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   
   TEMP_PVC=prime-$PVC_UID
   
   echo $TEMP_PVC
   

4. 다음 명령어를 실행하여 PersistentVolumeClaim을 삭제합니다. 종료자는 삭제 작업을 차단합니다. Ctrl+C 키를 누른 다음 다음 단계로 이동합니다.

   kubectl delete pvc PVC_NAME -n NAMESPACE
   

5. PersistentVolumeClaim에서 datalayer.gke.io/populate-target-protection 파이널라이저를 삭제합니다. 이 단계는 PersistentVolumeClaim을 삭제한 후에 필요합니다. 그렇지 않으면 gke-volume-populator가 PersistentVolumeClaim에 종료자를 다시 추가합니다.

   kubectl get pvc PVC_NAME -n NAMESPACE -o=json | \
   jq '.metadata.finalizers = null' | kubectl apply -f -
   

6. gke-managed-volumepopulator 네임스페이스에서 임시 PersistentVolumeClaim을 삭제합니다.

   kubectl delete pvc $TEMP_PVC -n gke-managed-volumepopulator
   

7. 임시 PersistentVolumeClaim, PersistentVolumeClaim, PersistentVolume 리소스가 삭제되었는지 확인합니다.

   kubectl get pvc,pv -A | grep -E "${TEMP_PVC?}|PVC_NAME|${PV_NAME?}"
   

8. Parallelstore 인스턴스가 삭제되었는지 확인합니다. Parallelstore 인스턴스는 PersistentVolume과 동일한 이름을 공유합니다. 2단계에서 PersistentVolume이 생성되지 않았음을 확인한 경우에는 이 명령어를 실행할 필요가 없습니다.

   gcloud beta parallelstore instances list \
       --project=PROJECT_ID \
       --location=- | grep ${PV_NAME?}
   

문제 해결

이 섹션에서는 GKE 볼륨 채우기 도구와 관련된 문제를 해결하는 방법을 설명합니다.

계속하기 전에 다음 명령어를 실행하여 PersistentVolumeClaim 이벤트 경고가 있는지 확인합니다.

kubectl describe pvc PVC_NAME -n NAMESPACE

오류: An internal error has occurred

다음 오류가 발생하면 Parallelstore API 내부 오류가 발생했음을 나타냅니다.

Warning
PopulateOperationStartError
gkevolumepopulator-populator                                                            Failed to start populate operation: populate data for PVC "xxx". Import data failed, error: rpc error: code = Internal desc = An internal error has occurred ("xxx")

이 문제를 해결하려면 다음 단계에 따라 지원팀에 데이터를 수집해야 합니다.

1. 다음 명령어를 실행하여 임시 PersistentVolumeClaim의 이름을 가져옵니다. 이때 자리표시자를 실제 이름으로 바꿉니다.

   PVC_UID=$(kubectl get pvc PVC_NAME -n NAMESPACE -o yaml | grep uid | awk '{print $2}')
   
   TEMP_PVC=prime-${PVC_UID?}
   
   echo ${TEMP_PVC?}
   

2. 다음 명령어를 실행하여 볼륨 이름을 가져옵니다.

   PV_NAME=$(kubectl describe pvc ${TEMP_PVC?} -n gke-managed-volumepopulator | grep "Volume:" | awk '{print $2}')
   

3. 오류 메시지, 프로젝트 이름, 볼륨 이름을 포함하여 지원팀에 문의하세요.

권한 문제

볼륨 채우기 중에 다음과 같은 오류가 발생하면 GKE에 권한 문제가 발생했음을 나타냅니다.

• Cloud Storage 버킷이 없음: PopulateOperationStartError 및 code = PermissionDenied
• Cloud Storage 버킷 또는 서비스 계정에 권한이 없음: PopulateOperationFailed 및 "code: "xxx" message:"Verify if bucket "xxx" exists and grant access"
• 서비스 계정 찾을 수 없음: code = Unauthenticated이 있는 PopulateOperationStartError

이 문제를 해결하려면 다음을 다시 한번 확인하세요.

• Cloud Storage 버킷 액세스: 버킷이 있고 서비스 계정에 roles/storage.objectViewer permission가 있는지 확인합니다.
• 서비스 계정: Kubernetes 서비스 계정과 IAM 서비스 계정이 모두 존재하고 올바르게 연결되어 있는지 확인합니다.
• Parallelstore 서비스 계정: 계정이 존재하고 필요한 권한 (IAM 계정의 roles/iam.serviceAccountTokenCreator 및 roles/iam.serviceAccountUser)이 있는지 확인합니다.

자세한 단계와 확인 명령어는 필요한 권한 설정하기를 참고하세요. 오류가 계속되면 오류 메시지, 프로젝트 이름, Cloud Storage 버킷 이름을 포함하여 지원팀에 문의하세요.

잘못된 인수 오류

InvalidArgument 오류가 발생하면 GCPDataSource 또는 PersistentVolumeClaim에 잘못된 값을 제공했을 가능성이 큽니다. 오류 로그에는 잘못된 데이터가 포함된 정확한 필드가 표시됩니다. Cloud Storage 버킷 URI 및 기타 관련 입력란이 정확한지 확인합니다.

다음 단계

• Parallelstore CSI 참고 문서 살펴보기
• Parallelstore 가로채기 라이브러리를 사용하여 워크로드 성능을 개선하는 방법 알아보기
• GKE에서 Keras를 사용하여 TensorFlow 모델을 학습시키는 튜토리얼 사용해 보기