버킷 재배치

이 페이지에서는 버킷을 한 위치에서 다른 위치로 이전하는 프로세스를 설명합니다. 버킷 재배치에 관한 자세한 내용은 버킷 재배치를 참고하세요.

시작하기 전에

버킷 이전 프로세스를 시작하기 전에 다음 단계를 완료하세요.

  1. 관리 허브를 사용 설정합니다.

  2. 소프트 삭제를 사용 설정합니다.

  3. 할당량 및 한도를 확인하여 새 위치에 버킷의 데이터를 수용할 만큼 충분한 할당량이 있는지 확인합니다.

  4. 버킷 이전 유형을 결정하여 쓰기 다운타임이 필요한지 파악합니다.

  5. 기존 버킷 태그를 삭제합니다.

  6. 인벤토리 보고서를 사용하는 경우 구성 저장

필요한 역할

한 위치에서 다른 위치로 버킷을 이전하는 권한을 얻으려면 관리자에게 프로젝트에 대한 스토리지 관리자(roles/storage.admin) 역할을 부여해 달라고 요청하세요.

이 역할은 버킷을 한 위치에서 다른 위치로 이전할 수 있는 권한 집합을 제공합니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 확장하세요.

필수 권한

인증된 사용자는 이 메서드를 사용하려면 버킷에 대한 다음 IAM 권한이 있어야 합니다.

  • storage.buckets.relocate
  • storage.bucketOperations.get
    버킷 이전 작업의 상태를 보려면 이 권한이 필요합니다.
  • storage.bucketOperations.list
    버킷 이전 작업 목록을 보려면 이 권한이 필요합니다.
  • storage.bucketOperations.cancel
    버킷 이전 작업을 취소하려면 이 권한이 필요합니다.

인증된 사용자는 이 메서드를 사용하기 위해 버킷에 대한 다음 권한도 필요할 수 있습니다.

  • storage.bucket.get
    버킷 이전 작업의 드라이 런증분 데이터 복사 중에 버킷의 메타데이터를 보려면 이 권한이 필요합니다.
  • storage.objects.liststorage.objects.get
    다른 위치로 이전하려는 버킷의 객체 목록을 보려면 이 권한이 필요합니다.

커스텀 역할을 사용하여 이 권한을 부여받을 수도 있고 다른 사전 정의된 역할로 이 권한을 부여받을 수도 있습니다. 어떤 역할이 어떤 권한과 연결되어 있는지 확인하려면 Cloud Storage에 대한 IAM 역할을 참고하세요.

프로젝트에 역할을 부여하는 방법은 프로젝트에 대한 액세스 관리를 참고하세요.

버킷 재배치

이 섹션에서는 버킷 이전을 사용하여 Cloud Storage 버킷을 한 위치에서 다른 위치로 이전하는 프로세스를 설명합니다. 버킷을 재배치할 때는 증분 데이터 복사 프로세스를 시작하고 모니터링한 후 최종 동기화 단계를 시작합니다. 이러한 단계에 관한 자세한 내용은 버킷 이전 프로세스 이해를 참고하세요.

테스트 실행 수행

버킷 이전 프로세스 중에 발생할 수 있는 문제를 최소화하려면 예행 연습을 실행하는 것이 좋습니다. 테스트 실행은 데이터를 이동하지 않고 버킷 이전 프로세스를 시뮬레이션하므로 문제를 조기에 포착하고 해결하는 데 도움이 됩니다. 시험 이전에서는 다음과 같은 비호환성을 확인합니다.

일부 문제는 실시간 리소스 가용성 등의 요인으로 인해 라이브 마이그레이션 중에만 표시될 수 있으므로 예행 연습으로 모든 문제를 파악할 수는 없지만 실제 이전 중에 시간이 많이 소요되는 문제가 발생할 위험을 줄일 수 있습니다.

명령줄

버킷 이전의 테스트 실행을 시뮬레이션합니다.

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION --dry-run

각 항목의 의미는 다음과 같습니다.

  • BUCKET_NAME은 재배치할 버킷의 이름입니다.

  • LOCATION은 버킷의 대상 위치입니다.

테스트 실행을 시작하면 장기 실행 작업이 시작됩니다. 작업 ID와 작업 설명이 표시됩니다. 예행 연습 완료를 추적하려면 진행 상황을 추적해야 합니다. 테스트 실행 진행률을 추적하는 방법에 관한 자세한 내용은 장기 실행 작업 세부정보 가져오기를 참고하세요.

