파일 시스템 전송 문제 해결

이 문서에서는 전송 및 에이전트 문제를 해결하는 방법과 에이전트 문제를 해결하는 데 도움이 되는 에이전트 로그를 찾을 수 있는 위치에 대해 설명합니다.

오류

다음 표에서는 전송 오류 메시지와 해결 방법을 설명합니다.

오류 메시지	오류 유형	오류의 의미	오류 해결 방법
전송 중 수정됨	FILE_MODIFIED_FAILURE	Storage Transfer Service가 소스 파일을 복사하려고 할 때마다 소스 파일이 전송 중에 수정되었습니다.	다음번 Storage Transfer Service 작업 중 지정된 파일에 쓰기를 금지합니다.
전송할 수 없음	PRECONDITION_FAILURE	Storage Transfer Service가 파일을 업로드하려고 할 때마다 소스 파일과 연결된 Cloud Storage 객체가 수정되었습니다.	전송 작업을 만들 때 고유한 Cloud Storage 객체 프리픽스를 사용하여 여러 전송 작업이 동일한 Cloud Storage 버킷에 동일한 파일을 쓰지 못하게 합니다.
소스 디렉터리를 찾을 수 없음	SOURCE_DIR_NOT_FOUND	지정된 소스 경로가 잘못되었거나 경로는 올바르지만 모든 에이전트가 경로에 액세스할 수 없습니다.	전송 작업 구성을 확인하고 다음을 확인합니다. 나열된 소스 경로가 올바릅니다. 각 에이전트는 디렉터리에 액세스할 수 있습니다.
작업의 소스 또는 대상 디렉터리를 찾을 수 없음	ROOT_DIR_NOT_FOUND	지정된 소스/대상 경로가 잘못되었거나 경로는 올바르지만 모든 에이전트가 경로에 액세스할 수 없습니다.	전송 작업 구성을 확인하고 다음을 확인합니다. 나열된 소스/대상 경로가 올바릅니다. 관련 에이전트에 디렉터리에 대한 액세스 권한이 있습니다.
파일을 찾을 수 없음	FILE_NOT_FOUND_FAILURE	소스 파일을 찾았지만 Cloud Storage로 전송되기 전에 삭제되었습니다.	파일이 실수로 삭제된 경우 다음 전송 작업에서 업로드할 수 있도록 파일을 복원합니다.
대상 버킷을 찾을 수 없음	BUCKET_NOT_FOUND	대상 버킷이 Cloud Storage에 존재하지 않습니다.	대상 버킷의 철자가 올바르며 대상 버킷이 존재하는지 확인합니다.
내부 메타데이터 객체를 찾을 수 없음	METADATA_OBJECT_ NOT_FOUND_FAILURE	Storage Transfer Service는 `storage-transfer` 프리픽스가 추가된 대상 버킷에 메타데이터를 저장합니다. 해당 전송 작업이 완료되기 전에 메타데이터 파일이 삭제되면 이 오류가 표시됩니다.	모든 전송 작업이 완료될 때까지 대상 버킷에서 `storage-transfer/` 프리픽스가 있는 객체를 삭제하지 마세요.
잘못된 파일 이름으로 인해 실패함	INVALID_FILE_NAME	소스 파일의 경로가 잘못되었습니다.	지정된 파일 경로를 확인하고 수정합니다. 경로에 Cloud Storage에서 지원하는 문자가 사용됐는지 확인합니다.
잘못된 재개 가능한 업로드 세션 URI로 인해 실패함	SESSION_URI_INVALID	재개 가능한 업로드 ID 또는 세션 URI가 만료되거나 취소되었습니다.	실패가 잘못 재시도됩니다. 지원팀에 문의해 주세요.
잘못된 파일 크기로 인해 실패함	INVALID_FILE_SIZE	파일 크기가 잘못되었습니다.	Cloud Storage로 전송할 때 파일 크기가 0 이상이고 5TiB 이하(최대 Cloud Storage 객체 크기)인지 확인합니다.
권한으로 인해 실패함	권한_실패 및 인증되지 않음	전송 에이전트에 작업을 수행할 수 있는 충분한 권한이 없습니다. 이 오류의 원인은 다음 두 가지입니다. 에이전트에 Google Cloud 권한이 충분하지 않은 경우 에이전트가 소스 파일 시스템에 대한 권한 부족으로 인해 파일 또는 디렉터리를 읽을 수 없는 경우	다음 사항을 확인하세요. 에이전트에 다음 IAM 역할이 있는지 확인합니다. `storagetransfer.transferAgent` 모든 대상 버킷의 `storage.admin` 이러한 역할은 에이전트가 사용하는 서비스 계정에 부여될 수 있으며, 또는 이러한 역할을 가진 사용자는 에이전트 설치 시 기본 사용자 인증 정보를 사용할 수 있습니다. 각 에이전트에서 소스 파일 시스템의 모든 경로를 읽을 수 있는지 확인합니다.
객체에는 버킷의 보존 정책이 적용되며, 이를 삭제하거나 덮어쓰거나 보관처리할 수 없습니다.	PERMISSION_FAILURE	버킷에는 보관 정책이 적용되고 객체가 이미 버킷에 있습니다. Storage Transfer Service에서 버킷의 기존 객체를 덮어쓸 수 없습니다. 이 오류는 파일이 소스에서 파일이 변경되거나 Storage Transfer Service가 네트워크 조건으로 인해 업로드를 두 번 시도하고 첫 번째 업로드가 성공한 경우에 표시될 수 있습니다.	Cloud Storage 버킷의 데이터가 예상과 일치하는지 확인합니다. 작업을 다시 실행하고 오류가 없는지 확인하여 소스 파일의 크기 및 수정 시간(mtime)이 Cloud Storage 객체와 일치하는지 확인할 수 있습니다.
서비스에 충분한 권한이 없음	SERVICE_PERMISSION_FAILURE	Storage Transfer Service에 작업을 수행할 수 있는 충분한 권한이 없습니다.	Storage Transfer Service는 일반적으로 `project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com` 형식의 Google 관리 서비스 계정을 사용하여 리소스에 액세스합니다. 특정 `PROJECT_NUMBER`를 확인하려면 `googleserviceaccounts.get` API 호출을 사용합니다. 서비스 계정에 다음 역할이 있는지 확인합니다. 프로젝트에 대한 `roles/storagetransfer.serviceAgent` 모든 대상 버킷에 대한 `roles/storage.admin`
에이전트가 지원되지 않음	AGENT_UNSUPPORTED_VERSION	에이전트 버전이 더 이상 Storage Transfer Service와 호환되지 않습니다.	에이전트 업데이트 불량으로 인한 일시적인 오류입니다. 이 오류가 발생하면 다음을 수행합니다. 모든 에이전트를 중지합니다. `sudo docker pull gcr.io/cloud-ingest/tsop-agent`를 실행하여 최신 Docker 이미지를 가져옵니다. Docker `run` 명령어를 실행하여 모든 에이전트 컨테이너를 시작합니다. 문제가 지속되면 지원팀에 문의하세요.
해시 불일치로 인해 실패함	HASH_MISMATCH_FAILURE	Storage Transfer Service에서 이 파일을 업로드하려고 할 때마다 업로드된 바이트가 손상됩니다. 이로 인해 온프레미스 파일의 해시가 결과 Cloud Storage 객체의 해시와 일치하지 않습니다.	이 오류는 여러 잠재적 문제로 인해 발생할 수 있습니다. 대량 전송에서 해시 불일치 오류가 1% 미만인 경우 실패한 파일을 다시 시도하세요. 해시 불일치 오류가 많은 경우(1% 이상) 에이전트 머신에서 잠재 메모리, CPU 또는 기타 하드웨어 오류를 조사하는 것이 좋습니다.
지원되지 않는 파일 모드로 인해 실패함	UNSUPPORTED_FILE_MODE	Storage Transfer Service에서 기기, 소켓, 명명된 파이프 또는 일반적이지 않은 파일과 같이 지원되지 않는 모드가 포함된 파일이 발생했습니다.	소스 디렉터리에서 이러한 특수 파일 형식을 삭제합니다.
파일 시스템의 오류로 인해 실패함	FILESYSTEM_ERROR	에이전트에 읽기, 탐색, 통계 등 파일 시스템 작업 수행 시 파일 시스템 오류 또는 운영체제 오류가 발생했습니다.	실패 설명을 참조하여 어떤 파일 시스템 작업이 실패했는지 확인합니다. 파일 시스템이 온프렘 에이전트가 액세스할 수 있으며 기본 파일 작업에 응답하는지 확인합니다.
알 수 없는 오류로 인해 실패함	UNKNOWN_FAILURE	예기치 않은 오류가 발생했습니다.	실패 설명을 읽습니다. 실패 설명에 문제 해결에 필요한 정보가 부족하면 지원팀에 문의하세요.
사양이 잘못되어 실패했습니다.	INVALID_SPEC	에이전트가 손상된 내부 사양을 받았습니다.	에이전트 호스트에서 데이터 손상이 있는지 확인하고 찾을 수 없는 경우 지원팀에 문의하세요.
비어 있거나 잘못된 매니페스트 파일로 인해 실패함	CONFORMANCE_FAILURE	잘못된 형식 또는 CSV 항목으로 인해 에이전트에서 유효한 CSV 바이트를 읽거나 가져올 수 없습니다.	매니페스트 항목이 유효한 파일 경로인지 확인합니다. 실패 설명에 문제 해결에 필요한 정보가 부족하면 지원팀에 문의하세요.
권한 거부됨 오류로 인해 멀티파트 업로드 대신 재개 가능한 업로드로 돌아감	PERMISSION_FAILURE	이 전송에는 멀티파트 업로드가 사용 설정되었지만 버킷에 올바른 권한이 설정되지 않았습니다.	필요한 권한은 파일 시스템 권한의 멀티파트 업로드 섹션을 참조하세요.

