GKE 볼륨 포퓰레이터 데이터 전송 문제 해결

이 가이드에서는 GKE 볼륨 포퓰레이터를 사용하여 GKE 클러스터로 데이터를 전송할 때 발생하는 일반적인 문제를 해결하는 방법을 보여줍니다. PersistentVolumeClaim (PVC) 및 PersistentVolume (PV) 생성, 디스크 성능, 데이터 전송 작업 실행과 관련된 문제를 디버깅하는 방법을 안내합니다.

임시 Kubernetes 리소스 검사

GKE 볼륨 포퓰레이터가 임시 리소스를 사용하는 방법은 다음과 같습니다.

  1. gke-managed-volumepopulator 네임스페이스에 임시 PVC가 생성됩니다.
  2. 전송에 관련된 각 영역에 대해 전송 작업, PV, PVC가 PVC의 네임스페이스에 생성됩니다.
  3. 데이터 전송이 완료되면 GKE 볼륨 포퓰레이터가 이러한 임시 리소스를 모두 자동으로 삭제합니다.

임시 리소스를 검사하려면 다음 단계를 따르세요.

  1. 환경 변수를 저장합니다.

    export PVC_NAME=PVC_NAME
export NAMESPACE=NAMESPACE

    다음 값을 바꿉니다.

    • PVC_NAME: PersistentVolumeClaim 리소스의 이름입니다.
    • NAMESPACE: 워크로드가 실행되는 네임스페이스입니다.

  2. 상태를 파악합니다.

    export PVC_UID=$(kubectl get pvc ${PVC_NAME} -n ${NAMESPACE} -o jsonpath='{.metadata.uid}')
export TEMP_PVC=prime-${PVC_UID}
echo ${TEMP_PVC}

  3. gke-managed-volumepopulator 네임스페이스에서 임시 PVC를 검사합니다.

    kubectl describe pvc ${TEMP_PVC} -n gke-managed-volumepopulator

  4. 네임스페이스에서 임시 PVC의 이름을 가져옵니다.

    export TEMP_PVC_LIST=($(kubectl get pvc -n "$NAMESPACE" -o json | grep -Eo "\"name\":\s*\"$TEMP_PVC[^\"]*\"" | awk -F'"' '{print $4}'))

for pvc in "${TEMP_PVC_LIST[@]}"; do
  echo "$pvc"
done

  5. 임시 PVC를 검사합니다.

    kubectl describe pvc "${TEMP_PVC_LIST[0]}" -n $NAMESPACE

  6. GKE 볼륨 포퓰레이터는 각 영역에 전송 작업을 만듭니다 (단일 영역 Hyperdisk ML 볼륨의 경우 하나, 다중 영역 Hyperdisk ML 볼륨의 경우 여러 개). 다음 명령어를 사용하여 전송 작업 이름을 가져옵니다.

    export TRANSFER_JOB=$(kubectl get pvc "${TEMP_PVC_LIST[0]}" -n "$NAMESPACE" -o "jsonpath={.metadata.annotations['volume-populator\.datalayer\.gke\.io/pd-transfer-requestid']}")

echo $TRANSFER_JOB

  7. 전송 작업을 검사합니다.

    kubectl describe job $TRANSFER_JOB -n $NAMESPACE

  8. 전송 작업에서 포드 이름을 가져옵니다.

    export TRANSFER_POD=$(kubectl get pods -n "$NAMESPACE" -l "job-name=$TRANSFER_JOB" -o jsonpath='{.items[0].metadata.name}')

echo $TRANSFER_POD

  9. 포드를 검사합니다.

    kubectl describe pod $TRANSFER_POD -n $NAMESPACE

    여러 영역에 PVC를 만들면 GKE 볼륨 포퓰레이터는 지정된 각 영역에 대해 별도의 임시 PVC와 전송 작업 리소스를 만듭니다. 전송에 관련된 모든 영역의 리소스를 검사하려면 TEMP_PVC_LIST의 색인인 0을 다른 숫자로 바꿉니다.