예행 연습에서 문제가 발견되면 증분 데이터 복사 단계 시작을 진행하기 전에 문제를 해결합니다.

REST API

JSON API

  1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

  2. destinationLocationvalidateOnly 매개변수를 포함해야 하는 버킷의 설정이 포함된 JSON 파일을 만듭니다. 전체 설정 목록은 Buckets: relocate 문서를 참고하세요. 다음은 일반적으로 포함되는 설정입니다.

    {
      "destinationLocation": "DESTINATION_LOCATION",
      "destinationCustomPlacementConfig": {
          "dataLocations": [
            LOCATIONS,
            ...
            ]
        },
      "validateOnly": "true"
    }

    각 항목의 의미는 다음과 같습니다.

    • DESTINATION_LOCATION은 버킷의 대상 위치입니다.
    • LOCATIONS구성 가능한 이중 리전에 사용할 위치 코드 목록입니다.
    • validateOnly는 테스트 실행을 위해 true로 설정됩니다.
  3. cURL을 사용하여 JSON API를 호출합니다.

    curl -X POST --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    각 항목의 의미는 다음과 같습니다.

    • JSON_FILE_NAME은 만든 JSON 파일의 이름입니다.
    • BUCKET_NAME은 재배치하려는 버킷의 이름입니다.

증분 데이터 복사 시작

명령줄

버킷 재배치 작업을 시작합니다.

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION

각 항목의 의미는 다음과 같습니다.

  • BUCKET_NAME은 재배치할 버킷의 이름입니다.

  • LOCATION은 버킷의 대상 위치입니다.

REST API

JSON API

  1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

  2. 버킷 설정이 포함된 JSON 파일을 만듭니다. 전체 설정 목록은 Buckets: relocate 문서를 참고하세요. 다음은 일반적으로 포함되는 설정입니다.

    {
      "destinationLocation": "DESTINATION_LOCATION",
      "destinationCustomPlacementConfig": {
          "dataLocations": [
            LOCATIONS,
            ...
            ]
        },
      "validateOnly": "false"
    }

    각 항목의 의미는 다음과 같습니다.

    • DESTINATION_LOCATION은 버킷의 대상 위치입니다.
    • LOCATIONS구성 가능한 이중 리전에 사용할 위치 코드 목록입니다.
    • validateOnly는 버킷 재배치의 증분 데이터 복사 단계를 시작하도록 false로 설정됩니다.
  3. cURL을 사용하여 JSON API를 호출합니다.

    curl -X POST --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

    각 항목의 의미는 다음과 같습니다.

    • JSON_FILE_NAME은 만든 JSON 파일의 이름입니다.
    • BUCKET_NAME은 재배치하려는 버킷의 이름입니다.

증분 데이터 복사 모니터링

버킷 이전 프로세스는 진행 상황을 확인하기 위해 모니터링해야 하는 장기 실행 작업입니다. 장기 실행 작업 목록을 정기적으로 확인하여 증분 데이터 복사 단계의 상태를 확인할 수 있습니다. 장기 실행 작업에 관한 세부정보를 가져오거나, 장기 실행 작업을 나열하거나, 취소하는 방법에 관한 자세한 내용은 Cloud Storage에서 장기 실행 작업 사용을 참고하세요.

다음 예는 증분 데이터 복사 작업에서 생성된 출력을 보여줍니다.

done: false
kind: storage#operation
metadata:
'@type': type.googleapis.com/google.storage.control.v2.RelocateBucketMetadata
commonMetadata:
  createTime: '2024-10-21T04:26:59.666Z
  endTime: '2024-12-29T23:39:53.340Z'
  progressPercent: 99
  requestedCancellation: false
  type: relocate-bucket
  updateTime: '2024-10-21T04:27:03.2892'
destinationLocation: US-CENTRAL1
finalizationState: 'READY'
progress:
  byteProgressPercent: 100
  discoveredBytes: 200
  remainingBytes: 0
  discoveredObjectCount: 10
  remainingObjectCount: 8
  objectProgressPercent: 100
  discoveredSyncCount: 8
  remainingSyncCount: 0
  syncProgressPercent: 100
relocationState: SYNCING
sourceLocation: US
validateOnly: false
writeDowntimeExpireTime: '2024-12-30T10:34:01.786Z'
name: projects//buckets/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w
response:
  '@type': type.googleapis.com/google.storage.control.v2.RelocateBucketResponse
  selfLink: https://storage.googleusercontent.com/storage/v1_ds/b/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w

