Flex 템플릿 문제 해결

이 페이지에서는 Dataflow Flex 템플릿을 사용할 때 유용할 수 있는 문제 해결 팁과 디버깅 전략을 제공합니다. 이 정보는 폴링 제한 시간을 감지하고 시간 초과 원인을 파악하며 문제를 해결하는 데 도움이 됩니다.

폴링 제한 시간 오류

작업이 다음 오류 메시지 중 하나를 반환할 수 있습니다.

Timeout in polling result file: FILE_PATH. Possible causes are:
1. Your launch takes too long time to finish. Please check the logs on stackdriver.
2. Service account SERVICE_ACCOUNT may not have enough permissions to pull
container image IMAGE_PATH or create new objects in FILE_PATH.
3. Transient errors occurred, please try again.

Timeout in polling result file: FILE_PATH.
Service account: SERVICE_ACCOUNT
Image URL: IMAGE_PATH
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling

이 문제는 다음과 같은 경우에 발생할 수 있습니다.

  1. 기본 Docker 이미지가 재정의된 경우
  2. SERVICE_ACCOUNT에 입력되는 서비스 계정에 필요한 권한이 없는 경우
  3. 외부 IP 주소가 중지되어 있으며, VM이 Google API 및 서비스에서 사용되는 외부 IP 주소 집합에 연결할 수 없는 경우
  4. 그래프를 만드는 프로그램이 너무 오래 걸려서 완료되지 않은 경우
  5. 파이프라인 옵션을 덮어쓰는 중인 경우
  6. Python 사용자: 종속 항목 설치 또는 스테이징에 너무 오래 걸리는 경우
  7. 일시적인 오류가 발생한 경우

이 문제를 해결하려면 먼저 작업 로그를 확인하고 재시도하여 오류가 일시적인지 확인합니다.

초기 시작 문제 섹션의 안내에 따라 직렬 포트 로깅을 사용 설정하면 추가 정보가 표시될 수 있습니다.

이 단계로 문제가 해결되지 않으면 다음 문제 해결 단계를 시도해 보세요.

(선택사항) 템플릿을 실행하여 문제 추가 진단

이 오류의 원인이 될 수 있는 이전 이유를 추가로 식별하려면 다음 전략을 사용하세요.

  1. Google에서 제공하는 WordCount 템플릿을 실행합니다. 공유 VPC 프로젝트의 서브넷, 작업자 VM의 비공개 IP, 사용할 Dataflow 작업자 서비스 계정과 같은 사용 사례에 고유한 파라미터를 제공해야 합니다. 이러한 파라미터를 제공하는 방법에 대한 자세한 내용은 gcloud 참조 및 API 참조를 확인하세요.

    이 작업을 완료할 수 있다면 네트워킹, IAM 권한, 비공개 Google 액세스가 올바르게 구성된 것일 수 있습니다.

  2. 작업 빌더를 사용하여 파이프라인 실행하기 빠른 시작을 완료합니다. 이 빠른 시작에서는 작업을 Flex 템플릿으로 실행합니다. 작업자 VM을 실행하기 전에 작업이 실패하면 런처 VM에 액세스하고 다음과 유사한 명령어를 사용하여 샘플 Docker 이미지를 다운로드해 보세요.

    docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-template

    이 명령어가 실패하면 이미지를 다운로드하는 데 네트워킹 문제가 있을 수 있습니다. 이 경우 내부 네트워킹팀과 협력하세요.

  3. Google 제공 Flex 템플릿을 실행하고 결과를 확인합니다. Google 제공 템플릿 작업이 성공적으로 완료되면 문제가 특정 맞춤 템플릿 코드 파일과 관련이 있을 가능성이 높습니다. 이 경우 문제를 해결하려면 특정 코드를 계속해서 문제 해결해야 합니다.

Docker 진입점 확인

제공된 템플릿 중 하나를 사용하는 대신 커스텀 Docker 이미지의 템플릿을 실행하는 경우 이 단계를 시도합니다.

다음 명령어를 사용하여 컨테이너 진입점을 확인합니다.

docker inspect $TEMPLATE_IMAGE

다음 출력이 예상됩니다.

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

다른 출력이 표시되면 Docker 컨테이너의 진입점이 재정의된 것입니다. $TEMPLATE_IMAGE를 기본값으로 복원합니다.