워크로드 아이덴티티 제휴가 사용 설정되어 있는지 확인

워크로드 아이덴티티 제휴를 사용하면 전송 포드가 Trusted Cloud by S3NS 서비스에 안전하게 액세스할 수 있습니다. 전송 포드가 Trusted Cloud by S3NS에 인증할 수 없는 경우 클러스터에서 GKE용 워크로드 아이덴티티 제휴가 사용 설정되어 있는지 확인합니다.

  1. 클러스터에서 workloadIdentityConfig가 사용 설정되어 있는지 확인하려면 다음 명령어를 실행합니다.

    gcloud container clusters describe CLUSTER_NAME
--location=LOCATION \
--project=PROJECT_ID \
--format="value(workloadIdentityConfig)"

    다음을 바꿉니다.

    • CLUSTER_NAME: 클러스터 이름입니다.
    • LOCATION: 클러스터의 컴퓨팅 리전 또는 영역입니다.
    • PROJECT_ID: Trusted Cloud 프로젝트 ID입니다.

  2. 명령어에서 다음 출력을 확인합니다.

    PROJECT_ID.svc.id.goog

  3. 출력에 workloadIdentityConfig가 누락된 경우 GKE용 워크로드 아이덴티티 제휴를 사용 설정합니다.

잘못된 트랜스퍼 경로

다음과 유사한 오류가 발생하면 GCPDatasource 리소스에 지정된 전송 경로가 잘못된 것이므로 전송이 실패합니다.

ERROR: (gcloud.storage.cp) The following URLs matched no objects or files:
gs://datasets-pd/llama2-7b-hfa/

이 문제를 해결하려면 GCPDatasource 리소스를 삭제하고 uri 필드를 올바른 값으로 업데이트한 후 리소스를 다시 만드세요.

버킷에 액세스할 권한이 없습니다.

Kubernetes 서비스 계정에 GCPDatasource 리소스에 지정된 버킷 URI에 대한 액세스 권한이 없으면 전송 작업이 실패합니다. 오류는 다음과 유사하게 표시될 수 있습니다.

ERROR: (gcloud.storage.cp) [test-gke-dev.svc.id.goog] does not have permission to access b instance [small-bucket-7] (or it may not exist): Caller does not have storage.objects.list access to the Google Cloud Storage bucket. Permission 'storage.objects.list' denied on resource (or it may not exist). This command is authenticated as test-gke-dev.svc.id.goog which is the active account specified by the [core/account] property.

이 문제를 해결하려면 버킷에서 디스크로 데이터를 전송하는 데 필요한 권한을 부여하세요.

gcloud storage buckets \
    add-iam-policy-binding gs://GCS_BUCKET \
     --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE"

다음을 바꿉니다.

  • GCS_BUCKET: Cloud Storage 버킷 이름
  • PROJECT_NUMBER: Trusted Cloud 프로젝트 번호
  • PROJECT_ID: Trusted Cloud 프로젝트 ID입니다.
  • NAMESPACE: 워크로드가 실행되는 네임스페이스입니다.
  • KSA_NAME: Kubernetes 서비스 계정의 이름입니다.
  • ROLE: 버킷에 액세스하는 데 필요한 권한을 제공하는 IAM 역할입니다. 예를 들어 roles/storage.objectViewer를 사용하여 버킷에 대한 읽기 전용 액세스 권한을 부여합니다.

오류: error generating accessibility requirements

gke-managed-volumepopulator 네임스페이스에서 PVC를 확인할 때 다음과 같은 일시적인 오류가 표시될 수 있습니다.

Error: error generating accessibility requirements: no available topology found.

GKE Autopilot 클러스터 또는 노드 자동 프로비저닝이 사용 설정된 Standard 클러스터를 사용하는 경우 클러스터에 Ready 노드가 없기 때문에 이 오류가 발생할 수 있습니다. 노드 자동 프로비저닝이 새 노드로 확장된 후 몇 분 이내에 오류가 해결됩니다.