다음 표에는 증분 데이터 복사 작업에서 생성된 출력의 키 필드에 관한 정보가 나와 있습니다.

필드 이름 설명 가능한 값
done 버킷 이전 작업이 완료되었음을 나타냅니다. true, false
kind 이 리소스가 저장소 작업을 나타냄을 나타냅니다.
metadata 작업에 대한 정보를 제공합니다.
metadata.@type 작업 유형을 버킷 재배치로 나타냅니다.
metadata.commonMetadata 모든 작업에 공통적인 메타데이터입니다.
metadata.commonMetadata.createTime 장기 실행 작업이 생성된 시간입니다.
metadata.commonMetadata.endTime 장기 실행 작업이 종료된 시간입니다.
metadata.commonMetadata.progressPercent 장기 실행 작업의 예상 진행률(백분율)입니다. 0~100%. 값이 -1이면 진행률을 알 수 없거나 해당되지 않음을 의미합니다.
metadata.commonMetadata.requestedCancellation 사용자가 장기 실행 작업 취소를 요청했는지 여부를 나타냅니다. true, false
metadata.commonMetadata.type 장기 실행 작업의 유형을 나타냅니다.
metadata.commonMetadata.updateTime 장기 실행 작업이 마지막으로 업데이트된 시간입니다.
metadata.destinationLocation 버킷의 대상 위치입니다.
metadata.finalizationState 마지막 동기화 단계를 시작할 준비가 되었음을 나타냅니다.
  • READY: 최종 동기화 단계를 시작할 수 있음을 나타냅니다. 하지만 progressPercent 필드의 값이 99에 도달할 때까지 기다리는 것이 좋습니다.
  • WAITING_ON_SYNC: 최종 동기화 단계를 시작할 수 없음을 나타냅니다.
  • NOT_REQUIRED: 이 버킷에는 최종 동기화 단계가 필요하지 않으며 건너뛸 수 있음을 나타냅니다.
  • BLOCKED_ON_ERRORS: 오류로 인해 종료 단계가 일시적으로 일시중지되었음을 나타냅니다. 이 단계를 진행하려면 오류를 해결해야 합니다.
  • RUNNING: 완료 단계가 진행 중임을 나타냅니다.
  • FINALIZED: 완료 단계가 성공적으로 완료되었음을 나타냅니다.
metadata.progress 이전 작업의 진행 세부정보입니다.
metadata.progress.byteProgressPercent 복사된 바이트의 진행률(백분율)입니다. 0~100%. 값이 -1이면 진행률을 알 수 없거나 해당되지 않음을 의미합니다.
metadata.progress.discoveredBytes 소스 버킷에서 발견된 바이트 수입니다.
metadata.progress.discoveredObjectCount 소스 버킷에서 발견된 객체 수입니다.
metadata.progress.discoveredSyncCount 소스 버킷에서 발견된 객체 메타데이터 업데이트 수입니다.
metadata.progress.objectProgressPercent 복사된 객체의 진행률(%)입니다. 0~100%. 값이 -1이면 진행률을 알 수 없거나 해당되지 않음을 의미합니다.
metadata.progress.remainingBytes 소스 버킷에서 대상 버킷으로 복사할 남은 바이트 수입니다.
metadata.progress.remainingObjectCount 소스 버킷에서 대상 버킷으로 복사할 객체가 남은 수입니다.
metadata.progress.remainingSyncCount 동기화할 남은 객체 메타데이터 업데이트 수입니다.
metadata.progress.syncProgressPercent 동기화할 객체 메타데이터 업데이트 진행률(%)입니다. 0~100%. 값이 -1이면 진행률을 알 수 없거나 해당되지 않음을 의미합니다.
metadata.relocationState 버킷 재배치의 전체 상태
  • SYNCING: 증분 데이터 복사 단계에서 소스 버킷에서 대상 버킷으로 객체를 적극적으로 복사하고 있음을 나타냅니다.
  • FINALIZING: 완료 단계가 시작되었음을 나타냅니다.
  • FAILED: 증분 데이터 복사 단계에서 오류가 발생하여 완료되지 않았음을 나타냅니다.
  • SUCCEEDED: 증분 데이터 복사 단계가 완료되었음을 나타냅니다.
  • CANCELLED: 증분 데이터 복사 단계가 취소되었음을 나타냅니다.
