온프레미스용 전송 문제 해결

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

Cloud Console에서 전송 오류 문제 해결

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

오류 메시지 오류 유형 오류의 의미 오류 해결 방법
전송 중 수정됨 FILE_MODIFIED_FAILURE Transfer Service for On Premises Data가 소스 파일을 업로드하려고 할 때마다 해당 소스 파일이 업로드 중에 수정되었습니다. 다음번 Transfer Service for On Premises Data 작업 중 지정된 파일에 쓰기를 금지합니다.
전송할 수 없음 PRECONDITION_FAILURE Transfer Service for On Premises Data가 파일을 업로드하려고 할 때마다 소스 파일과 연결된 Cloud Storage 객체가 수정되었습니다. 전송 작업을 만들 때 고유한 Cloud Storage 객체 프리픽스를 사용하여 여러 전송 작업이 동일한 Cloud Storage 버킷에 동일한 파일을 쓰지 못하게 합니다.
소스 디렉터리를 찾을 수 없음 SOURCE_DIR_NOT_FOUND 지정된 소스 경로가 잘못되었거나 경로는 올바르지만 모든 에이전트가 경로에 액세스할 수 없습니다. 전송 작업 구성을 확인하고 다음을 확인합니다.
파일을 찾을 수 없음 FILE_NOT_FOUND_FAILURE 소스 파일을 찾았지만 Cloud Storage로 전송되기 전에 삭제되었습니다. 파일이 실수로 삭제된 경우 다음 전송 작업에서 업로드할 수 있도록 파일을 복원합니다.
대상 버킷을 찾을 수 없음 BUCKET_NOT_FOUND 대상 버킷이 Cloud Storage에 존재하지 않습니다. 대상 버킷의 철자가 올바르며 대상 버킷이 존재하는지 확인합니다.
내부 메타데이터 객체를 찾을 수 없음 METADATA_OBJECT_NOT_FOUND_FAILURE Transfer Service for On Premises Data는 storage-transfer 프리픽스가 추가된 대상 버킷에 메타데이터를 저장합니다. 해당 전송 작업이 완료되기 전에 메타데이터 파일이 삭제되면 이 오류가 표시됩니다. 모든 전송 작업이 완료될 때까지 대상 버킷에서 storage-transfer/ 프리픽스가 있는 객체를 삭제하지 마세요.
잘못된 파일 이름으로 인해 실패함 INVALID_FILE_NAME 소스 파일의 경로가 잘못되었습니다. 지정된 파일 경로를 확인하고 수정합니다. 경로에 Cloud Storage에서 지원하는 문자가 사용됐는지 확인합니다.
권한으로 인해 실패함 PERMISSION_FAILURE 에이전트에 작업을 수행할 수 있는 충분한 권한이 없습니다. 이 오류의 원인은 다음 두 가지입니다.
  • 에이전트에 Google Cloud 권한이 충분하지 않은 경우
  • 에이전트가 소스 파일 시스템에 대한 권한 부족으로 인해 파일 또는 디렉터리를 읽을 수 없는 경우
다음을 확인합니다.
  • 에이전트에 다음 IAM 역할이 있는지 확인합니다.
    • roles/pubsub.editor
    • 모든 대상 버킷의 roles/storage.admin
    이러한 역할은 에이전트가 사용하는 서비스 계정에 부여되거나 에이전트 설치 시 이러한 역할을 가진 기본 사용자 인증 정보를 사용하는 사용자에게 부여될 수 있습니다.
  • 각 에이전트에서 소스 파일 시스템의 모든 경로를 읽을 수 있는지 확인합니다.
서비스에 충분한 권한이 없음 SERVICE_PERMISSION_FAILURE Transfer Service for On Premises Data에 작업을 수행할 수 있는 충분한 권한이 없습니다. Transfer Service for On Premises Data는 cloud-ingest-dcp@cloud-ingest.iam.gserviceaccount.com 서비스 계정을 사용하여 리소스에 액세스합니다. 서비스 계정에 다음 역할이 있는지 확인합니다.
  • 프로젝트에 대한 roles/pubsub.editor
  • 모든 대상 버킷에 대한 roles/storage.admin