에이전트 로그 보기

에이전트 로그에는 에이전트 프로세스와 관련된 정보가 포함되어 에이전트 연결 문제를 해결할 수 있습니다. 에이전트가 Google Cloud Console에 연결되어 있는 것으로 표시되고 전송 실패가 발생하면 오류 보기에서 전송 오류 샘플을 확인하세요. 전송 중에 고려되는 모든 Storage Transfer Service 파일의 레코드가 포함된 로그를 보려면 전송 로그 보기를 참조하세요.

기본적으로 에이전트 로그는 /tmp에 저장됩니다. --log-dir=logs-directory 명령줄 옵션을 사용하여 위치를 변경할 수 있습니다.

로그의 이름은 다음과 같습니다.

agent.hostname.username.log.log-level.timestamp

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

hostname - 에이전트가 실행 중인 호스트 이름입니다.
username - 에이전트를 실행하는 사용자 이름입니다.
log-level은 다음 중 하나입니다.
- INFO - 정보 제공 메시지
- ERROR - 전송 중에 오류가 발생했지만 전송 작업이 계속 실행되는 것을 막지는 않습니다.
- FATAL - 전송 작업을 계속 진행할 수 없는 오류가 발생했습니다.
timestamp - YYYYMMDD-hhmmss.thread-id 형식의 타임스탬프