metadata.sourceLocation 버킷의 소스 위치입니다.
metadata.validateOnly 버킷 이전의 드라이 런이 시작되었는지 여부를 나타냅니다. true, false
metadata.writeDowntimeExpireTime 쓰기 다운타임이 만료되는 시간입니다.
name 이 재배치 작업의 고유 식별자입니다.
형식: projects/_/buckets/bucket-name/operations/operation-id
response 작업의 응답입니다.
response.@type 응답 유형입니다.
selfLink 이 작업에 대한 링크입니다.

다른 Cloud Storage 기능과 상호작용할 때 제한으로 인해 문제가 발생할 수 있습니다. 제한사항에 관한 자세한 내용은 제한사항을 참고하세요.

최종 동기화 단계 시작

마지막 동기화 단계에는 버킷에 쓰기 작업을 실행할 수 없는 기간이 포함됩니다. 애플리케이션의 중단을 최소화하는 시점에 최종 동기화 단계를 예약하는 것이 좋습니다.

계속하기 전에 증분 데이터 복사 프로세스 모니터링 단계의 출력에서 finalizationState 값을 확인하여 버킷이 완전히 준비되었는지 확인합니다. 최종 동기화 단계를 진행하려면 finalizationState 값이 READY여야 합니다.

최종 동기화 단계를 조기에 시작하면 명령어는 The relocate bucket operation is not ready to advance to finalization running state 오류 메시지를 반환하지만 재배치 프로세스는 계속됩니다.

최종 동기화 단계를 시작하기 전에 progressPercent 값이 99이 될 때까지 기다리는 것이 좋습니다.

명령줄

finalizationState 값이 READY이 되면 버킷 이전 작업의 마지막 동기화 단계를 시작합니다.

gcloud storage buckets relocate --finalize --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

각 항목의 의미는 다음과 같습니다.

  • BUCKET_NAME은 재배치할 버킷의 이름입니다.
  • OPERATION_ID는 호출하는 메서드에 대한 응답으로 반환되는 장기 실행 작업의 ID입니다. 예를 들어 gcloud storage operations list를 호출하면 다음과 같은 응답이 반환되고 장기 실행 작업 ID는 AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74입니다.
 `name: projects/_/buckets/my-bucket/operations/AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74` 

이전 프로세스를 더 세부적으로 제어하려면 ttl 플래그를 설정합니다. 예를 들면 다음과 같습니다.

gcloud storage buckets relocate --finalize --ttl TTL_DURATION --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

각 항목의 의미는 다음과 같습니다.

TTL_DURATION은 이전 프로세스 중 쓰기 다운타임 단계의 TTL (수명)입니다. 문자열로 표현되며 12시간의 경우 12h와 같이 표시됩니다. TTL_DURATION는 쓰기 다운타임 단계의 최대 허용 시간을 결정합니다. 쓰기 다운타임이 이 한도를 초과하면 이전 프로세스가 자동으로 증분 복사 단계로 되돌아갑니다. 그러면 버킷에 대한 쓰기 작업이 다시 사용 설정됩니다. 값은 6h (6시간)~48h (48시간) 범위여야 합니다. 지정되지 않은 경우 기본값은 12h (12시간)입니다.

REST API

JSON API

  1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

  2. 버킷 이전 설정이 포함된 JSON 파일을 만듭니다. 전체 설정 목록은 Buckets: advanceRelocateBucket 문서를 참고하세요. 다음은 일반적으로 포함되는 설정입니다.

    {
        "expireTime": "EXPIRE_TIME",
        "ttl": "TTL_DURATION"
    }

    각 항목의 의미는 다음과 같습니다.

    • EXPIRE_TIME은 쓰기 다운타임이 만료되는 시간입니다.
    • TTL_DURATION은 이전 프로세스 중 쓰기 다운타임 단계의 TTL (수명)입니다. 문자열로 표현되며 12시간의 경우 12h와 같이 표시됩니다. TTL_DURATION는 쓰기 다운타임 단계의 최대 허용 시간을 결정합니다. 쓰기 다운타임이 이 한도를 초과하면 이전 프로세스가 자동으로 증분 복사 단계로 되돌아갑니다. 그러면 버킷에 대한 쓰기 작업이 다시 사용 설정됩니다. 값은 6h (6시간)~48h (48시간) 범위여야 합니다. 지정되지 않은 경우 기본값은 12h (12시간)입니다.
  3. cURL을 사용하여 JSON API를 호출합니다.

    curl -X POST --data-binary @JSON_FILE_NAME \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      "https://storage.googleapis.com/storage/v1/b/bucket/BUCKET_NAME/operations/OPERATION_ID/advanceRelocateBucket"

    각 항목의 의미는 다음과 같습니다.

    • JSON_FILE_NAME은 만든 JSON 파일의 이름입니다.
    • BUCKET_NAME은 재배치하려는 버킷의 이름입니다.
    • OPERATION_ID는 호출하는 메서드에 대한 응답으로 반환되는 장기 실행 작업의 ID입니다. 예를 들어 Operations: list를 호출하면 다음과 같은 응답이 반환되고 장기 실행 작업 ID는 AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74입니다.