서비스 계정 권한 확인

메시지에 언급된 서비스 계정에 다음 권한이 있는지 확인합니다.

  • 메시지에서 ${file_path}에 입력되는 Cloud Storage 경로를 읽고 쓸 수 있어야 합니다.
  • 메시지에서 ${image_url}에 입력되는 Docker 이미지를 읽을 수 있어야 합니다.

비공개 Google 액세스 구성

외부 IP 주소가 사용 중지된 경우 Compute Engine VM이 Google API 및 서비스에서 사용되는 외부 IP 주소 집합에 연결하도록 허용해야 합니다. VM의 네트워크 인터페이스에서 사용하는 서브넷에 비공개 Google 액세스를 사용 설정하세요.

구성 세부정보는 비공개 Google 액세스 구성을 참조하세요.

기본적으로 Compute Engine VM에 네트워크 인터페이스에 할당된 외부 IP 주소가 없으면 패킷을 다른 내부 IP 주소 대상으로만 전송할 수 있습니다.

런처 프로그램이 종료되지 않는지 확인

파이프라인을 실행할 수 있으려면 먼저 파이프라인을 생성하는 프로그램이 종료되어야 합니다. 폴링 오류는 이 작업을 수행하는 시간이 너무 오래 걸림을 나타낼 수 있습니다.

코드에서 원인을 찾기 위해 수행할 수 있는 몇 가지 작업은 다음과 같습니다.

  • 작업 로그를 보고 작업 완료 시간이 오래 걸리는 것으로 표시되는지 확인합니다. 예를 들어 외부 리소스에 대한 요청이 있을 수 있습니다.
  • 프로그램 종료를 방해하는 스레드가 없는지 확인합니다. 일부 클라이언트는 자체 스레드를 만들 수 있으며, 이러한 클라이언트가 종료되지 않으면 프로그램은 해당 스레드가 조인될 때까지 기다립니다.

템플릿을 사용하지 않는 파이프라인을 직접 실행하면 이러한 제한이 없습니다. 따라서 파이프라인이 템플릿으로 작동하지 않고 직접 작동한 경우에는 템플릿 사용이 근본 원인일 수 있습니다. 템플릿의 문제를 찾아서 템플릿을 수정하면 문제가 해결될 수 있습니다.

필요한 파이프라인 옵션이 숨겨졌는지 여부 확인

Flex 템플릿을 사용할 때는 파이프라인 초기화 중 모든 파이프라인 옵션이 아닌 일부만 구성할 수 있습니다. 자세한 내용은 이 문서의 작업 파일 읽기 실패 섹션을 참조하세요.

Python 사용자: 종속 항목 관리

requirements.txt 파일에 추가 종속 항목을 제공하는 Python Flex 템플릿 작업을 실행하는 경우 작업이 실행되지 않을 수 있습니다. 이 실패는 요구사항 파일에 지정된 종속 항목을 다운로드하거나 설치하는 데 Flex 템플릿 실행에 할당된 시간보다 오래 걸릴 때 발생합니다.

작업 성능을 최적화하려면 템플릿을 빌드할 때 종속 항목을 미리 패키징하여 템플릿 실행 중에 종속 항목을 다운로드하거나 설치할 필요가 없도록 합니다. 자세한 내용은 'Flex 템플릿 구성'의 Python용 종속 항목 패키징 섹션을 참고하세요.

작업 실행 실패

다음 섹션에서는 작업 실행 실패로 이어지는 일반적인 오류와 이러한 오류를 해결하거나 문제 해결하기 위한 단계를 보여줍니다.

초기 시작 문제

초기 단계에 템플릿 실행 프로세스가 실패하면 일반 Flex 템플릿 로그를 사용하지 못할 수 있습니다. 시작 문제를 조사하려면 템플릿 런처 VM에 대해 직렬 포트 로깅을 사용 설정합니다.

Java 템플릿에 로깅을 사용 설정하려면 enableLauncherVmSerialPortLogging 옵션을 true로 설정합니다. Python 및 Go 템플릿에 대해 로깅을 사용 설정하려면 enable_launcher_vm_serial_port_logging 옵션을 true로 설정합니다. Google Cloud 콘솔에서 파라미터는 선택적 파라미터 아래에 런처 VM 직렬 포트 로깅 사용 설정으로 나열됩니다.