로그 디렉터리에는 각 우선순위 수준의 최신 로그에 대한 심볼릭 링크가 포함되어 있습니다.

agent.ERROR
agent.FATAL
agent.INFO

느린 전송 속도

데이터를 전송하는 데 시간이 오래 걸리는 경우 다음을 확인하세요.

파일 시스템의 읽기 처리량은 원하는 업로드 속도의 약 1.5배여야 합니다. FIO를 사용하여 파일 시스템의 읽기 처리량을 테스트할 수 있습니다.

fio를 설치합니다.
```
 sudo apt install -y fio
 
```
새 fiotest 디렉터리를 만듭니다.
```
 TEST_DIR=/mnt/mnt_dir/fiotest
 sudo mkdir -p $TEST_DIR
 
```
읽기 처리량을 테스트합니다.
```
 sudo fio --directory=$TEST_DIR --direct=1
    --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8
    --time_based=1 --runtime=180 --name=read_test --size=1G
 
```
위 명령어를 실행하면 Fio가 보고서를 생성합니다. 'bw' 라벨이 지정된 행은 모든 스레드의 총 집계 대역폭을 나타내며 읽기 처리량을 위한 프록시로 사용될 수 있습니다.
iPerf3을 사용하여 Storage Transfer Service에 사용 가능한 인터넷 대역폭을 확인합니다.
각 전송 에이전트에 최소 4개의 vCPU와 8GB의 RAM이 있는지 확인합니다.

위의 조건을 확인했지만 여전히 전송 시간이 긴 경우 에이전트를 추가하여 데이터의 파일 시스템에 대한 동시 연결 수를 늘릴 수 있습니다.

전송 에이전트의 성능을 극대화하는 방법에 대한 자세한 내용은 에이전트 권장사항을 참조하세요.

에이전트 오류 문제 해결

다음 섹션에서는 전송 에이전트 오류를 해결하는 방법을 설명합니다.

에이전트가 연결되지 않음

전송 에이전트가 Google Cloud 콘솔에 연결된 것으로 표시되지 않는 경우 다음 안내를 따르세요.

에이전트가 Cloud Storage API에 연결할 수 있는지 확인합니다.
1. 전송 에이전트와 동일한 머신에서 다음 명령어를 실행하여 Cloud Storage API에 대한 에이전트 연결을 테스트합니다.
  
  gsutil cp test.txt gs://my-bucket
  
  다음과 같이 바꿉니다.
  
  my-bucket을 Cloud Storage 버킷 이름으로 바꿉니다.
프로젝트에서 VPC 서비스 제어를 사용하는 경우 에이전트 로그에서 오류를 확인합니다. VPC 서비스 제어가 잘못 구성된 경우 INFO 에이전트 로그에 다음 오류가 포함됩니다.

Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

이 출력에서 각 항목의 의미는 다음과 같습니다.
- id는 VPC 서비스 제어 오류의 고유 ID입니다.

에이전트가 연결되었지만 작업이 실패함

에이전트가 연결됨으로 표시되지만 전송 작업이 실패하는 경우 실패한 작업의 오류 세부정보를 확인합니다.