버킷 이전 프로세스 유효성 검사

이전을 시작한 후 이전이 완료되었는지 확인합니다. 이 섹션에서는 데이터 전송이 완료되었는지 확인하는 방법을 안내합니다.

다음 방법을 사용하여 이전 프로세스가 완료되었는지 확인합니다.

  • 장기 실행 작업 폴링: 버킷 재배치는 장기 실행 작업입니다. operation id를 사용하여 장기 실행 작업을 폴링하여 작업 진행 상황을 모니터링하고 success 상태를 확인하여 작업이 완료되었는지 확인할 수 있습니다. 이를 위해서는 작업이 최종 상태에 도달할 때까지 주기적으로 작업 상태를 쿼리해야 합니다. 장기 실행 작업 모니터링에 관한 자세한 내용은 Cloud Storage에서 장기 실행 작업 사용을 참고하세요.

  • Cloud 감사 로그 항목 분석: Cloud 감사 로그는 환경의 이벤트 및 작업에 관한 자세한 기록을 제공합니다. Google Cloud 이전과 연결된 Cloud 감사 로그 항목을 분석하여 이전이 완료되었는지 확인할 수 있습니다. 전송 중에 문제를 나타낼 수 있는 오류, 경고 또는 예기치 않은 동작이 있는지 로그를 분석합니다. Cloud 감사 로그 보기에 관한 자세한 내용은 감사 로그 보기를 참고하세요.

    다음 로그 항목은 이전이 성공했는지 실패했는지 확인하는 데 도움이 됩니다.

    • 이전 완료: Relocate bucket succeeded. All existing objects are now in the new placement configuration.

    • 재배치 실패: Relocate bucket has failed. Bucket location remains unchanged.

    Pub/Sub 알림을 사용하여 특정 성공 또는 실패 이벤트가 로그에 표시될 때 알림을 보내는 알림을 설정할 수도 있습니다. Pub/Sub 알림 설정에 관한 자세한 내용은 Cloud Storage용 Pub/Sub 알림 구성을 참고하세요.

버킷 이전 후 작업 완료

버킷을 이전한 후 다음 단계를 완료합니다.

  1. 선택사항: 버킷의 태그 기반 액세스 제어를 복원합니다.
  2. 기존 인벤토리 보고서 구성은 이전 프로세스 중에 보존되지 않으므로 수동으로 다시 만들어야 합니다. 인벤토리 보고서 구성을 만드는 방법에 대한 자세한 내용은 인벤토리 보고서 구성 만들기를 참고하세요.
  3. Terraform 및 Google Kubernetes Engine 구성 커넥터와 같은 코드 구성으로 인프라를 업데이트하여 버킷의 새 위치를 지정합니다.
  4. 지역 엔드포인트는 특정 위치에 연결되며 새 엔드포인트를 반영하도록 애플리케이션 코드를 수정해야 합니다.

실패한 버킷 이전 작업을 처리하는 방법

실패한 버킷 이전 작업을 처리하기 전에 다음 요소를 고려하세요.

  • 버킷 이전에 실패하면 임시 파일이나 불완전한 데이터 사본과 같은 오래된 리소스가 대상에 남아 있을 수 있습니다. 동일한 대상에 대한 버킷 이전을 다시 시작하려면 7~14일이 지나야 합니다. 즉시 다른 대상에 대한 버킷 이전을 시작할 수 있습니다.

  • 대상 위치가 데이터에 최적화된 위치가 아닌 경우 재배치를 롤백하는 것이 좋습니다. 그러나 즉시 이전을 시작할 수는 없습니다. 이전 절차를 다시 시작하려면 최대 14일의 대기 기간이 필요합니다. 이 제한은 안정성을 보장하고 데이터 충돌을 방지하기 위한 조치입니다.

다음 단계