전송 포드가 장시간 Pending 예약 중입니다.

PVC 이벤트에 전송 포드의 상태가 장시간 Pending로 표시될 수 있습니다.

전송 작업 이벤트를 확인하여 작업의 예약이 실패했는지 확인하려면 다음 단계를 따르세요.

  1. PVC를 설명합니다.

    kubectl describe pvc $PVC_NAME -n $NAMESPACE

    출력은 다음과 비슷합니다.

    Events:
  Type     Reason             Age                From                Message
  ----     ------             ----               ----                -------
Normal   TransferInProgress              1s (x2 over 2s)    gkevolumepopulator-populator                                                                      populateCompleteFn: For PVC pd-pvc79 in namespace default, job with request ID populator-job-0b93fec4-5490-4e02-af32-15b16435d559 is still active with pod status as - Phase: Pending

  2. 전송 포드를 검사하려면 임시 Kubernetes 리소스 검사의 단계를 따르세요.

    출력은 다음과 비슷합니다.

    Events:
  Type     Reason             Age                From                Message
  ----     ------             ----               ----                -------
  Warning  FailedScheduling   2m50s              default-scheduler   0/3 nodes are available: 1 Insufficient cpu, 2 node(s) had volume node affinity conflict. preemption: 0/3 nodes are available: 1 No preemption victims found for incoming pod, 2 Preemption is not helpful for scheduling.
  Warning  FailedScheduling   37s (x2 over 39s)  default-scheduler   0/3 nodes are available: 1 Insufficient cpu, 2 node(s) had volume node affinity conflict. preemption: 0/3 nodes are available: 1 No preemption victims found for incoming pod, 2 Preemption is not helpful for scheduling.
  Normal   NotTriggerScaleUp  2m40s              cluster-autoscaler  pod didn't trigger scale-up:

  3. NotTriggerScaleUp 메시지가 표시되면 클러스터에 노드 자동 프로비저닝이 사용 설정되어 있는지 확인합니다.

    gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --format="value(autoscaling.enableNodeAutoprovisioning)"

    다음을 바꿉니다.

    • CLUSTER_NAME: 클러스터 이름입니다.
    • LOCATION: 클러스터의 컴퓨팅 리전 또는 영역입니다.

  4. 출력이 'False'로 표시되면 다음 명령어를 사용하여 노드 자동 프로비저닝을 사용 설정합니다.

    gcloud container clusters update CLUSTER_NAME \
    --enable-autoprovisioning \
    --location=LOCATION \
    --project=PROJECT_ID \
    --min-cpu MINIMUM_CPU \
    --min-memory MINIMUM_MEMORY \
    --max-cpu MAXIMUM_CPU \
    --max-memory MAXIMUM_MEMORY \
    --autoprovisioning-scopes=https://www.googleapis.com/auth/logging.write,https://www.googleapis.com/auth/monitoring,https://www.googleapis.com/auth/devstorage.read_only

    다음을 바꿉니다.

    • CLUSTER_NAME: 노드 자동 프로비저닝을 사용 설정하기 위해 업데이트할 클러스터의 이름입니다.
    • LOCATION: 클러스터의 컴퓨팅 영역 또는 리전입니다. 예를 들면 us-central1-a 또는 us-central1입니다.
    • PROJECT_ID: Trusted Cloud by S3NS 프로젝트 ID입니다.
    • MINIMUM_CPU: 자동 프로비저닝할 최소 vCPU 수입니다. 예를 들면 10입니다.
    • MINIMUM_MEMORY: 자동 프로비저닝할 최소 메모리 양(GiB)입니다. 예를 들면 200입니다.
    • MAXIMUM_CPU: 자동 프로비저닝할 최대 vCPU 수입니다. 예를 들면 100입니다. 이 한도는 수동으로 생성된 기존 노드 풀과 GKE에서 자동으로 생성할 수 있는 모든 노드 풀의 CPU 리소스 합계입니다.
    • MAXIMUM_MEMORY: 자동 프로비저닝할 최대 메모리 양입니다. 예를 들면 1000입니다. 이 한도는 기존의 수동으로 생성된 노드 풀과 GKE에서 자동으로 생성할 수 있는 모든 노드 풀의 메모리 리소스 합계입니다.

  5. 노드 자동 프로비저닝이 사용 설정된 경우 노드 자동 프로비저닝에 전송 작업을 확장할 수 있는 충분한 자동 확장 resourceLimits이 있는지 확인합니다. 전송 작업은 기본적으로 vCPU 24개를 사용합니다.

    gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --format="value(autoscaling.resourceLimits)"

    다음을 바꿉니다.

    • CLUSTER_NAME: 클러스터 이름입니다.
    • LOCATION: 클러스터의 컴퓨팅 리전 또는 영역입니다.

    출력은 다음과 비슷합니다.

    {'maximum': '1000000000', 'resourceType': 'cpu'};{'maximum': '1000000000', 'resourceType': 'memory'};

  6. 노드 자동 프로비저닝에 자동 확장 한도가 충분하지 않으면 올바른 구성으로 클러스터를 업데이트합니다.

    gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --max-cpu MAXIMUM_CPU \
    --max-memory MAXIMUM_MEMORY

    다음을 바꿉니다.

    • CLUSTER_NAME: 노드 자동 프로비저닝을 사용 설정하기 위해 업데이트할 클러스터의 이름입니다.
    • LOCATION: 클러스터의 컴퓨팅 영역 또는 리전입니다. 예를 들면 us-central1-a 또는 us-central1입니다.
    • PROJECT_ID: Trusted Cloud by S3NS 프로젝트 ID입니다.
    • MAXIMUM_CPU: 자동 프로비저닝할 최대 vCPU 수입니다. 예를 들면 100입니다. 이 한도는 수동으로 생성된 기존 노드 풀과 GKE에서 자동으로 생성할 수 있는 모든 노드 풀의 CPU 리소스 합계입니다.
    • MAXIMUM_MEMORY: 자동 프로비저닝할 최대 메모리 양입니다. 예를 들면 1000입니다. 이 한도는 기존의 수동으로 생성된 노드 풀과 GKE에서 자동으로 생성할 수 있는 모든 노드 풀의 메모리 리소스 합계입니다.

  7. 노드 자동 프로비저닝이 사용 설정되지 않은 Standard 클러스터의 경우 전송 작업을 위해 만든 노드에 필요한 컴퓨팅 클래스 라벨이 있는지 확인합니다.

    kubectl get node -l cloud.google.com/compute-class=gcs-to-hdml-compute-class

  8. 출력에 전송 작업에 대해 만든 노드가 나열되지 않으면 노드에 gcs-to-hdml-compute-class 컴퓨팅 클래스 라벨을 추가합니다.

    kubectl label node NODE_NAME cloud.google.com/compute-class=gcs-to-hdml-compute-class

    NODE_NAME을 컴퓨팅 클래스 라벨을 추가하려는 노드의 이름으로 바꿉니다.

