Flex 템플릿 문제 해결

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

폴링 제한 시간 문제 해결

이 섹션에서는 폴링 제한 시간의 원인을 식별하는 단계를 설명합니다.

폴링 제한 시간

유연한 템플릿 작업이 다음 오류 메시지를 반환할 수 있습니다.

Timeout in polling result file: ${file_path}.
Service account: ${service_account_email}
Image URL: ${image_url}
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling

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

  1. 기본 Docker 이미지가 재정의되었습니다.
  2. ${service_account_email}에 입력되는 서비스 계정에 필요한 권한이 없습니다.
  3. 외부 IP 주소가 중지되어 있으며, VM이 Google API 및 서비스에서 사용되는 외부 IP 주소 집합에 연결할 수 없습니다.
  4. 그래프를 만드는 프로그램이 너무 오래 걸려서 완료되지 않습니다.
  5. 파이프라인 옵션을 덮어쓰는 중입니다.
  6. (Python만 해당) requirements.txt 파일에 문제가 있습니다.
  7. 일시적인 오류가 발생했습니다.

이 문제를 해결하려면 먼저 작업 로그를 확인하고 재시도하여 오류가 일시적인지 확인합니다. 이 단계로 문제가 해결되지 않으면 다음 문제 해결 단계를 시도해 보세요.

Docker 진입점 확인

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

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

docker inspect $TEMPLATE_IMAGE

다음 출력이 예상됩니다.

자바

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

요구사항 파일에서 Apache Beam 삭제(Python 전용)

Dockerfile에 apache-beam[gcp]가 있는 requirements.txt가 포함된 경우 파일에서 이를 삭제하고 개별적으로 설치합니다. 다음 명령어는 이 단계를 수행하는 방법을 보여줍니다.

RUN pip install apache-beam[gcp]
RUN pip install -U -r ./requirements.txt

요구사항 파일에 Apache Beam을 배치하면 실행 시간이 오래 걸리고 종종 시간 초과가 발생할 수 있습니다.

Python 사용 시 폴링 제한 시간

Flex 템플릿 및 Python을 사용하여 Dataflow 작업을 실행하는 경우 작업이 잠시 대기한 후 실행에 실패하고 다음 오류가 표시될 수 있습니다.

Timeout in polling

이 오류는 필요한 종속 항목을 설치하는 데 사용되는 requirements.txt 파일로 인해 발생합니다. Dataflow 작업을 시작하면 작업자 VM이 해당 파일에 액세스할 수 있도록 모든 종속 항목이 먼저 스테이징됩니다. 이 프로세스에는 requirements.txt 파일에서 모든 직접 및 간접 종속 항목을 다운로드하고 컴파일하는 과정이 포함됩니다. 일부 종속 항목은 컴파일하는 데 몇 분 정도 걸릴 수 있습니다. 특히 PyArrow의 컴파일이 오래 걸릴 수 있습니다. PyArrow는 Apache Beam 및 대부분의 Cloud 클라이언트 라이브러리에서 사용되는 간접 종속 항목입니다.

작업 성능을 최적화하려면 Dockerfile 또는 커스텀 컨테이너를 사용하여 종속 항목을 미리 패키징합니다. 자세한 내용은 'Flex 템플릿 구성'의 종속 항목 패키징을 참조하세요.

작업 실행 실패

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

초기 시작 문제

초기 단계에 템플릿 실행 프로세스가 실패하면 일반 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 with error message: ...: Unable to open template file

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

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

자바

  • 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 with error message: (ERROR_NUMBER): Unable to open template 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 로깅 접근 방법이 사용되기 때문에 작업 실행 중에 올바른 심각도가 표시됩니다.