Cloud Logging에서 템플릿 런처 VM의 직렬 포트 출력 로그를 볼 수 있습니다. 특정 런처 VM의 로그를 찾으려면 resource.type="gce_instance" "launcher-number" 쿼리를 사용합니다. 여기서 number는 YYYMMDD 형식의 현재 날짜로 시작합니다.

조직 정책에 따라 직렬 포트 출력 로깅을 사용 설정하지 못할 수 있습니다.

작업 파일 읽기 실패

Flex 템플릿에서 작업을 실행하려고 시도하면 작업에 다음 오류가 발생할 수 있습니다.

Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object...

이 오류는 필요한 파이프라인 초기화 옵션을 덮어쓸 때 발생합니다. Flex 템플릿을 사용할 때는 파이프라인 초기화 중 모든 파이프라인 옵션이 아닌 일부만 구성할 수 있습니다. Flex 템플릿에 필요한 명령줄 인수를 덮어쓰면 작업이 템플릿 런처로 전달된 파이프라인 옵션을 무시, 재정의, 폐기할 수 있습니다. 작업이 실행되지 않거나 Flex 템플릿을 사용하지 않는 작업이 실행될 수 있습니다.

이 문제를 방지하려면 파이프라인 초기화 중 사용자 코드 또는 metadata.json 파일에서 다음 파이프라인 옵션을 변경하지 마세요.

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

결과 파일을 읽을 수 없음

Flex 템플릿에서 작업을 실행하려고 시도하면 작업에 다음 오류가 발생할 수 있습니다.

Failed to read the result file : gs://BUCKET_NAME...

이 오류는 Compute Engine 기본 서비스 계정에 Flex 템플릿을 실행하는 데 필요한 모든 권한이 없으면 발생합니다. 필요한 권한 목록은 Flex 템플릿을 실행할 수 있는 권한을 참조하세요.

리소스에 대한 권한이 거부됨

Flex 템플릿에서 작업을 실행하려고 시도하면 작업에 다음 오류가 발생할 수 있습니다.

Permission "MISSING_PERMISSION" denied on resource "projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME" (or it may not exist).

이 오류는 사용된 서비스 계정에 Flex 템플릿을 실행하는 데 필요한 리소스에 액세스할 수 있는 권한이 없을 때 발생합니다.

이 문제를 방지하려면 서비스 계정에 필요한 권한이 있는지 확인합니다. 필요에 따라 서비스 계정 권한을 조정합니다.

플래그가 제공되었지만 정의되지 않음

worker_machine_type 파이프라인 옵션으로 Go Flex 템플릿을 실행하려고 시도하면 다음 오류와 함께 파이프라인이 실패합니다.

flag provided but not defined: -machine_type

이 오류는 Apache Beam Go SDK 버전 2.47.0 이하의 알려진 문제로 인해 발생합니다. 이 문제를 해결하려면 Apache Beam Go 버전 2.48.0 이상으로 업그레이드하세요.

원격 작업 서버 jar를 가져올 수 없음

인터넷에 연결되어 있지 않은 상태에서 Flex 템플릿에서 작업을 실행하려고 하면 다음 오류가 표시되고 작업이 실패할 수 있습니다.

Unable to fetch remote job server jar at
https://repo.maven.apache.org/maven2/org/apache/beam/beam-sdks-java-io-expansion-service/VERSION/beam-sdks-java-io-expansion-service-VERSION.jar:
\u003curlopen error [Errno 101] Network is unreachable\u003e

이 오류는 VM이 인터넷에서 Apache Beam Java 패키지를 다운로드할 수 없기 때문에 발생합니다. 이 패키지는 Flex 템플릿을 사용하여 다국어 작업을 실행할 때 필요합니다.

이 문제를 해결하려면 다음 중 하나를 변경하면 됩니다

  • 인터넷에 연결합니다. 인터넷에 연결되어 있으면 작업이 필요한 파일에 액세스할 수 있습니다.

  • 작업이 로컬에서 액세스할 수 있도록 Apache Beam Java 패키지를 로컬 디렉터리에 포함합니다. 파일을 /root/.apache_beam/cache/jars/ 디렉터리에 놓습니다. 예를 들면 /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar입니다.

지정된 경로에서 파일 시스템을 가져올 수 없음