오류 GCE quota exceeded개

전송 작업의 포드를 확인할 때 다음과 유사한 오류 메시지가 표시될 수 있습니다.

Node scale up in zones us-west1-b associated with this pod failed: GCE quota exceeded. Pod is at risk of not being scheduled.

  1. 전송 포드를 검사하려면 임시 Kubernetes 리소스 검사의 단계를 따르세요.

  2. 이 오류를 해결하려면 할당량을 늘리거나 확장 방해 요인이 될 수 있는 기존 리소스를 삭제하세요. 자세한 내용은 할당량 오류 문제 해결을 참고하세요.

Hyperdisk ML HDML_TOTAL_THROUGHPUT 초과 오류

gke-managed-volumepopulator 네임스페이스의 임시 PVC가 Hyperdisk ML 볼륨을 프로비저닝하지 못하면 데이터 전송을 위해 새 Hyperdisk ML 볼륨을 만드는 리전 할당량이 초과되었을 수 있습니다.

지역 할당량 문제로 인해 Hyperdisk ML 볼륨 프로비저닝이 실패했는지 확인하려면 GKE 볼륨 채우기 도구에서 생성한 임시 PVC와 연결된 이벤트 로그를 검사하세요. 다음 단계를 따르세요.

  1. 관련 환경 변수를 저장합니다.

    export PVC_NAME=PVC_NAME