에이전트가 지원되지 않음 AGENT_UNSUPPORTED_VERSION 에이전트 버전이 더 이상 Transfer Service for On Premises Data와 호환되지 않습니다. 에이전트 업데이트 불량으로 인한 일시적인 오류입니다. 이 오류가 발생하면 다음을 수행합니다.
  1. 모든 에이전트를 중지합니다.
  2. sudo docker pull gcr.io/cloud-ingest/tsop-agent를 실행하여 최신 Docker 이미지를 가져옵니다.
  3. Docker run 명령어를 실행하여 모든 에이전트 컨테이너를 시작합니다.
문제가 지속되면 지원팀에 문의하세요.
해시 불일치로 인해 실패함 HASH_MISMATCH_FAILURE Transfer Service for On Premises Data에서 이 파일을 업로드하려고 할 때마다 업로드된 바이트가 손상됩니다. 이로 인해 온프레미스 파일의 해시가 결과 Cloud Storage 객체의 해시와 일치하지 않습니다. 이 오류는 여러 잠재적 문제로 인해 발생할 수 있습니다. 대량 전송에서 해시 불일치 오류가 1% 미만인 경우 실패한 파일을 다시 시도하세요. 해시 불일치 오류가 많은 경우(1% 이상) 에이전트 머신에서 잠재 메모리, CPU 또는 기타 하드웨어 오류를 조사하는 것이 좋습니다.
지원되지 않는 파일 모드로 인해 실패함 UNSUPPORTED_FILE_MODE Transfer Service for On Premises Data에서 기기, 소켓, 명명된 파이프 또는 일반적이지 않은 파일과 같이 지원되지 않는 모드가 포함된 파일이 발생했습니다. 소스 디렉터리에서 이러한 특수 파일 형식을 삭제합니다.
파일 시스템의 오류로 인해 실패함 FILESYSTEM_ERROR 에이전트에 읽기, 탐색, 통계 등 파일 시스템 작업 수행 시 파일 시스템 오류 또는 운영체제 오류가 발생했습니다. 실패 설명을 참조하여 어떤 파일 시스템 작업이 실패했는지 확인합니다. 파일 시스템이 온프렘 에이전트가 액세스할 수 있으며 기본 파일 작업에 응답하는지 확인합니다.
알 수 없는 오류로 인해 실패함 UNKNOWN_FAILURE 예기치 않은 오류가 발생했습니다. 실패 설명을 읽습니다. 실패 설명에 문제 해결에 필요한 정보가 부족하면 지원팀에 문의하세요.
사양이 잘못되어 실패했습니다. INVALID_SPEC 에이전트가 손상된 내부 사양을 받았습니다. 에이전트 호스트에서 데이터 손상이 있는지 확인하고 찾을 수 없는 경우 지원팀에 문의하세요.

에이전트 로그 보기

에이전트 로그에는 에이전트 프로세스와 관련된 정보가 포함되어 에이전트 연결 문제를 해결할 수 있습니다. 에이전트가 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

에이전트 오류 문제 해결

다음 섹션에서는 온프레미스용 전송 에이전트 문제를 해결하는 방법을 설명합니다.

에이전트가 연결되지 않음

온프레미스용 전송 에이전트가 Google Cloud Console에 연결된 것으로 표시되지 않는 경우 다음을 수행하세요.

  1. 에이전트가 Cloud Storage API 및 Pub/Sub API에 연결할 수 있고 네트워크 또는 인증 문제가 없는지 확인합니다.

    1. 전송 에이전트와 동일한 머신에서 다음 명령어를 실행하여 Cloud Storage API에 대한 에이전트 연결을 테스트합니다.

      gsutil cp test.txt gs://my-bucket

      다음과 같이 바꿉니다.

      my-bucket을 Cloud Storage 버킷 이름으로 바꿉니다.

    2. 전송 에이전트와 동일한 머신에서 다음 명령어를 실행하여 Pub/Sub API에 대한 에이전트 연결을 테스트합니다.

      gcloud pubsub topics list --project=project-id

      다음과 같이 바꿉니다.

      project-id를 Google Cloud 프로젝트 이름으로 바꿉니다.

  2. 프로젝트에서 VPC 서비스 제어를 사용하는 경우 에이전트 로그에서 오류를 확인합니다. VPC 서비스 제어가 잘못 구성된 경우 INFO 에이전트 로그에 다음 오류가 포함됩니다.

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

    이 출력에서 각 항목의 의미는 다음과 같습니다.

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

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