Flex 템플릿에서 작업을 실행하려고 시도하면 작업에 다음 오류가 발생할 수 있습니다.

ValueError: Unable to get filesystem from specified path, please use
the correct path or ensure the required dependency is installed, e.g., pip
install apache-beam[gcp]. Path specified: PATH

이 오류는 작업에서 Flex 템플릿 컨테이너 이미지를 사용하고 컨테이너 이미지에 Java 설치가 포함되지 않으면 발생합니다.

이 문제를 해결하려면 다음 줄을 Dockerfile에 추가합니다.

sh RUN apt-get update && apt-get install -y openjdk-17-jdk

이 명령어는 Java를 컨테이너 환경에 설치합니다.

Flex 템플릿 런처 지연

Flex 템플릿 작업을 제출하면 작업 요청이 Spanner 큐로 이동합니다. 템플릿 런처는 Spanner 큐에서 작업을 선택한 후 템플릿을 실행합니다. Spanner에 메시지 백로그가 있으면 작업을 제출한 시간과 작업이 실행되는 시간 사이에 상당한 지연이 발생할 수 있습니다.

이 문제를 해결하려면 다른 리전에서 Flex 템플릿을 실행하세요.

템플릿 파라미터가 잘못됨

gcloud CLI를 사용하여 Google 제공 템플릿을 사용하는 작업을 실행하려고 시도하면 다음 오류가 발생합니다.

ERROR: (gcloud.beta.dataflow.flex-template.run) INVALID_ARGUMENT: The template
parameters are invalid. Details: defaultSdkHarnessLogLevel: Unrecognized
parameter defaultWorkerLogLevel: Unrecognized parameter

이 오류는 일부 Google 제공 템플릿이 defaultSdkHarnessLog 및 defaultWorkerLog 옵션을 지원하지 않기 때문에 발생합니다.

이 문제를 해결하려면 템플릿 사양 파일을 Cloud Storage 버킷에 복사합니다. 파일에 다음 파라미터를 추가합니다.

"metadata": {
    ...
    "parameters": [
      ...,
      {
        "name": "defaultSdkHarnessLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      },
      {
        "name": "defaultWorkerLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      }
    ]
  }

템플릿 파일을 변경한 후 다음 명령어를 사용해서 템플릿을 실행합니다.

--template-file-gcs-location=gs://BUCKET_NAME/FILENAME

다음 값을 바꿉니다.

  • BUCKET_NAME: Cloud Storage 버킷 이름
  • FILENAME: 템플릿 사양 파일의 이름

Flex 템플릿 런처 로그에 잘못된 심각도가 표시됨

커스텀 Flex 템플릿 실행이 실패하면 로그 파일에 ERROR 심각도로 다음 메시지가 표시됩니다.

ERROR: Error occurred in the launcher container: Template launch failed. See console logs.

실행 실패의 근본 원인은 일반적으로 이 메시지 이전의 로그에 INFO 심각도로 표시됩니다. 이 로그 수준이 잘못되었을 수 있지만, Flex 템플릿 런처에는 Apache Beam 애플리케이션에서 생성된 로그 메시지로부터 심각도 세부정보를 추출하는 방법이 없기 때문에 예상한 동작입니다.

런처 로그에서 모든 메시지에 대해 올바른 심각도를 확인하려면 일반 텍스트 대신 JSON 형식으로 로그를 생성하도록 템플릿을 구성합니다. 이렇게 구성하면 템플릿 런처가 올바른 로그 메시지 심각도를 추출할 수 있습니다. 다음 메시지 구조를 사용하세요.

{
  "message": "The original log message",
  "severity": "DEBUG/INFO/WARN/ERROR"
}

Java에서는 커스텀 JSON 어펜더 구현과 함께 Logback 로거를 사용할 수 있습니다. 자세한 내용은 GitHub에서 Logback 예시 구성과 JSON 어펜더 예시 코드를 참조하세요.

이 문제는 파이프라인이 실행될 때 Flex 템플릿 런처로 생성된 로그에만 영향을 줍니다. 실행에 성공하고 파이프라인이 실행되면 Dataflow 작업자가 생성한 로그의 적절한 심각도를 갖습니다.

Google 제공 템플릿에는 이러한 JSON 로깅 접근 방법이 사용되기 때문에 작업 실행 중에 올바른 심각도가 표시됩니다.