export NAMESPACE=NAMESPACE

    다음 값을 바꿉니다.

    • PVC_NAME: PersistentVolumeClaim 리소스의 이름입니다.
    • NAMESPACE: 워크로드가 실행되는 네임스페이스입니다.

  2. 임시 PVC의 상태를 확인합니다.

    export PVC_UID=$(kubectl get pvc ${PVC_NAME} -n ${NAMESPACE} -o jsonpath='{.metadata.uid}')
export TEMP_PVC=prime-$PVC_UID
echo $TEMP_PVC
kubectl describe pvc $TEMP_PVC -n gke-managed-volumepopulator

  3. PVC 이벤트를 확인하여 다음과 유사한 QUOTA_EXCEEDED error를 찾습니다.

    Events:
  Type     Reason                Age                 From                                                                                              Message
  ----     ------                ----                ----                                                                                              -------
  Warning  ProvisioningFailed    105s                pd.csi.storage.gke.io_gke-3ef909a7688d424b94a2-d0d9-b185-vm_6a77d057-54e3-415a-8b39-82b666516b6b  failed to provision volume with StorageClass "pd-sc": rpc error: code = Unavailable desc = CreateVolume failed: rpc error: code = Unavailable desc = CreateVolume failed to create single zonal disk pvc-73c69fa8-d23f-4dcb-a244-bcd120a3c221: failed to insert zonal disk: unknown error when polling the operation: rpc error: code = ResourceExhausted desc = operation operation-1739194889804-62dc9dd9a1cae-9d24a5ad-938e5299 failed (QUOTA_EXCEEDED): Quota 'HDML_TOTAL_THROUGHPUT' exceeded.  Limit: 30720.0 in region us-central1

이 문제를 해결하려면 다음 안내를 따르세요.

  1. 추가 할당량을 요청하여 프로젝트에 새 Hyperdisk ML 볼륨을 만듭니다.
  2. 프로젝트에서 사용하지 않는 Hyperdisk ML 디스크를 삭제합니다.

기기에 남아 있는 공간이 없음

PVC에 No space left on device 오류 메시지가 표시되면 Hyperdisk ML 볼륨이 가득 차서 더 이상 데이터를 쓸 수 없다는 의미입니다. 오류는 다음과 유사하게 표시될 수 있습니다.

Events:
  Type     Reason                   Age   From                          Message
  ----     ------                   ----  ----                          -------
  Warning  TransferContainerFailed  57m   gkevolumepopulator-populator  populateCompleteFn: For PVC vp-pvc in namespace default, job with request ID populator-job-c2a2a377-6168-4ff1-afc8-c4ca713c43e2 for zone us-central1-c has a failed pod container with message:  on device
ERROR: Failed to download one or more components of sliced download.
ERROR: [Errno 28] No space left on device

이 문제를 해결하려면 PVC를 삭제하고 PVC 매니페스트에서 spec.resources.requests.storage 필드의 값을 늘린 다음 PVC를 다시 만들어 전송 프로세스를 다시 시작하세요.

다음 단계

  • 문서에서 문제 해결 방법을 찾을 수 없는 경우 지원 받기를 참고하세요.